cmshoppe/docs/tasks/T-629.md

---
id: T-629
title: ②封面画廊切换记录后候选勾选区自适应布局修复
phase: 7
deps: [T-626]
status: DONE
created: 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`。