推进 SpacetimeDB adapter 与 client 收口

2026-04-29 16:53:54 +08:00
parent f82775b852
commit 62934b0809
17 changed files with 1023 additions and 597 deletions
--- a/docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md
+++ b/docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md
@@ -166,7 +166,7 @@ LLM、OSS、SMS、微信等外部副作用可以独立准备，不等待 `WP-SC`
 | WP-RT Runtime/Profile/Save | G1 后 | `module-runtime`、`spacetime-module/src/runtime/*`、runtime/save/profile API | RPG story 规则 | runtime setting、snapshot、wallet、played world、save archive 领域化 | `cargo test -p module-runtime`，runtime API 测试 |
 | WP-RPG Gameplay 域 | G1 后 | `module-combat`、`module-inventory`、`module-npc`、`module-progression`、`module-quest`、`module-runtime-item`、`module-story` | 创作域 | 战斗、背包、NPC、成长、任务、宝箱、story session 纯规则与跨域事件 | 各 module 测试；跨域应用结果测试 |
 | WP-RS Runtime Story 去兼容层 | G1 后 | `module-runtime-story`、`api-server/src/runtime_story/*`、`src/hooks/rpg-runtime-story/*` | 非 RPG 创作域 | 先将历史 `module-runtime-story-compat` 迁为新主链 crate，再删除 HTTP compat 层、接 session scoped 新接口、前端匹配新接口 | `cargo test -p module-runtime-story`，runtime story/API/前端定向测试 |
-| WP-ST SpacetimeDB Adapter | 领域任务输出稳定后 | `spacetime-module/src/**`、`migration.rs`、表目录 | `api-server` 业务逻辑 | table/reducer/procedure/mapper/queries 按上下文接入领域函数；必要 event/projection table；`lib.rs/migration.rs/表目录` 单 owner 合流 | `cargo check -p spacetime-module`，需要时 `spacetime build/generate` |
+| WP-ST SpacetimeDB Adapter | 领域任务输出稳定后 | `spacetime-module/src/**`、`migration.rs`、表目录 | `api-server` 业务逻辑 | table/reducer/procedure/mapper/queries 按上下文接入领域函数；必要 event/projection table；`lib.rs/migration.rs/表目录` 单 owner 合流；已完成 AI task event、Big Fish readiness event、Asset row mapper、Puzzle publish event | `cargo check -p spacetime-module`，需要时 `spacetime build/generate` |
 | WP-SC Spacetime Client | 对应 WP-ST facade 稳定后 | `spacetime-client/src/**`、绑定 mapper | 领域规则、未稳定 facade 的预判接线 | typed facade、错误映射、row snapshot mapper | `cargo check -p spacetime-client` |
 | WP-PF platform side effects | G1 后可独立准备；接入 API 前与 WP-API 对齐错误模型 | `platform-*`、`api-server` platform 接线 | 领域状态机 | LLM、OSS、SMS、微信等副作用统一 adapter | platform crate 测试或 API smoke |
 | WP-API api-server BFF | WP-SC facade 和 WP-PF 接口稳定后 | `api-server/src/**`，其中 `app.rs` 单 owner | SpacetimeDB table 定义、领域主规则、绕过 spacetime-client 的直连实现 | 路由、鉴权、SSE、请求响应映射、平台编排收口 | `cargo test -p api-server`，`cargo check -p api-server` |
@@ -755,6 +755,44 @@ npm.cmd run check:encoding -- docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_202
 1. `runtime`、`puzzle`、`custom_world` facade 仍有较多重复 SDK 错误映射，可继续按同一方式机械收口。
 2. mapper 中仍有部分历史 `Procedure(...)` 构造和旧兼容 JSON 容错逻辑，后续应结合对应工作包逐步替换，避免一次大改影响面过宽。

