Files
ws_health/doc/taro-plan.md
T

16 KiB
Raw Blame History

taroapp_escort 双端改造方案(微信 weapp + 抖音 tt)

本文是新会话的唯一执行依据。开工前先读 §2 决策、§6 契约、§9 阻塞项。 基线:ui/wxapp_escort 标签 phase1-native-baseline(commit aeafe21,分支 dev,工作区干净) 目标:ui/taroapp_escort(已作为 submodule 挂在父仓库,当前只有 README.md + .git gitfile)


1. 目标与范围

  • 用 Taro 4.1.9 + React + TypeScript + Webpack5 + Sass 建 ui/taroapp_escort,一份代码双端构建 weapp + tt。
  • Phase 1:只发布抖音;微信继续跑原生 wxapp_escort。
  • Phase 2:Taro 版补齐后全量切换——微信复用原 AppID 上传 Taro 产物,原生工程归档。
  • 不在本方案内:支付宝(alipay)、后端支付/下单改造、原生端新功能。

2. 已确认的决策

# 决策
D1 目录/工程名 ui/taroapp_escort;npm name = taroapp-escort;displayName = 暖橙陪诊
D2 双构建:weapp + tt,从第一天起两端都要能构建通过
D3 init 走「临时目录 → 拷入 submodule 目录(保留 .git 与 README.md)」
D4 tabBar 先沿用 custom: true 自定义;抖音端实测不通过则按 process.env.TARO_ENV 降级为原生 tabBar
D5 不引第三方 UI 库;自研 Icon / Loading / Markdown 三个组件替换 TDesign
D6 样式保留原 rpx 数值直搬(Taro 的 postcss 只转 px,rpx 原样透传)→ 4627 行 WXSS 近无损迁移
D7 Phase 1 期间原生 wxapp_escort 冻结:只做线上紧急修复,新需求一律进 Taro 端

3. 基线

  • ui/wxapp_escort @ dev / aeafe21,已打本地标签 phase1-native-baseline。
  • 远端 gitea 还没有该标签 → 需执行 git push origin phase1-native-baseline(尚未推送,待确认)。
  • 逐页移植时对照该标签的文件,不要对照工作区(原生端后续仍可能有紧急修复)。

4. 关键参数(不要改)

项 值
微信 AppID wxf73c79e16837af07(沿用不变)
抖音 AppID tt39dd4f60a7a3f3be01
业务 appId 键 现状 wxapp-escort,保持不变(后端 conf.json 选 appid/secret 的键);抖音侧取值待后端定,见 §9.1 B1
接口基址 https://api.huashengtec.com(本地调试:health 127.0.0.1:9004、user 127.0.0.1:9010)
WebSocket wss://api.huashengtec.com/health-ws/chat
设计基准宽 750(Taro designWidth: 750)

5. 目标工程结构

