cmshoppe/docs/tasks/T-631.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-631	商品套图原图自适应展示与批量选择删除	7	T-627	DONE	2026-07-14

问题 / 背景

⑥「商品套图」的商品原图列表当前使用固定 210px 高度的 QListWidget。当原图超过当前可见行数时，列表内部出现纵向滚动；其外层配置面板本身又是 QScrollArea，形成嵌套滚动，用户不容易一次看清最多 16 张原图。

原图管理当前还存在以下限制：

• 每次只能通过悬停删除按钮、右键菜单或 Delete 键删除当前一张图片，不能全选、反选或批量移除。
• ProductOriginalList 同时承担单击下载、双击预览和拖拽排序；直接改成 Qt 多行选择会让预览、当前项和拖拽语义混在一起。
• 后端只有 image_studio.remove_asset_if_unused(asset_id) 单张删除。它会在图片被生成任务或终选引用时拒绝删除，并且故意保留本地文件；若 GUI 简单循环删除多张，可能出现前几张已删除、后一张失败的部分成功状态。
• 远程蝦皮原图可能仍在后台下载。下载过程中删除对应资产会造成 worker 回写已删除记录或遗留孤立文件的竞态。

顾客需要商品原图区域取消内部上下滚动、按图片数量自然向下展开；每张真实图片增加勾选框，标题右侧增加「全选」「反选」，并能从任意已勾选图片的右键菜单一次删除多张。

方案

1. 商品原图列表按内容自然展开

• 取消商品原图列表当前固定 210px 高度；关闭列表自身的横向和纵向滚动条。
• 根据列表当前可用宽度、gridSize、间距和可见 tile 数动态计算列数、行数与内容高度，并更新列表高度。计算须包含现有最少 6 个展示位语义，最多按 16 张真实原图计算。
• 图片数量变化、窗口或 splitter 宽度变化、缩略图下载完成、拖拽排序及任务切换后都要重新计算高度；不得只在首次创建控件时计算一次。
• 商品原图列表自然向下撑开后，由左侧外层 suiteConfigScroll 负责整页滚动；不得通过撑大主窗口、恢复列表内部滚动或制造横向滚动来容纳图片。
• 动态高度必须有明确上限并保持布局稳定，不能因占位图、悬停删除按钮、勾选框或图片下载完成而造成行高跳变。

2. 用勾选状态管理批量选择

• 只为具有真实 asset_id 的原图项显示复选框；「添加」占位项不得参与全选、反选、批量删除或已选数量。
• 批量选择以每项 Qt.CheckStateRole 或等价的自定义 delegate 状态为唯一事实源，不把 QListWidget 改成容易影响拖拽的多行选择模式，也不使用会破坏现有 InternalMove 排序的 setItemWidget() 堆叠子控件方案。
• 单击复选框只切换批量选择；单击缩略图继续执行现有的按需后台下载/当前项行为；双击继续预览；从缩略图区域拖动继续调整原图顺序。复选框点击和拖拽手势不得互相误触。
• 在「商品原图」标题右侧依次显示 已选 N 张、全选、反选。全选与反选只处理当前项目中可见的真实原图；无真实原图时禁用。
• 勾选状态是当前界面的临时操作状态，不写 SQLite 或 config.json。普通刷新和拖拽排序时按 asset_id 保留仍存在图片的勾选状态；切换账号、商品或套图任务及删除成功后清空，避免跨项目误删。
• 生成中继续沿用现有禁止删除边界；选中集合中存在正在后台下载的图片时，批量删除须整体阻断并给中文提示，不能边下载边删除。

3. 右键与键盘删除交互

• 右键已勾选图片且已选数量大于 1 时，菜单显示 删除选中的 N 张图片…；数量为 1 时显示 删除选中图片…。
• 右键未勾选图片时，不得静默清空或扩展已有勾选集合；菜单保留单张 删除这张图片…，如同时已有其他勾选图片，可另外显示明确带数量的批量删除动作。
• Delete/Backspace 键在存在勾选图片时按勾选集合执行批量删除；没有勾选图片时保持删除当前单张的既有语义。所有路径统一进入同一确认与服务层逻辑。
• 删除确认框必须显示准确数量，并明确：只从当前商品的原图列表移除，不删除蝦皮线上图片，也不删除本地源文件；以后重新拉取蝦皮主图时，线上仍存在的图片可能重新出现。
• 如果勾选集合包含当前第 1 张主图，确认框额外提示“删除后下一张图片将成为主图”。取消确认不得改变勾选状态或排序。
• 现有悬停 × 继续作为单张快捷删除入口，但也必须复用相同的确认和后端校验，不另写一套删除逻辑。

4. 后端事务级批量移除

• 在 app/image_studio.py 增加面向商品原图的批量服务，例如 remove_original_assets_if_unused(project_id, asset_ids, ...)；GUI 不得直接循环调用单张删除函数。
• 服务入口先归一化并去重 ID，然后一次性校验：项目存在且未删除、所有 ID 均属于该项目、资产类型均为 original、所有资产均未被 job 或 selection 引用。不得删除其他项目或生成结果资产。
• 任意一张校验失败时，整批不删除，并返回可供 GUI 中文说明的阻断原因；禁止部分成功。
• 全部校验通过后，在同一个 SQLite 事务中删除对应资产行，并按剩余顺序连续更新 source_order。本地图片文件继续保留，遵守现有 remove_asset_if_unused() 的非破坏性文件语义。
• 单张删除入口可复用批量服务的单元素路径，或保留兼容包装；不能让单张与批量删除形成不同的引用校验和文件处理规则。
• UI 层在调用服务前检查当前任务生成状态和所选资产下载状态；服务层负责项目归属、资产类型、引用和事务完整性，两层职责不得混淆。

