geometry-tower-defense/docs/CombatNodeArchitecture.md

CombatNode 设计规范（开发约束）

最后更新：2026-03-06

1. 适用范围与目标

本文描述 CombatNode 域的后续开发标准。

说明：

• 本文是“目标架构约束”，不要求当前代码已经完全达成。
• 后续新增功能、重构、拆分类、review 职责边界时，以本文为准。
• 如果当前实现与本文不一致，新增代码优先向本文收敛，而不是继续扩大旧结构。

核心目标：

• CombatScheduler 收敛为“状态机管理器”，不再继续堆积加载、结算、奖励选择等业务细节。
• 战斗内资源收口到独立资源服务，由内部管理，不再由 CombatNodeComponent 直接持有真值。
• MapEntity 通过 MapData + Event 获取战斗上下文，不反查 CombatNode 域内部状态。

---

2. 架构总览

2.1 CombatNodeComponent（入口 Facade）

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatNodeComponent.cs

长期职责：

• 读取并缓存 DRLevel / DRLevelPhase / DRLevelSpawnEntry。
• 按主题筛选关卡。
• 启动/停止 CombatScheduler。
• 对外暴露只读运行时属性。
• 提供少量用户入口，例如 StartCombat、TryEndCombatByPlayer。

长期不负责：

• 不直接持有 Coin / Gold / BaseHp / Loot Backpack 的真值。
• 不直接缓存本局建塔属性快照。
• 不直接发布战斗流程事件。
• 不直接处理敌人掉落、结算、奖励选择、地图加载。

2.2 CombatScheduler（状态机管理器）

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs

长期职责：

• 持有共享运行时数据与共享服务实例。
• 管理状态实例。
• 提供统一的 ChangeState(...) 状态迁移入口。
• 提供敌人事件的公共处理入口。
• 作为状态机生命周期边界，统一做运行时重置。

长期不负责：

• 不直接硬编码加载流程。
• 不直接硬编码结算流程。
• 不直接硬编码奖励选择 UI 逻辑。
• 不直接硬编码 PhaseEndType 结束条件。

推荐状态类命名：

• CombatLoadingState
• CombatRunningPhaseState
• CombatWaitingForPhaseEndState
• CombatSettlementState
• CombatRewardSelectionState
• CombatFinishFormState
• CombatWaitingForReturnState
• CombatFailedState

实现约束：

• 上述状态类可以作为 CombatScheduler 的嵌套类实现，也可以拆成独立文件；但必须只服务于 CombatScheduler 状态机，不形成独立业务边界。
• 共享数据与共享服务统一收口到 CombatScheduler 内部持有的运行时承载体，不允许散落在各状态类中。
• 若 CombatScheduler 体量过大，允许在其内部实现中继续拆出：
  • CombatSchedulerRuntimeContext：承载共享运行时字段与共享服务引用
  • CombatSchedulerFlowCoordinator：承载多个状态共用的流程辅助方法
• 上述拆分只属于 CombatScheduler 的内部实现细化，不改变 CombatScheduler 作为唯一状态机边界的职责。
• 所有状态切换只能通过 CombatScheduler.ChangeState(...) 完成。
• 状态类不能彼此直接操控。

2.3 EnemyManager（敌人域 Facade）

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyManager.cs

长期职责：

• 对状态机提供统一敌人域接口。
• 编排敌人子服务。
• 暴露只读事实：
  • AliveEnemyCount
  • IsPhaseSpawnCompleted
  • HasAliveBoss
• 在敌人死亡或到家时，通过公共入口向 CombatScheduler 上报：
  • OnEnemyDefeated(DREnemy enemy)
  • OnEnemyReachedBase(DREnemy enemy)

长期不负责：

• 不直接给资源入账。
• 不直接扣基地血量。
• 不直接决定状态切换。

---

3. 状态机模型

3.1 状态列表（目标）

• Loading
• RunningPhase
• WaitingForPhaseEnd
• Settlement
• RewardSelection
• FinishForm
• WaitingForReturn
• Failed

说明：

• 正常结束流只有一条状态链：
  • Settlement -> RewardSelection(可选) -> FinishForm -> WaitingForReturn
• 正常通关、玩家主动结束、基地血量归零都走同一条结束链。
• Failed 仅用于异常失败，不用于“基地被击破”这类正常战斗失败。

3.2 CombatLoadingState

职责：