ui/taroapp_escort/
  config/index.ts        outputRoot: `dist/${process.env.TARO_ENV}`(两端产物隔离)
  src/
    app.ts / app.config.ts / app.scss     启动逻辑 + 全局色板令牌
    pages/                                与原生同名同层级(见 §8)
    components/                           Icon / Loading / Markdown / CustomTabBar
    utils/                                request api chatmsg date form order privacy platform
    assets/fonts/t.woff  assets/images/*
  doc/DESIGN.md                            从原生拷入(配色规范,唯一真源)
  doc/MIGRATION.md                         逐页勾选清单(新建)
  project.config.json                      微信 appid
  project.tt.json                          抖音 appid
  .gitignore

6. 迁移契约(必须逐字对齐,改了就出线上事故)

6.1 请求层 utils/request.ts

  • 默认实例基址 https://api.huashengtec.com;另有 user 服务实例用 USER_BASE_URL(user 与 health 是两个进程,本地调试必须分开,否则 user 接口会打到 health 端口)。
  • 每次请求 body 合并 appId(当前 'wxapp-escort')。这是后端选密钥的键,不能删不能改。
  • header 带 token(取 app.globalData.user.security.token)与 Content-Type: application/json。
  • 响应 code === 401 且未重试过 → 调 app.silentSignin(),成功则原请求重试一次;失败返回 { code: 401, msg: '请先登录', data: null }(调用方现有「res.msg 弹 toast」可直接复用)。
  • HTTP 非 2xx 直接 reject(new Error('HTTP xxx'))。
  • request.setUnauthorizedHandler(handler) 由 app 注入(单向依赖:api → request,反向会成环)。

6.2 接口表 utils/api.ts(逐条复刻)

  • user(走 user 实例):POST /user/wxgetphonenumber、POST /user/wxsignin、POST /user/signout、POST /user/update
  • escort:GET /health/escort-record/my、GET /health/escort-record/attendant、GET /health/escort-record/{id}、POST /health/escort-record、PUT /health/escort-record/{id}、PATCH /health/escort-record/{id}/status、DELETE /health/escort-record/{id}、GET /health/attendant、GET /health/attendant/{id}
  • healthProfile:GET /health/health-profile/mine、GET /health/health-profile/mine/{id}、POST /health/health-profile/mine、PUT /health/health-profile/mine/{id}、DELETE /health/health-profile/mine/{id}
  • resource:GET /health/service、GET /health/agreement、GET /health/ai-quick-questions
  • ai:POST /ai/chat

6.3 启动逻辑 app.ts(对齐原生 app.js)

  • onLaunch:注册 401 回调 → loadServices() + loadAgreement() 预取(Promise 缓存,失败清缓存以便重试)→ checkUpdate()。
  • onShow:globalData.authReady = silentSignin()。
  • silentSignin() 单飞语义必须保留:has_logout 标记存在时直接 resolve(false);并发只发一次;login 取 code → wxSignin;成功写 globalData.user。原生注释写明原因:并发重签会覆盖 token,导致本机持作废 token 后全部 401。
  • initChatSocket():AI WebSocket 懒创建。
  • checkUpdate():canIUse('getUpdateManager') 守卫 + getUpdateManager(onCheckForUpdate / onUpdateReady / onUpdateFailed)。
  • globalData:user、chatSocket、services、servicesReady、agreement、agreementReady、authReady。

6.4 WebSocket utils/chatmsg.ts

  • 地址 wss://api.huashengtec.com/health-ws/chat;connect() 单飞(调用方必须 await 成功后再 send)。
  • 心跳 30s:{ source: 'client', type: 'ping', content: '', id: 'heartbeat_<ts>' }。
  • 断线自动重连:最多 3 次、间隔 3s;close() 时关掉自动重连并 close({code:1000})。
  • 消息解析失败回调 { source: 'system', type: 'error', content: '收到无法解析的服务消息', id: '' }。

6.5 其余工具

  • order.ts:STATUS_MAP(pending/confirmed/in_progress/completed/cancelled,含 text/color/bg/border/desc)与 PAYMENT_STATUS_MAP(unpaid/partial/paid/refunding/refunded)——颜色值逐字保留。
  • date.ts:parseDate/formatDate/formatDateTime/calcAge/toISOString。YYYY-MM-DD 必须按本地年月日构造(各端 new Date(str) 解析不一致),并做回读校验。
  • privacy.ts:maskIdNumber(前4********后4)、maskOrderId(****后8大写)。
  • form.ts:未保存拦截。微信用 enableAlertBeforeUnload / disableAlertBeforeUnload,必须 canIUse 守卫;抖音能力待验,不可用则降级为页面内提示。

6.6 storage key(不能改名)

has_logout、ai_chat_history、ai_session_id、user_phonenumber

6.7 设计令牌

app.wxss 的 page{} 是全站唯一色板来源,整块搬进 app.scss(含 --brand-*、--ink*、--muted/--faint/--line/--sep/--paper/--white、--shadow-*,以及 --td-brand-color-* 映射)。改配色只改这一处。doc/DESIGN.md 是不变量,一并拷入新工程 doc/。

7. 资源搬迁

  • assets/fonts/t.woff:TDesign 图标字族,以 base64 内嵌到共享 SCSS 的 @font-face(不要引远程域名,真机不支持本地路径)。
  • images/:home.png、home-green.png、ai.png、ai-green.png、mine.png、mine-green.png、wechat_code.jpg。 home-w.png / ai-ink.png / home-ink.png 是历史遗留(自定义 tabBar 已改用图标字体),按页面实际引用决定是否搬。
  • app.config.ts 的 tabBar list 仍需 iconPath/selectedIconPath,即使 custom: true。
  • 原生 pages/attendant/ 是空遗留目录,不迁移。

8. 页面迁移清单(对照 phase1-native-baseline)

顺序即下表顺序:先易后难,AI 页最后。

# 原生路径 说明 难度 完成
1 pages/home/index 首页 中 ☐
2 pages/escort/itemlist 服务列表 低 ☐
3 pages/escort/itemdetail 服务详情 / 下单 高 ☐
4 pages/health/profilelist 就诊人列表 低 ☐
5 pages/health/profileedit 就诊人编辑 中 ☐
6 pages/mine/mine 我的(登出 / 授权) 中 ☐
7 pages/mine/profileedit 个人资料编辑 中 ☐
8 pages/mine/about 关于 低 ☐
9 pages/mine/contact 联系我们 低 ☐
10 pages/mine/business 合作与入驻 低 ☐
11 pages/escort/recordlist 订单记录 中 ☐
12 pages/escort/recorddetail 订单详情 高 ☐
13 pages/escort/agreement 用户协议 低 ☐
14 pages/escort/guide 服务指南 低 ☐
15 pages/ai/aichat AI 客服(socket + markdown) 最高 ☐

每页转化三件事:WXML→TSX、JS→TS、WXSS→SCSS(rpx 直搬)。

9. 平台差异与阻塞项

9.1 阻塞项(不解决,对应功能不可用)

# 阻塞 负责方 说明
B1 后端抖音登录 后端 conf.json 加抖音 AppSecret(AppID 已知);wxsignin 支持抖音 code(code2session 换 openid/session_key/unionid);请求需能区分平台(建议 appId 取 weapp-escort/ttapp-escort,或新增 platform 字段)
B2 后端手机号 后端 wxgetphonenumber 支持抖音 tt.getPhoneNumber 解密
B3 抖音域名白名单 你 / 运营 抖音开放平台配置 https://api.huashengtec.com、wss://api.huashengtec.com(开发者工具可先勾「不校验合法域名」自测)
B4 抖音上传 Token 你 只在插件 workbench 里填,不进对话/代码;本地构建不需要
B5 抖音类目 / 资质 你 影响 tt.getPhoneNumber 等能力可用性

B1/B2 未就绪前,抖音端登录做占位并显式标注,不要假装可用。

9.2 平台差异处理

能力 微信 抖音 处理
登录 wx.login tt.login Taro.login() 统一取 code,但必须带平台标识给后端(B1)
手机号 wx.getPhoneNumber tt.getPhoneNumber process.env.TARO_ENV 分支
更新 wx.getUpdateManager tt.getUpdateManager(待验) 能力守卫 + 分支,缺失则跳过
未保存拦截 enableAlertBeforeUnload 待验 守卫 + 降级为页面内提示
自定义 tabBar custom: true 待验 不通过则降级原生 tabBar(D4)
自定义导航 未使用(默认导航) — 继续用默认导航,避免申请「页面结构自定义」能力
横屏 — 抖音仅竖屏 不要使用 pageOrientation
请求 / WS / 存储 / 交互 wx.* tt.* 一律走 Taro.* 统一 API

9.3 微信专属遗留项

  • wx.canIUse → Taro.canIUse,或直接用 process.env.TARO_ENV + try/catch。
  • 不再需要「构建 npm」(无 TDesign 依赖)。
  • 原生 app.wxss 里那段 miniprogram_npm/tdesign-miniprogram/icon/icon.wxss 的 base64 字体替换流程(含 doc/review.md Q-P3-3)整体作废。

10. 执行步骤(新会话按此推进)

插件工具都要传目标项目的绝对路径 projectRoot。

Phase 0 脚手架

  1. prepare(action:"check", projectRoot=.../ui/taroapp_escort) —— 已跑过:Node v24.21.0、npm 11.19.0,通过。
  2. prepare(action:"init", projectRoot=<临时目录>),例如 ui/.taroapp_init(目标目录必须不存在)。
  3. status(projectRoot=<临时目录>, operationId) 轮询到 succeeded。
  4. prepare(action:"install", projectRoot=<临时目录>) → 同样轮询成功。
  5. 把临时目录内容(含隐藏文件,除 .git 外)拷入 ui/taroapp_escort,保留其 .git(gitfile → ../../.git/modules/ui/taroapp_escort)与 README.md;删掉临时目录。
  6. 改 package.json:name: "taroapp-escort"、displayName: "暖橙陪诊"、description 写实际功能(不能留 Local miniapp 之类模板占位)。
  7. config/index.ts 设 outputRoot: \dist/${process.env.TARO_ENV}``,两端产物隔离。
  8. project.config.json 填微信 appid;project.tt.json 填抖音 appid。
  9. .gitignore 加:node_modules/、dist/、.miniapp/、.temp/、.swc/、.taro-cache/。
  10. 验证双构建:prepare(action:"build", platform:"weapp") 与 platform:"tt",各自 status 轮询成功。

Phase 1 底座(不写业务页面)

  1. src/app.scss 搬全局令牌;src/assets/ 搬字体与图片;doc/DESIGN.md 拷入。
  2. src/utils/:request / api / chatmsg / date / form / order / privacy / platform(§6 契约)。
  3. src/components/:Icon(用 t.woff)、Loading、Markdown、CustomTabBar。
  4. app.config.ts:pages 清单 + tabBar(custom: true)。
  5. 起 H5 预览:control(action:"start", projectRoot) → 立即 workbench(projectRoot)(工作台自行轮询)。H5 里登录/socket 需兜底(Taro.login/connectSocket 在 H5 不可用)。

Phase 2 页面迁移

  1. 按 §8 顺序逐页迁移。
  2. 每完成 2~3 页跑一次 weapp + tt 构建,保持双端都绿。
  3. 在 doc/MIGRATION.md 逐页打勾。

Phase 3 验证与切换

  1. 抖音真机:先配好 B3/B4,再 qrcode(action:"generate", platform:"tt") → qrcode(action:"read", operationId)。
  2. 全量回归:登录、下单、订单状态流转、就诊人 CRUD、协议、AI 对话。
  3. 抖音开发版:publish(platform:"tt", ...)(只上传开发版,不提审)。
  4. 微信切换:构建 weapp → 用微信 AppID 上传,替换原生版本;观察若干天后再归档 wxapp_escort。

11. 风险与纪律

  • R1 双份维护(最大风险):Phase 1 窗口尽量短;原生端冻结(D7);维护差异/待同步清单。
  • R2 AI 页:markdown 渲染 + socket 是最大不确定项,放最后并预留时间。
  • R3 后端阻塞:B1/B2 是硬依赖,未就绪只能占位,不要声称可用。
  • R4 自定义 tabBar:抖音支持度未知,准备好降级(D4)。
  • R5 字体:base64 内嵌字体在抖音真机需实测。
  • R6 不能照搬平台结论:§9.2 里所有「待验」都必须用 tt 构建 / 真机验证后再下结论。
  • R7 引入 React + TS 是团队技能栈变化,后续所有页面都按 TSX 写。

12. 未决事项

  • 抖音业务 appId 键命名(ttapp-escort?)与后端接口形态(appId 区分 vs 新增 platform 字段)。
  • 抖音小程序是否已创建、类目资质是否齐(B5)。
  • gitea 新仓默认分支名(其余端用 dev,建议统一 dev)。
  • 标签 phase1-native-baseline 是否推送到远端(当前仅本地)。
  • 微信侧将来是否需要保留原生工程作为回滚手段(归档 vs 删除)。

13. 工具与命令速查

插件工具(参数以此为准,projectRoot 用绝对路径):

用途 调用
环境检查 prepare(action:"check", projectRoot)
初始化 prepare(action:"init", projectRoot) → status(projectRoot, operationId)
装依赖 prepare(action:"install", projectRoot) → 同上
本地构建 prepare(action:"build", platform:"weapp"|"tt") → 同上
启预览 control(action:"start", projectRoot) → 立即 workbench(projectRoot)
重启/停止 control(action:"restart"|"stop", projectRoot)
日志 inspect(source:"compile"|"runtime"|"network")
真机二维码 qrcode(action:"generate", platform:"tt") → qrcode(action:"read", operationId)
开发版上传 publish(platform:"tt", ...)(需工作台内确认)
状态 status(projectRoot)

git(在对应仓目录执行):

# 基线标签(已完成,未推送)
cd ui/wxapp_escort && git push origin phase1-native-baseline

# 新工程首次提交(Phase 0 结束后)
cd ui/taroapp_escort && git add -A && git commit -m "chore: Taro 双端脚手架"