Genarrative/docs/planning/EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md

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

1. 目的

这份文档用于把 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 壳层把边界钉死，再让服务端领域迁移、编辑器归口、前端瘦身分轨并行，最后由主流程壳层统一接入。