Tereis/TODO.md

Rogue Tetris TODO List

更新时间：2026-04-25

本清单基于当前代码实况重新整理，目的不是重复旧阶段计划，而是给下一轮开发提供可直接执行的任务顺序。

已核验现状

• 当前项目可以通过 build-mingw.ps1 正常编译
• 已有开始菜单、经典模式、Rogue 模式、规则页面
• 已有经典 / Rogue 主流程分流
• 已有等级、EXP、升级暂停、三选一升级 UI
• 已有较大规模强化池，已超出最初的 P1 范围
• 已有右侧 HUD、反馈浮层、Hold、特殊主动技能与多类特殊方块
• 当前渲染主要依赖 GDI 绘制，占位视觉已能支撑开发联调
• README.md 仍明显落后于当前实际功能

不变约束

• 不使用 class、继承、多态等面向对象特性
• 继续采用 struct + 全局状态 + 纯函数/过程函数 + 模块化源文件
• 经典模式继续作为稳定基线
• Rogue 模式继续独立演进，不把新逻辑重新塞回经典流程

当前主要问题

1. 状态仍然过于分散

• nType / type / state / point / target / nextTypes / holdType 仍是零散全局变量
• gameOverFlag / suspendFlag / currentScreen / currentMode / currentFallInterval 仍未收敛到统一运行时结构
• PlayerStats 已非常庞大，但仍混合“永久成长值 / 临时效果 / 主动道具 / 计时状态”
• 尚未形成明确的 PieceState / RuntimeState / BoardState 边界

2. 强化系统已能跑，但还不够“可维护”

• UpgradeEntry 已存在，但运行时强化状态仍主要散落在 PlayerStats
• 缺少真正的 UpgradeRuntime 聚合结构，后续继续加强化会越来越难维护
• 强化摘要、权重、可选条件、应用效果已经开始互相耦合
• 当前强化数量已经很多，继续直接往 switch 里堆功能风险很高

3. 文档、资源与代码现状不一致

• README.md 需要按当前 Rogue 版本重写
• TODO.md 以外的说明文档也需要同步功能现状
• assets 目录目前主要只有图标、背景图、音频文件，占位 UI 资源没有统一命名和落盘
• 当前程序实际上没有把 assets/images、assets/audio 真正接入主流程，只有图标进入资源编译

4. 缺少系统化回归与边界验证

• 连续升级、多选升级、诅咒升级的组合边界还没有形成固定检查项
• 失败复活、黑洞、清屏炸弹、空中换形、爆破/激光/十字方块之间还缺少系统回归
• 经典模式与 Rogue 模式共享底层逻辑，仍需要持续确认互不污染
• 当前没有最小回归测试清单，后续改结构风险很高

接下来建议按这个顺序做

第一优先级：先收敛状态结构

目标：在不改玩法的前提下，先把后续开发最痛的结构债降下来。

• 新增 PieceState 内容至少包含：当前方块类型、旋转状态、坐标、目标落点、Hold 状态、本回合是否已 Hold、当前特殊标记
• 新增 BoardState 内容至少包含：workRegion 与和棋盘直接相关的辅助数据
• 新增 RunState 或等效结构 内容至少包含：当前界面、当前模式、暂停、失败、当前下落间隔
• 把 Tetris.h 里的裸 extern 全局变量逐步迁入以上结构
• 保证迁移后仍维持纯过程式接口，不引入成员函数

完成标准：

• Tetris.h 中裸全局变量数量明显下降
• 生成、移动、固定、消行、渲染读取状态时不再依赖一串离散全局
• 迁移后项目仍可正常编译运行

第二优先级：把强化系统改成可继续扩展的形态

目标：在已有强化很多的前提下，避免后面每加一个功能都扩大维护成本。

• 新增 UpgradeRuntime 或等效结构 用于集中保存强化层数、主动技能次数、临时计时器、特殊开关
• 评估 PlayerStats 中哪些字段应保留为“玩家结算统计”，哪些应迁出到 UpgradeRuntime
• 整理 ApplyUpgradeById() 的职责边界 区分“加层数”“立即生效”“修改掉落速度”“发放主动道具”
• 整理强化摘要生成逻辑 避免右侧面板继续手写长串拼接
• 给强化池补一份分层标记 至少区分：基础成长、操作增强、主动技能、特殊方块、风险收益、进化类

完成标准：

• 新强化的接入步骤能稳定收敛为“定义数据 -> 写效果 -> 接摘要/显示”
• 不再继续向 PlayerStats 追加无边界字段

第三优先级：补齐占位资源与表现层基线

目标：把“纯 GDI 占位绘制”升级成“代码与资源协作的占位版本”，为后续替换美术留接口。

• 新建统一占位资源命名规范 例如：assets/ui/placeholder_panel_*、placeholder_upgrade_icon_*
• 至少补齐以下占位资源：
  • 升级卡片图标
  • 面板边框
  • 按钮 / 提示框底图
  • 规则页 / 菜单页的装饰性占位元素
• 明确哪些资源继续用 GDI 画，哪些开始从 assets 加载
• 检查 background.bmp、background.wav 是否要接入；如果短期不用，就从待办里单列，不再默认“已接入”
• 明确升级界面的选中态、普通态、诅咒态之外，是否还需要真正的禁用态

完成标准：

• 占位资源统一落在 assets 中
• 命名统一，不再出现临时散放资源
• 表现层替换资源时不需要回头改业务逻辑

第四优先级：平衡与回归

目标：把版本从“功能很多”拉到“继续改也不容易坏”。

• 调整等级需求曲线
• 调整强化权重与前置条件，减少无效选项
• 复查 Rogue 掉落速度曲线，避免后期过慢或过快
• 检查以下边界：
  • 连续升级时的 pendingCount / picksRemaining / optionCount
  • last_chance、terminal_clear、失败判定之间的顺序
  • 特殊方块落地后再消行时的结算顺序
  • Hold 后无法放置的失败分支
  • 黑洞 / 清屏炸弹 / 空中换形在暂停、升级、失败状态下的屏蔽是否完整
• 写出最小人工回归清单

建议最小回归清单：

• 经典模式正常开局、移动、旋转、消行、失败、重开
• Rogue 模式正常获得分数、EXP、升级
• 升级时稳定弹出正确数量的选项
• 多选升级结束后能正确回到游戏
• Hold、黑洞、清屏炸弹、空中换形只在允许状态下生效
• 最后一搏触发后不会直接卡死或丢失当前局状态

本轮之后立即可做的具体任务

A. 结构重构起手式

• 先只提取 PieceState
• 先把 type / state / point / target / holdType / holdUsedThisTurn / currentPieceIs* / nextTypes 收进去
• 保持函数名不变，先改内部访问路径，避免一次性大拆

B. 文档同步

• 重写 README.md 的“当前状态”和“项目简介”
• 补一段当前已实现强化类型总览
• 标明目前构建方式和已验证可编译状态

C. 回归清单落地

• 在项目根目录补一份简短测试清单文档
• 每次改动状态结构后先跑构建，再按清单手动验一轮

暂不优先处理

• 现在先不要继续无节制扩充强化种类
• 现在先不要做大规模视觉重绘
• 现在先不要把经典模式改造成也依赖 Rogue HUD

一句话总结

下一阶段的重点不是“再加多少强化”，而是先把已经做出来的 Rogue 系统整理成可继续扩展、可回归、可替换资源的结构。