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