From 4cf0f46e902e39019c1fcd19d9f3743651be75f9 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Tue, 14 Jul 2026 18:05:38 +0800
Subject: [PATCH] docs(tasks): add dynamic product image empty state

---
 docs/tasks/T-635.md | 106 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 docs/tasks/T-635.md

diff --git a/docs/tasks/T-635.md b/docs/tasks/T-635.md
new file mode 100644
index 0000000..efbe261
--- /dev/null
+++ b/docs/tasks/T-635.md
@@ -0,0 +1,106 @@
+---
+id: T-635
+title: 商品套图原图取消固定六个占位并强化添加入口
+status: TODO
+phase: 7
+deps: [T-631]
+created: 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` 与项目支持的最小窗口尺寸下检查空状态、按钮文字和原图区域无重叠。
+
+## 验证
+
+```bash
+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 个展示位”以外的既有行为。
+
+## 执行记录