cmshoppe/docs/tasks/T-635.md

id, title, status, phase, deps, created

id	title	status	phase	deps	created
T-635	商品套图原图取消固定六个占位并强化添加入口	TODO	7	T-631	2026-07-14

T-635 商品套图原图取消固定六个占位并强化添加入口

问题 / 背景

⑥「商品套图」当前会在真实商品原图不足 6 张时，向 ProductOriginalList 补入带“添加”图标的空 QListWidgetItem，因此全新商品虽然没有任何原图，界面仍固定显示 6 个图片位置。这个展示容易让用户误以为必须上传 6 张或最多只能上传 6 张，也让列表项数量与真实资产数量不一致；实际业务上限一直是 16 张。

顶部「添加图片」目前使用普通灰色按钮样式，与「历史生成」「打开结果文件夹」视觉权重相同。取消 6 个可点击占位后，它会成为添加本地图片的唯一显式入口，需要提高辨识度，但不能抢占底部「生成套图」主操作的层级。

T-631 曾明确保留“最少 6 个展示位”语义。本任务只覆盖该项旧约定；T-631 已完成的自然增高、外层滚动、勾选、批量删除、排序和预览行为继续保留。

目标

1. 商品没有真实原图时，列表真实项数量为 0，不再生成 6 个空图片位置。
2. 商品原图区域仍保留稳定、可识别的空状态和拖放范围，不因零图片完全塌陷。
3. 有图时只显示真实资产，并继续按实际数量自然向下扩展，最多 16 张。
4. 使用现有信息蓝强化「添加图片」，同时保持「生成套图」为页面唯一实心主按钮。

实现方案

1. 列表只承载真实资产

• 删除 _refresh_originals() 中将列表补足到 6 项的占位循环。
• ProductOriginalList.count()、可勾选项和可排序项都只对应当前项目的真实资产；不得用 UserRole=None 的假图片项维持布局。
• 原图计数继续显示真实数量与上限，例如无图时为 0/16、两张时为 2/16。
• 删除 _on_original_clicked() 中点击假占位项后打开文件选择框的分支；添加本地图片统一从顶部「添加图片」进入，拖放和粘贴仍可直接导入。

2. 零图片空状态

• 无真实图片时，列表内部显示简洁文字 暂无商品原图，但该文字不能作为 QListWidgetItem 参与数量、选择、排序或删除。
• 可通过列表绘制或等价的非数据项方式实现空状态；不得重新引入一个“空状态图片项”。
• 空列表保留约一行缩略图的稳定高度，继续接受文件拖放和剪贴板图片粘贴；不得把区域高度收缩为 0。
• 空列表时「已选 0 张」正常显示，「全选」「反选」保持禁用。
• 更新列表 tooltip，移除“点击占位图添加”的旧描述，只保留仍然有效的拖放、粘贴和排序提示。

3. 自适应高度与上限

• content_row_count() 和高度计算改为按真实图片数计算：0 张保留一行空状态高度，1 至 16 张按真实数量和可用列数计算行数。
• 保持横向、纵向内部滚动条关闭，由现有外层配置滚动区承载页面滚动。
• 真实图片上限仍为 MAX_ORIGINAL_ASSETS = 16，不修改导入、拉取、排序和存储协议。

4. 强化「添加图片」按钮

• 为 suiteAddImagesButton 增加对象级次要强调样式，复用项目现有信息蓝语义：
  • 默认：文字和边框 #0969da，背景 #eef4ff，文字加粗；
  • hover：背景 #dbeafe；
  • pressed：背景 #c7ddff；
  • disabled：背景 #f6f8fa、边框 #d8dee4、文字 #8c959f。
• 不使用成功绿、警告橙或危险红，也不改成与「生成套图」相同的实心蓝主按钮。
• 少于 16 张且未在导入、未在生成时保持可用；达到 16 张、正在导入或正在生成时禁用。
• 普通 tooltip 使用 添加本地商品原图；达到上限时提示 已达到16张商品原图上限。容量判断必须与导入服务使用同一资产口径，避免按钮显示可用但导入立即报满。

5. 保持既有交互

• 真实图片的勾选、全选、反选、右键批量删除、悬停删除、双击预览和拖拽排序保持不变。
• 未下载的蝦皮原图仍可单击触发后台下载，不因移除空占位而改变。
• 空状态和按钮样式不写入 SQLite 或配置文件，不影响商品项目持久化。

验收标准

• 全新商品没有原图时，original_list.count() 为 0，界面不显示 6 个“添加”缩略图。
• 零图片时显示 暂无商品原图 和 0/16，列表保留一行稳定高度；全选、反选不可用。
• 空列表仍可接收拖入文件和粘贴图片，成功后立即替换为空状态并显示真实缩略图。
• 1、2、5 张原图时分别只显示 1、2、5 个真实图片项，不自动补足到 6 个。
• 6、7、16 张时继续按宽度自然换行，列表内部无横向或纵向滚动条，外层页面滚动正常。
• 达到 16 张后不能继续通过「添加图片」导入；真实上限和原有中文数量提示保持不变。
• 「添加图片」使用定义的蓝色次要强调样式，hover、pressed、disabled 状态清晰；「生成套图」仍是唯一实心主按钮。
• 导入或生成期间「添加图片」禁用，结束后按真实容量恢复；tooltip 与当前状态一致。
• 真实图片的下载、勾选、批量删除、预览、排序及生成流程回归通过。
• 不修改数据库 schema、图片目录、cmhub、CDP 或其他标签页。

测试要求

• 更新 tests/test_product_suite_gui.py 中原来断言固定 6 项的用例，改为断言列表项数量等于真实资产数。
• 覆盖 0 张时非数据项空状态、稳定高度、拖放/粘贴信号和选择按钮禁用。
• 覆盖 1、2、5、6、7、16 张下的真实项数量和动态高度。
• 覆盖「添加图片」普通、满 16 张、导入中和生成中的样式/启用状态及 tooltip。
• 保留 T-631 已有勾选、右键、键盘删除、排序和批量事务测试。
• 在 1180x760 与项目支持的最小窗口尺寸下检查空状态、按钮文字和原图区域无重叠。

验证

py -3.10 -m unittest tests.test_product_suite_gui
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

非目标

• 不降低或提高最多 16 张商品原图的业务上限。
• 不新增第二个“添加图片”按钮或新的图片导入方式。
• 不调整拉取蝦皮主图、生成套图、删除本地资产或图片下载逻辑。
• 不修改 T-631 除“最少 6 个展示位”以外的既有行为。

执行记录