1
This commit is contained in:
@@ -0,0 +1,169 @@
|
||||
# 前端逻辑后移实施方案（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 后端。**
|
||||
Reference in New Issue
Block a user