Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,147 +0,0 @@
|
||||
# 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 和前端接口切到新后端。
|
||||
Reference in New Issue
Block a user