# 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_' }`。 - 断线自动重连:最多 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 底座(不写业务页面) 11. `src/app.scss` 搬全局令牌;`src/assets/` 搬字体与图片;`doc/DESIGN.md` 拷入。 12. `src/utils/`:`request` / `api` / `chatmsg` / `date` / `form` / `order` / `privacy` / `platform`(§6 契约)。 13. `src/components/`:`Icon`(用 t.woff)、`Loading`、`Markdown`、`CustomTabBar`。 14. `app.config.ts`:pages 清单 + tabBar(`custom: true`)。 15. 起 H5 预览:`control(action:"start", projectRoot)` → 立即 `workbench(projectRoot)`(工作台自行轮询)。H5 里登录/socket 需兜底(`Taro.login`/`connectSocket` 在 H5 不可用)。 ### Phase 2 页面迁移 16. 按 §8 顺序逐页迁移。 17. 每完成 2~3 页跑一次 `weapp` + `tt` 构建,保持双端都绿。 18. 在 `doc/MIGRATION.md` 逐页打勾。 ### Phase 3 验证与切换 19. 抖音真机:先配好 B3/B4,再 `qrcode(action:"generate", platform:"tt")` → `qrcode(action:"read", operationId)`。 20. 全量回归:登录、下单、订单状态流转、就诊人 CRUD、协议、AI 对话。 21. 抖音开发版:`publish(platform:"tt", ...)`(只上传开发版,不提审)。 22. 微信切换:构建 `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(在对应仓目录执行): ```sh # 基线标签(已完成,未推送) cd ui/wxapp_escort && git push origin phase1-native-baseline # 新工程首次提交(Phase 0 结束后) cd ui/taroapp_escort && git add -A && git commit -m "chore: Taro 双端脚手架" ```