后端重写提交

2026-04-22 12:34:49 +08:00
parent cf8da3f50f
commit 997a8daada
438 changed files with 53355 additions and 865 deletions
--- a/backend-rewrite-tasklist/00_MASTER_TASKLIST.md
+++ b/backend-rewrite-tasklist/00_MASTER_TASKLIST.md
@@ -6,6 +6,8 @@

 - [../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)
 - [../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md](../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md)
+- [../docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)
+- [../docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)

 关联拆分任务：

@@ -70,9 +72,9 @@

 重点：

-1. 迁移 story action 主循环
-2. 迁移 gameplay reducer
-3. 兼容当前 story view model 与 state 恢复接口
+1. 迁移 RPG runtime story 主循环
+2. 迁移 RPG 入口 / session / runtime 对应的后端边界与编译职责
+3. 兼容当前 story view model 与 state 恢复接口，并与 `rpgEntry / rpgSession / rpgRuntime / rpgRuntimeStory` 口径对齐

 详见：

@@ -82,9 +84,9 @@

 重点：

-1. 迁移传统 custom world 问答流
-2. 迁移 custom world library / gallery
-3. 迁移 custom world agent 会话、消息、卡片、操作
+1. 迁移 RPG 创作主链：Agent session、result preview、published profile
+2. 迁移 works / library / gallery / publish / enter-world 配套链路
+3. 旧 `custom-world/sessions` 传统问答流只按历史兼容台账处理，不再作为当前主链扩展目标

 详见：

--- a/backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md
+++ b/backend-rewrite-tasklist/02_M3_RUNTIME_PROFILE.md
@@ -3,12 +3,12 @@
 ## 1. SpacetimeDB 运行时主表

 - [ ] 设计 `runtime_snapshot`
- [ ] 设计 `runtime_setting`
- [ ] 设计 `profile_dashboard_state`
- [ ] 设计 `profile_wallet_ledger`
- [ ] 设计 `profile_played_world`
+- [x] 设计 `runtime_setting`
+- [x] 设计 `profile_dashboard_state`
+- [x] 设计 `profile_wallet_ledger`
+- [x] 设计 `profile_played_world`
 - [ ] 设计 `profile_save_archive`
- [ ] 设计 `user_browse_history`
+- [x] 设计 `user_browse_history`

 ## 2. 兼容快照策略

@@ -16,31 +16,31 @@
 - [ ] 设计 snapshot projection 刷新机制
 - [ ] 迁移当前 snapshot hydration / normalize 规则
 - [ ] 迁移当前 save archive 聚合逻辑
- [ ] 迁移当前 browse history 去重与排序逻辑
+- [x] 迁移当前 browse history 去重与排序逻辑

 ## 3. Axum facade

 - [ ] 兼容 `GET /api/runtime/save/snapshot`
 - [ ] 兼容 `PUT /api/runtime/save/snapshot`
 - [ ] 兼容 `DELETE /api/runtime/save/snapshot`
- [ ] 兼容 `GET /api/runtime/settings`
- [ ] 兼容 `PUT /api/runtime/settings`
- [ ] 兼容 `GET /api/runtime/profile/dashboard`
- [ ] 兼容 `GET /api/profile/dashboard`
- [ ] 兼容 `GET /api/runtime/profile/wallet-ledger`
- [ ] 兼容 `GET /api/profile/wallet-ledger`
- [ ] 兼容 `GET /api/runtime/profile/play-stats`
- [ ] 兼容 `GET /api/profile/play-stats`
+- [x] 兼容 `GET /api/runtime/settings`
+- [x] 兼容 `PUT /api/runtime/settings`
+- [x] 兼容 `GET /api/runtime/profile/dashboard`
+- [x] 兼容 `GET /api/profile/dashboard`
+- [x] 兼容 `GET /api/runtime/profile/wallet-ledger`
+- [x] 兼容 `GET /api/profile/wallet-ledger`
+- [x] 兼容 `GET /api/runtime/profile/play-stats`
+- [x] 兼容 `GET /api/profile/play-stats`
 - [ ] 兼容 `GET /api/runtime/profile/save-archives`
 - [ ] 兼容 `GET /api/profile/save-archives`
 - [ ] 兼容 `POST /api/runtime/profile/save-archives/:worldKey`
 - [ ] 兼容 `POST /api/profile/save-archives/:worldKey`
