1

2026-04-16 15:45:00 +08:00
parent 6363267bca
commit 91b63675eb
43 changed files with 5652 additions and 853 deletions
--- a/docs/audits/FUNCTION_RUNTIME_FULL_TEST_AUDIT_2026-04-16.md
+++ b/docs/audits/FUNCTION_RUNTIME_FULL_TEST_AUDIT_2026-04-16.md
@@ -0,0 +1,212 @@
+# Function 运行时完整测试审计（2026-04-16）
+
+## 1. 本次目标
+
+本次不是泛泛地跑一遍前端页面，而是围绕“游戏运行中的 function 主链路”做系统化核查，重点确认下面 4 件事：
+
+- 当前运行时 function 集合是否还能正确构建、过滤、排序和解析。
+- function 命中的前端承接链路是否仍然稳定。
+- 已服务端化的 runtime action function 是否还能闭环执行。
+- 工程门禁是否处于可持续回归的状态。
+
+## 2. 本次实际覆盖范围
+
+本轮重点覆盖了这些实现入口：
+
+- `src/data/stateFunctions.ts`
+- `src/data/functionCatalog/**`
+- `src/data/npcInteractions.ts`
+- `src/hooks/story/**`
+- `src/services/runtimeStoryService.ts`
+- `src/hooks/useGameFlow.ts`
+- `server-node/src/modules/story/**`
+- `server-node/src/modules/inventory/**`
+- `server-node/src/modules/runtime-item/**`
+- `server-node/src/modules/quest/**`
+- `scripts/smoke-server-node.ts`
+
+## 3. 实际执行的测试与检查
+
+### 3.1 前端 Vitest 全量测试
+
+执行命令：
+
+```bash
+npm.cmd test
+```
+
+结果：
+
+- `110` 个测试文件全部通过
+- `276` 条测试全部通过
+
+其中与 function 主链路直接相关、并已确认通过的测试包括：
+
+- `src/data/stateFunctions.test.ts`
+- `src/data/functionCatalog/functionCatalog.test.ts`
+- `src/data/npcInteractions.test.ts`
+- `src/hooks/story/choiceActions.test.ts`
+- `src/hooks/story/storyGenerationState.test.ts`
+- `src/hooks/story/runtimeStoryCoordinator.test.ts`
+- `src/components/AdventurePanel.test.tsx`
+- `src/services/runtimeStoryService.test.ts`
+
+补充说明：
+
+- 运行 `hostileNpcPresets.test.ts` 时会看到 “network disabled in test” 的日志。
+- 这不是本轮失败项，测试已验证在 LLM 不可达时会正确走 deterministic fallback。
+
+### 3.2 内容数据校验
+
+执行命令：
+
+```bash
+npm.cmd run check:content
+```
+
+结果：
+
+- `check:data` 通过
+- `check:overrides` 通过
+- `check:smoke` 通过
+- 输出为：`Content validation passed. scenes=24 monsters=16 characters=5 functions=12`
+
+结论：
+
+- 当前基础内容数据、override 与 smoke 内容校验没有发现新的 function 数据层问题。
+
+### 3.3 服务端测试
+
+执行命令：
+
+```bash
+npm.cmd run server-node:test
+```
+
+结果：
+
+- `108` 条服务端测试全部通过
+
+本轮已确认通过的 function 相关服务端能力包括：
+
+- `inventory_use`
+- `equipment_equip`
+- `npc_trade`
+- `npc_gift`
+- `npc_quest_accept`
+- `npc_quest_turn_in`
+- `treasure_inspect`
+- 战斗结算与 quest signal 推进
+
+结论：
+
+- 已服务端化的 runtime function 承接链路当前单测层面是稳定的。
+
+### 3.4 服务端 smoke
+
+执行命令：
+
+```bash
+npm.cmd run server-node:smoke
+```
+
+结果：
+
+- 失败
+- 报错：
+
+```text
+TypeError: Cannot read properties of undefined (reading 'enabled')
+```
+
+### 3.5 TypeScript 类型检查
+
+执行命令：
+
+```bash
+npm.cmd run typecheck
+```
+
+结果：
+
+- 失败
+- 失败位置：
+  - `src/hooks/useGameFlow.ts:339`
+
+### 3.6 生产构建
+
+执行命令：
+
+```bash
+npm.cmd run build
+```
+
+结果：
+
+- 通过
+
+结论：
+
+- 当前代码可构建，但并不代表类型门禁与 smoke 门禁同样健康。
+
+## 4. 本轮确认的问题
+
+## P1：`server-node:smoke` 已失效，无法完成服务端运行时冒烟验证
+
+- 现象：
+  - `npm.cmd run server-node:smoke` 无法启动临时 Express 服务，直接在 `createSmsVerificationService` 处报错。
+- 直接原因：
+  - [`scripts/smoke-server-node.ts`](../../scripts/smoke-server-node.ts) 里的 `createSmokeConfig()` 只构造了 `llm`、`dashScope` 等字段，没有补齐后续新增的 `smsAuth`、`wechatAuth`、`authSession` 配置块。
+  - [`server-node/src/config.ts`](../../server-node/src/config.ts) 中 `AppConfig` 已把这些字段定义为必需项。
+  - [`server-node/src/services/smsVerificationService.ts`](../../server-node/src/services/smsVerificationService.ts) 在 `createSmsVerificationService` 中直接读取 `config.smsAuth.enabled`，因此 smoke 配置一进入 `createAppContext` 就会崩。
+- 影响：
+  - 本地无法再用 smoke 脚本验证“服务端真实启动 + 认证 + runtime save/settings 回路”。
+  - 这会让 function 服务端化之后的真实接线路径少掉一层最接近运行时的保护。
+- 判断：
+  - 这是本轮最明确、最稳定复现的真实 bug。
+
+## P1：`typecheck` 门禁已破，`useGameFlow` 的 starter inventory 合并存在类型漂移
+
+- 现象：
+  - `npm.cmd run typecheck` 在 [`src/hooks/useGameFlow.ts`](../../src/hooks/useGameFlow.ts) 第 `339` 行失败。
+- 直接原因：
+  - 同文件中的 `mergeStarterInventoryItems<T extends { category: string; name: string }>` 会优先从显式 starter item 推断出一个“字段更严格”的 `T`。
+  - 但 fallback 侧传入的是 [`InventoryItem`](../../src/types/items.ts) 数组，而 `InventoryItem.description`、`equipmentSlotId`、`runtimeMetadata` 等字段本身是可选的。
+  - 于是 `explicitItems` 与 `fallbackItems` 在泛型推断后不再兼容，类型门禁被打穿。
+- 影响：
+  - 当前 starter inventory 初始化链路虽然能跑、也能通过构建，但已经失去 TypeScript 对结构一致性的保护。
+  - 这类问题后续很容易演变成“自定义世界显式初始物品”和“默认初始物品”在字段形态上继续分叉。
+- 判断：
+  - 这是一个真实的工程 bug，优先级高于纯测试文案问题。
+
+## 5. 本轮已确认通过的结论
+
+- state function 运行时构建、过滤、优先级、选项解析当前测试全绿。
+- function catalog 文档映射、helper option、trade/gift/recruit modal helper 当前测试全绿。
+- 前端 function 主链路相关测试在最新工作区状态下已全部通过。
+- 服务端 runtime story action、inventory、runtime-item、quest 承接链路当前测试全绿。
+- 内容数据层校验通过。
+- 生产构建通过。
+
+## 6. 结论
+
+如果只看“游戏运行中的 function 主链路”，当前结论是：
+
+- 前端 function 运行时逻辑：通过
+- 服务端 function action 承接：通过
+- 内容数据与 function 基础目录：通过
+- 工程回归门禁：不完整
+
+当前最需要处理的不是再扩 function 范围，而是先修复这两个门禁缺口：
+
+1. 修好 `server-node:smoke` 的配置构造，让服务端冒烟恢复可用。
+2. 修好 `useGameFlow` 的 starter inventory 类型漂移，让 `typecheck` 回到绿色基线。
+
+## 7. 备注
+
+本轮没有做两类事情：
+
+- 没有接入真实外部 LLM 做在线回归，本轮依赖的是本地测试里已有的 fallback 断言。
+- 没有人手逐个点击整局游戏所有 function 的视觉回放，本轮重点是自动化测试、服务端测试、内容校验与 smoke 门禁。
+
+因此，本审计可以说明“当前 function 系统的自动化测试层状况”，但不等于“所有视觉演出与在线模型联动都已人工验证完毕”。
--- a/docs/audits/README.md
+++ b/docs/audits/README.md
@@ -12,6 +12,7 @@
 - [FUNCTION_DESIGN_AUDIT_2026-04-03.md](./FUNCTION_DESIGN_AUDIT_2026-04-03.md)：Function 体系分层、职责边界和当前结构问题。
 - [FUNCTION_REQUIREMENT_COMPLETENESS_AUDIT_2026-04-14.md](./FUNCTION_REQUIREMENT_COMPLETENESS_AUDIT_2026-04-14.md)：Function 相关文档需求与当前实现对齐核查。
 - [FUNCTION_TEST_AUDIT_2026-04-14.md](./FUNCTION_TEST_AUDIT_2026-04-14.md)：Function 运行时测试补充、已确认 bug 与当前验证结果。
+- [FUNCTION_RUNTIME_FULL_TEST_AUDIT_2026-04-16.md](./FUNCTION_RUNTIME_FULL_TEST_AUDIT_2026-04-16.md)：Function 运行时完整测试、服务端承接验证与当前门禁缺口。
 - [ITEM_AND_BUILD_PRD_AUDIT_2026-04-05.md](./ITEM_AND_BUILD_PRD_AUDIT_2026-04-05.md)：物品生成与 Build 标签系统对 PRD 的落地情况。
 - [CUSTOM_WORLD_CREATOR_TOOL_AUDIT_2026-04-08.md](./CUSTOM_WORLD_CREATOR_TOOL_AUDIT_2026-04-08.md)：自定义世界创作工具当前问题、体验断层和优化优先级审计。