整理TODO

TODO.md

@@ -1,230 +1,167 @@
 # Rogue Tetris TODO List
 
-说明：本清单基于 [Rogue_Tetris_功能设计文档](./Rogue_Tetris_功能设计文档.md) 整理，后续实现严格遵守以下约束：
+更新时间：2026-04-25
+
+本清单基于当前代码实况重新整理，目的不是重复旧阶段计划，而是给下一轮开发提供可直接执行的任务顺序。
+
+## 已核验现状
+
+- [x] 当前项目可以通过 `build-mingw.ps1` 正常编译
+- [x] 已有开始菜单、经典模式、Rogue 模式、规则页面
+- [x] 已有经典 / Rogue 主流程分流
+- [x] 已有等级、EXP、升级暂停、三选一升级 UI
+- [x] 已有较大规模强化池，已超出最初的 P1 范围
+- [x] 已有右侧 HUD、反馈浮层、Hold、特殊主动技能与多类特殊方块
+- [x] 当前渲染主要依赖 GDI 绘制，占位视觉已能支撑开发联调
+- [ ] `README.md` 仍明显落后于当前实际功能
+
+## 不变约束
 
 - [x] 不使用 `class`、继承、多态等面向对象特性
-- [x] 以 `struct + 全局状态 + 纯函数/过程函数 + 模块化源文件` 组织代码
-- [x] 保留当前原版俄罗斯方块玩法，作为“经典模式”
-- [x] 新增开始菜单，进入游戏前先选择模式
-- [x] 模式至少包含：`经典模式`、`Rogue 模式`
-- [x] 强化选择界面固定为“三选一”三个选项框，视觉参考《吸血鬼幸存者》
-- [ ] 美术、图标、特效、音频先全部使用占位符资源
+- [x] 继续采用 `struct + 全局状态 + 纯函数/过程函数 + 模块化源文件`
+- [x] 经典模式继续作为稳定基线
+- [x] Rogue 模式继续独立演进，不把新逻辑重新塞回经典流程
 
-## 阶段 0：重构准备与技术基线
+## 当前主要问题
 
-目标：在不破坏现有可运行版本的前提下，为肉鸽系统预留结构。
+### 1. 状态仍然过于分散
 
-- [x] 盘点当前全局变量、输入流程、计时器流程、渲染流程
-- [x] 明确哪些旧逻辑保留，哪些逻辑需要拆分成独立过程函数
-- [x] 明确保留当前版本作为“经典模式”基线，不把 Rogue 逻辑硬塞进唯一流程
-- [x] 设计新的状态拆分方案：游戏主状态、棋盘状态、当前方块状态、玩家成长状态、强化状态、UI 状态
-- [x] 增加“菜单状态 / 模式选择状态”设计
-- [ ] 统一命名风格，避免后续继续扩散 `type/state/nType` 这类语义偏弱命名
-- [x] 明确“升级中暂停”和“普通暂停”是两个不同状态
-- [ ] 确定占位符资源策略：纯色块、边框、占位图标、占位按钮
+- [ ] `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` 全局变量逐步迁入以上结构
+- [ ] 保证迁移后仍维持纯过程式接口，不引入成员函数
 
 完成标准：
 
-- [x] 写出核心数据结构草案
-- [x] 写出模块拆分草案
-- [ ] 当前版本仍可正常编译运行
+- [ ] `Tetris.h` 中裸全局变量数量明显下降
+- [ ] 生成、移动、固定、消行、渲染读取状态时不再依赖一串离散全局
+- [ ] 迁移后项目仍可正常编译运行
 
-## 阶段 1：开始菜单与模式选择
+## 第二优先级：把强化系统改成可继续扩展的形态
 
-目标：先把“玩哪种模式”从启动流程里分出来，保证经典模式和 Rogue 模式能共存。
+目标：在已有强化很多的前提下，避免后面每加一个功能都扩大维护成本。
 
