Genarrative/docs/technical/M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md

M4 module-combat SpacetimeDB 基线设计（2026-04-21）

更新时间：2026-04-22

0. 文档目标

本文件只冻结一件事：

把 module-combat 从“只有 README 占位”推进到“首版 battle_state 与 resolve_combat_action 可真实编码、可编译、可继续扩展”的工程基线。

本轮不宣称完成完整 runtime story action 迁移，也不把 inventory / npc / story AI 续写 直接耦进战斗 reducer；跨子域写入继续收敛在 spacetime-module 聚合层。

---

1. 本轮落地范围

本轮只做下面 5 件事：

1. 新增 server-rs/crates/module-combat/ 真实 crate。
2. 冻结 battle_state 的首版领域类型、枚举、输入结构与字段校验 helper。
3. 冻结 resolve_combat_action 的首版输入、输出与纯规则推进逻辑。
4. 在 server-rs/crates/spacetime-module/ 中新增 battle_state 表。
5. 在 spacetime-module 中新增 create_battle_state、resolve_combat_action 两个 reducer。

---

2. 当前冻结的实现边界

2.1 首版必须支持的战斗 function

首版与 ../prd/AI_NATIVE_BATTLE_SINGLE_ACTION_FUNCTION_PRD_2026-04-18.md 保持一致，只支持以下单行为入口：

1. battle_attack_basic
2. battle_recover_breath
3. battle_use_skill
4. battle_escape_breakout
5. 旧兼容攻击类：
   • battle_all_in_crush
   • battle_guard_break
   • battle_probe_pressure
   • battle_feint_step
   • battle_finisher_window

本轮刻意不接入：

1. inventory_use
2. 技能与物品的正式外部明细读取
3. 与 quest_record、npc_state 的联动写入
4. 脱战后 story_event 追加与 AI 续写触发

2.2 为什么先不做 inventory_use

当前 Rust 侧还没有 inventory_slot 正式表，也没有稳定的战斗内物品快照输入。

如果现在把 inventory_use 硬塞进 module-combat，只会出现两种坏结果：

1. reducer 内部引入并不存在的 inventory 真相依赖；
2. 退回成“让 Axum 先算完再写 battle_state”的伪迁移。

因此本轮明确冻结为：

1. module-combat 先完成纯战斗状态推进；
2. inventory_use 留到 inventory_slot 与 runtime snapshot projection 口径稳定后再接。

---

3. battle_state 首版字段

首版 battle_state 冻结为以下字段：

1. battle_state_id
2. story_session_id
3. runtime_session_id
4. actor_user_id
5. target_npc_id
6. target_name
7. battle_mode
8. status
9. player_hp
10. player_max_hp
11. player_mana
12. player_max_mana
13. target_hp
14. target_max_hp
15. chapter_id
16. experience_reward
17. reward_items
18. turn_index
19. last_action_function_id
20. last_action_text
21. last_result_text
22. last_damage_dealt
23. last_damage_taken
24. last_outcome
25. version
26. created_at
27. updated_at

3.1 设计意图

首版只解决下面这些真相问题：

1. 当前战斗是否存在、是否仍在进行中；
2. 玩家与当前目标的 HP / MP 最小数值状态；
3. 当前是 fight 还是 spar；
4. 当前战斗归属哪个章节；
5. 本场战斗若胜利应发多少经验；
6. 本场战斗若胜利应发哪些已编译好的 reward item；
7. 最近一次动作结算了什么；
8. 当前 battle reducer 是否发生过版本推进。

3.2 当前刻意不放入的字段

本轮明确不放：

1. 多目标列表
2. 技能冷却 map
3. build buff 详情
4. 掉落预算、好感预算、剧情上下文大对象
5. 大型 rawGameState 镜像字段

原因很直接：这些都属于后续跨子域联动层，不适合在 battle_state 首版里重新堆一个大 JSON。

---

4. 枚举与动作口径

4.1 BattleMode

只保留两种：

1. Fight
2. Spar

4.2 BattleStatus

只保留三种：

1. Ongoing
2. Resolved
3. Aborted

说明：

1. Resolved 表示战斗已正常收束，包括胜利、切磋结束、成功逃脱。
2. Aborted 预留给后续 session 中断、外部清理、投影回滚等异常收束场景。

4.3 CombatOutcome

首版冻结：

1. Ongoing
2. Victory
3. SparComplete
4. Escaped

这与当前共享契约里的 RuntimeBattlePresentation.outcome 一致，避免首版就制造新的枚举翻译成本。

---

5. resolve_combat_action 首版规则

5.1 输入

首版 reducer 输入只包含：

1. battle_state_id
2. function_id
3. action_text
4. base_damage
5. mana_cost
6. heal
7. mana_restore
8. counter_multiplier
9. updated_at_micros