- [ ] 兼容 `GET /api/runtime/profile/browse-history`
- [ ] 兼容 `POST /api/runtime/profile/browse-history`
- [ ] 兼容 `DELETE /api/runtime/profile/browse-history`
- [ ] 兼容 `GET /api/profile/browse-history`
- [ ] 兼容 `POST /api/profile/browse-history`
- [ ] 兼容 `DELETE /api/profile/browse-history`
+- [x] 兼容 `GET /api/runtime/profile/browse-history`
+- [x] 兼容 `POST /api/runtime/profile/browse-history`
+- [x] 兼容 `DELETE /api/runtime/profile/browse-history`
+- [x] 兼容 `GET /api/profile/browse-history`
+- [x] 兼容 `POST /api/profile/browse-history`
+- [x] 兼容 `DELETE /api/profile/browse-history`

 ## 4. 阶段验收

@@ -48,3 +48,18 @@
 - [ ] 兼容路径与主路径返回一致
 - [ ] profile dashboard / browse history / save archive 行为一致
 - [ ] 前端当前恢复流程可在不改 UI 的前提下跑通
+
+## 5. 本轮进展记录
+
+- `2026-04-21`：已完成 `runtime_setting` 首版设计与 `GET/PUT /api/runtime/settings` 的 Rust 主链迁移。
+- 本轮已落地 `module-runtime`、`spacetime-module`、`spacetime-client`、`api-server` 四层串联，并补齐定向测试。
+- 详细设计与字段冻结见：
+  - [../docs/technical/M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](../docs/technical/M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)
+- `2026-04-22`：已完成 `user_browse_history` 表设计冻结、去重与排序规则迁移，以及 `/api/runtime/profile/browse-history` 与 `/api/profile/browse-history` 双路径 facade 落地。
+- `2026-04-22`：已补 `browse history` 的 API 入口必填字段校验、批量 shape 兼容与定向测试，详细设计见：
+  - [../docs/technical/M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md](../docs/technical/M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md)
+- `2026-04-22`：已冻结 `profile_dashboard_state`、`profile_wallet_ledger`、`profile_played_world` 三张 projection 表，以及 `dashboard / wallet-ledger / play-stats` 的 Axum + SpacetimeDB 读链设计。
+- `2026-04-22`：已完成 `api-server` 的 `runtime_profile` facade 编译与定向测试收口，`/api/runtime/profile/*` 与 `/api/profile/*` 六条只读路由均已接通。
+- `2026-04-22`：已通过 `cargo check -p api-server --tests --message-format short`、`cargo test -p shared-contracts --lib`、`cargo test -p api-server runtime_profile::tests:: -- --nocapture` 验证本轮 profile projection 读链。
+- 详细设计见：
+  - [../docs/technical/M3_PROFILE_DASHBOARD_AXUM_SPACETIMEDB_DESIGN_2026-04-22.md](../docs/technical/M3_PROFILE_DASHBOARD_AXUM_SPACETIMEDB_DESIGN_2026-04-22.md)
--- a/backend-rewrite-tasklist/03_M4_STORY_AND_GAMEPLAY.md
+++ b/backend-rewrite-tasklist/03_M4_STORY_AND_GAMEPLAY.md
@@ -1,48 +1,141 @@
 # M4：story action 与 gameplay reducer 任务清单

