# Express 后端化并行任务拆分规划（2026-04-08）

## 1. 目的

这份文档用于把 [EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md](./EXPRESS_BACKEND_REFACTOR_PLAN_2026-04-08.md) 进一步拆成可并行推进、尽量互不冲突的任务流。

目标不是把大重构拆成很多零碎 TODO，而是把它拆成：

- 可以同时开工
- 写入边界清晰
- 交付物明确
- 依赖关系稳定
- 最后容易集成

---

## 2. 并行拆分原则

## 2.1 基本原则

- 每条任务尽量拥有独占目录或独占模块，不去抢同一批热点文件。
- 热点集成文件只由“集成岗”或最后一轮集成处理，不作为多个任务的日常编辑目标。
- 先搭协议边界，再迁规则执行，再收缩前端。
- 前端与后端可以并行推进，但前提是先冻结 contract。
- 编辑器链路和正式运行时链路分开拆，避免互相阻塞。

## 2.2 当前最容易冲突的文件

以下文件建议默认只由集成岗或最后一轮联调处理：

- `server-node/src/context.ts`
- `server-node/src/routes/runtimeRoutes.ts`
- `server-node/src/app.ts`
- `src/services/apiClient.ts`
- `src/hooks/useStoryGeneration.ts`
- `src/hooks/useGameFlow.ts`
- `src/components/GameShell.tsx`

其他任务如果必须影响这些文件，优先通过：

- 新增独立模块
- 新增 adapter
- 新增中间层入口

而不是直接在热点文件中大改。

---

## 3. 建议并行批次

## 批次 A：可立即并行开工

- 任务 0：集成岗与接口冻结
- 任务 1：共享 contract 与目录抽离
- 任务 2：PostgreSQL 持久化基线收口
- 任务 3：服务端 HTTP 基础设施与统一响应壳层
- 任务 8：编辑器 API 归口与工具链隔离
- 任务 9：测试、观测与部署基线

## 批次 B：在 contract 初版落地后并行开工

- 任务 4：服务端 AI 编排收口
- 任务 5：运行时领域模块 A，Story / Combat / NPC
- 任务 6：运行时领域模块 B，Inventory / Quest / Build / Runtime Item
- 任务 7：前端 SDK、鉴权、持久化瘦身

## 批次 C：在服务端 action 和 view model 稳定后开工

- 任务 10：前端主流程壳层与大 hook 瘦身

---

## 4. 任务拆分

## 任务 0：集成岗与接口冻结

### 目标

负责冻结边界、维护接口文档、控制热点文件的合并节奏，避免多人同时改核心入口。

### 独占范围

- `docs/planning/**`
- `docs/technical/**`
- 最终集成时的热点入口文件

### 主要输出

- 统一任务看板
- contract 版本表
- 热点文件编辑规则
- 每日或每阶段集成清单

### 验收标准

- 团队知道哪些文件不能多人同时改
- 每条任务都有明确的上游 contract 与下游接入点

---

## 任务 1：共享 Contract 与目录抽离

### 目标

先把前后端共同识别的类型、schema、响应结构、错误结构抽出来，切断 `server-node -> src/**` 的长期反向依赖。

### 独占范围

- `packages/shared/**`
- 新建的共享类型、schema、contract 目录

### 可改边界

- `server-node/src/**` 中的 import 替换入口
- `src/**` 中的 import 替换入口

### 暂不负责

- 具体业务规则迁移
- 前端页面行为调整
- 数据库实现细节

### 主要输出

- 统一 API envelope
- 统一错误对象
- 统一 action / response contract
- 统一领域类型和状态枚举

### 验收标准

- 新增服务端模块不需要继续直接依赖前端目录里的实现细节
- 前后端都以共享 contract 为边界协作

### 并行关系

- 可与任务 2、任务 3、任务 8、任务 9 同时启动
- 是任务 4、任务 5、任务 6、任务 7 的上游基础

---

## 任务 2：PostgreSQL 持久化基线收口

### 目标

把“已经切到 PostgreSQL”的状态收成真正稳定的后端基线，清掉 SQLite 残留口径与仓储层耦合问题。

### 独占范围

- `server-node/src/config.ts`
- `server-node/src/db.ts`
- `server-node/src/repositories/**`
- `server-node/src/app.test.ts`
- `.env.example`

### 暂不负责

- 剧情规则
- 选项结算
- 前端状态瘦身

### 主要输出

- PostgreSQL 连接配置
- 仓储层接口统一
- 数据表初始化/迁移方案
- 运行时持久化测试基线
- 文档中的数据库现状统一

### 验收标准

- 后端运行时数据完全以后端数据库为准
- 配置、日志、测试、文档里不再把 SQLite 写成当前正式现状

### 并行关系

- 可与任务 1、任务 3、任务 8、任务 9 同时启动
- 为任务 5、任务 6、任务 7 提供稳定持久化基础

---

## 任务 3：服务端 HTTP 基础设施与统一响应壳层

### 目标

建立统一的服务端响应结构、错误结构、请求链路日志、版本字段和中间件壳层。

