1

docs/technical/RPG_RUNTIME_BOOTSTRAP_BACKEND_MIGRATION_2026-04-28.md

@@ -0,0 +1,70 @@
+# 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 的读取来源。
+
+## 接口
+
+新增：
+
+```text
+POST /api/runtime/story/sessions
+```
+
+请求：
+
+```json
+{
+  "worldType": "CUSTOM",
+  "customWorldProfile": {},
+  "character": {},
+  "runtimeMode": "play",
+  "disablePersistence": false
+}
+```
+
+响应：
+
+```json
+{
+  "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 表级状态读写。