# 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/planning/CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.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 首次点击也必须立刻生成一段剧情反馈”，否则不建议为了形式统一再强行改写当前分流模型。