1
This commit is contained in:
@@ -0,0 +1,588 @@
|
||||
# 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 壳层把边界钉死，再让服务端领域迁移、编辑器归口、前端瘦身分轨并行，最后由主流程壳层统一接入。**
|
||||
Reference in New Issue
Block a user