+## 0. 当前执行基线
+
+本阶段与当前仓库里的 RPG 入口与运行时主链重构直接对应，统一以以下文档为准：
+
+1. [../docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)
+2. [../docs/technical/FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md](../docs/technical/FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md)
+3. [../docs/technical/M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md](../docs/technical/M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md)
+
+当前任务清单只维护 Axum / SpacetimeDB 重写侧的后端迁移项，不再把旧 `GameShell / runtimeRoutes.ts / storyActionService.ts` 命名视为新架构目标。
+
+### 当前进展（`2026-04-22`）
+
+本阶段首轮已先把 `server-rs` 从“只有 `module-story` 占位目录”推进到“SpacetimeDB 侧 story 会话基座真实可编译”：
+
+1. 已新增 `server-rs/crates/module-story` 真实 crate。
+2. 已冻结 `story_session / story_event` 的首版领域类型、状态枚举和字段校验 helper。
+3. 已在 `server-rs/crates/spacetime-module` 中新增 `story_session`、`story_event` 两张表。
+4. 已新增 `begin_story_session`、`continue_story` 两个 reducer，形成最小会话事件链。
+5. 已新增 `begin_story_session_and_return`、`continue_story_and_return` 两个 procedure，形成可同步返回快照的最小 story session contract。
+6. 已重新执行 `spacetime generate`，把 `story_session / story_event` Rust bindings 刷入 `spacetime-client/src/module_bindings`。
+7. 已在 `server-rs/crates/spacetime-client` 中新增 `begin_story_session(...)`、`continue_story(...)` facade。
+8. 已在 `server-rs/crates/api-server` 中新增：
+   - `POST /api/story/sessions`
+   - `POST /api/story/sessions/continue`
+9. 已执行 `cargo check -p module-story -p spacetime-module -p spacetime-client -p api-server` 并通过。
+6. 已新增 `docs/technical/M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md`，冻结 `battle_state` 与 `resolve_combat_action` 的首版字段与规则口径。
+7. 已新增 `server-rs/crates/module-runtime-item` 真实 crate。
+8. 已冻结 `treasure_record` 的首版领域类型、完整奖励物品快照和字段校验规则。
+9. 已在 `server-rs/crates/spacetime-module` 中新增 `treasure_record` 表。
+10. 已新增 `resolve_treasure_interaction` reducer 与 `resolve_treasure_interaction_and_return` procedure，并把宝箱奖励同步写入 `inventory_slot`。
+11. 已新增 `docs/technical/M4_RPG_RUNTIME_INVENTORY_SPACETIMEDB_BASELINE_2026-04-21.md`，冻结 `inventory_slot` 与 `apply_inventory_mutation` 的首版字段与规则口径。
+12. 已新增 `server-rs/crates/module-inventory` 真实 crate。
+13. 已在 `server-rs/crates/spacetime-module` 中新增 `inventory_slot` 表。
+14. 已新增 `apply_inventory_mutation` reducer，形成最小背包主链。
+15. 已新增 `docs/technical/M4_MODULE_NPC_SPACETIMEDB_BASELINE_2026-04-21.md`，冻结 `npc_state`、`resolve_npc_social_action` 与 `resolve_npc_interaction` 的首版字段与交互口径。
+16. 已新增 `server-rs/crates/module-npc` 真实 crate。
+17. 已在 `server-rs/crates/spacetime-module` 中新增 `npc_state` 表。
+18. 已新增 `upsert_npc_state`、`resolve_npc_social_action`、`resolve_npc_interaction` 及对应 procedure。
+19. 已新增 `docs/technical/M4_MODULE_NPC_COMBAT_ORCHESTRATION_BASELINE_2026-04-21.md`，冻结 `npc_fight / npc_spar` 到 `battle_state` 的最小联合编排口径。
+20. 已在 `server-rs/crates/spacetime-module` 中新增 `resolve_npc_battle_interaction_and_return` procedure，把 NPC 开战交互与 battle 初始化写入串到同一事务。
+15. 已新增 `docs/technical/M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md`，冻结 `player_progression / chapter_progression` 的首版字段、成长曲线与章节预算口径。
+16. 已新增 `server-rs/crates/module-progression` 真实 crate。
+17. 已在 `server-rs/crates/spacetime-module` 中新增 `player_progression`、`chapter_progression` 两张表。
+18. 已新增 `get_player_progression_or_default`、`grant_player_progression_experience`、`upsert_chapter_progression`、`apply_chapter_progression_ledger_entry` 及对应 procedure。
+19. 已新增 `docs/technical/M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md`，冻结 `quest_record / quest_log / apply_quest_signal` 的首版字段、日志口径与交付状态流转规则。
+20. 已新增 `server-rs/crates/module-quest` 真实 crate。
+21. 已在 `server-rs/crates/spacetime-module` 中新增 `quest_record`、`quest_log` 两张表。
+22. 已新增 `accept_quest`、`apply_quest_signal`、`acknowledge_quest_completion`、`turn_in_quest` reducer，形成最小任务闭环。
+23. 已执行 `cargo test -p module-quest`、`cargo check -p spacetime-module`、`cargo check -p api-server` 与全量 `cargo check` 并通过。
+24. 已新增 `docs/technical/M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md`，冻结任务交付与战斗胜利到成长系统的联动口径。
+25. 已把 `turn_in_quest` 接到 `player_progression / chapter_progression` 的最小经验写入。
+26. 已把 `resolve_combat_action(Victory)` 接到 `player_progression / chapter_progression` 的最小经验写入。
+27. 已把 `turn_in_quest.reward.items` 接到 `inventory_slot` 发物链，形成任务交付的最小物品奖励闭环。
+28. 已新增 `docs/technical/M4_RPG_RUNTIME_STORY_SESSION_STATE_QUERY_DESIGN_2026-04-22.md`，冻结最小 `story state` 查询切片，只开放 `storySession + storyEvents` 真相态查询。
+29. 已在 `server-rs/crates/api-server` 中挂出 `GET /api/story/sessions/:storySessionId/state`，通过 `spacetime-client.get_story_session_state(...)` 读取 `SpacetimeDB procedure` 返回的会话快照与事件流。
+30. 已新增 `docs/technical/M4_COMBAT_REWARD_INVENTORY_INTEGRATION_2026-04-22.md`，冻结 `battle_state.reward_items` 与 `resolve_combat_action(Victory)` 发物到 `inventory_slot` 的最小联动口径。
+31. 已新增 `docs/technical/M4_MODULE_COMBAT_STATE_QUERY_DESIGN_2026-04-22.md`，冻结最小 `battle state` 查询切片，只开放单个 `battleState` 真相态查询。
+32. 已在 `server-rs/crates/spacetime-module` 中新增 `get_battle_state` procedure，按 `battle_state_id` 返回当前战斗快照。
+33. 已在 `server-rs/crates/spacetime-client` 中新增 `get_battle_state(...)` facade，供 Axum 同步读取 battle 真相态。
+34. 已在 `server-rs/crates/api-server` 中挂出 `GET /api/story/battles/:battleStateId`，通过 `spacetime-client.get_battle_state(...)` 返回单战斗快照。
+35. 已在 `server-rs/crates/spacetime-client` 中新增 `resolve_npc_battle_interaction(...)` facade，把 `resolve_npc_battle_interaction_and_return` procedure 映射为稳定 Rust record，供 Axum 直接消费。
+36. 已在 `server-rs/crates/api-server` 中挂出 `POST /api/story/npc/battle`，当前只接受 `npc_fight / npc_spar`，同步返回 `npcInteraction + battleState`。
+37. 已执行 `cargo check -p spacetime-client -p api-server` 并通过，完成 `module-npc -> spacetime-client -> api-server` 的最小 NPC 开战同步返回链闭环。
+38. 已重新执行 `spacetime generate --no-config --lang rust --out-dir D:\\Genarrative\\server-rs\\crates\\spacetime-client\\src\\module_bindings --module-path D:\\Genarrative\\server-rs\\crates\\spacetime-module --include-private --yes`，把 `get_battle_state`、`battle_state.reward_items` 与 `custom_world_agent_session` 相关 bindings 刷入 `spacetime-client/src/module_bindings`。
+39. 已把 `server-rs/crates/spacetime-client/src/lib.rs` 中原本占位返回错误的 `get_battle_state(...)` 改成真实 procedure 调用，当前 battle query 已不再停留在 facade stub。
+40. 已再次执行 `cargo check -p spacetime-client --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml` 与 `cargo check -p api-server --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`，当前 battle/story 新链路在编译层已恢复通过。
+41. 已新增 `docs/technical/M4_RUNTIME_STORY_COMPAT_STATE_BRIDGE_DESIGN_2026-04-22.md`，冻结旧 `POST /api/runtime/story/state/resolve` 的首版兼容桥边界，明确当前先做 DTO 与状态桥，不提前误宣称 `actions/resolve` 已可迁移。
+42. 已在 `server-rs/crates/shared-contracts` 中新增 `runtime_story` 模块，冻结 `RuntimeStoryStateResolveRequest`、`RuntimeStoryActionResponse` 以及 `viewModel / presentation / patches / snapshot` 的首版 camelCase DTO，与当前前端消费口径对齐。
+
+当前验证边界补充：
+
+1. `story_sessions` / `story_battles` 的二进制测试目标在当前机器上编译耗时很长，已有多轮回归尝试，但还没有在单次时窗内收敛到最终断言结果。
+2. `npm run check:encoding` 已启动到 `node scripts/check-encoding.mjs`，但当前尚未在单次时窗内跑完，不能标记为已完成。
+3. 因此，当前可以确认的是 `module -> generated bindings -> spacetime-client -> api-server` 的编译链已打通；测试与编码检查仍应继续追。
+
+当前这轮仍未扩到 `resolve_story_action`、`sync_runtime_snapshot_projection`、旧 `/api/runtime/story/*` 兼容接口和前端实际 runtime story API 切换，这些继续保留在后续 `M4` 工作项中。
+
 ## 1. SpacetimeDB gameplay 表