-- [x] 新增开始菜单界面，不启动即直接进入对局
-- [x] 菜单至少提供两个可选项：`经典模式`、`Rogue 模式`
-- [x] 增加菜单输入处理：上下/左右切换，确认进入
-- [x] 增加当前选中模式的高亮显示
-- [x] 增加菜单状态与对局状态之间的切换逻辑
-- [x] 从菜单进入经典模式时，沿用当前原版规则
-- [x] 从菜单进入 Rogue 模式时，进入带经验升级与强化的流程
-- [ ] 预留未来扩展入口，如“退出游戏”或“帮助说明”
+- [ ] 新增 `UpgradeRuntime` 或等效结构
+  用于集中保存强化层数、主动技能次数、临时计时器、特殊开关
+- [ ] 评估 `PlayerStats` 中哪些字段应保留为“玩家结算统计”，哪些应迁出到 `UpgradeRuntime`
+- [ ] 整理 `ApplyUpgradeById()` 的职责边界
+  区分“加层数”“立即生效”“修改掉落速度”“发放主动道具”
+- [ ] 整理强化摘要生成逻辑
+  避免右侧面板继续手写长串拼接
+- [ ] 给强化池补一份分层标记
+  至少区分：基础成长、操作增强、主动技能、特殊方块、风险收益、进化类
 
 完成标准：
 
-- [x] 启动后先进入菜单
-- [x] 两种模式都能正常进入
-- [x] 经典模式不受 Rogue 功能影响
+- [ ] 新强化的接入步骤能稳定收敛为“定义数据 -> 写效果 -> 接摘要/显示”
+- [ ] 不再继续向 `PlayerStats` 追加无边界字段
 
-## 阶段 2：核心数据结构改造
+## 第三优先级：补齐占位资源与表现层基线
 
-目标：把当前普通俄罗斯方块状态扩展成可承载 Rogue 系统的数据。
+目标：把“纯 GDI 占位绘制”升级成“代码与资源协作的占位版本”，为后续替换美术留接口。
 
-- [x] 新增 `MenuState` 或等效结构，记录菜单选项与当前选中项
-- [x] 新增 `GameState` 相关结构，记录运行态、暂停态、升级选择态、结算态
-- [x] 新增 `ModeState` 或模式标记，区分经典模式与 Rogue 模式
-- [ ] 新增 `PieceState` 结构，管理当前方块、下一方块、目标落点、是否可 Hold
-- [x] 新增 `PlayerStats` 结构，包含分数、等级、经验、所需经验、连击、总消行数
-- [ ] 新增 `UpgradeEntry` 结构，包含 `id`、名称、描述、分类、当前层数、是否可重复
-- [ ] 新增 `UpgradeRuntime` 结构，保存已获得强化和运行时效果值
-- [x] 新增 `UiState` 结构，保存当前三个升级选项、当前高亮项、弹窗可见性
-- [ ] 将现有散落的全局变量逐步收敛到几个结构体中
-- [x] 保留纯过程式调用，不引入成员函数
+- [ ] 新建统一占位资源命名规范
+  例如：`assets/ui/placeholder_panel_*`、`placeholder_upgrade_icon_*`
+- [ ] 至少补齐以下占位资源：
+  - [ ] 升级卡片图标
+  - [ ] 面板边框
+  - [ ] 按钮 / 提示框底图
+  - [ ] 规则页 / 菜单页的装饰性占位元素
+- [ ] 明确哪些资源继续用 GDI 画，哪些开始从 `assets` 加载
+- [ ] 检查 `background.bmp`、`background.wav` 是否要接入；如果短期不用，就从待办里单列，不再默认“已接入”
+- [ ] 明确升级界面的选中态、普通态、诅咒态之外，是否还需要真正的禁用态
 
 完成标准：
 
-- [ ] 代码中已能通过结构体访问大部分核心状态
-- [ ] 不再继续新增零散全局变量
+- [ ] 占位资源统一落在 `assets` 中
+- [ ] 命名统一，不再出现临时散放资源
+- [ ] 表现层替换资源时不需要回头改业务逻辑
 
-## 阶段 3：经典模式与 Rogue 模式分流
+## 第四优先级：平衡与回归
 