• 通过 CombatLoadSession 执行地图与基础战斗 UI 加载。
• 从局内资源管理器读取本局快照。
• 组装 MapData 并发起 ShowEntity(MapEntity)。

约束：

• 只负责加载，不负责初始化局内资源。
• 局内资源必须在进入状态机前初始化完成。

3.3 CombatRunningPhaseState

职责：

• 执行当前 DRLevelPhase 的行为。
• 推进 SpawnEntry 时序与出怪。
• 管理 EnemySpawnDirector 的阶段级初始化与重置。
• 在新 phase 开始时发布：
  • CombatProcessEventArgs
  • CombatEnemyHpRateChangedEventArgs

退出条件：

• 当前 phase 的所有 SpawnEntry 已执行完毕时，进入 WaitingForPhaseEnd。
• 若共享“结束战斗请求标记”已置位，也可结束当前运行态并转入正常结束链。

不负责：

• 不根据 PhaseEndType 判断 phase 是否真正结束。
• 不直接根据 BaseHp 或敌人死亡事件切状态。

3.4 CombatWaitingForPhaseEndState

职责：

• 不再生成新敌人。
• 根据 PhaseEndType 判断当前 phase 是否结束。

约束：

• PhaseEndType 的判断由独立判定服务负责，不在状态内硬编码。
• 每种 PhaseEndType 对应一个实现类。
• 该判定服务为本状态专用，不作为全局共享服务常驻在 CombatScheduler 上。

3.5 CombatSettlementState

职责：

• 进入时统一构造结算上下文。
• 根据共享资源状态完成结算修正。
• 决定后续进入 RewardSelection 还是 FinishForm。

负责的逻辑包括：

• 基地血量奖励/惩罚。
• 满血奖励选择的准入判断。
• 生成最终展示摘要。
• 准备待合并的结算背包快照。

约束：

• 不依赖单独的 CombatEndReason 字段。
• BaseHp <= 0 表示基地被击破。
• 正常通关与玩家主动结束在结算产出上不区分原因。

3.6 CombatRewardSelectionState

职责：

• 绑定、配置、打开、关闭 RewardSelectForm。
• 处理奖励选择过程。
• 将奖励选择结果写入“结束状态链持有的结算上下文”。

约束：

• 不重新判断“是否应该出现奖励选择”。
• 只处理选择过程本身。

3.7 CombatFinishFormState

职责：

• 绑定、配置、打开、关闭 CombatFinishForm。
• 读取结算上下文并展示最终结算结果。

3.8 CombatWaitingForReturnState

职责：

• 等待玩家从结算返回。
• 完成地图与战斗基础 UI 清理。
• 完成正常退出收尾。
• 在整场战斗真正退出时发布 NodeCompleteEventArgs。

3.9 CombatFailedState

职责：

• 表示异常失败。
• 保存并展示错误信息。
• 执行异常收尾与剩余资源回收。

约束：

• Failed 只处理异常路径。
• “基地血量为 0”不进入 Failed。

---

4. 共享服务与推荐命名

4.1 CombatLoadSession

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatLoadSession.cs

长期定位：

• 长期保留的独立加载服务。
• 专门负责地图与战斗内基础 UI 的加载/清理。

职责：

• 加载地图实体。
• 打开/关闭 CombatInfoForm。
• 跟踪加载成功/失败状态。
• 对外提供 CurrentMap 与 IsReady。

4.1.x CombatSchedulerRuntimeContext / CombatSchedulerFlowCoordinator（实现细化）

当前实现允许：

• 用 CombatSchedulerRuntimeContext 承载所有状态共享的运行时字段与共享服务引用。
• 用 CombatSchedulerFlowCoordinator 承载多个状态共用的流程辅助逻辑。

约束：

• 两者都必须由 CombatScheduler 持有并统一管理生命周期。
• 两者都不替代 CombatScheduler 对外暴露状态机边界。
• RuntimeContext 不负责状态切换。
• FlowCoordinator 不持有独立业务真值，只能围绕共享运行时做编排辅助。
• 状态类只允许通过 RuntimeContext + FlowCoordinator 访问共享状态与共享流程，不应再直接耦合其他状态实现细节。

4.2 PhaseLoopRuntime

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/PhaseLoopRuntime.cs

长期定位：

• 长期保留的独立 phase runtime 服务。

职责：

• 维护当前 DRLevelPhase。
• 维护 DisplayPhaseIndex、PhaseCount。
• 维护统一的 phase 时间基准，例如 phaseElapsedTime 或 phaseStartTime。
• 负责进入下一 phase。
• 持有统一“请求结束战斗”标记。

