Genarrative/docs/technical/FRONTEND_TO_BACKEND_MIGRATION_EXECUTION_PLAN_2026-04-21.md

前端逻辑后移实施方案（2026-04-21）

更新时间：2026-04-21

1. 目标

本方案只回答一件事：

怎样把当前仍残留在前端的正式运行时逻辑、正式会话真相与正式生成编排，继续收回到 Express 后端。

这份文档不是泛泛而谈的方向说明，而是直接面向本轮与后续几轮编码落地的实施基线。

---

2. 本轮确定的硬边界

根据仓库约束与当前审计结果，本轮继续冻结以下边界：

1. 前端只负责表现、输入采集、临时 UI 状态与服务端结果渲染。
2. 后端负责正式鉴权、正式会话、正式运行时快照、正式任务生成、正式运行时物品意图生成、正式自定义世界生成。
3. 浏览器内不再保存 access token，不再把浏览历史作为本地正式真相，不再保留正式 quest / runtime item / custom world 生成编排。
4. 运行时主链必须继续向“前端提交意图，后端解释快照并返回展示模型”收敛。

---

3. 现状拆分

当前残留问题已经收敛为三批：

3.1 第一批：正式真相仍在前端

1. src/services/apiClient.ts
   • 浏览器仍保存 access token，并拼接 Authorization: Bearer ...
2. src/services/authService.ts
   • 登录、微信绑定等流程仍把 access token 当作前端真相
3. src/components/game-shell/PreGameSelectionFlow.tsx
   • 浏览历史仍是本地写入 + 后端回填的双真相
4. src/services/platformBrowseHistory.ts
   • 维护浏览历史本地存储、迁移标记与同步状态

3.2 第二批：运行时主链仍依赖前端预写快照

1. src/hooks/story/runtimeStoryCoordinator.ts
   • 在请求 runtime state / runtime action 前，仍先 PUT /runtime/save/snapshot
2. src/hooks/story/npcEncounterActions.ts
   • 待接委托的“更换任务”“放弃任务”仍由前端正式结算

3.3 第三批：正式生成编排仍残留在浏览器

1. src/services/questDirector.ts
2. src/services/runtimeItemAiDirector.ts
3. src/services/aiService.ts 的 custom world profile 生成入口
4. src/services/ai.ts 中仍保留的浏览器侧 legacy AI orchestration

---

4. 分批实施策略

4.1 第一批：先收正式真相

鉴权

目标状态：

1. 后端通过 HttpOnly Cookie 持有 refresh session 与 access session。
2. 前端请求层不再读写 access token。
3. 前端只监听鉴权状态事件，不解释 token 生命周期。

本批涉及：

1. server-node/src/auth/accessSessionCookie.ts
2. server-node/src/routes/authRoutes.ts
3. server-node/src/middleware/auth.ts
4. src/services/apiClient.ts
5. src/services/authService.ts
6. src/components/auth/AuthGate.tsx

浏览历史

目标状态：

1. 浏览历史唯一真相在 runtimeRepository。
2. 前端不再保留本地浏览历史、迁移标记、同步标记。
3. 浏览历史只通过 storageService 读取和写入。

本批涉及：

1. src/components/game-shell/PreGameSelectionFlow.tsx
2. src/components/game-shell/PlatformHomeView.tsx
3. src/services/storageService.ts
4. src/services/platformBrowseHistory.ts

4.2 第二批：把 runtime story 快照解释权收回后端

目标状态：

1. 前端不再通过单独的 PUT /runtime/save/snapshot 预写快照再触发动作。
2. runtime state / runtime action 允许前端提交当前快照上下文，由后端内部决定是否写入、如何解释、何时持久化。
3. NPC 待接委托的 replace / abandon / accept 全部走后端 runtime action。

建议实施方式：

1. 扩展 packages/shared/src/contracts/story.ts
   • RuntimeStoryActionRequest 增加可选 snapshot
   • 新增 RuntimeStoryStateRequest
2. 新增 POST /api/runtime/story/state/resolve
3. storyActionService 内部统一处理“请求携带快照上下文时的服务端同步”
4. 把 npc_chat_quest_offer_replace / npc_chat_quest_offer_abandon 接到后端 runtime action

4.3 第三批：把正式生成编排收成后端唯一出口

目标状态：

1. questDirector 只保留轻量 SDK。
2. runtimeItemAiDirector 只保留轻量 SDK。
3. custom world profile 正式生成走后端 route。
4. 浏览器侧 src/services/ai.ts 不再承担正式浏览器主链。

建议实施方式：

1. server-node/src/routes/runtimeRoutes.ts
   • 补 custom-world/profile 正式 route
2. src/services/aiService.ts
   • custom world 入口改走后端
3. src/services/questDirector.ts
   • 只请求 /api/runtime/quests/generate
4. src/services/runtimeItemAiDirector.ts
   • 只请求 /api/runtime/items/runtime-intent

---

5. 本轮落地范围

本轮优先完成以下内容：

1. 鉴权 access token 从前端 localStorage 后移到后端 Cookie。
2. 浏览历史从前端本地真相后移到后端唯一真相。
3. custom world profile 正式生成入口补齐后端 route，并把前端收成 SDK。
4. questDirector / runtimeItemAiDirector 收缩为前端 SDK。
5. runtime story contract 开始补“随请求提交快照上下文”的后端承接能力，并把 NPC 待接委托 replace / abandon 接到后端。

---

6. 验收标准

第一批验收

1. 浏览器中不再保存 access token。
2. fetchWithApiAuth 不再拼接 Bearer token。
3. 浏览历史仅通过远端接口读写。
4. src/services/platformBrowseHistory.ts 不再是正式链路依赖。

第二批验收

1. runtimeStoryCoordinator.ts 不再在动作前独立 PUT /runtime/save/snapshot。
2. NPC 待接委托 replace / abandon / accept 都以后端返回结果为准。

第三批验收

1. questDirector.ts 与 runtimeItemAiDirector.ts 不再保留正式 fallback orchestration。
2. custom world profile 的浏览器正式入口不再直接 import legacy ./ai。

---

7. 一句话结论

这轮迁移的重点不是“把几个 helper 挪到 server-node 目录”，而是：

把前端里仍然承担正式真相、正式运行时解释和正式生成编排的那一层职责，继续收回到 Express 后端。