### 独占范围

- `server-node/src/http.ts`
- `server-node/src/errors.ts`
- `server-node/src/middleware/**`
- `server-node/src/app.ts`

### 可改边界

- 为 route 层提供新的响应 helper
- 为后续 action 接口提供统一 envelope

### 暂不负责

- 具体 story / combat / quest 业务逻辑
- 前端页面层接入

### 主要输出

- 统一 JSON 响应格式
- 统一错误格式
- `requestId`
- `latency` 与关键日志字段
- 路由级版本与元信息壳层

### 验收标准

- 后端所有新接口都能套用同一层响应约定
- 前端不需要为不同接口写多套错误解析逻辑

### 并行关系

- 可与任务 1、任务 2、任务 8、任务 9 同时启动
- 是任务 4、任务 5、任务 6、任务 7 的共同基础

---

## 任务 4：服务端 AI 编排收口

### 目标

把正式运行时的 prompt 组装、模型调用、容错、SSE 转发都收回后端，浏览器不再保留正式运行时 AI fallback。

### 独占范围

- `server-node/src/services/llmClient.ts`
- `server-node/src/services/chatService.ts`
- `server-node/src/services/storyService.ts`
- `server-node/src/services/customWorldGenerationService.ts`
- `server-node/src/services/questService.ts`
- `server-node/src/services/runtimeItemService.ts`

### 可新增目录

- `server-node/src/modules/ai/**`

### 暂不负责

- 前端主流程组件
- 数据库存储实现

### 主要输出

- 后端统一 AI orchestration 层
- 流式接口统一适配
- prompt 复用策略
- 前端 fallback 清理清单

### 验收标准

- 正式运行时不再依赖浏览器端大体量 AI 实现作为兜底
- AI 失败、超时、流式中断都能在后端统一处理

### 并行关系

- 建议在任务 1、任务 3 有初版后启动
- 可与任务 5、任务 6、任务 7 并行

---

## 任务 5：运行时领域模块 A，Story / Combat / NPC

### 目标

把剧情推进、战斗结算、NPC 交互这些最核心的运行时状态迁移到后端领域模块。

### 独占范围

- `server-node/src/modules/story/**`
- `server-node/src/modules/combat/**`
- `server-node/src/modules/npc/**`

### 可改边界

- 为 route/action 层提供服务接口
- 为前端提供 view model 所需聚合结果

### 暂不负责

- 背包、Build、任务奖励编排
- 编辑器接口

### 主要输出

- story action resolver
- combat resolution service
- npc interaction service
- 统一返回给 UI 的 presentation/view model 结构

### 验收标准

- 前端不再本地决定 function 合法性、战斗结果、NPC 关键关系变化
- 点击选项时，后端能返回完整下一步展示结果

### 并行关系

- 依赖任务 1、任务 3
- 可与任务 4、任务 6、任务 7 并行

---

## 任务 6：运行时领域模块 B，Inventory / Quest / Build / Runtime Item

### 目标

把任务推进、运行时物品、背包/装备、Build 收益等剩余核心规则迁到后端。

### 独占范围

- `server-node/src/modules/inventory/**`
- `server-node/src/modules/quest/**`
- `server-node/src/modules/build/**`
- `server-node/src/modules/runtime-item/**`

### 可改边界

- 调用任务 2 的仓储层
- 使用任务 1 的共享 contract

### 暂不负责

- 前端页面层改造
- Story / Combat / NPC 主链路

### 主要输出

- inventory mutation service
- quest signal progression service
- build calculation service
- runtime item resolution service

### 验收标准

- 背包、任务、Build、运行时物品不再由前端保留正式结算逻辑
- 这些领域能独立测试，不依赖 UI hook

### 并行关系

- 依赖任务 1、任务 2、任务 3
- 可与任务 4、任务 5、任务 7 并行

---

## 任务 7：前端 SDK、鉴权、持久化瘦身

### 目标

让前端从“业务执行层”退回“API 消费层 + 表现层状态协调层”。

### 独占范围

- `src/services/apiClient.ts`
- `src/services/authService.ts`
- `src/services/storageService.ts`
- `src/services/aiService.ts`
- `src/hooks/useGamePersistence.ts`
- `src/hooks/useGameSettings.ts`

### 暂不负责

- 页面组件大范围重构
- `useStoryGeneration.ts` 主流程瘦身

### 主要输出

- 轻量前端 SDK
- 统一鉴权请求层
- 统一错误态与重试策略
- 远端快照/设置消费层
- 正式运行时浏览器 fallback 下线方案

### 验收标准

- 前端服务层不再保留完整正式规则或正式 AI 编排
- 存档与设置以后端返回结果为准

### 并行关系

- 依赖任务 1、任务 3
- 可与任务 4、任务 5、任务 6 并行
- 为任务 10 提供稳定的 API 消费层

---

## 任务 8：编辑器 API 归口与工具链隔离

### 目标

把编辑器的写盘、生成、任务查询能力从“散落接口”整理成清晰的编辑器后端模块，避免继续污染正式运行时。

### 独占范围

