tasks.md 3.91 KB

任务列表:历史记录列表增量渲染 + 视口懒加载

阶段 1:增量 prepend(已完成 2026-04-24)

  • 1.1 HistoryManager.load_history_item_fast(timestamp) — 轻量单条读取(不走 index.json)
  • 1.2 抽出 _build_history_list_item(item) — 单条 widget 构建逻辑
  • 1.3 prepend_history_item(timestamp) — 增量插入 + 异常回退 refresh_history()
  • 1.4 四处 refresh_history() 调用点切换为 prepend_history_item(timestamp)
    • 1.4.1 on_generation_completeimage_generator.py:2895
    • 1.4.2 on_image_generatedimage_generator.py:2919
    • 1.4.3 _on_my_task_completedimage_generator.py:4514
    • 1.4.4 款式设计 tab on_generation_successimage_generator.py:4568
  • 1.5 语法自检通过(python -c "import ast; ast.parse(...)"

仍保留全量刷新(刻意保留,不影响使用习惯):

  • 手动点"刷新"按钮
  • 首次切到历史 tab
  • 删除单条 / 清空全部(阶段 2 才会动)

阶段 2:Model/Delegate 视口懒加载(下周启动)

Step 1 — 引入 Model/View 架构(已完成 2026-04-27)

  • 2.1 新增 HistoryListModel(QAbstractListModel)
    • 2.1.1 数据仅 list[str] timestamps(按时间戳倒序)
    • 2.1.2 实现 rowCount / data(index, role) / flags
    • 2.1.3 data() 按需调 HistoryManager.load_history_item_fast(timestamp),内部 OrderedDict LRU(max=300)缓存 icon/display_text/tooltip
    • 2.1.4 支持 prepend_timestamp / remove_timestamp / reset_timestamps / invalidate_cache
  • [~] 2.2 HistoryItemDelegate(QStyledItemDelegate)Step 1 暂未引入自定义 delegate
    • 2.2.1 沿用 QStyledItemDelegate 默认实现(IconMode 默认绘制 icon + 文本,与 QListWidget 一致)
    • 2.2.2 sizeHint 沿用默认(与 QListWidget IconMode 行为一致)
    • 备注:Step 2 引入异步 thumbnail 加载时再考虑是否需要自定义 delegate
  • 2.3 历史 tab 替换
    • 2.3.1 self.history_list = QListWidget(...)QListView(...) + IconMode/IconSize/Spacing/Adjust/Static 全部对齐旧版
    • 2.3.2 setModel(self.history_model)(delegate 沿用默认)
    • 2.3.3 clicked(QModelIndex) / customContextMenuRequested + indexAt(position) 信号迁移
  • 2.4 refresh_history 简化为 history_model.reset_timestamps([item.timestamp for ...])(不再建 widget)
  • 2.5 prepend_history_item 简化为 history_model.prepend_timestamp(timestamp)
  • 2.6 delete_history_item UI 侧改为 history_model.remove_timestamp(timestamp)(失败回退 refresh)
  • 2.7 clear_history UI 侧改为 history_model.reset_timestamps([])

Step 2 — 缩略图缓存 + 异步加载(性能优化)

  • 2.8 QPixmapCache 接入 delegate paint()(key = thumb_path)
  • 2.9 设置 cache limit(默认 ~50 MB,足够 ~500 张 thumb.jpg)
  • 2.10 ThumbnailLoader(QRunnable) 后台加载
    • 2.10.1 QThreadPool.globalInstance() 丢任务
    • 2.10.2 加载完回主线程 dataChanged(index) 触发 delegate 重绘
    • 2.10.3 cache miss 时 delegate 先画占位图,不阻塞滚动

Step 3 — 收尾与回归

  • 2.11 回归测试:
    • 2.11.1 单击历史项 → 详情面板正常联动
    • 2.11.2 双击 / 右键菜单 / 删除 / 清空 全部正常
    • 2.11.3 生成新图 → 立即出现在列表顶部
    • 2.11.4 滚动 300+ 条流畅,Activity Monitor 观察内存稳定
    • 2.11.5 Mac 连续工作 4 小时无闪退
  • 2.12 删除过时的 _build_history_list_item / QListWidgetItem 构造代码
  • 2.13 更新本文档(阶段 2 勾选完毕)

验证标准

  • 阶段 1:Mac 连续工作一天,崩溃次数从 14 次/日显著下降(目标:0 次)
  • 阶段 2:历史记录 1000 条时,首次切到历史 tab 的 UI 响应时间 < 200ms;滚动过程中内存峰值不超过 500 MB