# CodeX TODO

最后更新：2026-03-07

## 当前目标

按 `docs/CombatNodeArchitecture.md` 继续收敛 `CombatNode` 域职责。当前骨架已经基本到位，后续重点是：
- 继续保持 `CombatScheduler` 作为唯一状态机边界，避免把新业务重新堆回本体。
- 继续完成 `MapData + Event` 解耦收尾，确认 `MapEntity` 不再反查 `CombatNode` 域运行时。
- 稳定 `CombatSettlementContext` 的模型边界，避免流程控制字段和展示摘要继续混杂增长。
- 补 Unity 编译、PlayMode 和失败路径回归验证，把这轮结构调整真正跑通。

## 已完成

### 1. 状态类已收口到 CombatScheduler/CombatStates
- 状态类当前位于 `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatStates/`。
- `CombatStateBase` 已统一改为 `Context + Flow` 双引用模式。
- 各状态不再直接访问 `CombatScheduler._xxx` 私有字段，而是通过：
  - `CombatSchedulerRuntimeContext`
  - `CombatSchedulerFlowCoordinator`

关键文件：
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatStates/CombatStateBase.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatStates/*.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSchedulerRuntimeContext.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSchedulerFlowCoordinator.cs`

### 2. 第一轮目标命名、骨架与接线已建立
- `CombatResourceManager` 已重命名为 `CombatInRunResourceManager`。
- 已新增掉落解析骨架：
  - `EnemyDropResolveContext`
  - `EnemyDropResolveResult`
  - `EnemyDropResolver`
- 已新增 phase end 骨架并接入等待退出状态：
  - `IPhaseEndCondition`
  - `PhaseEndConditionContext`
  - `PhaseEndConditionFactory`
  - `NonePhaseEndCondition`
  - `TimeElapsedPhaseEndCondition`
  - `EnemiesClearedPhaseEndCondition`
  - `BossDeadPhaseEndCondition`

关键文件：
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatInRunResourceManager.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/EnemyDropResolver.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/PhaseEndConditions/`

### 3. 局内资源真值已迁到 CombatInRunResourceManager
目前 `CombatInRunResourceManager` 已经接管：
- `CurrentCoin`
- `CurrentBaseHp`
- `MaxBaseHp`
- `GainedCoin`
- `GainedGold`
- 本局 `BuildTowerStats` 快照
- 奖励背包快照

已实现的资源接口：
- `InitializeForCombat(DRLevel level)`
- `MarkCombatEnded()`
- `Reset()`
- `TryConsumeCoin(int coin)`
- `AddCoin(int coin)`
- `ApplyBaseDamage(int damage)`
- `TryGetBuildTowerStats(int buildIndex, out TowerStatsData stats)`
- `AddEnemyDefeatedReward(int gainedCoin, int gainedGold)`
- `AddSettlementGold(int gainedGold)`
- `GetRewardInventorySnapshot()`

附带完成：
- `CombatCoinChangedEventArgs` 增加了 `DeltaCoin`
- `CombatBaseHpChangedEventArgs` 增加了 `DeltaBaseHp`
- coin/baseHp 变化事件现在由 `CombatInRunResourceManager` 发布，而不是 `CombatNodeComponent`
- `Reset()` 现在会清理 `ParticipantTowerInstanceIds`

关键文件：
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatInRunResourceManager.cs`
- `Assets/GameMain/Scripts/Event/Combat/CombatCoinChangedEventArgs.cs`
- `Assets/GameMain/Scripts/Event/Combat/CombatBaseHpChangedEventArgs.cs`

### 4. CombatScheduler / CombatNodeComponent 已做一轮收口
#### CombatScheduler
- 启动时会先初始化 `CombatInRunResourceManager`
- 提供资源转发属性：
  - `CurrentCoin`
  - `CurrentGold`
  - `CurrentBaseHp`
  - `CurrentBuildTowerCount`
- 提供资源转发方法：
  - `TryConsumeCoin(...)`
  - `AddCoin(...)`
  - `TryGetBuildTowerStats(...)`
- 失败调试入口：
  - `TryDebugFail(...)`
- 不再通过 `CombatNodeComponent` 读写 baseHp/coin 真值
- 当前主职责已收紧为：
  - 生命周期入口
  - 状态切换入口
  - 对外公开查询/操作接口
  - 敌人事件公共入口
  - 事件桥回调入口

#### CombatScheduler 内部实现细化
- 已新增 `CombatSchedulerRuntimeContext`
  - 承载共享运行时字段与共享服务引用
- 已新增 `CombatSchedulerFlowCoordinator`
  - 承载多个状态共用的流程辅助方法
- 当前 `CombatScheduler` 本体不再直接堆所有共享字段和公用流程辅助

#### CombatNodeComponent
- 不再持有这些字段：
  - `_currentCoin`
  - `_currentGold`
  - `_currentBaseHp`
  - `_currentBuildTowerStats`
- 当前只保留：
  - 关卡数据缓存
  - `CurrentLevel / CurrentThemeType`
  - 战斗启动/结束协调
  - 最终结算摘要字段（`LastDefeatedEnemyCount / LastGainedCoin / LastGainedGold`）
  - 对 `CombatScheduler` 的只读/操作转发

关键文件：
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSchedulerRuntimeContext.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSchedulerFlowCoordinator.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatNodeComponent.cs`

### 5. EnemyManager 事件边界已改为只上报敌人事实
- `EnemyManager` 现在只向 `CombatScheduler` 上报：
  - `OnEnemyDefeated(DREnemy enemy)`
  - `OnEnemyReachedBase(DREnemy enemy)`
- coin/gold/baseDamage 的公共副作用已统一收口到 `CombatScheduler`
- `EnemyDropResolver + CombatInRunResourceManager` 已接到公共敌人事件入口上

关键文件：
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyManager.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/EnemyDropResolver.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs`

### 6. PhaseEndCondition 已正式接入 WaitingForPhaseEnd
- `CombatWaitingForPhaseEndState` 已改为通过：
  - `PhaseEndConditionFactory.Create(...)`
  - `IPhaseEndCondition.ShouldExit(...)`
  判定 phase 结束
- `PhaseLoopRuntime` 当前只保留 phase runtime 数据与 phase 进入逻辑，不再负责 `PhaseEndType` 判定

关键文件：
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatStates/CombatWaitingForPhaseEndState.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/PhaseEndConditions/`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/PhaseLoopRuntime.cs`

### 7. 结束链与异常失败链已做协议收口
- 正常结束：
  - `NodeCompleteEventArgs` 只在 `WaitingForReturn` 完成后发布
- 异常失败：
  - 使用 `CombatFailedState`
  - 弹出单按钮 `DialogForm`
  - 点击 `Return Menu` 后发布 `CombatFailureReturnEventArgs`
- `ProcedureMenu` 已区分正常结束与异常失败两条返回协议

关键文件：
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatStates/CombatWaitingForReturnState.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatStates/CombatFailedState.cs`
- `Assets/GameMain/Scripts/Event/Combat/CombatFailureReturnEventArgs.cs`
- `Assets/GameMain/Scripts/Procedure/ProcedureMenu.cs`

### 8. CombatSettlementContext 已收紧为结束链共享上下文
- 当前由 `Settlement -> RewardSelection -> FinishForm -> WaitingForReturn` 共享
- 已显式承载：
  - 结算事实
  - 奖励背包
  - 奖励选择相关流程标记
  - 低血惩罚相关事实
- 低血惩罚已改为“先记录事实，提交阶段再统一落库”，不再在结算构造期直接写库存
- `CombatFinishForm` 当前只消费它真正展示需要的摘要，不再把额外结算事实继续灌进 UI Context

关键文件：
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSettlementContext.cs`
- `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSettlementFlowService.cs`
- `Assets/GameMain/Scripts/UI/Combat/UseCase/CombatFinishFormUseCase.cs`

### 9. CombatInfoForm 已补手动失败测试入口
- `CombatInfoForm.OnFailButtonClick()` 可手动触发异常失败链
- 新增 `CombatDebugFailEventArgs`
- 当前可直接用于测试：
  - `CombatFailedState`
  - 失败 Dialog
  - `CombatFailureReturnEventArgs`

关键文件：
- `Assets/GameMain/Scripts/UI/Combat/View/CombatInfoForm.cs`
- `Assets/GameMain/Scripts/UI/Combat/Controller/CombatInfoFormController.cs`
- `Assets/GameMain/Scripts/UI/Combat/UseCase/CombatInfoFormUseCase.cs`
- `Assets/GameMain/Scripts/Event/Combat/CombatDebugFailEventArgs.cs`

## 还没完成

### 1. MapData + Event 解耦还没完全收口
当前：
- `CombatLoadingState` 已经会组装更完整的 `MapData`
- `MapEntity` 已经主要从 `MapData` 取初始上下文
- 但还需要继续确认地图侧事件和运行时依赖是否已经完全摆脱对 `CombatNode` 域的反查

目标状态：
- `CombatLoadingState` 从 `CombatInRunResourceManager` 读取快照
- `CombatLoadingState` 组装更完整的 `MapData`
- `MapEntity` 后续通过 `MapData + Event` 获取上下文，而不是反查 `CombatNode`

### 2. CombatScheduler 本体仍然还有收紧空间
当前：
- 生命周期入口、状态切换入口、对外公开接口、事件桥回调入口仍在 `CombatScheduler.cs`
- 共享字段和共享流程已经拆到了 `RuntimeContext + FlowCoordinator`
- 但 `FlowCoordinator` 目前仍直接依赖 `CombatScheduler` 宿主对象

目标状态：
- 对外公开接口与内部宿主职责进一步分离
- 若继续收紧，可评估是否引入极小宿主接口，只暴露：
  - `ChangeState(...)`
  - 必要的回调/转发入口
- 继续避免把新业务重新塞回 `CombatScheduler.cs`

### 3. CombatSettlementContext 还可以继续整理字段分层
当前：
- `CombatSettlementContext` 已能支撑结束链
- 但字段仍是平铺增长

目标状态：
- 更明确地区分：
  - 流程控制字段
  - 结算事实字段
  - 展示摘要字段
- 避免后续继续把 UI 需求和流程控制混在一起

### 4. 需要补实际运行验证
当前改动已覆盖：
- 状态机结构
- 结束链/失败链协议
- 手动失败测试入口
- `CombatSchedulerRuntimeContext + CombatSchedulerFlowCoordinator`
- `CombatSettlementContext` 与延迟提交惩罚

但仍缺：
- Unity 编译验证
- PlayMode/手点验证
- 失败路径回收验证
- 新开局后无残留状态验证

## 推荐的后续执行顺序

1. 做 `MapData + Event` 解耦收尾，排查 `MapEntity` 和地图侧事件是否还反查 `CombatNode`
2. 评估是否给 `FlowCoordinator` 引入极小宿主接口，继续收紧 `CombatScheduler` 本体
3. 继续整理 `CombatSettlementContext` 的字段分层
4. 补 Unity 编译与手动回归验证

## 当前做变更时要记住的约束

- 状态切换只能通过 `CombatScheduler.ChangeState(...)`
- 不要把新业务继续堆回 `CombatScheduler.cs`，优先考虑：
  - 状态私有逻辑
  - `CombatSchedulerFlowCoordinator`
  - 现有独立服务
- `CombatNodeComponent` 现在应该保持轻量 facade，不要再把 coin/baseHp/build snapshot 回流到它
- coin/baseHp 变化事件应继续由 `CombatInRunResourceManager` 发布
- `Failed` 只处理异常失败，不处理“基地血量归零”的正常失败路径
- 状态类应继续只通过 `CombatSchedulerRuntimeContext + CombatSchedulerFlowCoordinator` 访问共享状态与共享流程

## 当前关键入口文件速查

- 状态机宿主：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs`
- 共享运行时承载：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSchedulerRuntimeContext.cs`
- 共享流程协调：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSchedulerFlowCoordinator.cs`
- 局内资源真值：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatInRunResourceManager.cs`
- 状态类：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatStates/`
- 加载服务：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatLoadSession.cs`
- phase runtime：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/PhaseLoopRuntime.cs`
- phase end 条件骨架：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/PhaseEndConditions/`
- 敌人域 facade：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyManager.cs`
- CombatNode 入口 facade：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatNodeComponent.cs`
- 结束链共享上下文：
  - `Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatSettlementContext.cs`
- 异常失败返回事件：
  - `Assets/GameMain/Scripts/Event/Combat/CombatFailureReturnEventArgs.cs`

## 备注

- 当前环境没有可用的本地 C# 编译器（`dotnet / mcs / csc / msbuild / xbuild` 都不可用），所以本轮改动主要依赖文本级检查。
- 仓库目前有一些与本任务无关的脏文件，继续改动时只聚焦 `CombatNode` 相关文件即可，不要顺手回滚无关改动。