Genarrative/docs/technical/RPG_RUNTIME_BOOTSTRAP_BACKEND_MIGRATION_2026-04-28.md

RPG 运行时开局 GameState 后端迁移落地（2026-04-28）

目标

本次只收口 RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_AUDIT_2026-04-28.md 的 4.1 P0 运行时开局 GameState 装配仍在前端。

边界

前端保留：

1. 选择世界、选择角色、切换 tab、地图弹层等 UI 状态。
2. 世界选择后的“尚未选角”中间态，用于展示角色选择页面。
3. 调用后端开局接口并接收快照。

后端负责：

1. 生成 runtimeSessionId 与 runtimeActionVersion。
2. 装配正式初始 GameState。
3. 装配初始场景、opening act、首遇 NPC、NPC state。
4. 装配初始背包、初始装备、血蓝、货币、技能冷却。
5. 写入 runtime snapshot，成为后续 runtime story 的读取来源。

接口

新增：

POST /api/runtime/story/sessions

请求：

{
  "worldType": "CUSTOM",
  "customWorldProfile": {},
  "character": {},
  "runtimeMode": "play",
  "disablePersistence": false
}

响应：

{
  "sessionId": "runtime-...",
  "serverVersion": 1,
  "snapshot": {
    "version": 2,
    "savedAt": "...",
    "bottomTab": "adventure",
    "gameState": {},
    "currentStory": null
  }
}

验收

1. useRpgSessionBootstrap.ts 不再在 handleCharacterSelect 中本地构造完整初始 GameState。
2. 开局后 gameState.runtimeSessionId 来自后端。
3. 开局后 gameState.currentScene === "Story"。
4. 自定义世界 opening act 能写入 storyEngineMemory.currentSceneActState。
5. 自定义世界角色 initialItems 能进入背包并自动装配可推断槽位。
6. 后端测试覆盖 opening act、首遇 NPC、初始物品、装备。

后续

本次仍沿用 runtime story compat 的 JSON GameState 桥接形态。后续阶段应继续把 runtime_story action 从“快照桥接”推进为 SpacetimeDB 表级状态读写。