Genarrative/docs/audits/FUNCTION_REQUIREMENT_COMPLETENESS_AUDIT_2026-04-14.md

Function 需求完整性核查（2026-04-14）

1. 核查范围

本次核查按当前线程上下文，聚焦 function 体系相关文档与实现，不扩大到整个项目全部 PRD。

本次实际对照了这些文档：

• docs/audits/FUNCTION_DESIGN_AUDIT_2026-04-03.md
• docs/reference/FUNCTION_SCRIPT_CATALOG_2026-04-04.md
• docs/experience/ADVENTURE_RUNTIME_DEV_EXPERIENCE.md
• docs/audits/engineering/README.md

本次实际核对了这些实现入口：

• src/data/functionCatalog/**
• src/data/stateFunctions.ts
• src/data/npcInteractions.ts
• src/components/AdventurePanel.tsx
• src/hooks/story/choiceActions.ts
• src/hooks/story/npcEncounterActions.ts
• src/hooks/story/npcInteraction.ts
• src/services/runtimeStoryService.ts
• server-node/src/modules/story/**
• server-node/src/modules/inventory/**
• server-node/src/modules/runtime-item/**
• server-node/src/modules/quest/**

2. 核查结论

结论先说：

• function 主链路需求已经基本落地，不需要再继续“为了完整而过度迭代”。
• 当前最主要的缺口不是再发明一套新 function 流程，而是把已有链路补齐回归测试，确保后续不会回退。
• 本轮核查后，已把两条仍缺直接测试兜底的核心链路补上。

3. 已确认已经落地的需求

3.1 function 目录化与分层收口

已实现：

• state / npc / treasure / flow / panel 五类 function 已统一收口到 src/data/functionCatalog/
• src/data/functionCatalog/index.ts 已提供统一导出
• SERVER_RUNTIME_FUNCTION_IDS 也已和 catalog 文档映射对齐

判断：

• 这部分需求已完成，不需要继续重做结构。

3.2 story_continue_adventure 延迟展示链路

已实现：

• npc_chat 在 npcEncounterActions.ts 中先生成聊天正文，再把后续选项写入 deferredOptions
• choiceActions.ts 在点击 story_continue_adventure 时会直接恢复 deferredOptions
• AdventurePanel.tsx 已按 functionId 而不是 actionText 识别该特殊按钮

判断：

• 这条主功能链路已经真正存在，不属于“文档写了、实现没跟上”。

3.3 modal 型 function 的首次点击分流

已实现：

• npc_trade
• npc_gift
• npc_recruit

这些 function 当前都明确是“首次点击先分流，再在确认后进入真正执行链”。

当前实现路径：

• 首次点击：
  • choiceActions.ts
  • storyGenerationState.ts
  • npcInteraction.ts
• 确认后：
  • trade / gift / quest 进入 server runtime action
  • recruit 进入本地招募对白与本地状态提交链

判断：

• 这不是未实现，而是当前架构设计如此。
• 文档里“确认后要继续推进剧情/结算”的要求已经满足。

3.4 Task6 function 的服务端化

已实现：

• inventory_use
• equipment_equip
• equipment_unequip
• forge_craft
• forge_dismantle
• forge_reforge
• npc_trade
• npc_gift
• npc_quest_accept
• npc_quest_turn_in
• treasure_secure
• treasure_inspect
• treasure_leave

这些 function 已经在前端 runtimeStoryService.ts、服务端 story runtime / inventory / runtime-item / quest 模块里形成闭环。

判断：

• 这部分不需要再回退到前端本地重写。

4. 本轮发现的真实缺口

本轮真正仍未完整落地的，不是功能行为本身，而是下面两条回归保护：

4.1 npc_chat -> story_continue_adventure -> deferredOptions

问题：

• 文档明确要求这条链路要清楚、可验证。
• 代码已经有，但之前没有直接测试“点击继续冒险后必须展示 deferredOptions”。

本轮已补：

• src/hooks/story/choiceActions.test.ts
  • 新增 reveals deferred adventure options when story_continue_adventure is selected

4.2 AdventurePanel 对 continue option 的识别方式

问题：

• 文档明确要求不要再靠文案识别 continue option。
• 实现已经改成按 functionId 识别，但之前没有组件层测试锁住。

本轮已补：

• src/components/AdventurePanel.test.tsx
  • 验证 story_continue_adventure 即使 actionText 改掉，仍然显示延迟选项提示
  • 验证仅 actionText 相同但 functionId 不同，不会误触发提示

5. 本轮新增测试

本轮新增：

• src/components/AdventurePanel.test.tsx
• src/hooks/story/choiceActions.test.ts
  • 新增 deferred options 恢复用例

6. 验收结论

按当前 function 相关文档要求判断：

• 核心运行时需求：已实现
• 延迟展示链路：已实现
• modal 分流架构：已实现
• Task6 服务端承接：已实现
• 回归测试盲区：本轮已补齐关键缺口

最终建议：

• 这块现在不应该继续过度迭代。
• 后续应以“新增需求再增量补测试”为主，而不是再次重构 function 主链路。
• 除非后续 PRD 明确要求“modal 首次点击也必须立刻生成一段剧情反馈”，否则不建议为了形式统一再强行改写当前分流模型。