basil
/
geometry-tower-defense
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geometry-tower-defense/docs/CodeX-TODO.md

20 KiB
Raw Blame History

CodeX TODO

最后更新：2026-03-09

目标：基于当前仓库现状，为 docs/TODO.md 的 M1 收口补一份更可执行的补充顺序。 原则：先收主流程，再补硬规则，最后统一文档与验收口径。

执行规则

  1. 优先完成会阻塞 M1 验收的内容，不提前展开 M2 深度功能。
  2. 每一项先收“流程可走通”，再收“规则完整”，最后再做表现层补齐。
  3. ProcedureMain + NodeMapForm + PlayerInventory + CombatNode 视为当前主链路，后续补充都围绕这条链路推进。

阶段 S1 - 收口主流程

状态 ID 任务 交付物路径 验收标准
[x] S1-01 统一梳理 M1 当前状态与文档口径 docs/CodeX-TODO.md
docs/TODO.md		 当前实现、目标状态、未完成项三者口径一致
[x] S1-02 收口 ProcedureMain 的 Run 推进主链路 Assets/GameMain/Scripts/Procedure/ 从开始游戏到 Boss 结算可稳定走完整条链
[x] S1-03 收口节点进入、完成、失败后的统一回流 Assets/GameMain/Scripts/Procedure/
Assets/GameMain/Scripts/Event/		 战斗 / 事件 / 商店都能统一推进当前 Run
[x] S1-04 收口 Run 完成后的正式结束态 Assets/GameMain/Scripts/Procedure/
Assets/GameMain/Scripts/UI/Game/		 10 节点完成后有明确的结束表现与收尾逻辑

S1 验收清单

手工流程验收

  • 从主菜单进入游戏后，能进入 ProcedureMain，并看到 NodeMapForm + MainForm。
  • 当前节点可进入，非当前节点不可进入。
  • 普通战斗节点胜利后，会返回节点地图；当前节点变 Completed，下一节点变可进入。
  • 普通战斗节点在正常非胜利结算后（例如基地血量归零），会返回节点地图；当前节点仍按 Completed 处理，并推进到下一节点。
  • 战斗节点只在出现异常回退时，才会返回节点地图并把当前节点标记为 Exception；不会错误推进到下一节点。
  • 事件节点完成后，会返回节点地图，并推进到下一节点。
  • 商店节点退出后，会返回节点地图，并推进到下一节点。
  • 连续完成到第 10 个 Boss 节点后，不会再回普通 NodeMapForm。
  • Boss 完成后，会弹出正式结束对话框，而不是只停在流程内部状态。
  • 点击结束对话框确认后，会切回 Menu 场景并重新进入主菜单。
  • 回到主菜单后，不残留 NodeMapForm、MainForm、DialogForm。

运行时状态验收

  • Hub 阶段下，只允许当前节点进入。
  • NodeActive 阶段下，Hub UI 已关闭，不能重复从节点地图进入节点。
  • 普通节点成功后，会回到 Hub。
  • 节点发生异常回退后，会回到 Hub，但不会推进下一节点。
  • Boss 成功完成后，会进入 RunCompletedPendingFinish，并由正式结束态接管。
  • 正式结束态确认后，会走 ProcedureChangeScene -> ProcedureMenu 的回菜单链路。

回归测试验收

  • Unity Test Runner 的 Assets/Tests/EditMode 全部通过。
  • RunState 创建、固定序列、成功推进、异常标记相关测试全部通过。
  • NodeCompleteEventArgs 正常完成、正常非胜利、异常回退三种语义与库存快照 clone 测试全部通过。
  • ProcedureMainRunFlowService 的成功推进、异常回退、RunCompleted、NoChange 分支测试已补齐并全部通过。
  • ProcedureMainRunCompletionService 的“只弹一次结束对话框”和“只在完成态允许回菜单”测试已补齐并全部通过。

2026-03-09 更新：已补 NodeCompleteEventArgs 三种语义测试，以及 ProcedureMain 当前节点匹配守卫测试；你已确认本轮在 Unity Test Runner 中重新实跑 Assets/Tests/EditMode 且全部通过。

S1 通过标准

  • 从主菜单开始，一条 Run 可以稳定经历“节点进入 -> 节点完成 / 异常回流 -> Boss 完成 -> 正式结束态 -> 返回主菜单”，且过程中不会出现错误推进、重复进入、Boss 后回到普通 Hub、或 UI 残留。

S1-01 对齐结论

