# CombatNode Architecture

最后更新：2026-03-02

## 1. 总览
CombatNode 当前分为三层：
- `CombatNodeComponent`：入口与关卡数据装配。
- `CombatScheduler`：战斗状态机与阶段推进，以及关卡内资源结算。
- `EnemyManager`：敌人系统 Facade（对外接口保持稳定，内部由多个子服务协作）。

本文重点记录 `EnemyManager` 与 `CombatScheduler` 的职责边界（尤其资源管理收口后的模型）。

## 2. EnemyManager 相关类

### 2.1 EnemyManager（Facade）
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyManager.cs`

职责：
- 对 `CombatScheduler` 提供统一接口：`OnInit / BeginPhase / OnUpdate / EndPhase / OnDestroy`。
- 编排敌人域子服务，不承载具体业务细节。
- 转发状态：`AliveEnemyCount`、`IsPhaseRunning`、`IsPhaseSpawnCompleted`。
- 处理敌人实体事件（Show/Hide）后的结果上报：
  - 击杀：上报 `coin/gold` 到 `CombatScheduler.OnEnemyDefeatedRewardResolved(...)`
  - 到家：上报 `baseDamage` 到 `CombatScheduler.OnEnemyReachedBase(...)`

不负责：
- 不直接维护刷怪时间轴。
- 不直接维护出生点缓存与路径查询。
- 不直接维护敌人追踪结构。
- 不直接维护掉落池抽样与背包库存。
- 不直接维护敌人配置兜底和血量倍率算法。

### 2.2 EnemySpawnDirector（刷怪时序）
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemySpawnDirector.cs`

职责：
- 管理 `DRLevelSpawnEntry` 的运行时实例（`SpawnEntryRuntime`）。
- 按时间推进 `Stream / Burst / Boss` 生成逻辑。
- 输出“当前应生成多少敌人”，通过回调交给 `EnemyManager.SpawnEnemies` 执行。
- 维护阶段刷怪状态：`IsPhaseRunning`、`IsPhaseSpawnCompleted`。

### 2.3 SpawnerResolver（出生点与路径）
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/SpawnerResolver.cs`

职责：
- 缓存当前地图可用 `Spawner`。
- 支持 `SpawnOrder` 映射与 fallback 轮询。
- 对外提供 `TryResolveSpawnPath(...)`，返回世界坐标路径点。
- 在地图切换时刷新缓存，避免每次刷怪全量扫描。

### 2.4 EnemyLifecycleTracker（敌人生命周期追踪）
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyLifecycleTracker.cs`

职责：
- 追踪本局敌人 `entityId -> DREnemy`。
- 维护 `AliveEnemyCount`。
- 处理 `ShowSuccess / ShowFailure / HideComplete` 对追踪状态的变更。
- 提供批量导出 tracked ids，用于 `CleanupTrackedEnemies` 清场。

### 2.5 EnemyConfigService（敌人配置与倍率）
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyConfigService.cs`

职责：
- 读取 `DREnemy`，处理默认配置兜底。
- 计算循环周目下的基础血量倍率（按 `displayPhaseIndex / phaseCount` 推导 loop）。
- 缓存数据表引用并在 `Reset` 时清理。

## 3. CombatScheduler 资源收口

### 3.1 CombatResourceManager（关卡内资源统一管理）
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatResourceManager.cs`

职责：
- 统一维护关卡内资源状态：
  - `GainedCoin`、`GainedGold`
  - `BackpackInventoryData`（结算背包快照）
- 处理击杀奖励入账：`AddEnemyDefeatedReward(...)`
- 处理局外掉落抽样与物品构建：`TryRollOutGameItemDrop(...)`
- 对结算 UI 提供只读快照：`GetRewardInventorySnapshot()`

### 3.2 CombatScheduler 与资源类关系
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs`

当前模型：
- `CombatScheduler` 持有 `_combatResourceManager`。
- `GainedCoin/GainedGold` 属性透传资源类。
- `OnEnemyDefeatedRewardResolved(...)` 统一触发：
  - 货币入账
  - 关卡内掉落判定
- `EnterFinishFlow(...)` 从资源类取 `BackpackInventoryData` 作为结算数据。

## 4. 协作流程（简版）
1. `CombatScheduler.BeginNextPhase()` 调 `EnemyManager.BeginPhase(...)`。
2. `EnemyManager` 刷新 `SpawnerResolver` 缓存，并通知 `EnemySpawnDirector.BeginPhase(...)`。
3. 每帧 `EnemyManager.OnUpdate(...)`：
   - `SpawnerResolver.RefreshCache(...)`
   - `EnemySpawnDirector.OnUpdate(..., SpawnEnemies)`
4. `SpawnEnemies(...)` 执行实际生成：
   - `SpawnerResolver.TryResolveSpawnPath(...)`
   - `EnemyConfigService.GetEnemyConfig(...)`
   - `EnemyConfigService.ResolveScaledEnemyBaseHp(...)`
   - `EnemyLifecycleTracker.TrackEnemy(...)`
   - `GameEntry.Entity.ShowEnemy(...)`
5. 敌人回收时 `EnemyManager.OnHideEntityComplete(...)`：
   - `EnemyLifecycleTracker.TryHandleHideComplete(...)`
   - 若击杀：上报 `coin/gold` 给 `CombatScheduler.OnEnemyDefeatedRewardResolved(...)`
   - 若到家：上报 `baseDamage` 给 `CombatScheduler.OnEnemyReachedBase(...)`
6. `CombatScheduler.OnEnemyDefeatedRewardResolved(...)`：
   - `CombatResourceManager.AddEnemyDefeatedReward(...)`
   - `CombatResourceManager.TryRollOutGameItemDrop(...)`
7. `CombatScheduler.EnterFinishFlow(...)`：
   - 读取 `CombatResourceManager.GetRewardInventorySnapshot()`
   - 打开结算 UI

## 5. 关键不变量
- 存活敌人数以 `EnemyLifecycleTracker.AliveEnemyCount` 为唯一真值来源。
- 刷怪阶段状态以 `EnemySpawnDirector` 为唯一真值来源。
- 关卡内资源以 `CombatResourceManager` 为唯一真值来源。
- `EnemyManager` 只做敌人域编排与结果上报，不再持有奖励库存。
- 清场必须只作用于本局 tracked 敌人，避免误伤其他实体。

## 6. 维护建议
- 新增刷怪类型：优先改 `EnemySpawnDirector`。
- 新增路径/出生规则：优先改 `SpawnerResolver`。
- 新增敌人追踪策略：优先改 `EnemyLifecycleTracker`。
- 新增敌人配置兜底或倍率策略：优先改 `EnemyConfigService`。
- 新增货币/掉落/结算背包规则：优先改 `CombatResourceManager`。