PERF_OPTIMIZATION_CHECKLIST.md

ROCreader H700 性能优化清单

目标：在不改变功能、不改变界面表现、不影响构建和打包流程的前提下，逐项降低 CPU/GPU/IO 唤醒与持续占用。

当前基线

• 项目入口与主要运行逻辑集中在 src/main.cpp
• 构建入口保持不变：
  • Makefile
  • build_and_run.sh
  • cross_compile_and_package.sh
  • cross_compile_low_glibc.sh
  • package_to_apps.sh
• 当前环境缺少 git、rg、g++，因此本地只能做源码级与脚本级静态核查，不能在当前机器上完成实际编译验证
• 本清单按“小步提交、逐项验证、易回退”执行；每一轮只做一项优化

优化清单

• 第 1 项：静止场景停止无意义重绘
  • 范围：主循环空闲等待后的后续执行路径
  • 目标：当没有输入、没有活动动画、没有文本增量加载时，不再继续走整帧更新与渲染
  • 约束：不改变现有动画、翻页、滚动、设置菜单、TXT 增量排版的视觉表现
• 第 2 项：标题跑马灯只在确实需要时驱动刷新
  • 范围：书架聚焦标题滚动
  • 目标：只有文本实际超出可视宽度时才进入跑马灯计时和位移更新
• 第 3 项：配置/历史/收藏/TXT 恢复快照改为脏标记延迟写盘
  • 范围：ConfigStore、ProgressStore、PathSetStore 和 TXT resume cache 写盘时机
  • 目标：减少高频小 IO 与 TF 卡唤醒
• 第 4 项：书架扫描结果做目录级缓存
  • 范围：分类切换、目录进入、历史/收藏聚合扫描
  • 目标：减少重复递归扫描带来的 CPU 与 IO 峰值
• 第 5 项：PDF 首页面封面生成结果做磁盘缩略图缓存
  • 范围：无手动封面时的 PDF cover fallback
  • 目标：减少重复 PDF 光栅化带来的 CPU 峰值
• 第 6 项：延迟写盘唤醒不再触发整帧重绘
  • 范围：主循环 idle wait 与 deferred flush 的衔接路径
  • 目标：只为 flush 配置/历史/进度而唤醒时，不再顺带执行无意义渲染
• 第 7 项：音频后端改为首次播放时懒初始化
  • 范围：SfxBank 初始化时机与启动阶段音频设备占用
  • 目标：保留音频配置兼容性的前提下，避免启动后立即常驻音频后端
• 第 8 项：静态 UI 纹理尺寸查询结果缓存
  • 范围：状态栏、导航、设置预览等长期存在的 UI 纹理
  • 目标：减少渲染阶段重复 SDL_QueryTexture 的 CPU 小开销
• 第 9 项：书架标题省略结果缓存
  • 范围：未聚焦标题的省略字符串测量与生成
  • 目标：减少重复 measure + Utf8Ellipsize 的文本缓存查找开销
• 第 10 项：PDF 阅读页增加二级翻页缓存
  • 范围：阅读器中上一页/下一页来回切换时的页纹理复用
  • 目标：减少相邻页面往返时的重复渲染与纹理重建
• 第 11 项：封面加载失败回退改为复用同一解码结果
  • 范围：手动封面与 PDF 缩略图缓存命中后的纹理创建路径
  • 目标：避免因规范化失败而重复二次解码同一图片文件

完成情况

• 11/11 项已完成
• 已覆盖静止重绘、标题跑马灯、脏标记写盘、书架扫描缓存、PDF 封面缓存、延迟唤醒去重绘、音频懒初始化、UI 纹理尺寸缓存、标题省略缓存、PDF 二级翻页缓存、封面失败回退复用
• 最近一次 Windows smoke 已通过，未见回归
• 后续若再做性能工作，将作为新的独立小项单独验证，不再并入本清单