- [ ] 设计 `story_session`
- [ ] 设计 `story_event`
- [ ] 设计 `npc_state`
- [ ] 设计 `quest_record`
- [ ] 设计 `inventory_slot`
- [ ] 设计 `treasure_record`
- [ ] 设计 `battle_state`
- [ ] 设计 `player_progression`
- [ ] 设计 `chapter_progression`
+- [x] 设计 `story_session`
+- [x] 设计 `story_event`
+- [x] 设计 `npc_state`
+- [x] 设计 `quest_record`
+- [x] 设计 `inventory_slot`
+- [x] 设计 `treasure_record`
+- [x] 设计 `battle_state`
+- [x] 设计 `player_progression`
+- [x] 设计 `chapter_progression`

 ## 2. 核心 reducer

 - [ ] 设计 `resolve_story_action`
- [ ] 设计 `continue_story`
- [ ] 设计 `begin_story_session`
+- [x] 设计 `continue_story`
+- [x] 设计 `begin_story_session`
 - [ ] 设计 `sync_runtime_snapshot_projection`
- [ ] 设计 `apply_quest_signal`
- [ ] 设计 `apply_inventory_mutation`
- [ ] 设计 `resolve_npc_interaction`
- [ ] 设计 `resolve_treasure_interaction`
- [ ] 设计 `resolve_combat_action`
- [ ] 设计 `update_progression_state`
+- [x] 设计 `apply_quest_signal`
+- [x] 设计 `apply_inventory_mutation`
+- [x] 设计 `resolve_npc_interaction`
+- [x] 设计 `resolve_treasure_interaction`
+- [x] 设计 `resolve_combat_action`
+- [x] 设计 `update_progression_state`

