Genarrative/docs/technical/M4_COMBAT_REWARD_INVENTORY_INTEGRATION_2026-04-22.md

M4 Combat Reward Inventory Integration（2026-04-22）

更新时间：2026-04-22

0. 文档目标

本文件只冻结一件事：

把 resolve_combat_action(Victory) 从“只发经验”推进到“经验与战利品可在同一事务内结算”的最小主链口径。

本轮不回收完整 runtime item 导演层，也不在 module-combat 内直接做 AI 语义生成；只承接已经编译好的 reward item 快照。

---

1. 本轮落地范围

本轮只落实下面 4 件事：

1. 在 module-combat 中为 battle_state 补充 reward_items 字段。
2. 允许 BattleStateInput 在初始化时携带已经编译好的战利品快照。
3. 在 spacetime-module::resolve_combat_action 中，当结果为 Victory 时同步把 reward_items 写入 inventory_slot。
4. 保持 module-combat 仍然是纯规则 crate，不直接依赖 module-inventory。

---

2. 当前冻结的战利品口径

2.1 battle_state.reward_items

首版字段固定复用 module-runtime-item::RuntimeItemRewardItemSnapshot。

原因：

1. 宝箱链已经用这套 reward item contract 打通到 inventory_slot。
2. 任务奖励当前仍有独立 QuestRewardItem，但战斗奖励更接近 runtime item 导演层。
3. 先复用现有 reward item 快照，避免本轮再发明第三套 combat 专属掉落结构。

2.2 battle 初始化来源

当前 battle_state.reward_items 不在战斗 reducer 内生成，只允许由上游在创建 battle 时传入：

1. resolve_npc_battle_interaction_and_return
2. 后续 Axum façade / runtime story orchestration
3. 其它明确的 battle create 聚合入口

也就是说：

1. module-combat 只消费已确定的 reward item 快照
2. 不在 reducer 内做随机、提示词、外部世界图谱推导

当前已接通：

1. resolve_npc_battle_interaction_and_return
2. POST /api/story/npc/battle
3. POST /api/story/battles

这几条入口都只负责透传已编译奖励，不负责现场生成掉落。

---

3. Victory 发物规则

当 resolve_combat_action 结算结果满足：

1. outcome == Victory

则 spacetime-module 需要继续执行：

1. experience_reward > 0 时写 player_progression / chapter_progression
2. reward_items.len() > 0 时写 inventory_slot

3.1 发物方式

当前固定规则：

1. 每个 reward item 显式映射成一条 InventoryMutation::GrantItem
2. source_kind = CombatDrop
3. source_reference_id = battle_state_id
4. 同一 battle_state_id 只允许发放一次

3.2 幂等约束

本轮先采用与 quest / treasure 一致的“按来源引用查重”思路：

1. 若当前 actor 的 inventory_slot 中已经存在 source_reference_id = battle_state_id
2. 视为该 battle reward 已发放
3. Victory 再次重放时跳过发物，但不影响 battle_state 已收束结果

---

4. 与既有链路的边界

4.1 与 module-combat

module-combat 继续只负责：

1. battle_state 结构
2. resolve_combat_action 状态推进
3. 胜负结果收束

不负责：

1. inventory 写表
2. progression 写表
3. runtime item 生成

4.2 与 module-runtime-item

本轮不把战斗奖励映射 helper 上提到 module-runtime-item。

原因：

1. 当前 RuntimeItemRewardItemSnapshot -> InventoryItemSnapshot 的 helper 语义固定为 TreasureReward
2. 若直接复用，会把 source_kind 写错成 TreasureReward
3. 本轮先在 spacetime-module 里补一个 combat 专用映射，后续再统一抽象

---

5. 当前刻意未做

本轮明确不做下面这些扩张：

1. 不把 Node 版 monster_drop AI 导演层整体迁到 Rust
2. 不在 resolve_npc_battle_interaction_and_return 里现场计算掉落
3. 不处理 battle reward 的货币、好感、情报
4. 不处理战斗内 inventory_use
5. 不把掉落展示或 Battle Reward 面板接到前端

---

6. 验证要求

本轮完成后至少执行：

1. npm run check:encoding
2. cargo test -p module-combat --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml
3. cargo check -p module-combat -p spacetime-module --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml

---

7. 下一步建议

按当前节奏，后续应继续按下面顺序推进：

1. 把 Node 侧 monster_drop runtime item 编译逻辑迁到 Rust 聚合层。
2. 视复用收益决定是否把 battle / treasure 的 reward item 归一化 helper 上提到 module-runtime-item。
3. 最后再把 battle reward 展示、story patch 和前端接口切到新后端。