260 lines
16 KiB
Markdown
260 lines
16 KiB
Markdown
# 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 双端脚手架"
|
||
```
|