109 lines
5.0 KiB
Markdown
109 lines
5.0 KiB
Markdown
# 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 或热点入口发生明显演进，应优先更新这份文档，而不是让口径只停留在聊天记录里。
|