+### 2026-04-29 WP-SC 错误映射第三批收口
+
+已完成：
+
+1. 继续把剩余大块 facade 中的 SDK 调用错误统一收口为 `SpacetimeClientError::from_sdk_error`。
+2. 本批覆盖：
+   - `runtime`
+   - `puzzle`
+   - `custom_world`
+3. 本批只替换重复 SDK 错误映射，不改变 procedure 名称、输入构造、返回 mapper 或调用顺序。
+4. 发现 PowerShell 写回 Rust 文件会给首行插入 UTF-8 BOM 后，已用局部补丁清理，避免破坏编码约束。
+
+当前 `spacetime-client/src/*.rs` facade 中已不再保留重复的 `.map_err(|error| SpacetimeClientError::Procedure(error.to_string()))` 模式。
+
+待继续：
+
+1. mapper 中仍有部分历史 `Procedure(...)` 构造，可按领域继续渐进收口。
+2. 后续新增 `WP-ST` facade 后，需要继续补 typed facade 与 row snapshot mapper。
+
+### 2026-04-29 WP-SC mapper 错误映射收尾
+
+已完成：
+
+1. 继续收口 `spacetime-client/src/mapper.rs` 中稳定 procedure result 的重复错误构造。
+2. 将 runtime settings、profile dashboard、wallet ledger、recharge、referral、reward、redeem code、play stats、runtime snapshot、save archive 的 `ok=false` 与缺快照分支统一到：
+   - `SpacetimeClientError::procedure_failed`
+   - `SpacetimeClientError::missing_snapshot`
+3. 将 custom world、puzzle 既有稳定 result mapper 的 procedure 失败与缺返回数据分支统一到同一 helper。
+4. 修复 auth store snapshot import mapper 中两处历史乱码错误文案，恢复为明确中文语义：`认证快照导入结果`。
+5. 保留 `custom_world_profile 不存在` 这类领域语义错误，不强行改成缺快照错误。
+
+当前结论：
+
+1. `spacetime-client/src/*.rs` facade 中已不再保留重复的 `.map_err(|error| SpacetimeClientError::Procedure(error.to_string()))` 模式。
+2. `spacetime-client/src/mapper.rs` 中仅保留需要领域语义表达的 `Procedure(...)` 构造。
+3. 本次未修改 `spacetime-module`、`migration.rs`、生成绑定、`api-server` 路由或前端。
+4. `WP-SC` 当前基础设施收口已完成；后续只在 `WP-ST` 新 facade 或 row shape 稳定后，按领域补 typed facade 与 row snapshot mapper。
+
 ### 2026-04-29 WP-ST AI Task 事件 Adapter 切片

 已完成：
@@ -851,6 +889,22 @@ npm.cmd run check:encoding -- docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_202

 结果：通过。`cargo check -p api-server` 仍有既有 `api-server/src/prompt/rpg/runtime_chat.rs` 未使用 prompt helper warning，非本次新增。

+后端启动：
+
+```powershell
+npm.cmd run api-server:maincloud
+```
+
+结果：已执行。命令在 90 秒观察窗口内超时，因为 `cargo run` 前台常驻且本轮编译较慢；继续等待后确认 `127.0.0.1:3100` 已由本仓库 `server-rs/target/debug/api-server.exe` 监听。`GET /healthz` 返回 `200`，`GET /api/story/battles/battle_001` 未登录返回 `401`，`GET /api/story/sessions/storysess_001/runtime-projection` 未登录返回 `401`。
+
+后端启动：
+
+```powershell
+npm.cmd run api-server:maincloud
+```
+
+结果：命令在 60 秒观察窗口内超时。随后探测 `http://127.0.0.1:3100/healthz` 未连通；进程检查发现存在两组遗留的 `npm run api-server:maincloud -> scripts/api-server-maincloud.mjs -> cargo run -p api-server` 链路，同时还有并行 `module-assets` 测试和 `spacetime-module` 检查在运行。该结果不是本次 WP-API route 编译错误，需清理本次遗留 api-server 启动链后再做一次干净启动。
+
 ### 2026-04-29 WP-API runtime projection 接线

 已完成：
@@ -888,6 +942,30 @@ npm.cmd run api-server:maincloud

 结果：命令在 90 秒观察窗口内超时，因为 `cargo run` 前台常驻；随后确认 `127.0.0.1:3100` 已由本仓库 `server-rs/target/debug/api-server.exe` 监听。`GET /healthz` 返回 `200`，`GET /api/story/sessions/storysess_001/runtime-projection` 未登录返回 `401`，无效 bearer token 返回 `401`。

