optimize puzzle gallery access

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -84,14 +84,19 @@ npm run check:server-rs-ddd
 
 ## SpacetimeDB schema 变更规则
 
-1. 任何 table、reducer、procedure、row shape 或 bindings 变化，都必须同步 `server-rs/crates/spacetime-module/src/migration.rs`、本文件表目录和生成绑定。
+1. 任何 table、view、reducer、procedure、row shape 或 bindings 变化，都必须同步本文件表 / view 目录和生成绑定；真实 table 变化还必须同步 `server-rs/crates/spacetime-module/src/migration.rs`，view 属于派生投影，不写入迁移导入导出表清单。
 2. 已有表新增字段必须放在 Rust 表结构体最后，并设置明确 `#[default(...)]`。
 3. 删除字段、改名、重排字段、改类型或修改字段属性前，必须先询问用户并确认迁移计划。
 4. Vec 字段不要直接写无法 const 求值的 default；需要默认空集合时优先使用 `Option<Vec<T>>` 加 `#[default(None::<Vec<T>>)]`，业务层归一为空数组。
-5. 修改后运行：
+5. 运行态读表必须按已声明索引访问。只要 table 上存在覆盖查询前缀的 `#[index(...)]` 或主键 / unique accessor，列表、详情、快照组装和计数都先用对应 accessor `.filter(...)` / `.find(...)`，再在内存中处理索引无法覆盖的残余条件；不得用 `.iter().filter(...)` 扫整表替代现成索引。
+6. 面向公开列表的只读投影优先做成 public view，并由 `api-server` 的 `spacetime-client` 长期订阅后读本地 cache。不要让 HTTP 列表接口每次请求都调用 procedure 重新组装全量列表；需要请求时间窗口的轻量统计可订阅公开统计表后在 `api-server` 本地聚合，需要写入副作用的详情、点赞、游玩记录仍可走 procedure / reducer。
+7. 多列索引按 SpacetimeDB 绑定生成的元组参数直接传入，例如 `.filter((source_type, profile_id, played_day))`；前缀查询只传前缀元组，例如 `.filter((scope_kind, scope_id.as_str()))`。不要为了绕过类型问题退回整表遍历。
+8. procedure result 必须返回 typed snapshot / typed value。`spacetime-client` mapper 不得再通过 `row_json/session_json/work_json/items_json/run_json/event_json/feedback_json: Option<String>` 做跨层 JSON 字符串传输，也不得在 mapper 里反序列化旧 `*JsonRecord` 兼容结构。业务内部持久化字段如 `profile_payload_json`、`levels_json` 等不属于 procedure result 载荷例外，仍按各自表契约处理。
+9. 修改后运行：
 
 ```bash
 npm run spacetime:generate
+npm run check:spacetime-runtime-access
 npm run check:spacetime-schema
 npm run check:server-rs-ddd
 ```
@@ -460,6 +465,13 @@ npm run check:server-rs-ddd
 - Rust 结构体：`PuzzleWorkProfileRow`
 - 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
 
+### `puzzle_gallery_view`
+
+- Rust view：`puzzle_gallery_view`
+- 返回类型：`Vec<PuzzleWorkProfile>`
+- 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
+- 说明：拼图广场公开列表投影，只暴露 `publication_status = Published` 的作品；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM puzzle_gallery_view` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'puzzle'` 后，从本地 cache 构造 `/api/runtime/puzzle/gallery` 响应，并在本地按当前请求时间聚合 `recentPlayCount7d`，不再每个 HTTP 请求调用 `list_puzzle_gallery` procedure。
+
 ### `quest_log`
 
 - Rust 结构体：`QuestLog`