修复云端数据一致性问题

2026-07-29 11:03:44 +08:00
parent a3dd080b6f
commit 17727ab1dd
12 changed files with 389 additions and 41 deletions
@@ -0,0 +1,48 @@
+# 云端数据正确性修复设计
+
+## 目标
+
+修复排行榜快照无法显示本人信息、清除数据不彻底、TTS 服务端缓存失效及排行榜列表 key 无效四项问题。保持排行榜快照的低延迟特性，不向客户端公开其他用户的 openid。
+
+## 范围
+
+包含：
+
+1. 排行榜快照请求的本人排名与高亮。
+2. 云端训练数据的全量删除。
+3. TTS 缓存文档的正确读取。
+4. 排行榜 WXML 的稳定列表 key。
+5. Node 回归测试。
+
+不包含：排行榜防作弊、数据模型重构、云函数部署配置文档。
+
+## 设计
+
+### 排行榜
+
+定时任务继续写入不包含原始 openid 的公开快照。每个榜单项会保存仅供云函数匹配的 SHA-256 `memberKey`（由 openid 生成），用户请求命中快照时用当前调用者的 openid 生成同样的指纹，从而准确定位其榜单项并返回 `myEntry`。`memberKey` 在返回客户端前剥离，不在页面数据和本地缓存中保存。若用户未进入快照上限，返回空 `myEntry`，避免将完整榜单或其他用户标识暴露给客户端。
+
+实时强刷路径保留现有全量计算逻辑，但返回数据与快照路径保持一致。榜单列表项以 `rank` 作为 WXML 的稳定 key。
+
+### 清除数据
+
+`clearAll()` 在已获取当前 openid 后，以游标或分页方式查询该 openid 的全部 `plank_data` 文档并逐一删除。任一单条删除失败会被记录并抛出，使调用页不显示“已清除”的错误成功状态；本地数据仍按现有流程清除。
+
+### TTS 缓存
+
+`doc(cacheKey).get()` 的 `data` 是单文档对象。缓存读取改为直接读取 `data.fileID`，并继续保留文件不存在时重新合成的降级路径。
+
+## 错误处理
+
+- 快照或本人文档不可用时，排行榜继续降级至现有实时计算或本地展示路径。
+- 无法获取 openid 时不尝试跨用户删除；清除操作返回失败。
+- 删除任一云端文档失败时，不伪造成功反馈。
+- TTS 缓存缺失或失效时才重新合成。
+
+## 验收标准
+
+1. 快照命中时，榜内用户可被高亮；榜外用户可获得其个人排名（前提是快照包含其名次）。
+2. 同一 openid 的多份云端文档均会被删除，之后重启不会恢复旧训练数据。
+3. 未提供客户端 fileID 时，已有 `tts_cache` 文档会返回缓存文件，而非重新合成。
+4. 排行榜循环不再引用不存在的 `openid` key。
+5. 新增回归测试能先复现并验证上述行为。