-## 3. 迁移模块规则
+## 3. 当前主链模块落位

- [ ] 迁移 `story`
- [ ] 迁移 `combat`
+- [ ] 迁移 `rpg-entry` 配套后端入口能力
+- [ ] 迁移 `rpg-profile` 资料域
+- [ ] 迁移 `rpg-runtime-story`
+- [x] 迁移 `combat`
 - [ ] 迁移 `inventory`
 - [ ] 迁移 `npc`
- [ ] 迁移 `progression`
- [ ] 迁移 `quest`
- [ ] 迁移 `runtime-item`
- [ ] 迁移 `runtime` 的状态归一化规则
+- [x] 迁移 `progression`
+- [x] 迁移 `quest`
+- [x] 迁移 `runtime-item`
+- [ ] 迁移 runtime snapshot 归一化、view model compiler 与状态同步规则

 ## 4. 兼容接口

 - [ ] 兼容 `POST /api/runtime/story/actions/resolve`
 - [ ] 兼容 `GET /api/runtime/story/state/:sessionId`
+- [ ] 兼容 `POST /api/runtime/story/state/resolve`
 - [ ] 兼容 `POST /api/runtime/story/initial`
 - [ ] 兼容 `POST /api/runtime/story/continue`

+补充说明：
+
+1. 当前已落地的是新的 Rust facade：
+   - `POST /api/story/sessions`
+   - `POST /api/story/sessions/continue`
+   - `GET /api/story/sessions/:storySessionId/state`
+   - `GET /api/story/battles/:battleStateId`
+   - `POST /api/story/npc/battle`
+2. 其中前 3 个接口是 `story session` 真相链路，后 2 个接口是 battle / NPC 开战真相链路，都不等价于旧 Node 的 LLM `runtime/story/*` 兼容接口。
+3. 当前新增的 `story state` 查询只返回 `storySession + storyEvents`，还没有兼容旧 `RuntimeStoryActionResponse`、`currentStory`、`availableOptions`。
+4. 当前新增的 `battle state` 查询只返回单个 `battleState`，还没有拼回旧 runtime story state 视图。
+5. 在 `resolve_story_action / story state` contract 未冻结前，不应误勾选旧兼容接口。
+
 ## 5. ViewModel 兼容

 - [ ] 兼容当前 `RuntimeStoryActionResponse`