5.2 为什么允许输入 base_damage

本轮 module-combat 的职责是把战斗推进规则固定到 SpacetimeDB。

但玩家技能、装备 build、物品 buff、成长曲线这些正式真相仍未迁完，因此首版允许上游把已算好的 base_damage / mana_cost / heal / mana_restore 作为确定输入传进 reducer。

这意味着当前模块边界是：

1. module-combat 负责状态推进、反击、逃跑、战斗收束规则；
2. 更高层的 build / skill / item 数值来源仍可在后续模块中逐步收敛；
3. 等 inventory / progression / runtime build 真相表稳定后，再继续把这些输入收得更窄。

5.3 动作规则

A. battle_escape_breakout

直接结束战斗：

1. status = Resolved
2. last_outcome = Escaped
3. last_damage_dealt = 0
4. last_damage_taken = 0

B. battle_recover_breath

恢复类动作：

1. 玩家回复 heal
2. 玩家回复 mana_restore
3. 若战斗仍持续，则按 counter_multiplier 吃一次敌方反击

C. battle_attack_basic / 旧兼容攻击类 / battle_use_skill

攻击类动作：

1. 目标扣除 base_damage
2. 若目标已收束，则按 battle_mode 进入 Victory / SparComplete
3. 若目标未收束，则玩家按 counter_multiplier 吃一次敌方反击

5.4 反击规则

首版固定：

1. fight 下敌方基础反击伤害 = max(4, round(target_max_hp * 0.14 * counter_multiplier))
2. spar 下敌方基础反击伤害固定为 1

这是对当前 Node 逻辑的直接收敛，先保证行为方向不漂移，不在本轮发明新的战斗公式。

5.5 HP 下限规则

1. fight 下正常下限为 0
2. spar 下双方 HP 最低保留为 1

这样能保留当前“切磋点到为止”的旧行为，不把 spar 错结算成死亡战斗。

---

6. spacetime-module 接线口径

6.1 battle_state 表

spacetime-module 首版只新增一张 private 真相表：

1. battle_state

建议索引：

1. by_story_session_id
2. by_runtime_session_id
3. by_actor_user_id

6.2 reducer

当前仍只保留两个战斗 reducer：

1. create_battle_state
2. resolve_combat_action

职责：

1. create_battle_state 只负责插入 battle 真相，不负责故事会话编排。
2. resolve_combat_action 负责推进 battle 真相。
3. 当 Victory 收束时，由 spacetime-module 聚合层继续把 experience_reward 联动写入 player_progression / chapter_progression。
4. 当 Victory 收束且 reward_items 非空时，由 spacetime-module 聚合层继续把战利品写入 inventory_slot。
5. resolve_combat_action 仍不负责 AI 续写和 quest signal 全量分发。

---

7. 与后续子域的边界

7.1 与 story

当前关系：

1. story 负责更高层 action 路由与后续 story_event 追加；
2. combat 只返回 battle 真相推进结果。

后续再补：

1. 战斗结束时的 story_event
2. 脱战后的 continue_story / resolve_story_action

7.2 与 inventory

当前不直接耦合到 module-combat reducer。

后续再补：

1. 战斗内 inventory_use
2. 消耗品扣减
3. 战斗 buff 写入

当前已存在的聚合层联动：

1. Victory 时可把 battle_state.reward_items 写入 inventory_slot

7.3 与 progression

当前不直接在 module-combat reducer 内发经验与等级变更。

后续再补：

1. hostile scaling 与 reward 编译口径

当前已存在的聚合层联动：

1. fight_victory 的经验发放
2. 章节账本写入

7.4 与 npc

当前不直接改好感。

后续再补：

1. spar_complete 的 affinity 变化
2. fight / spar 与 encounter 状态同步

---

8. 本轮验收口径

满足以下条件，视为本轮 module-combat 基线完成：

1. server-rs/crates/module-combat 已从 README 占位升级为真实 crate。
2. battle_state、BattleMode、BattleStatus、CombatOutcome、ResolveCombatActionInput 已冻结到代码。
3. spacetime-module 已新增 battle_state 表。
4. spacetime-module 已新增 create_battle_state 与 resolve_combat_action reducer。
5. cargo check -p module-combat -p spacetime-module 通过。

---

9. 下一步建议

在本轮基线稳定后，下一步按以下顺序推进最稳：

1. 设计 inventory_slot 与战斗内 inventory_use 的最小真相输入。
2. 设计 resolve_story_action 如何编排 story + combat + npc + quest + inventory。
3. 把 battle_state 结束事件接入 story_event。
4. 再把 Axum facade 与 RuntimeStoryActionResponse.battle 真正打通。