From 3e91360f88790450377e42802aaabd103d50369f Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Wed, 22 Jul 2026 17:38:40 +0800
Subject: [PATCH] docs(tasks): add product suite primary image sorting task

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

diff --git a/docs/tasks/T-688.md b/docs/tasks/T-688.md
new file mode 100644
index 0000000..262d302
--- /dev/null
+++ b/docs/tasks/T-688.md
@@ -0,0 +1,55 @@
+---
+id: T-688
+title: 商品套图主图拖拽排序反馈与拉取保护
+phase: 7
+deps: [T-631, T-658b]
+status: TODO
+created: 2026-07-22
+---
+
+## 问题 / 背景
+
+⑥「商品套图」的商品原图列表已经支持内部拖拽排序，列表第一张也是未勾选「每张上传图分别作为主图生成」时的主图；但是现有界面只以文字顺序隐含该规则，用户不容易确认“拖到第一张”是否已经生效。
+
+另外，拉取蝦皮主图时会有后台 worker 同步、下载和刷新原图列表。此时如果继续进行内部排序，用户的拖拽顺序可能与后台同步刷新竞争，造成排序结果不直观。生成过程中已有整体禁用原图列表的保护，拉取过程中需要更精确地只禁止内部排序，不把整个套图界面锁死。
+
+## 方案
+
+### 1. 明确第一张主图语义
+
+- 保持现有业务规则：未勾选「每张上传图分别作为主图生成」时，第 1 张商品原图是本轮所有任务的主图，其余最多 7 张按当前顺序作为参考图；勾选后第 1 张仍是白底图主图，其他分类按既有逐图主图规则执行。
+- 第 1 张真实原图显示清晰、非破坏性的「主图」视觉标识；后续图片显示「参考 N」。不得依赖颜色单独传达主图语义。
+- 列表 tooltip 改为明确中文说明：可拖动图片调整顺序，拖到第一位即可设为主图。
+- 排序持久化成功后，在状态栏提示“已更新商品原图顺序，第一张图片为主图”；不弹确认框，不修改蝦皮线上商品或已有生成结果。
+
+### 2. 拉取期间只锁定内部排序
+
+- `pull_running()` 为真时，禁止商品原图列表发起或接收内部拖拽排序；界面保留图片查看、状态显示和其他非冲突操作，不得把整个 GUI 灰化。
+- 内部排序被锁定时，hover/tooltip 明确提示“正在拉取蝦皮主图，完成后可调整图片顺序”。
+- `reorder_originals()` 保留服务层防御：即使通过迟到 signal 或直接调用进入，拉取中也不得写入排序，必须刷新回数据库当前顺序并给出中文状态提示。
+- 拉取完成、失败、取消和任务切换后恢复排序能力；生成运行中继续沿用既有禁用原图列表边界。
+
+### 3. 数据与历史边界
+
+- 继续复用 `image_studio.reorder_original_assets()` 的事务排序；不新增数据库字段，不改任务生成快照。
+- 已创建的生图 job 继续使用 T-658b 冻结的 `source_asset_id/reference_asset_ids`；之后拖动仅影响下一轮生成，不得修改第一轮历史、重试或恢复的图片输入。
+- 不改变本地原图下载、蝦皮主图拉取、cmhub 提交/轮询/下载、计费、终选、导出或①至⑤模块行为。
+
+## 验收要点
+
+- 用户能从第 1 张图片的「主图」标识和 tooltip 明确理解：拖到第一位即可设为主图。
+- 将任意原图拖到第一位后，数据库 `source_order` 持久化正确，刷新或重启后顺序不丢失，并显示排序成功状态提示。
+- 未勾选逐图主图时，下一轮 job 的主图和参考图顺序与拖拽后的顺序一致；已经存在的 job 快照不变。
+- 拉取蝦皮主图期间，内部拖拽排序不可用且不会写入数据库；其他非冲突操作不被整页锁死。拉取结束、失败、取消后可再次排序。
+- 生成中保持原有禁用边界，不出现拉取/生成状态切换后排序错误恢复或永久禁用。
+- 自动验证：
+  - `py -3.10 -m unittest tests.test_product_suite tests.test_product_suite_gui`
+  - `py -3.10 -m unittest tests.test_image_studio`
+  - `py -3.10 -m unittest discover -s tests`
+  - `py -3.10 -m ruff check app tests main.py`
+  - `py -3.10 -m compileall app main.py`
+  - `git diff --check`
+
+## 执行记录
+
+- 待实施。