cmshoppe/docs/tasks/T-629.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-629	②封面画廊切换记录后候选勾选区自适应布局修复	7	T-626	DONE	2026-07-14

问题 / 背景

②「AI生成」列表双击任务行后会打开封面画廊。当前记录首次显示时，右侧生成图及其勾选框位置正常；按 ↑ / ↓ 切换到上一条或下一条记录后，候选图下方的勾选框可能进入图片显示区域，造成控件与图片重叠。

已核实的代码现状：

• T-626 让候选图片尺寸根据 viewport 和候选数量在 180～360px 内变化，但候选 item 仍由“图片 + QRadioButton + 说明文字”共同组成，整体高度没有使用各子控件的实际尺寸统一计算。
• _candidate_thumbnail_target_size() 使用固定 CANDIDATE_TEXT_HEIGHT = 72 预留图片下方区域；实际勾选框和说明文字高度会受候选名称、自动换行、字体及 Windows DPI 影响，固定值不能代表下一条记录的真实高度。
• _rebuild_candidate_items() 切换任务时先沿用上一条记录的 candidate_thumbnail_size 创建新 item，再依赖约 60ms 的 resize timer 延迟重算；切换瞬间可能出现“新内容 + 旧尺寸/旧高度”的布局组合。
• _update_candidate_thumbnail_layout() 主要更新 item 宽度和图片 label 的正方形尺寸，没有显式把 item 最小高度同步为本轮布局的真实 sizeHint()。
• 候选滚动区关闭垂直滚动；内容高度估算不足时没有垂直空间兜底，控件会被压缩、裁切或表现为进入图片区域。
• 现有 GUI 测试验证了候选图片尺寸、横向内容宽度和任务切换，但测试样本的候选数量较接近，也没有断言图片、勾选框和说明文字之间的几何关系，因此未覆盖本缺陷。

方案

1. 按完整候选卡片计算布局

• 修改 app/gui/tabs/generate.py 的 CoverGalleryDialog，将每个候选项作为完整卡片管理：图片、勾选框、说明文字和布局间距必须参与同一次尺寸计算。
• 推荐抽出内部候选卡片组件或等价 helper，提供 set_thumbnail_size(size)；更新图片尺寸后主动使内部布局失效并重新计算几何尺寸。
• 不再把固定 CANDIDATE_TEXT_HEIGHT = 72 作为图片下方区域的唯一高度依据。图片目标尺寸应根据 viewport 扣除候选卡片实际控制区高度后计算；固定值最多只能作为最小预留值。
• 控制区实际高度至少包含：
  • QRadioButton.sizeHint().height()；
  • 说明文字在当前 item 宽度下的 heightForWidth() 或布局实际 sizeHint()；
  • 布局 margins 和 spacing。
• 每轮更新后，候选 item 的最小高度必须不小于内部布局实际所需高度；candidate_content 的最小高度和实际高度必须不小于所有候选 item 的最大所需高度。
• 勾选框必须处于独立的图片下方布局行，不使用绝对坐标或覆盖层放置。

2. 切换任务时同步重排

• switch_task() / _reload_task_and_candidates() 重建候选列表后，应基于新任务的候选数量和当前 viewport 立即执行一次强制尺寸计算及布局同步。
• 新候选 item 不应等待 resize timer 才从上一条记录尺寸切换到当前记录尺寸。现有约 60ms timer 可继续用于合并窗口连续 resize 事件，但不能作为任务切换正确性的唯一保障。
• 同步更新候选 item、图片 label、候选内容容器的宽高后，调用必要的 invalidate()、activate()、updateGeometry() 或等价 Qt 布局刷新接口。
• 切换记录后把候选横向滚动位置重置到起点，避免下一条记录打开时停留在上一条的横向偏移；不得改变当前候选选择、未保存确认及 ↑ / ↓ 导航语义。

3. 候选文案与防御性布局

• 候选项可见名称保持简短稳定，例如「当前生效」「候选 2」；完整文件名放入中文 tooltip，避免长文件名通过换行无上限撑高控制区。
• 元信息保持简洁，优先单行或受控换行；图片读取失败占位仍占用与正常图片相同的图片区域。
• 正常路径应通过正确的内容高度消除重叠，不以开启垂直滚动条作为主要修复。若保留防御性垂直滚动，仍必须保证每个候选卡片内部不重叠。
• 画廊处于最小支持窗口或 Windows 高 DPI 环境时，可以缩小图片或出现横向滚动，但不能让图片覆盖勾选框和说明文字。