-目标：先把公共逻辑和模式专属逻辑分开，避免后续互相污染。
-
-- [x] 抽离经典模式与 Rogue 模式共享的核心逻辑：移动、旋转、落地、消行、渲染基础棋盘
-- [x] 经典模式保持当前简单计分与基础 UI
-- [x] Rogue 模式单独接入经验、等级、强化、升级界面
-- [x] 输入处理按模式分流，避免经典模式响应强化界面按键
-- [x] 渲染流程按模式分层：公共层、经典模式层、Rogue 模式层
-
-完成标准：
-
-- [x] 两种模式共用一套基础方块逻辑
-- [x] Rogue 新功能不会破坏经典模式
-
-## 阶段 4：分数、经验、等级主循环
-
-目标：把“消行 -> 得分 -> 获得经验 -> 触发升级”接入 Rogue 模式主循环。
-
-- [x] 重写消行结算函数，返回本次消除行数
-- [x] 按文档接入基础得分：1/2/3/4 行分别对应不同分值
-- [x] 按文档接入经验收益：1/2/3/4 行分别给予不同 EXP
-- [ ] 接入倍率计算：分数倍率、经验倍率、四消奖励、连击奖励
-- [x] 新增升级判定函数，支持一次结算后连续升多级
-- [x] 升级触发时停止下落计时与普通输入
-- [ ] 在右侧信息面板显示等级、EXP、所需 EXP、当前已获得强化摘要
-
-完成标准：
-
-- [x] 消行后可以稳定增加分数和经验
-- [x] 达到阈值后必定进入升级选择状态
-
-## 阶段 5：强化池与三选一系统
-
-目标：先完成最关键的 Rogue 核心体验。
-
-- [ ] 建立强化池初始化函数，不使用类，采用静态数组或 `std::vector<UpgradeEntry>`
-- [ ] 先实现一批 P1 基础强化，优先选 6 个左右最稳定的：
-- [x] `score_multiplier`
-- [x] `combo_bonus`
-- [x] `slow_fall`
-- [x] `preview_plus_one`
-- [x] `exp_multiplier`
-- [x] `last_chance`
-- [x] 随机抽取 3 个不重复选项，避免当前局内明显无效选项
-- [x] 支持重复强化的层数叠加
-- [x] 选中后立即应用效果并返回游戏
-- [x] 为后续强化扩展预留 `applyUpgradeById()` 分发函数
-
-完成标准：
-
-- [x] 每次升级都稳定弹出三个选项框
-- [x] 选择任一选项后效果立即生效
-
-## 阶段 6：升级界面 UI
-
-目标：实现参考《吸血鬼幸存者》的三选一视觉结构，先用占位表现。
-
-- [x] 增加全屏或半透明遮罩，压暗游戏场景
-- [x] 中央显示三个横向或纵向排列的选项框
-- [x] 每个选项框至少包含：占位图标、强化名、强化说明、强化分类、当前层数
-- [x] 支持键盘选择：`A/D` 或方向键切换，`Enter/Space` 确认
-- [ ] 高亮态、选中态、禁用态视觉区分明确
-- [x] 保证四个框尺寸一致、布局稳定，不因文本长度错位
-- [x] 右侧现有信息面板在升级状态下保留或弱化显示，但不能抢焦点
-- [ ] 占位资源统一放入 `assets`，命名先按 `placeholder_*`
-
-完成标准：
-
-- [x] 升级界面可以独立显示
-- [x] 三个选项框可操作、可确认、可关闭
-- [x] 视觉结构已经接近目标形式，后续只需替换资源
-
-## 阶段 7：玩法强化第一轮
-
-目标：把最影响体验的几个强化真正接入玩法。
-
-- [x] 分数倍率：影响所有结算得分
-- [x] 连击奖励：连续多次成功消行追加奖励
-- [x] 慢速下落：降低自然下落速度
-- [x] 额外预览：从 1 个 Next 扩展到 2~3 个
-- [x] EXP 强化：提升经验获取倍率
-- [x] 最后一搏：失败前自动清除底部 3 行，仅触发一次
-
-完成标准：
-
-- [x] 每个强化都能在实际对局中观察到效果
-- [ ] 强化效果叠加后不会引发明显逻辑冲突
-
-## 阶段 8：特殊机制第二轮
-
-目标：在主体验稳定后再上特殊规则，避免一开始把复杂度拉满。
-
-- [x] Hold 功能改造成可解锁能力，而不是默认启用
-- [ ] 扩展更多预览块显示
-- [x] 清扫者：累计消行触发底部清除
-- [x] 爆破方块：生成特殊方块并实现 3x3 清除
-- [x] 减压：升级后清除最高占用行
-- [x] 稳定结构：小概率自动填补邻近空洞
-- [x] 双倍成长 / 赌徒 / 方块改运等特殊强化
-
-完成标准：
-
-- [x] 至少 2 个特殊机制能稳定跑通
-- [ ] 不会明显破坏基础俄罗斯方块节奏
-
-## 阶段 9：界面补全与反馈
-
-目标：让系统信息足够清楚，不靠猜测理解机制。
-
-- [x] 右侧面板补充等级、EXP 条、强化列表、当前倍率
-- [x] 增加本次结算浮动提示：`+Score`、`+EXP`、`Level Up`
-- [x] 为特殊强化增加简短提示文案
-- [x] 增加暂停、升级、失败三种不同遮罩样式
-- [ ] 增加占位图标、占位按钮、占位边框资源
-- [ ] 检查中文排版、字号、留白、长文本换行
-
-完成标准：
-
-- [x] 玩家能看懂自己为什么升级、为什么得分变化
-
-## 阶段 10：平衡与稳定性
-
-目标：把版本从“能跑”拉到“能玩”。
+目标：把版本从“功能很多”拉到“继续改也不容易坏”。
 
 - [ ] 调整等级需求曲线
