79 lines
6.8 KiB
Markdown
79 lines
6.8 KiB
Markdown
# 唐侦探接入学堂：本地实现与交接
|
||
|
||
日期：2026-09-08。目标仓库为 `Pictures/xuetang`，前端 `TUICallKit-Vue3`，后端 `server`。
|
||
|
||
已完成本地代码接入。**尚不是已部署、可上传或真机验收通过的版本**：全量素材保留后包体积仍需处理；数据库迁移、真实接口联调和真机体验未执行。
|
||
|
||
COS 素材迁移补充见 [TANG-DETECTIVE-COS.md](TANG-DETECTIVE-COS.md)：现已核齐204个媒体原路径，但配置数据库证书验证未通过，真实上传和地址切换尚未执行。下面的本地包体积/测试数据为迁移接入基线，不应当作远程素材模式的验收结果。
|
||
|
||
## 入口与保留内容
|
||
|
||
血糖管理页 `tongji/pages/weekly.vue` 增加《唐侦探》图标卡片，与现有《识糖小课堂》三消并列。点击经 `tongji/tang-detective/index.vue` 进入原生横屏故事；游戏首页增加“返回学堂”和阅读存档状态。入口沿用宿主图标、绿色卡片和文字层级，不改三消、血糖记录、通话或登录流程。
|
||
|
||
保留原十五回、六个主页面、十五个章节页面、三个音频播放器，共24页及18个原生分包；图片和音频原字节复制，不生成或重新编码。
|
||
|
||
原来源：`/Users/dagedagededagege/Documents/Codex/2026-07-22/new-chat/wechat-miniprogram/miniprogram`。原目录未修改。473文件快照在 `native/tang-detective/`，SHA-256清单在 `build/tang-detective-source-manifest.json`。不导入旧 `app.js`、私有工程配置或凭据；原 `app.json` 仅作为构建元数据。迁移修改均在构建插件和 `native-adapter/tang-detective/` 中完成。
|
||
|
||
H5可构建并显示明确的微信运行提示，**没有把原生游戏转换成网页可玩版本**。原配音的人工审核和远程音频配置状态保持不变；不能把迁移当作试听、授权或发布验收。
|
||
|
||
## 接口与存档
|
||
|
||
三个独立接口使用现有 `token` 请求头：
|
||
|
||
| 方法 | 路径 | 用途 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/tang/catalog` | 十五回合法章节、事件、页码、卡片目录 |
|
||
| GET | `/api/tang/progress` | 当前登录用户的阅读存档 |
|
||
| POST | `/api/tang/saveProgress` | 修订匹配的替换/重置、幂等确认 |
|
||
|
||
前端和宿主共用 `config/api.js` 的 `API_BASE_URL`；原生构建生成独立的只含公开地址的 `utils/platformConfig.js`。需要调试另一套服务器时修改该公开地址并重建；不要在文件内写token或密钥。当前默认地址沿用宿主配置，本轮未请求该地址。
|
||
|
||
存档桥仅上传白名单ID、已完成事件、当前页和修订；不上传健康回答、正文快照、音频、偏好、患者信息或账号凭据。后端新增独立用户存档表，不写三消排行榜。
|
||
|
||
游客记录仅留本机，不自动转到登录账号。服务端确认用户ID后隔离本机存档；token指纹只用于本机身份映射，不保存另一份token。续签同一账号可恢复其本机待同步队列。旧账号页面回调不能写入新账号存档。原版旧存储键保留、不自动导入。
|
||
|
||
断网保留本机进度；保存请求串行、600ms合并，超时8秒。超时重试复用原请求ID和正文。发生版本/故事代次冲突时暂停自动覆盖，首页点击存档状态选择云端或本机，确认前保留可恢复的本机备份。重置保留收藏，服务端递增故事代次。永久契约错误不在页面切换时自动重试。
|
||
|
||
后端完整契约、错误码和验证边界见 `../server/docs/tang-detective-progress.md`（从仓库根：`server/docs/tang-detective-progress.md`），机器契约为 `server/docs/tang-detective.openapi.yaml`。
|
||
|
||
## 怎样运行
|
||
|
||
在前端目录执行：
|
||
|
||
```sh
|
||
npm ci --ignore-scripts --no-audit --no-fund
|
||
# 仅首次、TUICallKit尚不存在时，按项目原README准备SDK：
|
||
test -e TUICallKit || cp -R node_modules/@trtc/calls-uikit-wx-uniapp TUICallKit
|
||
test -f static/RTCCallEngine.wasm.br || cp node_modules/@trtc/call-engine-lite-wx/RTCCallEngine.wasm.br static/RTCCallEngine.wasm.br
|
||
npm run test:tang
|
||
npm run build:mp-weixin
|
||
npm run check:tang-output
|
||
node scripts/check-tang-native-compiler.cjs
|
||
```
|
||
|
||
原生编译检查使用本机已安装的微信开发者工具内 `wcc`/`wcsc`，不打开应用、不上传、不播放。其他机器可通过 `TANG_WECHAT_COMPILER_DIR` 指向其编译器目录。
|
||
|
||
微信产物为 `dist/build/mp-weixin`。使用微信开发者工具打开该目录进行后续模拟器/真机检查；本轮没有自动打开用户已有工具窗口。调试构建仍用原项目 `npm run dev:mp-weixin`，开发监听及工具窗口由启动者负责关闭。
|
||
|
||
后端部署前由有权限的人核对数据库前缀、备份及运行环境，再审阅 `server/sql/1.9.20260908/add_tang_detective_progress.sql`；该脚本本轮未执行。先具备表和接口，再验证真实登录同步。不要运行现有三消上报接口来验证唐侦探。
|
||
|
||
## 实测与缺口
|
||
|
||
- 微信生产构建、H5生产构建：退出码0。
|
||
- `npm run test:tang` 共44项通过：7项导入测试、27项存档桥/基础生命周期测试、10项加载真实章节与播放器的生命周期回归；不访问真实API或数据库。
|
||
- 产物校验：24页、204份媒体、328个相对模块依赖；473份源快照与原目录哈希无漂移。
|
||
- 本机微信编译器：24页WXML、WXSS编译退出码0，无诊断输出。只证明本机编译语法，不证明页面交互/设备表现。
|
||
- 后端15章、60事件、120页、15卡ID逐项核对通过；OpenAPI YAML解析通过。
|
||
- 两份PHP契约脚本已写，因本机没有PHP运行时而**未执行**；也没有真实MySQL、HTTP中间件、并发数据库或线上联调证据。
|
||
- 未做模拟器交互、横屏小屏布局、真机、音频试听、目标老人/医生审核、上传或公开发布。
|
||
|
||
独立代码审查发现并复核闭环了5项迁移问题：离线重置后的新阅读保护、卸载资源清理、旧账号确认回调隔离、队列落盘失败后的恢复、播放器延迟初始化生命周期。复核仍限本地代码与模拟平台接口，不升级为真机或服务器验收。
|
||
|
||
当前原始文件主包3,157,378字节、总包32,595,927字节（约3.16MB和32.60MB，非微信上传压缩体积）。精确分包数据与哈希见 `build/tang-detective-native-validation.json`。**不得直接宣称可上传**；需要后续分包/受控静态资源托管方案及真实包分析，不应靠删除章节、改画质或关闭检查掩盖问题。
|
||
|
||
## 回退与资源
|
||
|
||
要停用入口，可回退本次入口/路由/构建插件接入；不要删除原项目、用户存档或新增存档表。保留快照和适配层便于逐项比较。没有提交或推送Git，没有部署服务器。
|
||
|
||
本任务的构建/测试/原生编译子进程均结束；测试临时目录已清理。依赖、SDK、本地构建结果和交接文件保留。没有打开浏览器、播放器或本地服务；用户已有应用与服务未触碰。
|