约束：

• 只做 phase 运行时数据管理，不直接切状态。

4.3 CombatInRunResourceManager（推荐命名）

当前相关文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatResourceManager.cs

目标职责：

• 持有本局 Coin 真值。
• 持有本局累计 Gold 真值。
• 持有本局 BaseHp 真值。
• 持有本局战利品背包。
• 持有本局建塔属性快照。
• 提供只读快照给结束状态链与加载状态使用。
• 发布资源变化事件：
  • CombatCoinChangedEventArgs
  • CombatBaseHpChangedEventArgs

初始化约束：

• 在进入状态机前完成初始化。
• 由内部从 PlayerInventory 获取并缓存本局建塔快照。

事件约束：

• Coin / BaseHp 变化事件同时携带“当前值”和“变化量”。
• Gold 只是结算累计值，不要求战斗内实时事件驱动。

4.4 EnemyDropResolver（推荐命名）

当前相关文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatResourceManager.cs

目标职责：

• 只负责敌人死亡后的掉落判定。
• 输入：
  • DREnemy
  • 当前阶段索引
  • 当前主题或关卡上下文
• 输出：
  • 掉落结果对象（coin / gold / loot）

约束：

• 不直接修改资源状态。
• 不直接读取 CombatNodeComponent、MapEntity、EnemyManager 内部状态。

4.5 IPhaseEndCondition（推荐命名）

目标职责：

• 作为 PhaseEndType 判定接口。
• 每种 PhaseEndType 对应一个实现类。

只读输入：

• 当前 DRLevelPhase
• phase 时间信息
• AliveEnemyCount
• IsPhaseSpawnCompleted
• HasAliveBoss

输出：

• bool ShouldExit

约束：

• 不直接切状态。
• 不直接发事件。
• 不直接改资源。

---

5. EnemyManager 子服务边界

5.1 EnemySpawnDirector

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemySpawnDirector.cs

职责：

• 长期保留为独立服务。
• 基于 spawnEntries + phase time 计算当前应执行的刷怪行为。
• 提供“当前 phase 的 SpawnEntry 是否已全部执行完”的事实。

生命周期：

• 由 CombatRunningPhaseState 在状态进入/退出时初始化与重置。

5.2 SpawnerResolver

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/SpawnerResolver.cs

职责：

• 缓存当前地图可用 Spawner。
• 提供出生点与路径解析。

5.3 EnemyLifecycleTracker

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyLifecycleTracker.cs

职责：

• 维护 AliveEnemyCount 真值。
• 维护 HasAliveBoss 真值。
• 追踪本局 tracked 敌人。
• 导出 tracked ids 供清场使用。

Boss 识别规则：

• Boss 身份由 DRLevelSpawnEntry.EntryType == Boss 决定。
• 不由 DREnemy 自身类型决定。

5.4 EnemyConfigService

文件：Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyConfigService.cs

职责：

• 读取 DREnemy。
• 处理默认配置兜底。
• 计算循环周目下的基础血量倍率。

---

6. 事件与数据流规范

6.1 MapEntity 与 Combat 域解耦

必须保持：

• MapEntity 不直接查询 CombatNodeComponent 的运行时资源字段。
• 战斗初始上下文通过 MapData 注入。
• Coin 初值通过 MapData 传入。
• 后续 Coin 变化通过 CombatCoinChangedEventArgs 同步。
• TowerStatsData 等本局不变量直接放进 MapData。
• MapEntity 不反查 Combat 域内部服务。

MapData 组装规则：

• 由 CombatLoadingState 从局内资源管理器读取快照。
• 由 CombatLoadingState 打包成 MapData 后再 ShowEntity(MapEntity)。

6.2 敌人事件处理

统一边界：

• EnemyManager 只上报：
  • OnEnemyDefeated(DREnemy enemy)
  • OnEnemyReachedBase(DREnemy enemy)
• CombatScheduler 公共层负责处理敌人事件的通用副作用：
  • 击杀：调用 EnemyDropResolver，再调用局内资源管理器入账。
  • 到家：调用局内资源管理器扣减 BaseHp。

约束：

• 敌人事件入口不直接调用 ChangeState(...)。
• BaseHp <= 0 的判断由当前状态在 OnUpdate 中处理。

6.3 战斗流程事件

发布边界：

• 资源变化事件由局内资源管理器发布。
• 流程/阶段事件由状态机或具体状态发布。