@@ -56,4 +149,5 @@
 - [ ] 当前前端 story 选项点击后可走新后端闭环
 - [ ] NPC / quest / treasure / combat 主循环行为不回退
 - [ ] `story state` 恢复链可用
+- [ ] 后端边界与当前 `rpgEntry -> rpgSession -> rpgRuntime -> rpgRuntimeStory -> rpgProfile` 口径一致
 - [ ] 旧 Node 版 story route 回归用例完成平移
--- a/backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md
+++ b/backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md
@@ -1,68 +1,87 @@
 # M5：custom world / gallery / agent 任务清单

+## 0. 当前执行基线
+
+本阶段与当前仓库里的创作链重构直接对应，统一以以下文档为准：
+
+1. [../docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)
+2. [../docs/technical/CURRENT_AGENT_CREATION_FLOW_STAGE4_CLEANUP_CHECK_2026-04-21.md](../docs/technical/CURRENT_AGENT_CREATION_FLOW_STAGE4_CLEANUP_CHECK_2026-04-21.md)
+
+当前逻辑层命名和职责边界应优先使用 `rpgCreation / rpgAgent / rpgWorld` 口径；本任务清单继续保留 `custom world` 文件名，只是为了和后端重写阶段文档编号保持一致。
+
+本轮首批可编码表设计见：
+
+3. [../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md](../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md)
+4. [../docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISH_WORLD_STAGE4_DESIGN_2026-04-21.md](../docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISH_WORLD_STAGE4_DESIGN_2026-04-21.md)
+5. [../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md](../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AXUM_FACADE_STAGE5_DESIGN_2026-04-22.md)
+6. [../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md](../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md)
+
 ## 1. SpacetimeDB custom world 表

- [ ] 设计 `custom_world_profile`
- [ ] 设计 `custom_world_session`
- [ ] 设计 `custom_world_agent_session`
- [ ] 设计 `custom_world_agent_message`
- [ ] 设计 `custom_world_agent_operation`
- [ ] 设计 `custom_world_draft_card`
+- [x] 设计 `custom_world_profile`
+- [x] 设计 `custom_world_session`
+- [x] 设计 `custom_world_agent_session`
+- [x] 设计 `custom_world_agent_message`
+- [x] 设计 `custom_world_agent_operation`
+- [x] 设计 `custom_world_draft_card`
 - [ ] 设计 `custom_world_asset_link`
- [ ] 设计 `custom_world_gallery_entry`
+- [x] 设计 `custom_world_gallery_entry`

-## 2. 传统 custom world 问答流
+## 2. 当前 RPG 创作主链

- [ ] 迁移 `create session`
- [ ] 迁移 `answer question`
- [ ] 迁移 `generate stream`
- [ ] 迁移 profile compile
- [ ] 迁移 library 存储与删除
- [ ] 迁移 publish / unpublish
- [ ] 迁移 gallery 列表与详情
+- [ ] 迁移 result preview compiler
+- [x] 迁移 published profile compile（Stage 3 已落地）
+- [ ] 迁移 works 聚合读模型
+- [x] 迁移 library 存储与删除（Stage 2 设计已冻结，待继续接 Axum 兼容）
+- [x] 迁移 publish / unpublish（Stage 2 设计已冻结，待继续接 Agent publish gate）
+- [x] 迁移 publish_world 串联主链（Stage 4 设计已冻结，待继续接 Axum action / publish gate）
+- [ ] 迁移 publish gate / enter-world gate
+- [x] 迁移 gallery 列表与详情（Stage 2 设计已冻结，待继续接 Axum 兼容）

-## 3. custom world agent 主链
+## 3. RPG 创作 Agent 主链