+### 2026-04-29 WP-API story battle typed DTO 收口
+
+已完成：
+
+1. 将 story battle / NPC battle 的请求与响应 DTO 收口到 `shared-contracts/src/story.rs`。
+2. `api-server/src/story_battles.rs` 不再定义本地临时 request struct，也不再用 `json!` 手拼成功响应。
+3. API 层仍只负责鉴权、request context、请求解析、`spacetime-client` facade 调用、typed DTO 映射和错误 envelope。
+4. 保持 battle mode、NPC battle function id、reward item 基础格式校验在 BFF 入参边界；战斗结算规则仍由 `module-combat` 与 SpacetimeDB facade 承担。
+5. 新增 `story_battle_responses_use_story_contract_shape` 共享契约序列化回归测试。
+6. 本次未修改 SpacetimeDB 表结构，未触碰 `migration.rs`。
+
+验证：
+
+```powershell
+cargo test -p api-server story_battle --manifest-path server-rs/Cargo.toml
+cargo test -p shared-contracts story_battle_responses_use_story_contract_shape --manifest-path server-rs/Cargo.toml
+cargo fmt -p api-server -p shared-contracts --manifest-path server-rs/Cargo.toml --check
+cargo check -p api-server --manifest-path server-rs/Cargo.toml
+npm.cmd run check:server-rs-ddd
+npm.cmd run check:encoding -- server-rs/crates/shared-contracts/src/story.rs server-rs/crates/api-server/src/story_battles.rs docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md
+```
+
+结果：通过。`cargo check -p api-server` 仍有既有 `api-server/src/prompt/rpg/runtime_chat.rs` 未使用 prompt helper warning，非本次新增。
+
 后端启动：

 ```powershell
@@ -896,6 +974,40 @@ npm.cmd run api-server:maincloud

 结果：编译通过，仅有既有 prompt helper warning；运行阶段因 `127.0.0.1:3100` 端口已被既有 `api-server` 进程占用而退出，错误为 `AddrInUse / 10048`。随后探测 `http://127.0.0.1:3100/healthz` 返回 `200`，确认本地已有服务在线。