- `src/editor/shared/**`
- `src/components/preset-editor/**`
- `src/components/npcVisualEditorPersistence.ts`
- `src/components/preset-editor/characterAssetStudioPersistence.ts`
- `scripts/dev-server/**`
- `server-node/src/modules/editor/**`
- `server-node/src/modules/assets/**`

### 暂不负责

- 主游戏运行时 action 逻辑
- 正式剧情流转

### 主要输出

- `/api/editor/*` 与 `/api/assets/*` 命名空间
- 统一 editor client SDK
- 写接口权限边界
- 编辑器工具链迁移清单

### 验收标准

- 编辑器组件不再散落直连多个写接口
- 编辑器 API 与运行时 API 的职责边界清晰

### 并行关系

- 可与任务 1、任务 2、任务 3、任务 9 同时启动
- 与任务 5、任务 6、任务 10 基本不冲突

---

## 任务 9：测试、观测与部署基线

### 目标

为整个后端化改造提供自动回归、链路日志和部署基线，避免“功能迁过去了但不可验证”。

### 独占范围

- `server-node/src/**/*.test.ts`
- `scripts/**`
- 部署与运维相关文档
- 反向代理与 smoke 测试脚本

### 暂不负责

- 具体业务模块实现

### 主要输出

- 后端接口测试
- 关键主链路 smoke
- request/response 日志校验
- 同域部署基线
- 回滚、备份、迁移检查清单

### 验收标准

- `web + server` 改造过程有最小自动回归保护
- 关键接口失败时能追踪到请求链路

### 并行关系

- 可与任务 1、任务 2、任务 3、任务 8 同时启动
- 后续持续跟进任务 4、任务 5、任务 6、任务 7、任务 10 的交付

---

## 任务 10：前端主流程壳层与大 Hook 瘦身

### 目标

在服务端 action 和前端 SDK 稳定后，把 `GameShell`、`useStoryGeneration` 这一层改成真正的表现层协调器。

### 独占范围

- `src/hooks/useStoryGeneration.ts`
- `src/hooks/story/**`
- `src/hooks/useGameFlow.ts`
- `src/components/GameShell.tsx`
- `src/components/AdventurePanel.tsx`
- `src/components/NpcModals.tsx`
- `src/components/auth/**`

### 暂不负责

- 数据库、服务端仓储
- 编辑器 API

### 主要输出

- 面向 action/view model 的前端流程层
- 页面表现态与业务态分离
- 大 hook 拆分后的协调层
- 更容易测试和替换的主流程壳层

### 验收标准

- 前端主流程不再直接吞下完整运行时规则
- 页面层主要消费后端 view model，而不是本地自算结果

### 并行关系

- 依赖任务 5、任务 6、任务 7 至少有一轮稳定输出
- 是最后一批大规模前端接入任务

---

## 5. 推荐协作顺序

## 第一步：先定边界

先启动：

- 任务 0
- 任务 1
- 任务 2
- 任务 3

这一轮完成后，团队会得到：

- 统一 contract
- 稳定数据库基线
- 稳定后端响应壳层
- 稳定任务分工边界

## 第二步：领域层和工具层分头推进

在第一步基础上并行启动：

- 任务 4
- 任务 5
- 任务 6
- 任务 7
- 任务 8
- 任务 9

这一轮是整个改造的主生产阶段。

## 第三步：最后收前端主流程

最后启动：

- 任务 10

原因很简单：

- 如果太早改 `useStoryGeneration` 和 `GameShell`，前端还没有稳定的 action contract 和 view model，会反复返工。

---

## 6. 建议的多人分工方式

如果是 4 人并行，建议：

- 1 人负责任务 1 + 任务 0 的 contract/集成
- 1 人负责任务 2 + 任务 3 的后端基建
- 1 人负责任务 4 + 任务 5 的运行时主链
- 1 人负责任务 8 + 任务 9，之后转入任务 7 或任务 10

如果是 6 人并行，建议：

- 1 人负责任务 0 + 任务 1
- 1 人负责任务 2
- 1 人负责任务 3 + 任务 9
- 1 人负责任务 4
- 1 人负责任务 5
- 1 人负责任务 6 + 任务 8

前端主流程任务 10 建议在第二轮由最熟悉当前 UI 壳层的人接手。

---

## 7. 合并规则建议

- 每条任务优先新增目录和新模块，少直接改热点文件。
- 热点文件统一在集成窗口合并，不在多个任务里同步推进。
- 任何任务如果需要改 `useStoryGeneration.ts`，默认先暂停并和任务 10 对齐。
- 任何任务如果需要改 `server-node/src/routes/runtimeRoutes.ts`，默认先走任务 0 的接口冻结表。
- 编辑器链路和正式运行时链路不要混在同一个 PR 里。

---

## 8. 一句话结论

这次重构最稳的并行方式不是“大家一起改前后端”，而是：

**先用 contract、数据库基线和 HTTP 壳层把边界钉死，再让服务端领域迁移、编辑器归口、前端瘦身分轨并行，最后由主流程壳层统一接入。**