当前实现

  • ProcedureMain + NodeMapForm 已能创建固定 10 节点 Run，并驱动战斗 / 事件 / 商店三类节点的主流程入口。
  • RunState、FixedRunNodeSequenceBuilder、RunStateAdvanceService 与对应 Editor 测试已存在，说明 Run 模型、固定序列、节点推进基础能力已经落地。
  • 战斗节点已有结算、奖励选择、失败返回；事件和商店节点也会发出 NodeEnterEventArgs / NodeCompleteEventArgs，主流程闭环已能稳定走通。
  • P0-10 ~ P0-12 不是纯空白：
    • 出战前已有“参与区至少有 1 座塔”的最低门槛；
    • 品质 / Tag 已在组装、商店、展示链路中分散使用；
    • 耐久已有字段、展示与扣减入口。

M1 目标状态

  • M1 验收口径应以“从开始游戏到 Boss 节点结算结束，当前 Run 能稳定走完整条链”为准。
  • NodeMapForm 已可视为 M1 所需的节点流程界面；M1 不额外要求节点地图选择 UI 或表现层打磨。
  • 战斗 / 事件 / 商店都需要统一节点进入、完成、失败后的回流方式，避免每类节点各走一套。
  • 出战合法性需要从“至少有参战塔”收口为“满足完整三组件条件才可出战”。

仍未完成

  • 出战合法性仍停留在“参与区至少有 1 座塔”的最低门槛，尚未收口为“三组件完整合法参战”。
  • 品质 / Tag / 耐久在代码里已有局部实现，但还没有统一规则入口，因此仍应视为未收口项，而不是 M1 已完成项。

阶段 S2 - 对齐节点流程 UI 的 MVP 口径

状态 ID 任务 交付物路径 验收标准
[x] S2-01 确认 NodeMapForm 已满足 M1 所需的节点流程界面 docs/CodeX-TODO.md
docs/TODO.md		 不再把“正式节点地图表现”视为 M1 阻塞项
[x] S2-02 明确 M1 不扩展节点地图选择 UI 与表现层打磨 docs/CodeX-TODO.md
docs/MVP-Scope.md		 与 MVP-Scope.md 的范围口径一致

阶段 S3 - 收口出战合法性

状态 ID 任务 交付物路径 验收标准
[x] S3-01 定义“合法参战塔”的最终判定口径 docs/CodeX-TODO.md
Assets/GameMain/Scripts/Definition/		 流程层与 UI 层共用同一套判定口径
[x] S3-02 收口组装区与参战区的合法性校验 Assets/GameMain/Scripts/UI/Game/
Assets/GameMain/Scripts/CustomComponent/PlayerInventory/		 不合法塔不能进入参战区
[x] S3-03 在战斗入口补齐最终出战校验 Assets/GameMain/Scripts/Procedure/ 不满足完整条件时无法进入战斗节点
[x] S3-04 给出 UI / 日志层明确反馈 Assets/GameMain/Scripts/UI/Game/
Assets/GameMain/Scripts/Procedure/		 玩家知道为什么不能出战

S3-01 判定口径

  • S3-01 只收口 M1 所需的最小合法参战规则：塔实例存在，且能解析到枪口 / 轴承 / 底座三个组件实例。
  • 当前阶段不把品质、Tag、耐久、属性强度纳入“合法参战塔”定义；这些仍分别留在 S4、S5 收口。
  • 流程层、库存层、UI 层后续都必须共用同一个判定入口，不能再分别维护“至少有塔”“参战区非空”“组件看起来完整”这类分散判断。
  • 判定结果不能只返回 bool，还要能区分至少以下失败原因：塔不存在、缺枪口、缺轴承、缺底座。
  • 批量校验参战区时，需要同时给出“合法参战塔列表”“非法参战塔及原因”“是否至少存在一座合法参战塔”三个结果，供 S3-02 ~ S3-04 直接复用。

2026-03-09 更新：CombatParticipantTowerValidationService、CombatParticipantTowerValidationResult、CombatParticipantTowerValidationSummary 已落地；Unity Test Runner 已确认相关 EditMode 测试通过。

S3-02 当前落地状态

  • 参战分配链路已统一改为返回结果对象，而不是只返回 bool。
  • RepoFormUseCase、PlayerInventoryComponent、PlayerInventoryTowerRosterService、InventoryParticipantUtility 已接入 S3-01 的统一合法性校验入口。
  • 当前可稳定区分以下分配失败原因：塔不存在、塔缺少三组件之一、已在参战区、参战区已满。
  • 组装区 / 参战区 UI 仍保持“失败时静默拦截”的当前策略；战斗入口已补最终二次校验，避免旧快照、脏状态或外部改动绕过 S3-02 直接进入战斗。
  • 战斗入口校验失败时，ProcedureMain 现在会同时写明失败日志，并弹出 DialogForm 给出明确原因；空参战区会提示“至少需要 1 座完整装配了枪口、轴承、底座的塔”，脏数据则会列出具体缺失组件。