+### 2026-04-29 WP-API story runtime projection route 接线
+
+已完成：
+
+1. 确认 `api-server` 已挂载新主链 route：
+   - `GET /api/story/sessions/{story_session_id}/runtime-projection`
+2. `story_sessions::get_story_runtime_projection` 只执行 BFF 编排：
+   - 从鉴权 token 取得 `actor_user_id`。
+   - 调用 `spacetime_client.get_story_runtime_projection_source(story_session_id, actor_user_id)`。
+   - 调用 `module_runtime_story::build_story_runtime_projection(source)` 输出 `StoryRuntimeProjectionResponse`。
+3. route 不恢复 `/api/runtime/story/*`，不绕过 `spacetime-client` 访问 SpacetimeDB，不在 API 层复制领域投影规则。
+4. 新增/确认 API 测试：
+   - `get_story_runtime_projection_requires_authentication`
+   - `get_story_runtime_projection_returns_bad_gateway_when_spacetime_not_published`
+   - `runtime_story_legacy_routes_are_not_mounted`
+5. 本次未修改 SpacetimeDB 表结构，未触碰 `migration.rs`。
+
+后续接线边界：
+
+1. `WP-FE-S` 可在后端 route 稳定后迁移 `src/services/rpg-runtime/rpgRuntimeStoryClient.ts` 到 `/api/story/sessions/{storySessionId}/runtime-projection`。
+2. `WP-FE-H` 与 `WP-FE-C` 继续等待 service client 完成后再动 hooks/components。
+3. `WP-DEL` 仍需等前端迁移完成后，统一删除旧 `runtime_story` contract、旧前端 client/helper 和旧 prompt helper。
+
+验证：
+
+```powershell
+cargo test -p api-server get_story_runtime_projection --manifest-path server-rs/Cargo.toml
+cargo test -p api-server runtime_story_legacy_routes_are_not_mounted --manifest-path server-rs/Cargo.toml
+cargo check -p api-server --manifest-path server-rs/Cargo.toml
+npm.cmd run check:server-rs-ddd
+```
+
+结果：通过。`cargo check -p api-server` 仍有既有 `api-server/src/prompt/rpg/runtime_chat.rs` 未使用 prompt helper warning，非本次新增。
+
 后端启动：

 ```powershell
@@ -989,6 +1101,82 @@ spacetime build --project-path server-rs/crates/spacetime-module

 原因：当前环境未找到 `spacetime` CLI，可执行文件不在 PATH 中。

+### 2026-04-29 WP-ST SpacetimeDB 根入口 warning 收口
+
+已完成：
+
+1. 新增 `SERVER_RS_DDD_WP_ST_ROOT_REEXPORT_WARNING_CLEANUP_2026-04-29.md`，记录本次根入口治理。
+2. 在 `spacetime-module/src/lib.rs` 顶部补充中文注释，说明根模块继续 re-export 各领域类型是为了 SpacetimeDB 绑定生成。
+3. 局部允许 `ambiguous_glob_reexports`，收口多个领域包同名 normalize helper 带来的持续 warning。
+4. 本次不改变任何 table、reducer、procedure、migration 或前端绑定 shape。
+
+验证：
+
+```powershell
+cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml
+npm.cmd run check:server-rs-ddd
+npm.cmd run check:encoding -- server-rs/crates/spacetime-module/src/lib.rs
+```
+
+结果：通过，`spacetime-module` 编译不再输出 `ambiguous glob re-exports` warning。
+
+### 2026-04-29 WP-ST Puzzle 发布事件 Adapter 切片
+
+已完成：
+
+1. 新增 `SERVER_RS_DDD_WP_ST_PUZZLE_EVENT_ADAPTER_2026-04-29.md`，记录本次 Puzzle event table 接入边界。
+2. 在 `spacetime-module/src/puzzle.rs` 新增 `puzzle_event` public event table。
+3. `puzzle_event` 当前承接 `WorkPublished`，用于订阅端、BFF 或审计流程感知拼图作品发布成功事实。
+4. `publish_puzzle_work_tx` 在成功写入 `puzzle_work_profile` 并更新 `puzzle_agent_session` 后写入事件。
+5. 已同步 `migration.rs` 迁移白名单，加入 `puzzle_event`，并补齐既有 `puzzle_leaderboard_entry`。
+6. 已同步 `SPACETIMEDB_TABLE_CATALOG.md` 的 Puzzle 表目录和查询说明。
+
+边界说明：
+
+1. `puzzle_event` 不是作品真相表，正式作品状态仍以 `puzzle_work_profile` 和 `puzzle_agent_session` 为准。
+2. `puzzle_leaderboard_entry` 本次只补迁移白名单和文档账本，不改变成绩规则。
+3. 本次未修改 `api-server`、`spacetime-client`、前端 services/hooks/components。
+
+验证：
+
+```powershell
+cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml
+cargo test -p module-puzzle --manifest-path server-rs/Cargo.toml
+npm.cmd run check:server-rs-ddd
+npm.cmd run check:encoding -- server-rs/crates/spacetime-module/src/puzzle.rs server-rs/crates/spacetime-module/src/migration.rs docs/technical/SPACETIMEDB_TABLE_CATALOG.md docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md docs/technical/SERVER_RS_DDD_WP_ST_PUZZLE_EVENT_ADAPTER_2026-04-29.md
+```
+
+结果：通过。`cargo test -p module-puzzle` 共 13 个测试通过。
+
+### 2026-04-29 WP-ST Asset Row Mapper Adapter 切片
+
+已完成：
+
+1. 新增 `SERVER_RS_DDD_WP_ST_ASSET_ROW_MAPPER_ADAPTER_2026-04-29.md`，记录本次资产 Adapter 收口范围。
+2. `upsert_asset_object` 改为先构造 `AssetObjectUpsertSnapshot`，再通过 `build_asset_object_row` 落 SpacetimeDB row。
+3. `upsert_asset_entity_binding` 改为先构造 `AssetEntityBindingSnapshot`，再通过 `build_asset_entity_binding_row` 落 SpacetimeDB row。
+4. 本次不改变资产表结构、不改 reducer / procedure 签名、不改 `migration.rs`。
+5. 本次未修改 `api-server`、`spacetime-client`、前端 services/hooks/components。
+
+验证：
+
+```powershell
+cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml
+cargo test -p module-assets --manifest-path server-rs/Cargo.toml
+npm.cmd run check:server-rs-ddd
+npm.cmd run check:encoding -- docs/technical/SERVER_RS_DDD_WP_ST_ASSET_ROW_MAPPER_ADAPTER_2026-04-29.md server-rs/crates/spacetime-module/src/asset_metadata/objects.rs server-rs/crates/spacetime-module/src/asset_metadata/bindings.rs
+```
+
+结果：通过。`cargo test -p module-assets` 共 8 个测试通过。
+
+后端启动：
+
+```powershell
+npm.cmd run api-server:maincloud
+```
+
+结果：命令在 60 秒观察窗口内超时，但随后探测 `http://127.0.0.1:3100/healthz` 返回 `200`，本地存在 `api-server` 运行进程。本切片未触发新的 Rust 编译错误。
+
 ### 2026-04-29 WP-RS 领域投影 builder 切片

 已完成：
