# Express 后端并行任务完成度审计（2026-04-09） ## 1. 审计范围 本次审计以 `docs/planning/EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md` 为基准，只检查仓库内可直接验证的代码、测试、脚本和文档产物。 不能仅靠仓库静态内容确认的团队协作物，例如看板、口头冻结流程、每日集成节奏，只按“仓库内可见状态”记录，不把它们误判成完全验收。 --- ## 2. 任务完成度总览 | 任务 | 状态 | 结论 | | --- | --- | --- | | 任务 0：集成岗与接口冻结 | 基本完成 | 已补齐接口冻结与集成清单文档，contract 版本表、热点文件编辑规则、集成窗口检查项都已落库；但团队执行节奏本身仍无法仅凭仓库静态确认。 | | 任务 1：共享 Contract 与目录抽离 | 部分完成 | `packages/shared` 已建立并承接 auth/runtime/story contract，且 NPC Task6 bridge 与 chat prompt builder 已进一步下沉到后端本地模块；但 AI 编排主链仍残留少量 `src/**` 反向依赖，分层尚未完全闭合。 | | 任务 2：PostgreSQL 持久化基线收口 | 已完成 | `server-node/src/config.ts`、`db.ts`、`repositories/**`、迁移脚本、`pg-mem` 测试与部署文档均已到位。 | | 任务 3：HTTP 基础设施与统一响应壳层 | 已完成 | 统一错误格式、`requestId`、route meta、响应壳层、观测测试已落地。 | | 任务 4：服务端 AI 编排收口 | 基本完成 | orchestration 模块、SSE 转发和主链调用已回到后端，但仍有少量 prompt/规则模块通过 `src/**` 复用，属于后续继续收敛项。 | | 任务 5：Story / Combat / NPC | 已完成 | 后端 story action route、session 组装、combat/npc 领域服务和对应回归测试已落地。 | | 任务 6：Inventory / Quest / Build / Runtime Item | 已完成 | 对应模块、服务与回归测试已经覆盖主要正式运行时结算。 | | 任务 7：前端 SDK、鉴权、持久化瘦身 | 部分完成 | `apiClient`、`authService`、`storageService` 已统一，但前端仍保留一部分存档归一化和主流程协调职责。 | | 任务 8：编辑器 API 归口与工具链隔离 | 基本完成 | editor/assets 模块、前端 editor client、迁移文档均已出现，职责边界基本清晰。 | | 任务 9：测试、观测与部署基线 | 已完成 | baseline test、smoke、proxy smoke、部署与回滚清单、日志链路均已具备。 | | 任务 10：前端主流程壳层与大 Hook 瘦身 | 部分完成 | `GameShellRuntime` / `useGameShellRuntimeViewModel` 以及新的 `storyRequestCoordinator` 已拆出，但 `useStoryGeneration.ts` 仍然过重，主流程尚未彻底退回“表现层协调器”。 | --- ## 3. 本轮补齐项 本轮先补齐了任务 0 缺失的仓库内协作产物： - 新增 `docs/technical/EXPRESS_BACKEND_INTEGRATION_FREEZE_2026-04-09.md` - 落库当前 contract 版本表 - 明确热点文件编辑规则 - 补齐 shared/runtime/editor/frontend 壳层各自的集成窗口清单 这让任务 0 不再只停留在规划文档里，而是有了一份可随版本一起更新的冻结口径。 随后补上了一段此前仍偏向前端快照解释的恢复链路： - `src/hooks/story/runtimeStoryCoordinator.ts` - 新增 `resumeServerRuntimeStory` - 继续游戏时，若当前是正式运行时故事快照，会先请求 `/api/runtime/story/state/:sessionId` - 让当前 `storyText` 与可用 `options` 优先以后端 runtime state 为准 - `src/hooks/useGamePersistence.ts` - `continueSavedGame()` 现在会优先走后端 runtime story 恢复 - 如果服务端恢复失败，再回退到本地快照归一化结果 - 额外补了 `bottomTab` 归一化，避免恢复时吃到宽泛字符串 - `src/hooks/story/runtimeStoryCoordinator.test.ts` - 新增“继续游戏时优先从后端恢复 runtime story”的测试 - 新增“非正式运行时快照不额外请求后端”的测试 这次补丁对应的是任务 7 与任务 10 之间的一段未完全闭合边界：前端在恢复流程里不应该只把远端存档当作“原始 JSON 缓存”，而应优先相信后端当前 runtime state。 此外，本轮还继续补了任务 1 的一段后端分层收口： - 新增 `server-node/src/modules/runtime/runtimeStatePrimitives.ts` - 后端本地承接 `addInventoryItems` - 后端本地承接 `removeInventoryItem` - 后端本地承接 `incrementGameRuntimeStats` - 后端本地承接 `buildRelationState` - 新增 `server-node/src/modules/runtime/runtimeStatePrimitives.test.ts` - 校验背包合并、移除、运行时统计累加、关系阶段映射 - 调整桥接层： - `server-node/src/bridges/legacyInventoryRuntimeBridge.ts` - `server-node/src/bridges/legacyNpcTask6Bridge.ts` - `server-node/src/modules/quest/questTask6Bridge.ts` 这意味着任务 5/6 主链里最基础的一批状态原语，已经不再依赖前端 `src/data/runtimeStats.ts`、`src/data/attributeResolver.ts`、`src/data/npcInteractions.ts` 的对应实现。 本轮又继续把 NPC Task6 bridge 里最后一批直接挂到前端 `npcInteractions.ts` 的函数下沉到了后端本地： - 新增 `server-node/src/modules/npc/npcTask6Primitives.ts` - 后端本地承接 `applyStoryChoiceToStanceProfile` - 后端本地承接 `buildInitialNpcState` - 后端本地承接 `syncNpcTradeInventory` - 后端本地承接 `getGiftCandidates` - 后端本地承接 `buildNpcGiftCommitActionText` - 后端本地承接 `buildNpcGiftResultText` - 后端本地承接 `buildNpcTradeTransactionActionText` - 后端本地承接 `buildNpcTradeTransactionResultText` - 新增 `server-node/src/modules/npc/npcTask6Primitives.test.ts` - 覆盖 NPC 初始库存生成 - 覆盖交易库存刷新时保留非交易物品 - 覆盖赠礼偏好排序 - 调整桥接层： - `server-node/src/bridges/legacyNpcTask6Bridge.ts` 这意味着 Task6 的 NPC 交易/赠礼/初始库存这条支链，已经不再直接依赖前端 `src/data/npcInteractions.ts`。 同时还把叙事语言检测工具下沉到了共享层： - 新增 `packages/shared/src/llm/narrativeLanguage.ts` - `src/services/narrativeLanguage.ts` 改为复用共享实现 - `server-node/src/modules/ai/storyOrchestrator.ts` 改为直接依赖共享层 这部分虽然不是大块业务迁移，但它属于任务 1 最稳定的一类收口：把纯函数共识从前端目录中抽离出来。 再补充一批已经完成的后端纯原语迁移： - 新增 `server-node/src/modules/runtime/runtimeEconomyPrimitives.ts` - 后端本地承接 `formatCurrency` - 后端本地承接 `getInventoryItemValue` - 后端本地承接 `getNpcPurchasePrice` - 后端本地承接 `getNpcBuybackPrice` - 新增 `server-node/src/modules/runtime/runtimeTreasureTexts.ts` - 后端本地承接 `buildTreasureResultText` - 新增 `server-node/src/modules/runtime/runtimeEconomyPrimitives.test.ts` - 覆盖交易定价、货币文本、宝藏奖励文本 对应桥接层： - `server-node/src/bridges/legacyNpcTask6Bridge.ts` - 不再依赖前端 `src/data/economy.ts` - `server-node/src/bridges/legacyTreasureRuntimeBridge.ts` - 不再从前端导出 `buildTreasureResultText` 这说明任务 5/6 主链中一部分交易、礼物、宝藏结算反馈文本，也已经从前端数据层抽离。 本轮又进一步补了 NPC 状态与叙事记忆的后端本地原语： - 新增 `server-node/src/modules/runtime/runtimeNpcStatePrimitives.ts` - 后端本地承接 `normalizeNpcPersistentState` - 后端本地承接 `markNpcFirstMeaningfulContactResolved` - 新增 `server-node/src/modules/runtime/runtimeNarrativeMemory.ts` - 后端本地承接 `appendStoryEngineCarrierMemory` - 新增 `server-node/src/modules/runtime/runtimeNpcStatePrimitives.test.ts` - 覆盖 NPC 状态归一化、首次有效接触标记、叙事载体记忆写入 对应桥接层： - `server-node/src/bridges/legacyNpcTask6Bridge.ts` - 不再依赖前端 `src/services/storyEngine/echoMemory.ts` - 不再依赖前端 `src/data/npcInteractions.ts` 中的 NPC 状态归一化与首次接触标记逻辑 这进一步缩小了后端在任务 5/6 主链上对前端 story-engine 服务目录的借用范围。 本轮还整块收口了 Quest 与 Runtime Item 两条桥接链： - 新增 `server-node/src/modules/quest/runtimeQuestModule.ts` - 后端本地承接 `buildQuestForEncounter` - 后端本地承接 `evaluateQuestOpportunity` - 后端本地承接 `buildFallbackQuestIntent` - 后端本地承接 `compileQuestIntentToQuest` - 后端本地承接 `buildQuestGenerationContextFromState` - 后端本地承接 `buildQuestIntentPrompt` - 后端本地承接 Quest 进度归一化与 signal 推进 - 更新桥接层： - `server-node/src/bridges/legacyQuestProgressBridge.ts` - `server-node/src/bridges/legacyQuestRuntimeBridge.ts` 这意味着 Quest 的“确定性委托构建 + AI 意图上下文 + 任务推进”已经不再依赖前端 `src/data/questFlow.ts`、`src/services/questDirector.ts`、`src/services/questPrompt.ts`。 同时，Runtime Item 也已经收回到后端本地： - 新增 `server-node/src/modules/runtime-item/runtimeItemModule.ts` - 后端本地承接 `buildRuntimeItemAiIntent` - 后端本地承接 `buildRuntimeItemIntentPrompt` - 后端本地承接 `buildLooseRuntimeItemGenerationContext` - 后端本地承接 `buildQuestRuntimeItemGenerationContext` - 后端本地承接 `buildDirectedRuntimeReward` - 后端本地承接 `buildRuntimeInventoryStock` - 后端本地承接 `flattenDirectedRuntimeRewardItems` - 新增 `server-node/src/modules/runtime-item/runtimeTreasureModule.ts` - 后端本地承接 `resolveTreasureReward` - 更新桥接层： - `server-node/src/bridges/legacyRuntimeItemBridge.ts` - `server-node/src/bridges/legacyRuntimeItemResolutionBridge.ts` - `server-node/src/bridges/legacyTreasureRuntimeBridge.ts` 这说明 Runtime Item / Treasure 相关的 AI 意图、奖励生成和库存生成，也已经从前端目录中抽离。 本轮还继续整块收口了 Build / Inventory / Forge / Equipment 规则桥接： - 新增 `server-node/src/modules/runtime/runtimeEquipmentModule.ts` - 后端本地承接 `getEquipmentSlotFromItem` - 后端本地承接 `getEquipmentSlotLabel` - 后端本地承接 `getEquipmentBonuses` - 后端本地承接 `applyEquipmentLoadoutToState` - 新增 `server-node/src/modules/runtime/runtimeInventoryEffectsModule.ts` - 后端本地承接 `isInventoryItemUsable` - 后端本地承接 `resolveInventoryItemUseEffect` - 后端本地承接 `buildInventoryUseResultText` - 新增 `server-node/src/modules/runtime/runtimeForgeModule.ts` - 后端本地承接 `getForgeRecipeViews` - 后端本地承接 `executeForgeRecipe` - 后端本地承接 `executeDismantleItem` - 后端本地承接 `executeReforgeItem` - 后端本地承接 `getReforgeCostView` - 后端本地承接 `buildForgeSuccessText` - 新增 `server-node/src/modules/runtime/runtimeBuildModule.ts` - 后端本地承接 `appendBuildBuffs` - 后端本地承接 `getPlayerBuildDamageBreakdown` - 后端本地承接 `resolvePlayerOutgoingDamageResult` 对应桥接层： - `server-node/src/bridges/legacyBuildRuntimeBridge.ts` - `server-node/src/bridges/legacyInventoryRuntimeBridge.ts` 这意味着 Build / Inventory / Forge / Equipment 相关的后端主链结算，已经不再依赖前端 `src/data/buildDamage.ts`、`src/data/equipmentEffects.ts`、`src/data/forgeSystem.ts`、`src/data/inventoryEffects.ts`。 本轮又补了一段任务 1 的 AI 编排收口： - 新增 `server-node/src/modules/ai/chatPromptBuilders.ts` - 后端本地承接 character chat reply / suggestions / summary prompt 组装 - 后端本地承接 npc chat / recruit prompt 组装 - 调整： - `server-node/src/modules/ai/chatOrchestrator.ts` - `server-node/src/modules/ai/orchestrator.test.ts` 这意味着 chat orchestration 已不再依赖前端 `src/services/characterChatPrompt.ts` 与 `src/services/prompt.ts`。 本轮继续把 story orchestration 主链也收回到了后端本地： - 新增 `server-node/src/modules/ai/storyPromptBuilders.ts` - 后端本地承接 `SYSTEM_PROMPT` - 后端本地承接 `buildUserPrompt` - 重写 `server-node/src/modules/ai/storyOrchestrator.ts` - 正式生产链不再依赖前端 `src/services/prompt.ts` - 正式生产链不再依赖前端 `src/data/stateFunctions.ts` - 正式生产链不再依赖前端 `src/data/scenePresets.ts` - 正式生产链不再依赖前端 `src/data/hostileNpcs.ts` - 调整： - `server-node/src/modules/ai/orchestrator.test.ts` 到这里，`server-node` 正式生产代码路径里，Story / Chat / Quest / Runtime Item / Treasure / Build / Inventory / Forge / NPC Task6 主链都已经从前端 `src/**` 目录脱钩。 本轮也继续推进了任务 10 的主流程瘦身： - 新增 `src/hooks/story/storyRequestCoordinator.ts` - 抽离运行时 option source 解析 - 抽离服务端 option catalog 回退策略 - 抽离 initial / next story 请求参数协调 - 新增 `src/hooks/story/storyRequestCoordinator.test.ts` - 覆盖服务端 option catalog 切换 - 覆盖显式 option catalog 短路 - 覆盖服务端目录加载失败时回退本地可用项 - 调整： - `src/hooks/useStoryGeneration.ts` 这说明 `useStoryGeneration.ts` 虽然仍重，但“故事请求协调”已经不再和主流程 UI 状态、NPC/战斗/宝藏后续处理混在同一个大段里。 本轮又补了一段任务 10 的纯展示逻辑拆分： - 新增 `src/hooks/story/storyPresentation.ts` - 抽离 story options 去重与补齐 - 抽离对白 turn 解析 - 抽离 dialogue story moment 组装 - 抽离 typewriter delay - 新增 `src/hooks/story/storyPresentation.test.ts` - 覆盖对白解析与 dialogue story moment - 覆盖选项池去重与补齐 - 调整： - `src/hooks/useStoryGeneration.ts` 这意味着 `useStoryGeneration.ts` 又减少了一批与 React 状态本身无关的纯函数逻辑，任务 10 的主流程壳层拆分继续向前推进。 本轮还补上了任务 1 的最后一条后端反向依赖： - 删除 `server-node/src/bridges/legacyCustomWorldAiBridge.ts` - 重写 `server-node/src/modules/ai/customWorldOrchestrator.ts` - 后端本地承接 custom world generation 的 deterministic 生成流程 - 后端本地承接 generation progress 汇报 这意味着 `server-node/src/**` 的正式生产代码路径已经不再反向依赖前端 `src/**` 目录。 --- ## 4. 仍需继续收口的重点 ### 4.1 任务 1 的剩余问题 当前从仓库内直接扫描看，`server-node/src/**` 的正式生产代码路径已经不再存在对前端 `src/**` 的反向依赖。 其中 Story / Chat / Quest / Runtime Item / Treasure / Build / Inventory / Forge / Equipment / NPC Task6 / Custom World generation 相关正式生产链都已经从这个列表中退出。 同时，`server-node/src/modules/ai/orchestrator.test.ts` 已不再直接依赖前端 `src/services/prompt.ts` 与 `src/data/stateFunctions.ts`。 这说明任务 1 在“后端正式生产运行时不反向依赖前端目录”这一层面已经完成。 #### 4.1.1 当前残留依赖的真实形态 从当前状态看，任务 1 后续不再是“补洞”，而是“优化”： - 继续提高 custom world generation 的质量与保真度 - 继续把真正通用的 prompt / JSON repair / batch helper 整理进 `packages/shared` 或 `server-node/src/modules/ai/**` - 维持后端不再回流引用前端目录的约束 #### 4.1.2 更适合的继续收口顺序 结合当前状态，任务 1 后续更适合做的是能力优化： 1. 继续增强 custom world generation 的语义保真度与校验强度。 2. 继续把 prompt builder、JSON repair、批处理工具整理到 `packages/shared` 或 `server-node/src/modules/ai/**`。 3. 持续维持“后端正式生产代码不反向依赖前端目录”的约束，避免后续重新开洞。 ### 4.2 任务 7 的剩余问题 前端虽然已经大量改成 SDK 消费层，但 `src/persistence/runtimeSnapshot.ts` 里仍保留较重的存档归一化与迁移修复逻辑。 这部分后续仍建议继续向后端迁移，避免前后端双边解释快照。 #### 4.2.1 `runtimeSnapshot.ts` 当前仍承担的职责 从文件本身看，`src/persistence/runtimeSnapshot.ts` 仍不是一个单纯的“读取后端结果并转成 UI 状态”的轻薄消费层。 它当前仍直接负责： - 存档迁移 manifest 应用 - roster 归一化 - player currency 默认值补齐 - equipment loadout 回填与属性重算 - NPC persistent state 归一化 - quest log 归一化 - runtime stats 归一化 - scene encounter preview 修复 - story engine memory 缺省补齐 这说明任务 7 的剩余问题，不只是“前端还有一点 normalize 代码”，而是： - 前端仍在解释正式存档的结构语义 - 前端仍在决定若干正式运行时字段的缺省和修复策略 - 后端与前端之间仍存在“双边都能定义快照有效形态”的空间 #### 4.2.2 下一步更合适的迁移方向 结合本轮已经补上的“继续游戏优先以后端 runtime story state 为准”这段恢复链路，任务 7 后续更适合继续向这个方向推进： 1. 把 `runtimeSnapshot.ts` 中的迁移、归一化、缺省补齐继续下沉到后端持久化层或专门的 runtime snapshot service。 2. 让前端拿到的远端快照尽量已经是“可直接消费的正式形态”，而不是“仍需前端补算的半成品”。 3. 把前端保留的本地 hydrate 逻辑收缩到纯 UI 恢复字段，例如当前页签、面板开合、局部显示态。 只有这样，任务 7 才算真正回到“前端只做消费层，后端才是正式状态解释者”的目标。 ### 4.3 任务 10 的剩余问题 当前最大的未完成项仍然是： - `src/hooks/useStoryGeneration.ts` 它仍承担了大量： - 正式运行时故事编排 - 本地 fallback 组织 - NPC / 宝藏 / 战斗后续协调 - 主流程状态推进 现阶段虽然已经有： - `src/hooks/useGameShellRuntime.ts` - `src/components/game-shell/useGameShellRuntimeViewModel.ts` - `src/hooks/story/runtimeStoryCoordinator.ts` - `src/hooks/story/storyRequestCoordinator.ts` 但主流程还没有彻底完成 action/view model 化，任务 10 仍应视为“进行中”。 #### 4.3.1 `useStoryGeneration.ts` 当前仍然为什么过重 从仓库现状看，`src/hooks/useStoryGeneration.ts` 目前仍有约 1700 行，且其过重问题已经不是单纯“文件太长”，而是它还保留着大量正式业务协调职责。 当前这个 hook 里仍集中着： - `buildStoryContextFromState` 这一整块故事上下文拼装 - AI 请求前的 option catalog / fallback 组织 - NPC / 宝藏 / 战斗 / inventory / goal / session 多条子链的集中协调 - 本地 fallback story 生成 - 一部分运行时规则与 narrative context 的最终拼装入口 这意味着即使已经拆出了： - `runtimeStoryCoordinator` - `storyRequestCoordinator` - `choiceActions` - `npcEncounterActions` - `sessionActions` `useStoryGeneration.ts` 仍然不是“单纯的 UI 壳层 hook”，而更像前端侧的运行时总协调器。 #### 4.3.2 任务 10 后续更值得优先拆的部分 按当前文件结构看，后续最值得优先继续抽离的不是零散按钮逻辑，而是下面三类真正还握在主 hook 里的核心块： 1. `buildStoryContextFromState` 这一整块 story-engine 叙事上下文装配。 2. `buildFallbackStoryForState` / `getAvailableOptionsForState` 这类“正式规则兜底与选项来源判断”。 3. NPC / Treasure / Character Chat / Session 这些子流之间的最终总装协调。 如果只是继续把零散函数拆到 `src/hooks/story/**`，但上述三块还留在主 hook 里，那么任务 10 仍然不会真正完成。 ### 4.4 建议的下一轮补齐顺序 结合任务 1、任务 7、任务 10 当前的剩余形态，后续更合适的补齐顺序建议是： 1. 先继续收任务 7 的 runtime snapshot 解释权，把正式快照的迁移、修复、归一化口径继续回收到后端。 2. 再继续收任务 10，把 `useStoryGeneration.ts` 压回主流程协调壳层，而不是继续让它承担正式运行时总装职责。 这样排的原因是： - 任务 1 已经完成后，新的主阻塞就变成了任务 7 和任务 10。 - 如果任务 7 不继续收，前端仍会在恢复链路里保留正式状态解释权，任务 10 也很难真正变薄。 - 等到 runtime state 与 snapshot 口径都更稳定后，再继续瘦 `useStoryGeneration.ts`，返工会更少。 --- ## 5. 本轮验证 已通过： - `npm run server-node:test` - `npx vitest run src/hooks/story/storyRequestCoordinator.test.ts src/hooks/story/runtimeStoryCoordinator.test.ts` - `npm run typecheck` - `npm run check:encoding` --- ## 6. 结论 从仓库可验证结果看，任务 2、3、5、6、9 已经达到“可认为完成”的状态；任务 0、4、8 基本完成；任务 1、7、10 仍有明显后续收口空间。 当前最主要的未完成中心已经不再是后端基建，而是： **把前端主流程和存档恢复彻底收成“以后端 runtime state 和 view model 为唯一真相源”。**