2026-03-09 更新：你已在 Unity Test Runner 中确认 Assets/Tests/EditMode 全部通过，其中包含 CombatParticipantTowerValidationServiceTests 与 ParticipantTowerAssignResultTests。

2026-03-09 更新：ProcedureMainCombatEntryValidationService 与战斗入口拦截已落地；你已确认 Unity Test Runner 全部通过，并手工验证了“空参战区开始战斗”会被拦截且弹出明确提示。

阶段 S4 - 收口品质 / Tag 规则

状态 ID 任务 交付物路径 验收标准
[x] S4-01 先确定 M1 需要的品质 / Tag 规则边界 docs/CodeX-TODO.md
docs/TODO.md		 文档先对齐，再落代码
[x] S4-02 把品质计算整理成单一入口 Assets/GameMain/Scripts/Definition/
Assets/GameMain/Scripts/CustomComponent/PlayerInventory/		 组装、掉落、商店使用一致结果
[x] S4-03 先固化 Tag 系统设计与首发范围 docs/TagSystemDesign.md
docs/CodeX-TODO.md		 Tag 的来源、汇总、生效与首发集合口径固定
[ ] S4-04 实现组件实例 Tag 的统一生成入口 Assets/GameMain/Scripts/Definition/
Assets/GameMain/Scripts/CustomComponent/PlayerInventory/		 掉落、商店、初始种子、事件奖励共用同一生成结果
[ ] S4-05 实现组塔后的 Tag 汇总与展示入口 Assets/GameMain/Scripts/Definition/
Assets/GameMain/Scripts/CustomComponent/PlayerInventory/
Assets/GameMain/Scripts/UI/		 组件 Tag 可汇总为塔级结果，且 UI 展示口径一致
[ ] S4-06 实现首批基础 Tag 的战斗生效 Assets/GameMain/Scripts/Entity/
Assets/GameMain/Scripts/Components/
Assets/GameMain/Scripts/Definition/		 首发 6~8 个基础 Tag 至少完成一批可验证效果
[ ] S4-07 补齐 Tag 规则与数据表的映射关系 Assets/GameMain/Scripts/DataTable/
Assets/GameMain/Scripts/Definition/		 表字段不是只存在而未被消费，Tag 参数可配置可解释

2026-03-09 更新：InventoryRarityRuleService 已落地；塔品质计算与组件品质归一化已统一收口，PlayerInventoryTowerAssemblyService、ShopFormUseCase、EnemyDropResolver、InventorySeedUtility 已接入同一规则入口。你已确认 Unity Test Runner 中 Assets/Tests/EditMode 全部通过，其中包含新增的 InventoryRarityRuleServiceTests。

2026-03-09 更新：S4-03 文档口径已冻结；TagSystemDesign.md 已明确组件实例生成、塔级 Stack 汇总、四段触发阶段、Tag.txt + TagRule 双表方向，以及 MVP 正式首发 7 个 Tag：Fire、Ice、Crit、Execution、Shatter、Inferno、AbsoluteZero。BurnSpread 已明确后移。

S4-01 边界结论

  • S4-01 只收口 M1 所需的最小规则闭环：先统一“品质如何算、Tag 如何生成/过滤、哪些链路必须共用同一结果”，当前阶段不要求 Tag 立即产生战斗效果。
  • 品质在当前仓库中不是空白功能：组件实例已有 Rarity 字段，掉落、商店、初始种子都已能给组件实例赋品质；塔组装时也已有“三组件品质取平均并四舍五入”的现有实现。
  • M1 对品质的目标口径是：塔品质必须由枪口 / 轴承 / 底座三个组件品质决定，且结果在组装、掉落、商店、展示、事件条件筛选等链路中可复现、可解释、口径一致。
  • M1 当前不把“品质决定配件槽位数量”视为阻塞项；配件系统本体尚未进入主链路，这部分仍保留在后续深度阶段，而不是作为 S4-01 当下必须落地的规则。
  • Tag 在当前仓库中也不是空白功能：组件表已有 PossibleTag，实例数据与展示链路也已有 Tags 字段与名称展示，但现在更接近“静态拷贝 + 展示消费”，还没有统一生成 / 过滤入口。
  • M1 对 Tag 的目标口径是：Tag 结果必须有统一来源，且在组装、掉落、商店、展示链路中可复现、可解释；不能再继续分散为“哪边方便哪边直接复制 PossibleTag”。
  • Tag.txt 的 MinRarity 与三张组件表的 PossibleTag 都应视为 S4-03 ~ S4-04 的规则输入，而不是已经被完整消费的既成事实；当前文档必须明确这一点，避免误判为“表字段已落地”。
  • 设计稿中的深度规则暂不纳入 M1 必收口范围：不要求现在就实现按品质随机 Tag 数量、不要求实现 Tag 等级成长，也不要求实现 Tag 的战斗数值效果。