--- a/docs/technical/SERVER_RS_DDD_WP_SC_SPACETIME_CLIENT_REFACTOR_2026-04-29.md
+++ b/docs/technical/SERVER_RS_DDD_WP_SC_SPACETIME_CLIENT_REFACTOR_2026-04-29.md
@@ -52,7 +52,18 @@
 3. 前端迁移必须等待 `WP-API` route 和 DTO 稳定后，再按 `services -> hooks -> components` 接入。
 4. 若后续改变 table / reducer / procedure，必须由 `WP-ST` 同步表目录和必要的绑定生成记录。

-## 6. 验收
+## 6. 本次完成范围
+
+1. `SpacetimeClientError` 已新增并接入统一 helper：
+   - `from_sdk_error`
+   - `procedure_failed`
+   - `missing_snapshot`
+2. 已覆盖现有稳定 facade 的 SDK 错误映射，包含 AI、Big Fish、assets、auth、story、combat、inventory、npc、runtime、puzzle、custom world。
+3. `mapper.rs` 中稳定 procedure result 的重复 `ok=false` 默认错误和缺快照错误已收口到统一 helper。
+4. auth store snapshot import mapper 中历史乱码错误文案已恢复为中文语义。
+5. 领域语义错误继续保留原样，例如 `custom_world_profile 不存在`，避免把业务不存在误归类为缺快照。
+
+## 7. 验收

 必须执行：

