optimize puzzle gallery access

.hermes/shared-memory/pitfalls.md

@@ -83,6 +83,22 @@
 - 验证：运行仓库已有编码检查；人工抽查修改文件中的中文内容。
 - 关联：`AGENTS.md`、`npm run check:encoding`。
 
+## SpacetimeDB 运行态查询不要绕过已有索引或用 procedure JSON 回传
+
+- 现象：运行态接口看起来只查当前用户、作品或任务，却在 `spacetime-module` 中使用 `ctx.db.<table>().iter().filter(...)` 整表遍历；或者 procedure result 返回 `items_json/run_json/work_json` 等 JSON 字符串，`spacetime-client` mapper 再反序列化成旧兼容结构。
+- 原因：新增索引或 typed snapshot 后，没有同步清理旧 mapper / 测试兼容层，也没有用静态检查拦截回退写法。
+- 处理：表上已有主键、unique 或 `#[index]` 覆盖查询前缀时，先用对应 accessor `.find(...)` / `.filter(...)`，只对索引无法覆盖的条件做内存残余过滤；procedure result 返回 typed snapshot / typed value，不再跨层传 `*_json: Option<String>` 作为 payload。
+- 验证：执行 `npm run check:spacetime-runtime-access`、`npm run check:server-rs-ddd`，涉及绑定变化时先执行 `npm run spacetime:generate` 和 `npm run check:spacetime-schema`。
+- 关联：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`scripts/check-spacetime-runtime-access.mjs`、`server-rs/crates/spacetime-module/src/*`、`server-rs/crates/spacetime-client/src/mapper.rs`。
+
+## 拼图广场列表不要每次 HTTP 请求调用 SpacetimeDB procedure
+
+- 现象：`/api/runtime/puzzle/gallery` 每个请求都走 `spacetime-client.list_puzzle_gallery()` 调用 SpacetimeDB procedure，导致 SpacetimeDB WASM 侧重复组装全量列表，客户端再映射一遍；历史实现还出现过 procedure JSON 字符串往返。
+- 原因：`api-server` 的服务器端 `spacetime-client` 没有订阅可公开读取的 gallery 投影，虽然 SDK 支持 client cache，但请求路径仍把列表读取当作 procedure 调用。
+- 处理：`spacetime-module` 中用 public view `puzzle_gallery_view` 暴露已发布拼图作品；`spacetime-client` 建连接后订阅 `SELECT * FROM puzzle_gallery_view` 和 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'puzzle'` 并等待 `on_applied`，HTTP gallery 只从 `connection.db().puzzle_gallery_view().iter()` 本地 cache 读取和排序，再用已同步的 `public_work_play_daily_stat` 在本地聚合 7 日播放数。旧 `list_puzzle_gallery` procedure 只作兼容，不再作为 HTTP gallery 主路径。
+- 验证：搜索 `server-rs/crates/spacetime-client/src/puzzle.rs` 不应再出现 gallery 主路径调用 `list_puzzle_gallery_then`；执行 `cargo check --manifest-path server-rs/Cargo.toml -p spacetime-client`、`cargo check --manifest-path server-rs/Cargo.toml -p api-server` 和 schema/runtime access 检查。
+- 关联：`server-rs/crates/spacetime-module/src/puzzle.rs`、`server-rs/crates/spacetime-client/src/lib.rs`、`server-rs/crates/spacetime-client/src/puzzle.rs`、`/api/runtime/puzzle/gallery`。
+
 ## 忘记密码后仍提示手机号或密码错误先查认证快照同步
 
 - 现象：用户通过“忘记密码”重设密码后，接口返回成功或页面进入登录态，但再次使用新密码登录仍提示“手机号或密码错误”；重启后还可能出现 `Bearer JWT 版本已失效`，日志里的 token version 与本地快照不一致。