- [ ] 迁移 session create
- [ ] 迁移 session snapshot
- [ ] 迁移 message submit
- [ ] 迁移 message stream
- [ ] 迁移 operation query
+- [x] 迁移 session create（Stage 6 首批 Agent session skeleton）
+- [x] 迁移 session snapshot（Stage 6 首批 Agent session skeleton）
+- [x] 迁移 message submit（Stage 7 deterministic message / operation 最小闭环）
+- [x] 迁移 message stream（Stage 8 SSE facade 已落地）
+- [x] 迁移 operation query（Stage 7 deterministic message / operation 最小闭环）
 - [ ] 迁移 card detail
 - [ ] 迁移 card update
+- [ ] 迁移 action registry / supportedActions
 - [ ] 迁移 draft foundation
+- [ ] 迁移 result preview 生成
 - [ ] 迁移 entity generation
- [ ] 迁移 role asset sync
+- [ ] 迁移 role / scene asset sync
+- [ ] 迁移 checkpoint / blocker / quality findings 主链

 ## 4. Axum 编排层

 - [ ] 接入 LLM 编排
 - [ ] 接入世界草稿编译
+- [ ] 接入服务端 result preview 编译
 - [ ] 接入角色 / 地点 / 场景 NPC 生成
 - [ ] 接入封面图生成
 - [ ] 接入场景图生成
 - [ ] 接入 OSS 对象写入与绑定
 - [ ] 接入 SSE 事件分发

-## 5. 兼容接口
+## 5. 当前正式接口与历史兼容台账

- [ ] 兼容 `/api/runtime/custom-world/sessions`
- [ ] 兼容 `/api/runtime/custom-world/sessions/:sessionId`
- [ ] 兼容 `/api/runtime/custom-world/sessions/:sessionId/answers`
- [ ] 兼容 `/api/runtime/custom-world/sessions/:sessionId/generate/stream`
- [ ] 兼容 `/api/runtime/custom-world-library`
- [ ] 兼容 `/api/runtime/custom-world-library/:profileId`
- [ ] 兼容 `/api/runtime/custom-world-library/:profileId/publish`
- [ ] 兼容 `/api/runtime/custom-world-library/:profileId/unpublish`
- [ ] 兼容 `/api/runtime/custom-world-gallery`
- [ ] 兼容 `/api/runtime/custom-world-gallery/:ownerUserId/:profileId`
+### 5.1 当前正式接口
+
+- [x] 兼容 `/api/runtime/custom-world-library`（Stage 5 首批 Axum facade）
+- [x] 兼容 `/api/runtime/custom-world-library/:profileId`（owner-only detail 查询已补齐）
+- [x] 兼容 `/api/runtime/custom-world-library/:profileId/publish`（Stage 5 首批 Axum facade）
+- [x] 兼容 `/api/runtime/custom-world-library/:profileId/unpublish`（Stage 5 首批 Axum facade）
+- [x] 兼容 `/api/runtime/custom-world-gallery`（Stage 5 首批 Axum facade）
+- [x] 兼容 `/api/runtime/custom-world-gallery/:ownerUserId/:profileId`（Stage 5 首批 Axum facade）
 - [ ] 兼容 `/api/runtime/custom-world/works`
- [ ] 兼容 `/api/runtime/custom-world/agent/sessions`
- [ ] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId`
- [ ] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/messages`
- [ ] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/messages/stream`
- [ ] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/actions`
- [ ] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/operations/:operationId`
+- [x] 兼容 `/api/runtime/custom-world/agent/sessions`（Stage 6 首批 Axum facade）
+- [x] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId`（Stage 6 首批 Axum facade）
+- [x] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/messages`（Stage 7 deterministic message submit）
+- [x] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/messages/stream`（Stage 8 SSE facade）
+- [x] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/actions`（Stage 5 仅支持 `publish_world` 显式 draft payload）
+- [x] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/operations/:operationId`（Stage 7 deterministic operation query）
 - [ ] 兼容 `/api/runtime/custom-world/agent/sessions/:sessionId/cards/:cardId`
 - [ ] 兼容 `/api/custom-world/entity`
 - [ ] 兼容 `/api/runtime/custom-world/entity`
@@ -72,9 +91,17 @@
 - [ ] 兼容 `/api/custom-world/cover-image`
 - [ ] 兼容 `/api/custom-world/cover-upload`

