gengxin

TUICallKit-Vue3/docs/TANG-DETECTIVE-COS.md

@@ -0,0 +1,56 @@
+# 唐侦探素材 COS 迁移
+
+## 当前状态（2026-09-08）
+
+**尚未上传，也没有切换真实 COS 地址。** 数据库端口可达，但其 TLS 自签名证书不受 Node.js 默认信任库、项目 `server/public/cacert.pem` 或本机系统信任库信任。没有关闭证书/主机名校验，没有读取到 COS 密钥，没有执行任何 COS 写操作，也没有改数据库或桶权限。
+
+需提供配置数据库的可信 CA 证书文件路径，或已授权可用的 SSH 连接名；不要把数据库密码、COS 密钥或登录 token 发到聊天、清单或前端文件中。自签名证书不等于一定存在安全问题，但不能把“能连通”当成“身份已验证”。
+
+473 个原字节快照文件中：160 个 JPG、44 个 MP3、0 个视频，共 204 个原路径、24,052,082 字节，按内容与扩展名去重后为 180 个对象。此次范围为实际迁入游戏的媒体，不包括源码外的草稿、试听实验或重新生成素材。原目录与 `native/tang-detective/` 均保留。
+
+## 上传与校验
+
+独立工具位于 `scripts/tang-cos/`，不会加入小程序运行时。使用 Node.js 22 或更新版本，在前端根目录运行：
+
+```sh
+npm ci --prefix scripts/tang-cos --ignore-scripts --no-audit --no-fund
+node scripts/tang-cos/upload.mjs inventory
+node --test scripts/tang-cos/upload.test.mjs
+```
+
+在得到服务器管理员提供的可信 CA 文件后，将 `TANG_DB_CA_FILE` 设为该文件路径；若证书已受系统信任，可用 Node.js 的 `--use-system-ca`。不得把抓取到的陌生对端证书直接设为信任根。工具始终启用证书链和主机名校验。
+
+```sh
+node scripts/tang-cos/upload.mjs inspect
+node scripts/tang-cos/upload.mjs upload
+```
+
+`inspect` 只通过只读 SQL 查询 `server/config/database.php` 配置的 `${prefix}config` 表中 `storage/default`、`storage/qcloud` 两项。仅输出目标桶、地域、公开域名和凭据存在状态，不输出数据库连接秘密或 COS 密钥。当前没有 `server/.env`；若以后新增，工具会停止而非猜测 PHP 环境解析规则，应在原生服务器运行环境中确认配置读取方式。
+
+`upload` 使用腾讯官方 `cos-nodejs-sdk-v5`，只执行逐对象 HEAD/PUT，不经过会写文件表的后台上传接口。每个对象键为：
+
+```text
+tang-detective/season-01/media-v1/<完整SHA256>.<原扩展名>
+```
+
+上传前核验所有快照文件；已有对象必须大小及 SHA-256 元数据相符，否则停止。PUT 使用 MD5 传输校验、SHA-256 元数据及禁止覆盖请求头，不设置 ACL、不删除对象。内容寻址降低误覆盖风险；禁止覆盖请求头不能替代已有对象检查。
+
+每个对象上传后必须通过**无凭据的精确 HTTPS 地址**完整下载，核对大小、SHA-256 和媒体类型；音频/视频还检查 `Range` 分段读取。首个对象无法公开读取便停止，绝不自动把桶改为公开。此时最多留下首个已写入对象，由回执记录，工具不自动删除。
+
+只有全部对象成功后才生成 `build/tang-detective-cos-manifest.json`，一一保留 204 个原路径映射。该文件不存在时构建继续使用本地媒体；不得手写虚假成功清单。逐对象上传/复用及验证证据写入 `build/tang-detective-cos-upload-receipt.json`；每次显式上传均有独立运行ID，旧回执保留到 `build/tang-detective-cos-upload-attempts/`。前置配置失败也记录为本次失败，不能借用上次成功结论。PUT 发出前持久化 `unknown`，响应不确定时做只读复查，未能确认则保持未知，不写成“确定未上传”。工具错误只输出脱敏错误码，不输出签名 URL 或原始 SDK 错误。数据库建连、查询和关闭分别有8秒、8秒、2秒截止时间，超时仅销毁本任务连接。
+
+## 后续验收边界
+
+本轮已执行的本地验证：
+
+- `npm run test:tang`：72/72通过（既有44项、远程素材13项、上传工具15项）；远程测试只用独占临时目录中的模拟地址与响应。
+- 微信生产构建、H5生产构建均退出0；未启动网页预览或开发服务。
+- 实际微信产物校验通过：24页、204媒体、`mediaMode: local`。原始文件总量32,595,927字节、主包3,157,378字节，和原本地模式一致；**不能把模拟远程输出的节省量说成实际包体积已解决**。
+- 本机微信编译器检查24页WXML/WXSS通过；不等于模拟器交互或真机运行。
+- 原来源和迁入快照各473文件逐项SHA-256复核，无漂移。
+- 默认本地模式以及模拟远程模式的相对模块依赖检查均通过；远程模式覆盖120页原图哈希、112正式/8临时层级、8段第一回试听状态、断网图片最终文字回退、迟到事件、分享坏缓存和输出符号链接保护。
+- 真实COS上传、无凭据远程下载、真实音频Range和微信合法域名尚未验证；没有真实启用清单或上传回执。
+
+完整下载哈希证明文件传输一致，不代表声音已获听审、商用/克隆授权、医学审核或微信真机通过。第一回内部试听与未配置的后续整页音频审核状态均不得因上传而提升。
+
+完成真实上传、地址切换和构建后，仍需核对微信后台的请求/下载合法域名及对应 HTTPS 证书，实测首屏、翻页、分享、试听、后台暂停和断网回退。此次未修改微信后台配置，也未部署服务器或发布小程序。

