Genarrative/docs/technical/EXPRESS_BACKEND_INTEGRATION_FREEZE_2026-04-09.md

Express 后端接口冻结与集成清单（2026-04-09）

1. 目的

这份文档补齐 docs/planning/EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md 中任务 0 缺失的仓库内产物，用来明确：

• 当前 contract 的冻结版本
• 热点文件的编辑规则
• 各类改动进入集成窗口前的最小检查清单

它不是新的重构计划，而是给当前并行改造提供一个统一落库的“不要互相踩”的边界表。

---

2. Contract 版本表

范围	当前版本	源头文件	说明
统一 API envelope	2026-04-08 / v1	packages/shared/src/http.ts	ApiResponse、错误结构、meta 字段、envelope 头约定的统一来源。
auth contract	2026-04-08	packages/shared/src/contracts/auth.ts	前后端都以 shared auth contract 识别登录、用户信息与 token 响应。
runtime snapshot/settings contract	2026-04-08	packages/shared/src/contracts/runtime.ts	存档、设置、自定义世界会话与库表相关请求/响应来源。
runtime story action contract	2026-04-08	packages/shared/src/contracts/story.ts	RuntimeStoryActionRequest/Response、Task5/Task6 function id 与 view model 来源。
Node HTTP route meta	2026-04-08	server-node/src/app.ts	/api/auth、/api/runtime/story、/api/editor、/api/assets 都以这一轮 route version 为当前冻结口径。
editor/assets route 命名空间	2026-04-08	server-node/src/modules/editor/editorRoutes.ts、server-node/src/modules/assets/**	编辑器与资产接口统一走 /api/editor/*、/api/assets/*。

---

3. 热点文件编辑规则

以下文件继续视为高冲突入口，默认不要在多个任务里并行大改：

• 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

统一规则：

• 新需求优先新增独立模块，再通过桥接或小入口接入，不要直接把逻辑堆进热点文件。
• 需要改 server-node/src/routes/runtimeRoutes.ts 时，先确认 shared contract 是否已落库，再补 route 接入。
• 需要改 src/hooks/useStoryGeneration.ts 时，优先确认是否其实应该落到 server-node/src/modules/**、src/services/runtimeStoryService.ts 或 src/hooks/story/**。
• 编辑器链路与正式运行时链路不要混在同一轮提交里。
• 如果同一轮同时碰到后端 action 与前端 UI 壳层，先冻结 action/view model，再接 UI。

---

4. 集成窗口清单

4.1 shared contract 变更

• 只在 packages/shared/** 改类型、schema、纯序列化约定。
• 同步检查 server-node/src/** 和 src/** 是否都已切到 shared contract。
• 至少跑一次 npm run server-node:test。
• 如果前端消费层也改了，再补 npm run typecheck。

4.2 runtime action / domain module 变更

• 业务规则优先写在 server-node/src/modules/**，不要直接写回前端 hook。
• 如果影响 RuntimeStoryActionResponse，同步检查 packages/shared/src/contracts/story.ts。
• 至少覆盖对应模块测试，或补到 server-node/src/modules/story/storyActionRoutes.test.ts。
• 合并前至少跑一次 npm run server-node:test。

4.3 persistence / repository / config 变更

• 只把 PostgreSQL 视为正式基线。
• 如果改到 server-node/src/db.ts、repositories/**、迁移脚本，优先确认 pg-mem 测试仍通过。
• 合并前至少跑一次 npm run server-node:test。

4.4 editor / assets 变更

• 后端入口只放在 /api/editor/*、/api/assets/*。
• 前端统一从 src/editor/shared/editorApiClient.ts 或对应 persistence 层进入。
• 不要新增旧 Vite 本地插件式散落接口。

4.5 前端壳层接入变更

• 优先消费 runtime story state / action response / shared contract，不要把正式规则写回前端。
• 如果恢复流程有改动，优先以后端 runtime state 为准。
• 若影响主流程，至少补对应 hook / view model 测试并跑 npm run typecheck。

---

5. 当前剩余非冻结区

以下几块仍处于“可继续收口但尚未完全冻结”的状态，改动时要额外小心：

• server-node/src/bridges/legacyBuildRuntimeBridge.ts
• server-node/src/bridges/legacyInventoryRuntimeBridge.ts
• server-node/src/modules/ai/storyOrchestrator.ts
• server-node/src/modules/ai/chatOrchestrator.ts
• server-node/src/modules/ai/customWorldOrchestrator.ts

它们目前仍残留一部分对 src/** 历史实现的复用，不建议在没有额外测试兜底时顺手混改。

---

6. 本轮落库结论

从 2026-04-09 起，仓库内已经具备任务 0 要求的这几类最小产物：

• contract 版本表
• 热点文件编辑规则
• 集成窗口检查清单

后续如果 shared contract、runtime action 或热点入口发生明显演进，应优先更新这份文档，而不是让口径只停留在聊天记录里。