4. 回归测试

• 更新 tests/test_gui.py，构造候选数量和文案高度明显不同的两条任务，覆盖：
  • 单候选切换到 3 张以上候选；
  • 多候选切换回单候选；
  • 连续按 ↑ / ↓ 往返切换；
  • 当前生效候选、历史候选、长文件名及损坏图片占位。
• 测试应在弹窗显示并处理 Qt 事件后检查真实几何关系，至少断言：
  • 勾选框顶部位于对应图片底部和布局间距之后；
  • 说明文字位于勾选框之后；
  • item 最小高度覆盖内部布局 sizeHint()；
  • candidate_content 高度覆盖最高候选 item；
  • 所有候选 item 的横向范围不互相重叠。
• 分别检查任务切换同步完成后的状态，以及 resize timer 触发后的状态，防止只在延迟重排后暂时恢复。
• 保留 T-572、T-573、T-574、T-626 的方向键导航、横向滚动、保存和响应式缩放回归测试。

验收要点

• 双击②列表任意行打开封面画廊后，按 ↓ 或 ↑ 切换记录，所有候选图的勾选框始终完整位于图片下方，不进入图片、遮挡图片或被裁切。
• 在单候选、多候选、长候选名称、图片读取失败及候选数量变化场景下，图片、勾选框和说明文字均不重叠。
• 切换记录完成后立即获得正确布局，不出现可感知的先重叠再跳回现象。
• 调整弹窗大小后，候选图片继续按 T-626 的范围自适应，候选卡片整体高度同步刷新。
• 在常见 1366×768、1920×1080 及 Windows 100% / 125% / 150% 显示缩放下，控件无重叠和明显布局抖动。
• 不影响候选选择、保存提示、重置图片、原图查看、未保存确认和 ↑ / ↓ 切换记录。
• 验证命令：
  • py -3.10 -m unittest tests.test_gui
  • python -m ruff check app tests main.py
  • py -3.10 -m compileall app main.py
  • py -3.10 -m unittest discover -s tests
  • git diff --check

边界（不改什么）

• 不修改候选图发现、归档、排序、选择或保存语义。
• 不修改 SQLite schema、任务生成状态、提示词、AI/cmhub 请求、生图并发或图片保存格式。
• 不修改 Excel、③更新蝦皮、CDP 或蝦皮网页操作逻辑。
• 不通过增大固定窗口、硬编码更大的文字区高度或隐藏勾选框规避布局问题。

执行记录

• 2026-07-14：完成 T-629。
  • 复现确认：从单候选切换到 6 张候选时，旧实现把候选内容高度暂时设为图片高度 360px，但完整卡片实际需要 402px，导致勾选框被压到图片内部；延迟 resize timer 执行后才可能恢复。
  • app/gui/tabs/generate.py：新增内部候选卡片组件，统一按图片、勾选框、说明文字、margin 和 spacing 的实际尺寸计算固定卡片高度；内容容器按所有卡片真实宽高同步尺寸，候选卡片顶部对齐。
  • 任务切换和候选重建后立即按新候选数量及当前 viewport 强制重算图片与完整卡片尺寸，不再依赖约 60ms timer 才获得正确布局；切换记录时同时重置横向滚动位置，窗口连续 resize 仍保留合并重绘。
  • 非当前候选的可见名称改为「候选 N」，完整文件名保留在中文 tooltip，避免长文件名干扰尺寸；损坏图片继续使用固定图片区和「图片读取失败」占位。
  • tests/test_gui.py：新增真实 ↓ 键切换回归测试，覆盖单候选到多候选、长文件名、损坏图片、切换同步阶段、Qt 事件处理后、横向滚动复位和往返切换；逐卡断言图片、勾选框、说明文字及横向卡片几何不重叠。
  • 当前工作区运行 tests.test_gui 时，仅有任务开始前已存在的默认封面提示词 papa1.txt 改名造成的 2 项旧断言失败；未回退用户改动。在只包含 T-629 三个文件的隔离 worktree 中验证通过：py -3.10 -m unittest tests.test_gui（182 项）、py -3.10 -m unittest discover -s tests（462 项）、python -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check。