+### 5.2 历史兼容台账（非当前主链）
+
+- [ ] 评估 `/api/runtime/custom-world/sessions` 是否仍需保留历史兼容映射
+- [ ] 评估 `/api/runtime/custom-world/sessions/:sessionId` 是否仍需保留历史兼容映射
+- [ ] 评估 `/api/runtime/custom-world/sessions/:sessionId/answers` 是否仍需保留历史兼容映射
+- [ ] 评估 `/api/runtime/custom-world/sessions/:sessionId/generate/stream` 是否仍需保留历史兼容映射
+
 ## 6. 阶段验收

- [ ] 传统 custom world 主链可用
- [ ] custom world library / gallery 主链可用
- [ ] custom world agent 主链可用
+- [ ] RPG 创作主链可用：`agent session -> result preview -> published profile`
+- [ ] works / library / gallery / publish / enter-world 主链可用
+- [ ] RPG 创作 Agent 主链可用
 - [ ] agent 会话、消息、卡片、操作不再依赖单大 JSON 会话体
+- [ ] 旧 `custom-world/sessions` 问答流不再作为当前主链扩展目标
--- a/backend-rewrite-tasklist/07_CROSS_CUTTING_AND_ACCEPTANCE.md
+++ b/backend-rewrite-tasklist/07_CROSS_CUTTING_AND_ACCEPTANCE.md
@@ -29,15 +29,18 @@
 - [ ] 每个阶段完成后同步更新设计文档
 - [ ] 每个阶段完成后补一份落地记录
 - [ ] 完成接口迁移后更新新的模块与 API 索引文档
+- [ ] `M4` 结构变更同步对齐 `docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md`
+- [ ] `M5` 结构变更同步对齐 `docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md`

 ## 2. 第一优先级建议执行顺序

 1. 先做 `M0`，冻结基线，避免迁移过程中口径漂移。
 2. 再做 `M1 + M2`，先把 Axum 壳与鉴权打稳。
 3. 再做 `M3`，优先跑通快照、设置、profile。
-4. 再做 `M4`，把 story action 主循环真正迁走。
-5. 然后做 `M5`，迁 custom world 与 agent。
-6. 最后做 `M6 + M7`，收口 assets、editor、部署与切流。
+4. 进入 `M4` 和 `M5` 前，先用两份 `2026-04-21` 执行方案冻结当前仓库里的 RPG 运行时链与创作链结构口径。
+5. 再做 `M4`，把 RPG runtime story 主循环真正迁走。
+6. 然后做 `M5`，迁 RPG 创作主链、works/library/gallery 与 agent。
+7. 最后做 `M6 + M7`，收口 assets、editor、部署与切流。

 ## 3. 最终验收清单

@@ -47,5 +50,7 @@
 - [ ] Axum 已成为唯一 HTTP / SSE / 副作用边界
 - [ ] SpacetimeDB 已成为唯一运行时状态真相源
 - [ ] 阿里云 OSS 已成为唯一资产对象仓
+- [ ] `M4` 已与 `rpgEntry / rpgSession / rpgRuntime / rpgRuntimeStory / rpgProfile` 主链口径一致
+- [ ] `M5` 已与 `agent session -> result preview -> published profile` 主链口径一致
 - [ ] 前端主流程在不大改 UI 的前提下可跑通
 - [ ] 能完成灰度切流，并保留可回退能力
--- a/backend-rewrite-tasklist/README.md
+++ b/backend-rewrite-tasklist/README.md
@@ -23,6 +23,12 @@
 - [M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md](./M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md)：`M0` 仓库边界决议文档，用于持续冻结 `server-rs/` 落位、迁移期双栈共存、Axum 边界与副作用收口原则。
 - [M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md](./M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md)：`M0 ~ M7` 阶段验收矩阵，用于固定每阶段的入口条件、核心交付、退出条件与跨阶段回归焦点。

+## 当前 M4 / M5 结构基线
+
+- `M4` 当前涉及的前后端脚本结构、命名根、route/service/compiler/repository 落位，统一参照 [../docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)。
+- `M5` 当前涉及的创作入口、Agent session、result preview、works/library/gallery、publish 与 enter-world 主链，统一参照 [../docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)。
+- 旧 `custom-world/sessions` 传统问答链已经退出当前仓库正式主链；后续若在 `M5` 中提及，只按历史兼容台账处理，不再作为当前功能扩展目标。
+
 ## 维护规则

 1. 总纲与拆分文件都以本目录为唯一维护位置。