S4 拆分方案

  • S4-02 只处理品质入口统一，不与 Tag 生成细节耦合；目标是把“塔品质计算、组件品质输入、展示品质”都收口到统一规则服务。
  • S4-03 对应 docs/TagSystemDesign.md 的文档收口阶段：固定 Tag 的候选池、实例生成时机、组塔汇总方式、战斗触发阶段、以及 MVP 正式首发 7 个基础 Tag 的集合。
  • S4-04 是 Tag 系统的第一段代码落地：为组件实例引入统一的 Tag 生成入口，不再直接复制 PossibleTag 全量候选；掉落、商店、初始种子、事件奖励必须共用同一套生成逻辑与随机口径。
  • S4-05 负责把三组件 Tag 汇总为塔级结果，并统一背包、组装、商店、详情面板的展示口径；此阶段不要求完成全部战斗效果，但不能再停留在“简单并集去重”的临时实现上。
  • S4-06 只落首批基础 Tag 的战斗效果，不一次展开全部 12 个 Tag；优先级按 TagSystemDesign.md 收口为状态类和数值修正类，例如 Fire、Ice、Crit、Execution、Shatter、Inferno、AbsoluteZero。
  • S4-07 负责把 Tag 设计真正映射回数据表与 DataRow，不再只保留 MinRarity 与 PossibleTag 两个弱约束字段；至少要支持权重、触发阶段、说明或效果参数中的一部分配置化消费。

S4-03 首发范围结论

  • MVP 首发 Tag 总量仍受 docs/MVP-Scope.md 的 6~8 个约束，但当前正式首发集合已固定为 7 个。
  • 首批优先做状态类与数值修正类，不优先做穿透、传播、爆炸、多命中等高侵入效果。
  • 当前正式首发基础集合为：Fire、Ice、Crit、Execution、Shatter、Inferno、AbsoluteZero。
  • BurnSpread、Pierce、Overpenetrate、FreezeMask、IgniteBurst 默认放到后续扩展阶段，不作为 S4 当前完成标准。

阶段 S5 - 收口耐久规则

状态 ID 任务 交付物路径 验收标准
[ ] S5-01 先确认 M1 是否保留完整耐久闭环 docs/CodeX-TODO.md
docs/TODO.md		 范围先明确，避免边做边改目标
[ ] S5-02 若保留，定义耐久对属性/出战资格的影响方式 Assets/GameMain/Scripts/Definition/
Assets/GameMain/Scripts/Entity/		 规则口径清晰且可测试
[ ] S5-03 实现耐久扣减后的实际生效 Assets/GameMain/Scripts/CustomComponent/PlayerInventory/
Assets/GameMain/Scripts/Entity/		 耐久不再只是展示字段
[ ] S5-04 实现 0 耐久销毁或失效闭环 Assets/GameMain/Scripts/CustomComponent/PlayerInventory/
Assets/GameMain/Scripts/UI/		 归零后行为符合最终口径

阶段 S6 - 回归与文档收尾

状态 ID 任务 交付物路径 验收标准
[ ] S6-01 补主链路回归测试 Assets/GameMain/Tests/ Run 推进、节点回流、Boss 完成可回归验证
[ ] S6-02 补规则侧测试 Assets/GameMain/Tests/ 合法性、品质、Tag、耐久关键公式可验证
[ ] S6-03 回写 docs/TODO.md 的真实状态 docs/TODO.md 文档状态与仓库现状一致
[ ] S6-04 清理临时描述、过期 TODO、命名偏差 docs/
Assets/GameMain/Scripts/		 后续推进时不再被旧口径误导

推荐执行顺序

  1. 先做 S1，把主流程真正收成一条稳定可验收的链。
  2. S2 已完成口径对齐，NodeMapForm 不再作为 M1 阻塞项。
  3. 接下来优先做 S3，补齐出战合法性，解决 P0-10。
  4. 再做 S4，统一品质 / Tag 的规则口径，解决 P0-11。
  5. 最后做 S5，决定耐久是完整收口还是同步缩范围，解决 P0-12。
  6. 全部完成后做 S6，补测试并同步文档状态。

本周建议开工顺序

  1. S1 与 S2 已完成口径收口，可直接进入规则侧收尾
  2. S3-01 ~ S3-04 已完成，当前可转入 S4
  3. 接下来决定 S4 和 S5 是完整实现还是同步缩范围
  4. 最后补 S6-01 ~ S6-04

备注

  • 这份清单只规划补充顺序，不试图在文档里展开所有实现细节。
  • 如果后续确认 M1 不做完整品质 / Tag / 耐久闭环，应先改 docs/TODO.md，再调整本清单。