Files
ws_health/doc/taro-plan.md
T

260 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 底座(不写业务页面)
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 双端脚手架"
```