geometry-tower-defense/docs/CodeX-TODO.md

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 相关文件即可，不要顺手回滚无关改动。