--- a/docs/technical/SERVER_RS_DDD_WP_ST_ASSET_ROW_MAPPER_ADAPTER_2026-04-29.md
+++ b/docs/technical/SERVER_RS_DDD_WP_ST_ASSET_ROW_MAPPER_ADAPTER_2026-04-29.md
@@ -0,0 +1,51 @@
+# server-rs DDD WP-ST Asset Row Mapper Adapter 落地记录（2026-04-29）
+
+## 1. 背景
+
+`module-assets` 已提供资产对象和实体绑定的领域 snapshot / record 构建能力。`spacetime-module` 的资产 Adapter 之前在 upsert 过程中直接重复拼装 SpacetimeDB row 与返回 snapshot，字段规则分散在 Adapter 内。
+
+本次不改变资产表结构，不改变 reducer / procedure 签名，只把 row 构造收口到更明确的 snapshot -> row mapper。
+
+## 2. 本次范围
+
+允许修改：
+
+1. `server-rs/crates/spacetime-module/src/asset_metadata/objects.rs`
+2. `server-rs/crates/spacetime-module/src/asset_metadata/bindings.rs`
+3. 本文档
+4. 全局任务清单进度记录
+
+禁止修改：
+
+1. `server-rs/crates/spacetime-module/src/migration.rs`
+2. `docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
+3. `server-rs/crates/api-server/src/**`
+4. `server-rs/crates/spacetime-client/src/**`
+5. 前端 services/hooks/components
+
+## 3. 设计
+
+本次新增两个 Adapter 内部 mapper：
+
+1. `build_asset_object_row(&AssetObjectUpsertSnapshot) -> AssetObject`
+2. `build_asset_entity_binding_row(&AssetEntityBindingSnapshot) -> AssetEntityBinding`
+
+`upsert_asset_object` 和 `upsert_asset_entity_binding` 先构造领域 snapshot，再由 mapper 落 SpacetimeDB row。这样后续继续迁移到 `module-assets` 应用服务时，Adapter 的职责会更清楚：只做 row 查询、幂等定位、snapshot 持久化和 procedure result 返回。
+
+## 4. 边界说明
+
+1. 本次不新增、删除或修改 SpacetimeDB table 字段。
+2. 本次不改 `migration.rs`。
+3. 本次不改 `spacetime-client` 绑定和 facade。
+4. 本次不改 HTTP/BFF 和前端。
+
+## 5. 验收命令
+
+```powershell
+cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml
+cargo test -p module-assets --manifest-path server-rs/Cargo.toml
+npm.cmd run check:server-rs-ddd
+npm.cmd run check:encoding -- docs/technical/SERVER_RS_DDD_WP_ST_ASSET_ROW_MAPPER_ADAPTER_2026-04-29.md server-rs/crates/spacetime-module/src/asset_metadata/objects.rs server-rs/crates/spacetime-module/src/asset_metadata/bindings.rs
+```
+
+结果：通过。
--- a/docs/technical/SERVER_RS_DDD_WP_ST_PUZZLE_EVENT_ADAPTER_2026-04-29.md
+++ b/docs/technical/SERVER_RS_DDD_WP_ST_PUZZLE_EVENT_ADAPTER_2026-04-29.md
@@ -0,0 +1,30 @@
+# WP-ST 拼图发布事件 Adapter 落地说明
+
+## 背景
+
+`module-puzzle` 已经承载拼图作品创建、发布、运行和成绩规则，`spacetime-module/src/puzzle.rs` 负责把领域对象映射为 SpacetimeDB table/procedure。当前发布成功事实只体现在 `puzzle_work_profile` 和 `puzzle_agent_session` 的最终行状态中，订阅端若要捕获一次性发布动作，需要轮询或自行对比快照。
+
+本次切片属于 `WP-ST SpacetimeDB Adapter`，只新增 SpacetimeDB 事件投影，不新增业务规则，也不兼容旧 Node/PostgreSQL 路径。
+
+## 落地范围
+
+1. 新增 `puzzle_event` public event table。
+2. 新增 `PuzzleEventKind::WorkPublished`，用于表示作品发布成功。
+3. 在 `publish_puzzle_work_tx` 完成 `puzzle_work_profile` upsert 和 `puzzle_agent_session` 更新后写入事件。
+4. 将 `puzzle_event` 纳入 `migration.rs` 迁移白名单。
+5. 顺手补齐已有 `puzzle_leaderboard_entry` 的迁移白名单和表目录记录，避免 schema 账本遗漏。
+
+## 边界
+
+1. `puzzle_event` 只承接跨层订阅和审计所需的轻量事实。
+2. 正式作品真相仍以 `puzzle_work_profile` 和 `puzzle_agent_session` 为准。
+3. 排行榜真相仍以 `puzzle_leaderboard_entry` 为准，本次不改成绩规则。
+4. 前端和 `spacetime-client` 后续如需消费发布事件，应订阅 `puzzle_event`，不要把事件表当作作品列表来源。
+
+## 验收
+
+1. `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`
+2. `cargo test -p module-puzzle --manifest-path server-rs/Cargo.toml`
+3. `npm.cmd run check:server-rs-ddd`
+4. `npm.cmd run check:encoding -- <本次修改文件>`
+5. 若本机安装 `spacetime` CLI，再执行 `spacetime build --project-path server-rs/crates/spacetime-module` 和绑定生成。
--- a/docs/technical/SERVER_RS_DDD_WP_ST_ROOT_REEXPORT_WARNING_CLEANUP_2026-04-29.md
+++ b/docs/technical/SERVER_RS_DDD_WP_ST_ROOT_REEXPORT_WARNING_CLEANUP_2026-04-29.md
@@ -0,0 +1,40 @@
+# server-rs DDD WP-ST SpacetimeDB 根入口 warning 收口记录（2026-04-29）
+
+## 1. 背景
+
+`spacetime-module/src/lib.rs` 需要继续从各 `module-*` re-export 领域类型，供 SpacetimeDB table、reducer、procedure 和绑定生成使用。当前多个领域包仍暴露同名 normalize helper，导致 `cargo check -p spacetime-module` 持续出现 `ambiguous glob re-exports` warning。
+
+这些同名 helper 只影响 value namespace 的公开导出，不影响 SpacetimeDB 表、输入、输出和枚举类型。
+
+## 2. 本次范围
+
+允许修改：
+
+1. `server-rs/crates/spacetime-module/src/lib.rs`
+2. 本文档
+3. 全局任务清单进度记录
+
+禁止修改：
+
+1. `module-*` 领域公开 API
+2. `spacetime-client/src/module_bindings/**`
+3. `api-server/src/**`
+4. 前端 services/hooks/components
+
+## 3. 处理方式
+
+在 `spacetime-module/src/lib.rs` 顶部增加中文注释，并局部允许 `ambiguous_glob_reexports`：
+
+1. 保留根模块 re-export，避免影响 SpacetimeDB 绑定生成和既有 adapter 引用。
+2. 明确 warning 来源是领域 helper 同名，不是 schema 或 reducer 冲突。
+3. 后续等各领域包进一步缩小公开 API 时，再移除该 lint 允许。
+
+## 4. 验收
+
+```powershell
+cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml
+npm.cmd run check:server-rs-ddd
+npm.cmd run check:encoding -- server-rs/crates/spacetime-module/src/lib.rs
+```
+
+结果：通过，`spacetime-module` 编译不再输出 `ambiguous glob re-exports` warning。
--- a/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
+++ b/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
@@ -26,7 +26,7 @@ spacetime sql <db> "SELECT * FROM custom_world_gallery_entry"
 | 运行时档案 | `runtime_setting`, `runtime_snapshot`, `user_browse_history`, `profile_dashboard_state`, `profile_wallet_ledger`, `profile_redeem_code`, `profile_redeem_code_usage`, `profile_played_world`, `profile_save_archive` |
 | RPG 运行时 | `story_session`, `story_event`, `npc_state`, `inventory_slot`, `battle_state`, `treasure_record`, `quest_record`, `quest_log`, `player_progression`, `chapter_progression` |
 | 世界创作 | `custom_world_profile`, `custom_world_session`, `custom_world_agent_session`, `custom_world_agent_message`, `custom_world_agent_operation`, `custom_world_draft_card`, `custom_world_gallery_entry` |
-| 拼图 | `puzzle_agent_session`, `puzzle_agent_message`, `puzzle_work_profile`, `puzzle_runtime_run` |
+| 拼图 | `puzzle_agent_session`, `puzzle_agent_message`, `puzzle_work_profile`, `puzzle_event`, `puzzle_runtime_run`, `puzzle_leaderboard_entry` |
 | 大鱼吃小鱼 | `big_fish_creation_session`, `big_fish_agent_message`, `big_fish_asset_slot`, `big_fish_event`, `big_fish_runtime_run` |
 | 资产 | `asset_object`, `asset_entity_binding` |
 | AI 任务 | `ai_task`, `ai_task_stage`, `ai_text_chunk`, `ai_result_reference`, `ai_task_event` |
@@ -419,6 +419,18 @@ SELECT * FROM puzzle_work_profile WHERE owner_user_id = '<user_id>' ORDER BY upd
 SELECT * FROM puzzle_work_profile WHERE publication_status = 'Published';
 ```

+### `puzzle_event`
+
+- 作用：拼图创作事件表，目前记录作品发布成功事实，供订阅端、BFF 或审计流程感知创作流已产出公开作品；正式作品状态仍以 `puzzle_work_profile` 和 `puzzle_agent_session` 为准。
+- 可见性：`public event`。
+- 结构：`event_id PK: String`, `profile_id: String`, `work_id: String`, `session_id: Option<String>`, `owner_user_id: String`, `event_kind: PuzzleEventKind`, `occurred_at: Timestamp`。
+- 索引：`profile_id`, `owner_user_id`。
+
+```sql
+SELECT * FROM puzzle_event WHERE profile_id = '<profile_id>' ORDER BY occurred_at ASC;
+SELECT * FROM puzzle_event WHERE owner_user_id = '<user_id>' ORDER BY occurred_at DESC;
+```
+
 ### `puzzle_runtime_run`

 - 作用：拼图游玩运行态，保存当前关卡、网格、已玩 profile 列表、标签和运行快照。
@@ -430,6 +442,17 @@ SELECT * FROM puzzle_runtime_run WHERE run_id = '<run_id>';
 SELECT * FROM puzzle_runtime_run WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
 ```

+### `puzzle_leaderboard_entry`
+
+- 作用：拼图关卡真实成绩表，按用户、作品和网格规格保留最佳成绩，用于结算弹窗排行榜。
+- 结构：`entry_id PK: String`, `profile_id: String`, `grid_size: u32`, `user_id: String`, `nickname: String`, `best_elapsed_ms: u64`, `last_run_id: String`, `updated_at: Timestamp`。
+- 索引：`profile_id + grid_size`, `user_id + profile_id + grid_size`。
+
+```sql
+SELECT * FROM puzzle_leaderboard_entry WHERE profile_id = '<profile_id>' AND grid_size = 4 ORDER BY best_elapsed_ms ASC;
+SELECT * FROM puzzle_leaderboard_entry WHERE user_id = '<user_id>' AND profile_id = '<profile_id>' AND grid_size = 4;
+```
+
 ## 大鱼吃小鱼表

 ### `big_fish_creation_session`