按UI、美术资源、数值顺序重组TODO清单

TODO.md

@@ -2,166 +2,175 @@
 
 更新时间：2026-04-25
 
-本清单基于当前代码实况重新整理，目的不是重复旧阶段计划，而是给下一轮开发提供可直接执行的任务顺序。
+当前开发主线：
 
-## 已核验现状
+1. 整理 UI
+2. 补充美术资源
+3. 调整数值
 
-- [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 模式继续独立演进，不把新逻辑重新塞回经典流程
+- [x] 项目可以通过 `build-mingw.ps1` 正常编译
+- [x] 已有主菜单、经典模式、Rogue 模式、规则页
+- [x] 已有 Rogue HUD、等级、EXP、升级暂停、三选一升级界面
+- [x] 已有较完整的强化池、特殊方块、主动技能与反馈提示
+- [x] 已将 Rogue 主要逻辑拆到独立文件，便于后续继续整理表现层
 
-## 当前主要问题
+## 第一阶段：整理 UI
 
-### 1. 状态仍然过于分散
+目标：先把现有界面统一干净，信息层级明确，布局稳定，操作反馈清楚。
 
-- [ ] `nType / type / state / point / target / nextTypes / holdType` 仍是零散全局变量
-- [ ] `gameOverFlag / suspendFlag / currentScreen / currentMode / currentFallInterval` 仍未收敛到统一运行时结构
-- [ ] `PlayerStats` 已非常庞大，但仍混合“永久成长值 / 临时效果 / 主动道具 / 计时状态”
-- [ ] 尚未形成明确的 `PieceState` / `RuntimeState` / `BoardState` 边界
+### 1. 主菜单与规则页
 
-### 2. 强化系统已能跑，但还不够“可维护”
+- [ ] 统一主菜单、规则页、游戏内面板的视觉语言
+- [ ] 调整标题、正文、提示文案的字号层级
+- [ ] 检查菜单卡片间距、对齐和高亮态，避免现在的“能用但不够整”
+- [ ] 规则页重新梳理信息分组
+  建议分成：基础操作、Rogue 机制、主动技能、当前版本说明
+- [ ] 精简过长文案，减少一屏内的信息拥挤
 
-- [ ] `UpgradeEntry` 已存在，但运行时强化状态仍主要散落在 `PlayerStats`
-- [ ] 缺少真正的 `UpgradeRuntime` 聚合结构，后续继续加强化会越来越难维护
-- [ ] 强化摘要、权重、可选条件、应用效果已经开始互相耦合
-- [ ] 当前强化数量已经很多，继续直接往 `switch` 里堆功能风险很高
+### 2. 游戏内 HUD
 
-### 3. 文档、资源与代码现状不一致
+- [ ] 统一右侧面板的留白、卡片高度和分区顺序
+- [ ] 明确 HUD 的核心信息优先级
+  建议顺序：模式 / 分数 / 等级 EXP / 当前强化摘要 / Hold / Next / 按键提示
+- [ ] 检查经典模式 HUD，避免与 Rogue HUD 风格割裂太大
+- [ ] 压缩强化摘要显示，避免后期强化太多时面板失控
+- [ ] 检查提示文本换行和截断，尤其是中文长句
 
-- [ ] `README.md` 需要按当前 Rogue 版本重写
-- [ ] `TODO.md` 以外的说明文档也需要同步功能现状
-- [ ] `assets` 目录目前主要只有图标、背景图、音频文件，占位 UI 资源没有统一命名和落盘
-- [ ] 当前程序实际上没有把 `assets/images`、`assets/audio` 真正接入主流程，只有图标进入资源编译
+### 3. 升级选择界面
 
-### 4. 缺少系统化回归与边界验证
+- [ ] 统一升级界面中卡片的标题、分类、描述、等级标签布局
+- [ ] 明确三种状态的视觉差异
+  - [ ] 普通态
+  - [ ] 当前选中态
+  - [ ] 诅咒态
+- [ ] 补一个真正的“不可选/不显示”处理策略，避免后续扩展时 UI 语义混乱
+- [ ] 调整升级卡片高度和内部间距，减少文本拥挤
+- [ ] 检查 3 项 / 5 项升级时的布局一致性
+- [ ] 检查升级结束返回游戏时的反馈是否足够清楚
 
-- [ ] 连续升级、多选升级、诅咒升级的组合边界还没有形成固定检查项
-- [ ] 失败复活、黑洞、清屏炸弹、空中换形、爆破/激光/十字方块之间还缺少系统回归
-- [ ] 经典模式与 Rogue 模式共享底层逻辑，仍需要持续确认互不污染
-- [ ] 当前没有最小回归测试清单，后续改结构风险很高
+### 4. 浮层与反馈
 
-## 接下来建议按这个顺序做
+- [ ] 统一暂停、失败、升级三类覆盖层的边框、底色和标题样式
+- [ ] 调整反馈浮层的位置、尺寸和显示时间
+- [ ] 统一提示文案格式
+  建议统一成：事件标题 + 核心收益/变化
+- [ ] 检查连续触发多种效果时，反馈是否被覆盖得过快
 
-## 第一优先级：先收敛状态结构
+### 5. 当前阶段完成标准
 
-目标：在不改玩法的前提下，先把后续开发最痛的结构债降下来。
+- [ ] 主菜单、规则页、游戏 HUD、升级界面视觉风格一致
+- [ ] 中文排版、字号、留白、对齐达到可继续细化的基线
+- [ ] 玩家在不看代码的情况下能读懂主要状态和操作反馈
 
-- [ ] 新增 `PieceState`
-  内容至少包含：当前方块类型、旋转状态、坐标、目标落点、Hold 状态、本回合是否已 Hold、当前特殊标记
-- [ ] 新增 `BoardState`
-  内容至少包含：`workRegion` 与和棋盘直接相关的辅助数据
-- [ ] 新增 `RunState` 或等效结构
-  内容至少包含：当前界面、当前模式、暂停、失败、当前下落间隔
-- [ ] 把 `Tetris.h` 里的裸 `extern` 全局变量逐步迁入以上结构
-- [ ] 保证迁移后仍维持纯过程式接口，不引入成员函数
+## 第二阶段：补充美术资源
 
-完成标准：
+目标：把现在代码里硬绘制的占位 UI，逐步替换为统一命名、统一风格的占位资源。
 
-- [ ] `Tetris.h` 中裸全局变量数量明显下降
-- [ ] 生成、移动、固定、消行、渲染读取状态时不再依赖一串离散全局
-- [ ] 迁移后项目仍可正常编译运行
+### 1. 建立资源规范
 
-## 第二优先级：把强化系统改成可继续扩展的形态
+- [ ] 新建 `assets/ui/` 目录
+- [ ] 统一占位资源命名
+  例如：
+  - [ ] `placeholder_panel_*`
+  - [ ] `placeholder_button_*`
+  - [ ] `placeholder_upgrade_icon_*`
+  - [ ] `placeholder_overlay_*`
+- [ ] 明确哪些资源继续用 GDI 绘制，哪些改成资源加载
 
-目标：在已有强化很多的前提下，避免后面每加一个功能都扩大维护成本。
+### 2. 先补最需要的资源
 
-- [ ] 新增 `UpgradeRuntime` 或等效结构
-  用于集中保存强化层数、主动技能次数、临时计时器、特殊开关
-- [ ] 评估 `PlayerStats` 中哪些字段应保留为“玩家结算统计”，哪些应迁出到 `UpgradeRuntime`
-- [ ] 整理 `ApplyUpgradeById()` 的职责边界
-  区分“加层数”“立即生效”“修改掉落速度”“发放主动道具”
-- [ ] 整理强化摘要生成逻辑
-  避免右侧面板继续手写长串拼接
-- [ ] 给强化池补一份分层标记
-  至少区分：基础成长、操作增强、主动技能、特殊方块、风险收益、进化类
+- [ ] 主菜单卡片背景 / 边框占位资源
+- [ ] 规则页分区标题装饰
+- [ ] HUD 面板边框与卡片底图
+- [ ] 升级卡片图标占位资源
+- [ ] 升级卡片背景与诅咒态装饰
+- [ ] 浮层弹窗底图
+- [ ] 按钮 / 键位提示底图
 
-完成标准：
+### 3. 背景与氛围资源
 
-- [ ] 新强化的接入步骤能稳定收敛为“定义数据 -> 写效果 -> 接摘要/显示”
-- [ ] 不再继续向 `PlayerStats` 追加无边界字段
+- [ ] 评估是否接入现有 `background.bmp`
+- [ ] 如果保留纯色 / 渐变背景，则补一版更统一的背景方案
+- [ ] 评估 `background.wav` 是否接入
+- [ ] 如果暂时不用音频，就在文档里明确标记为“资源已存在但未接入”
 
-## 第三优先级：补齐占位资源与表现层基线
+### 4. 资源接入与替换
 
-目标：把“纯 GDI 占位绘制”升级成“代码与资源协作的占位版本”，为后续替换美术留接口。
+- [ ] 给升级卡片图标留出稳定的资源映射方式
+- [ ] 给菜单 / HUD / 浮层补最小资源加载接口
+- [ ] 避免资源路径和业务逻辑耦合过深
+- [ ] 替换时保证没有资源也能回退到当前占位绘制
 
-- [ ] 新建统一占位资源命名规范
-  例如：`assets/ui/placeholder_panel_*`、`placeholder_upgrade_icon_*`
-- [ ] 至少补齐以下占位资源：
-  - [ ] 升级卡片图标
-  - [ ] 面板边框
-  - [ ] 按钮 / 提示框底图
-  - [ ] 规则页 / 菜单页的装饰性占位元素
-- [ ] 明确哪些资源继续用 GDI 画，哪些开始从 `assets` 加载
-- [ ] 检查 `background.bmp`、`background.wav` 是否要接入；如果短期不用，就从待办里单列，不再默认“已接入”
-- [ ] 明确升级界面的选中态、普通态、诅咒态之外，是否还需要真正的禁用态
+### 5. 当前阶段完成标准
 
-完成标准：
+- [ ] UI 主要元素已经有统一的占位资源体系
+- [ ] `assets` 目录不再只是零散图标和背景图
+- [ ] 后续替换正式美术时不需要重写界面结构
 
-- [ ] 占位资源统一落在 `assets` 中
-- [ ] 命名统一，不再出现临时散放资源
-- [ ] 表现层替换资源时不需要回头改业务逻辑
+## 第三阶段：调整数值
 
-## 第四优先级：平衡与回归
+目标：在界面和资源相对稳定后，再系统调整 Rogue 的节奏、强度和成长曲线。
 
-目标：把版本从“功能很多”拉到“继续改也不容易坏”。
+### 1. 等级与成长节奏
 
 - [ ] 调整等级需求曲线
-- [ ] 调整强化权重与前置条件，减少无效选项
-- [ ] 复查 Rogue 掉落速度曲线，避免后期过慢或过快
-- [ ] 检查以下边界：
-  - [ ] 连续升级时的 `pendingCount / picksRemaining / optionCount`
-  - [ ] `last_chance`、`terminal_clear`、失败判定之间的顺序
-  - [ ] 特殊方块落地后再消行时的结算顺序
-  - [ ] Hold 后无法放置的失败分支
-  - [ ] 黑洞 / 清屏炸弹 / 空中换形在暂停、升级、失败状态下的屏蔽是否完整
-- [ ] 写出最小人工回归清单
+- [ ] 调整 EXP 获取速度
+- [ ] 调整升级频率，避免前期过快、后期过慢
 
-建议最小回归清单：
+### 2. 掉落与操作节奏
 
-- [ ] 经典模式正常开局、移动、旋转、消行、失败、重开
-- [ ] Rogue 模式正常获得分数、EXP、升级
-- [ ] 升级时稳定弹出正确数量的选项
-- [ ] 多选升级结束后能正确回到游戏
-- [ ] Hold、黑洞、清屏炸弹、空中换形只在允许状态下生效
-- [ ] 最后一搏触发后不会直接卡死或丢失当前局状态
+- [ ] 调整 Rogue 基础下落速度
+- [ ] 检查 `slow_fall`、`time_dilation`、`fever`、`high_pressure`、`extreme_player` 的叠加结果
+- [ ] 避免速度效果叠加后出现明显失控或无感
 
-## 本轮之后立即可做的具体任务
+### 3. 强化池权重
 
-### A. 结构重构起手式
+- [ ] 调整基础成长类强化的出现频率
+- [ ] 调整主动技能类强化的出现频率
+- [ ] 调整进化类强化的前置条件和权重
+- [ ] 减少明显无效或当前局收益过低的选项
+- [ ] 检查 3 选 1 / 5 选 2 时的整体体验
 
-- [ ] 先只提取 `PieceState`
-- [ ] 先把 `type / state / point / target / holdType / holdUsedThisTurn / currentPieceIs* / nextTypes` 收进去
-- [ ] 保持函数名不变，先改内部访问路径，避免一次性大拆
+### 4. 特殊机制强度
 
-### B. 文档同步
+- [ ] 调整爆破、激光、十字、彩虹方块的触发频率
+- [ ] 调整黑洞、清屏炸弹、空中换形的获得与使用强度
+- [ ] 调整最后一搏、终末清场的保命收益
+- [ ] 检查特殊机制是否破坏基础俄罗斯方块节奏
 
-- [ ] 重写 `README.md` 的“当前状态”和“项目简介”
-- [ ] 补一段当前已实现强化类型总览
-- [ ] 标明目前构建方式和已验证可编译状态
+### 5. 回归检查
 
-### C. 回归清单落地
+- [ ] 经典模式基础体验不受 Rogue 调整影响
+- [ ] Rogue 模式升级、选择、恢复流程稳定
+- [ ] 特殊方块落地后结算顺序正确
+- [ ] 主动技能在暂停、升级、失败状态下不会误触发
+- [ ] 多次升级、多选升级、诅咒升级组合下状态不乱
 
-- [ ] 在项目根目录补一份简短测试清单文档
-- [ ] 每次改动状态结构后先跑构建，再按清单手动验一轮
+### 6. 当前阶段完成标准
+
+- [ ] Rogue 模式的升级节奏稳定
+- [ ] 强化不再明显偏科或频繁出废选项
+- [ ] 特殊机制保留爽感，但不压垮基础玩法
+
+## 配套支持项
+
+这些事项不是当前主线，但在推进 UI / 资源 / 数值时需要同步维护。
+
+- [ ] `README.md` 按当前版本重写
+- [ ] 补一份简短人工回归清单文档
+- [ ] 继续维持 Rogue 逻辑分文件管理，避免重新塞回单文件
+- [ ] 如果后续 UI 改动开始受零散全局变量影响，再启动 `PieceState` 抽取
 
 ## 暂不优先处理
 
-- [ ] 现在先不要继续无节制扩充强化种类
-- [ ] 现在先不要做大规模视觉重绘
-- [ ] 现在先不要把经典模式改造成也依赖 Rogue HUD
+- [ ] 现在先不要继续大规模新增强化种类
+- [ ] 现在先不要优先做深度结构重构
+- [ ] 现在先不要先调数值再返工 UI
 
 ## 一句话总结
 
-下一阶段的重点不是“再加多少强化”，而是先把已经做出来的 Rogue 系统整理成可继续扩展、可回归、可替换资源的结构。
+接下来先把界面整理顺，再把占位资源补齐，最后在稳定表现层上做数值和平衡。