发布时间：

• NodeEnterEventArgs：Loading 完成并正式进入首个 RunningPhase 时。
• CombatProcessEventArgs：新 phase 的 RunningPhase.OnEnter。
• CombatEnemyHpRateChangedEventArgs：与 CombatProcessEventArgs 同时发布。
• NodeCompleteEventArgs：WaitingForReturn 完成清理、整场战斗真正退出时。

---

7. 结束链与结算上下文

7.1 统一结束链

正常结束统一走：

• Settlement
• RewardSelection（可选）
• FinishForm
• WaitingForReturn

7.2 结算上下文

归属：

• 作为 CombatScheduler 上的共享字段存在。
• Settlement 在 OnEnter 时统一构造。
• RewardSelection 只追加奖励结果。
• FinishForm 与 WaitingForReturn 只读取。

最小字段集合：

• 最终结算的 Gold/Coin 结果
• 待合并的背包快照
• BaseHp 结算结果
• 是否进入过奖励选择
• FinishForm 所需摘要数据

奖励选择约束：

• 满血奖励选择结果只写入结算上下文。
• 不直接写入局内资源管理器。
• 最终由结束状态链统一合并到玩家背包。

---

8. 核心不变量（必须保持）

1. CombatScheduler 只做状态机管理与共享运行时收口，不继续吸收具体业务细节。
2. CombatNodeComponent 不再持有战斗内资源真值。
3. 局内 Coin / Gold / BaseHp / Loot Backpack / BuildTowerSnapshots 以 CombatInRunResourceManager 为唯一真值来源。
4. 敌人死亡掉落判定以 EnemyDropResolver 为唯一判定入口。
5. 存活敌人数与 HasAliveBoss 以 EnemyLifecycleTracker 为唯一真值来源。
6. Phase 运行时信息与统一结束标记以 PhaseLoopRuntime 为唯一真值来源。
7. PhaseEndType 的退出条件以 IPhaseEndCondition 实现类为唯一判定入口。
8. 状态切换只能通过 CombatScheduler.ChangeState(...) 完成。
9. 敌人事件处理入口不直接切状态，状态只能在自己的 OnUpdate 中决定迁移。
10. MapEntity 通过 MapData + Event 获取战斗上下文，不反查 Combat 域内部运行时。

---

9. 清理职责

• 敌人清理：EnemyManager，且只清理本局 tracked 敌人。
• 地图与战斗基础 UI 清理：CombatLoadSession。
• 结算/奖励 UI 清理：结束状态链或 Failed 状态。
• 运行时数据重置：CombatScheduler 在状态机生命周期边界统一执行。

---

10. 扩展开发规范

10.1 新增刷怪类型或 SpawnEntry 行为

优先改 EnemySpawnDirector，不要把时序细节塞进 CombatRunningPhaseState。

10.2 新增 Phase 结束条件

新增 IPhaseEndCondition 实现类，不要在 CombatWaitingForPhaseEndState 里写大分支。

10.3 新增敌人掉落规则

优先改 EnemyDropResolver，不要在 EnemyManager 或状态类里直接计算掉落。

10.4 新增战斗内资源或建塔快照规则

优先改 CombatInRunResourceManager，不要回流到 CombatNodeComponent。

10.5 新增地图/战斗基础 UI 加载规则

优先改 CombatLoadSession 或 CombatLoadingState，不要把加载细节塞回 CombatScheduler 本体。

10.6 新增强化结算、奖励选择、结算 UI 逻辑

优先改结束状态链：

• CombatSettlementState
• CombatRewardSelectionState
• CombatFinishFormState
• CombatWaitingForReturnState

10.7 新增战斗流程事件

优先由具体状态或局内资源管理器发布，不要回流到 CombatNodeComponent。

---

11. 代码变更检查清单（PR 自检）

1. 新逻辑是否落在正确的状态或服务，而不是继续堆进 CombatScheduler 本体？
2. CombatNodeComponent 是否仍然保持为轻量入口 Facade？
3. 是否破坏了局内资源、掉落判定、phase runtime、phase end 判定的唯一真值来源？
4. 敌人事件处理是否仍然只做公共副作用，而不直接切状态？
5. 状态迁移是否仍然统一走 ChangeState(...)？
6. MapEntity 是否仍然只通过 MapData + Event 获取战斗上下文？
7. 清理是否仍按“敌人 / 地图基础 UI / 结算 UI / 运行时数据”分工执行？