TUICallKit-Vue3/docs/TANG-DETECTIVE-DEVTOOLS-CHECK-20260908.md

@@ -0,0 +1,39 @@
+# 唐侦探微信开发者工具检查
+
+日期：2026-09-08。结论：前端宿主可启动，但服务端阅读接口检查未通过，不能认定完整接入可用。
+
+## 实际观察
+
+- 微信开发者工具 RC 2.02.2607171；迁移项目运行日志标注基础库 3.17.2。
+- 当前项目路径：`/Users/dagedagededagege/Pictures/xuetang/TUICallKit-Vue3/dist/build/mp-weixin`。
+- 实际模拟器显示 `pages/index/index` 的宿主首页。
+- 控制台两次读取均可见：
+  - `GET https://admin.zhenyangtang.com.cn/api/tang/catalog 404`
+  - `GET https://admin.zhenyangtang.com.cn/api/tang/progress 404`
+- 这些证据说明当时配置地址上的章节目录和阅读存档请求失败；仅凭404不能区分未部署、路由失效、代理转发或地址指向错误。没有因此修改服务器或部署代码。
+
+## 操作与证据边界
+
+主Agent先识别出原先打开的是 `Work/TUICallKit-Vue3/zyt-migration/...` 的旧三消项目，再经导入对话框选中本次迁移目录。在准备隔离测试副本期间，工具报告用户改变了应用状态；重新读取发现用户已将原迁移项目打开并操作。主Agent没有点击该导入对话框的“创建”，没有把用户后续操作记为自己完成的测试。
+
+因此，本轮已核实的是正确项目的实际界面与失败请求；不是主Agent完成了一遍《唐侦探》玩法流程。入口、C01/C15翻页、试听播放/暂停、退出后声音停止、真机及云端保存均没有本轮完整通过证据。
+
+只读源码核对发现宿主启动可能自动登录，返回学堂还可能关联健康上下文；不能直接把同AppID的新目录当作独立游客。主Agent准备过独立临时副本：原app入口字节保留，前置内存存储和业务请求阻断。代码审查在假wx环境中验证了15种替换失败均会阻止宿主执行，但副本**没有导入开发者工具运行**，不能用这项检查冒充模拟器测试或全包沙箱认证。
+
+本轮没有修改产品源码、没有清理用户存储、没有主动提交健康资料或执行上传/发布。用户打开的原项目可能已自动发起其他请求；本轮没有审计其全部请求及副作用，不声称该原项目全程离线。
+
+## 当时产物标识
+
+| 文件 | SHA-256 |
+| --- | --- |
+| `app.js` | `1161a9f9dab28d3ae592e3b13bcdf3ffaf81a214e2d7e751d7003c143865e66c` |
+| `app.json` | `bd6aa0028069fd2b0801681e2e62ab8faf3ddc9544ea5375e8f7db5c33e6c92e` |
+| `tang-detective/.native-import-state.json` | `8518b430dbe156a19a6dd317034e8935090e7be805337ab35c29c944f5721b32` |
+
+## 下一步
+
+先由具备权限的执行者确认当前域名的服务端部署及路由，使两个GET接口返回契约规定的响应，再在独立测试账号下验证保存接口、完整页面路径和试听。COS仍未上传，不应把当前本地媒体表现当作云端媒体通过。
+
+实际专业Agent：微信开发专业Agent核对测试路线与自动写入边界；代码审查专业Agent复核临时隔离代码。未启动其他专业Agent。
+
+资源：临时副本未运行，收尾删除该任务独占副本；原素材与产物保留。现有旧项目以及用户新打开的迁移项目窗口均保留，没有关闭用户工作窗口。本轮没有启动播放器、开发服务或常驻后台进程。

TUICallKit-Vue3/docs/TANG-DETECTIVE-INTEGRATION.md

@@ -0,0 +1,78 @@
+# 唐侦探接入学堂：本地实现与交接
+
+日期：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、本地构建结果和交接文件保留。没有打开浏览器、播放器或本地服务；用户已有应用与服务未触碰。