# 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 表级状态读写。