# Rogue Tetris TODO List

更新时间：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] 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 系统整理成可继续扩展、可回归、可替换资源的结构。