-- [ ] 调整强化出现权重，避免过强或无效强化频繁出现
-- [ ] 调整下落速度、经验速度、升级频率
-- [x] 修复升级状态下的非法输入问题
-- [ ] 修复连续升级、失败复活、爆破消行等边界问题
-- [ ] 增加最基础回归测试清单
+- [ ] 调整强化权重与前置条件，减少无效选项
+- [ ] 复查 Rogue 掉落速度曲线，避免后期过慢或过快
+- [ ] 检查以下边界：
+  - [ ] 连续升级时的 `pendingCount / picksRemaining / optionCount`
+  - [ ] `last_chance`、`terminal_clear`、失败判定之间的顺序
+  - [ ] 特殊方块落地后再消行时的结算顺序
+  - [ ] Hold 后无法放置的失败分支
+  - [ ] 黑洞 / 清屏炸弹 / 空中换形在暂停、升级、失败状态下的屏蔽是否完整
+- [ ] 写出最小人工回归清单
 
-回归检查：
+建议最小回归清单：
 
-- [ ] 开局正常生成方块
-- [ ] 消行得分与经验正确
-- [x] 升级必出 3 个选项框
-- [x] 选择后恢复游戏且不丢状态
-- [ ] 复活、暂停、失败、重开互不冲突
+- [ ] 经典模式正常开局、移动、旋转、消行、失败、重开
+- [ ] Rogue 模式正常获得分数、EXP、升级
+- [ ] 升级时稳定弹出正确数量的选项
+- [ ] 多选升级结束后能正确回到游戏
+- [ ] Hold、黑洞、清屏炸弹、空中换形只在允许状态下生效
+- [ ] 最后一搏触发后不会直接卡死或丢失当前局状态
 
-## 建议实现顺序
+## 本轮之后立即可做的具体任务
 
-1. 先做阶段 1 到阶段 3，把“菜单选模式 + 经典 / Rogue 分流”打通。
-2. 再做阶段 4 到阶段 6，完成 Rogue 的经验升级与三选一界面。
-3. 然后做阶段 7，把第一批基础强化真正接上。
-4. 最后做阶段 8 到阶段 10，补特殊机制、表现和调平衡。
+### A. 结构重构起手式
 
-## 当前最近一轮执行清单
+- [ ] 先只提取 `PieceState`
+- [ ] 先把 `type / state / point / target / holdType / holdUsedThisTurn / currentPieceIs* / nextTypes` 收进去
+- [ ] 保持函数名不变，先改内部访问路径，避免一次性大拆
 
-- [x] 加入开始菜单状态
-- [x] 做出模式选择菜单占位 UI
-- [x] 接入 `经典模式 / Rogue 模式` 两个入口
-- [x] 建立新的状态结构体与头文件声明
-- [x] 拆分经典模式与 Rogue 模式主循环
-- [x] 重写消行结算返回值
-- [x] 加入 `PlayerStats`
-- [x] 加入经验与升级判定
-- [x] 加入升级状态切换
-- [x] 做出三个升级选项框的占位 UI
-- [x] 接入第一批 6 个基础强化
+### B. 文档同步
+
+- [ ] 重写 `README.md` 的“当前状态”和“项目简介”
+- [ ] 补一段当前已实现强化类型总览
+- [ ] 标明目前构建方式和已验证可编译状态
+
+### C. 回归清单落地
+
+- [ ] 在项目根目录补一份简短测试清单文档
+- [ ] 每次改动状态结构后先跑构建，再按清单手动验一轮
+
+## 暂不优先处理
+
+- [ ] 现在先不要继续无节制扩充强化种类
+- [ ] 现在先不要做大规模视觉重绘
+- [ ] 现在先不要把经典模式改造成也依赖 Rogue HUD
+
+## 一句话总结
+
+下一阶段的重点不是“再加多少强化”，而是先把已经做出来的 Rogue 系统整理成可继续扩展、可回归、可替换资源的结构。