5. 测试与界面验证

• tests/test_product_suite_gui.py 覆盖：
  • 原图列表横向/纵向滚动条关闭，0、6、7、16 张及宽度变化后高度和行数重新计算；
  • 只有真实图片有勾选状态，全选、反选和 已选 N 张 结果正确，空列表按钮禁用；
  • 普通刷新和排序保留有效 asset ID 的勾选，项目/任务切换及删除成功清空；
  • 复选框、单击下载、双击预览和拖拽排序语义互不覆盖；
  • 右键已选/未选图片及 Delete 键产生正确的单张或批量动作，确认文案包含数量和主图变化提示；
  • 生成中或选中图片下载中时批量删除被整体阻断。
• tests/test_image_studio.py 覆盖：
  • 多张未引用原图在单事务中删除，剩余 source_order 连续；
  • 选择中混入其他项目 ID、非原图 ID、不存在 ID 或已被 job/selection 引用的图片时全部不删除；
  • 删除资产行后本地文件仍存在；单张兼容入口与批量入口校验语义一致。
• 在最小支持窗口、常规窗口和 Windows 100% / 125% / 150% 显示缩放下人工检查 6、9、16 张原图：列表不出现内部滚动条，外层滚动自然，复选框不遮挡缩略图或文字，标题栏操作不重叠。

验收要点

• 商品原图列表不再固定高度或显示内部上下滚动条，最多 16 张图片按当前宽度自然换行并向下撑开，左侧配置区仍可正常滚动。
• 每张真实原图都有可操作的复选框，标题右侧可全选、反选并显示准确已选数量；占位项不参与选择。
• 预览、按需下载、拖拽排序、悬停单张删除与新增批量选择互不回归。
• 从已勾选图片右键或按 Delete 可一次删除选中集合；右键未勾选图片不会暗中改变批量范围。
• 批量删除只有全部校验通过才生效，引用中、跨项目、下载中或生成中的集合不会出现部分删除。
• 删除后下一张正确成为主图、剩余顺序连续；本地文件和蝦皮线上图片不被删除，重新拉取线上原图的语义有明确提示。
• 自动验证：
  • py -3.10 -m unittest tests.test_product_suite_gui
  • py -3.10 -m unittest tests.test_image_studio
  • py -3.10 -m unittest discover -s tests
  • python -m ruff check app tests main.py
  • py -3.10 -m compileall app main.py
  • git diff --check

边界（不改什么）

• 不删除本地图片文件，不删除或修改蝦皮线上商品图片；本任务的“删除”只表示从当前本地商品项目的原图资产列表移除。
• 不修改拉取蝦皮主图的 CDP 选择器、Chrome 前后台策略、登录检测和 Shopee 页面操作流程。
• 不修改 cmhub 生图提交、轮询、下载、并发、重试或计费逻辑，不修改生成结果/历史结果删除语义。
• 不把原图勾选状态持久化，不新增 SQLite 字段；只扩展现有图片资产服务的事务级批量操作。
• 不修改①～⑤模块 UI，不修改主窗口全局样式。

执行记录

• 2026-07-14 完成。
• ⑥商品原图列表已关闭横向/纵向内部滚动条，按当前可用宽度、固定缩略图尺寸和最多16张原图动态计算行数与高度；最少6个展示位保持不变，图片区自然向下展开并由外层 suiteConfigScroll 统一滚动。
• 每张真实原图通过自定义 delegate 显示独立复选框，添加占位图不参与选择。标题栏新增「已选 N 张 / 全选 / 反选」；普通刷新和拖拽排序按 asset_id 保留勾选，任务切换及删除成功后清空。复选框点击不会触发下载或预览，缩略图单击、双击、拖拽和悬停单张删除保持原语义。
• 右键菜单和 Delete/Backspace 已统一支持单张或勾选集合删除。确认框显示准确数量，包含主图变化、本地源文件保留、蝦皮线上图片不删除及重新拉取可能恢复的说明；生成中或任一选中图片仍在后台下载时整批阻断。
• app/image_studio.py 新增 remove_original_assets_if_unused()：一次校验项目、原图类型、job/终选引用，在同一个 SQLite 事务中删除资产行并连续重排 source_order；任一 ID 无效或被引用时整批不变，本地文件始终保留。
• 已同步 docs/04-architecture.md、docs/api.md 与 docs/routes.md。新增 GUI 和服务层测试，覆盖 0/6/7/16 张及宽度变化、选择状态、任务切换、点击/键盘/右键路由、运行与下载阻断、跨项目/非原图/不存在/job/终选引用的事务回滚。
• 离屏界面检查通过：1180×760 下16张图片为3列6行，内部滚动范围为0、外层滚动正常；960×640 的 Windows 125% / 150% 缩放模拟下标题栏操作不重叠，复选框不遮挡缩略图文字或右上角单张删除入口。
• 当前工作区全量测试仅有任务开始前已存在的默认封面提示词重命名导致3个旧 papa1 断言失败；在只包含 T-631 暂存内容的干净验证工作树中运行 py -3.10 -m unittest discover -s tests，479项全部通过。python -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check 全部通过。