16 KiB
16 KiB
taroapp_escort 双端改造方案(微信 weapp + 抖音 tt)
本文是新会话的唯一执行依据。开工前先读 §2 决策、§6 契约、§9 阻塞项。 基线:
ui/wxapp_escort标签phase1-native-baseline(commitaeafe21,分支dev,工作区干净) 目标:ui/taroapp_escort(已作为 submodule 挂在父仓库,当前只有README.md+.gitgitfile)
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的 tabBarlist仍需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.mdQ-P3-3)整体作废。
10. 执行步骤(新会话按此推进)
插件工具都要传目标项目的绝对路径 projectRoot。
Phase 0 脚手架
prepare(action:"check", projectRoot=.../ui/taroapp_escort)—— 已跑过:Node v24.21.0、npm 11.19.0,通过。prepare(action:"init", projectRoot=<临时目录>),例如ui/.taroapp_init(目标目录必须不存在)。status(projectRoot=<临时目录>, operationId)轮询到succeeded。prepare(action:"install", projectRoot=<临时目录>)→ 同样轮询成功。- 把临时目录内容(含隐藏文件,除
.git外)拷入ui/taroapp_escort,保留其.git(gitfile →../../.git/modules/ui/taroapp_escort)与README.md;删掉临时目录。 - 改
package.json:name: "taroapp-escort"、displayName: "暖橙陪诊"、description写实际功能(不能留Local miniapp之类模板占位)。 config/index.ts设outputRoot: \dist/${process.env.TARO_ENV}``,两端产物隔离。project.config.json填微信 appid;project.tt.json填抖音 appid。.gitignore加:node_modules/、dist/、.miniapp/、.temp/、.swc/、.taro-cache/。- 验证双构建:
prepare(action:"build", platform:"weapp")与platform:"tt",各自status轮询成功。
Phase 1 底座(不写业务页面)
src/app.scss搬全局令牌;src/assets/搬字体与图片;doc/DESIGN.md拷入。src/utils/:request/api/chatmsg/date/form/order/privacy/platform(§6 契约)。src/components/:Icon(用 t.woff)、Loading、Markdown、CustomTabBar。app.config.ts:pages 清单 + tabBar(custom: true)。- 起 H5 预览:
control(action:"start", projectRoot)→ 立即workbench(projectRoot)(工作台自行轮询)。H5 里登录/socket 需兜底(Taro.login/connectSocket在 H5 不可用)。
Phase 2 页面迁移
- 按 §8 顺序逐页迁移。
- 每完成 2~3 页跑一次
weapp+tt构建,保持双端都绿。 - 在
doc/MIGRATION.md逐页打勾。
Phase 3 验证与切换
- 抖音真机:先配好 B3/B4,再
qrcode(action:"generate", platform:"tt")→qrcode(action:"read", operationId)。 - 全量回归:登录、下单、订单状态流转、就诊人 CRUD、协议、AI 对话。
- 抖音开发版:
publish(platform:"tt", ...)(只上传开发版,不提审)。 - 微信切换:构建
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 双端脚手架"