From e3ac8f870165e26be48615126cfde0022680d416 Mon Sep 17 00:00:00 2001
From: chengma <chengma2027@gmail.com>
Date: Tue, 14 Jul 2026 17:58:20 +0800
Subject: [PATCH] docs(tasks): add vertical product suite category rows

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

diff --git a/docs/tasks/T-634.md b/docs/tasks/T-634.md
new file mode 100644
index 0000000..1e84c57
--- /dev/null
+++ b/docs/tasks/T-634.md
@@ -0,0 +1,97 @@
+---
+id: T-634
+title: 商品套图结构配置改为纵向独立计数行
+status: TODO
+phase: 7
+deps: [T-622, T-631]
+created: 2026-07-14
+---
+
+# T-634 商品套图结构配置改为纵向独立计数行
+
+## 背景
+
+当前「商品套图」的「套图结构配置」将分类做成多列并排的按钮，并通过当前选中分类共用一组数量控件。用户需要先选分类，再确认和修改数量，默认分类之间的用途差异也不够直观。
+
+本任务将分类配置改为一类一行，每一行直接展示独立数量控件和必要说明。现有分类数据结构已经按分类分别保存数量，本任务只调整 GUI 展示与交互，不修改数据库、生成接口或任务结构。
+
+## 目标
+
+1. 默认分类和自定义分类都采用全宽纵向行展示，不再三列并排。
+2. 每个分类始终显示自己的数量步进控件，不再依赖先选中分类后使用共享计数器。
+3. 为三个默认分类增加固定用途说明，帮助用户快速理解各类图片的生成目的。
+4. 保持现有分类数量、排序、持久化和生成任务语义不变。
+
+## 实现方案
+
+### 1. 分类行布局
+
+- 将「套图结构配置」中的分类改为一类一行的紧凑纵向布局。
+- 默认分类行第一行展示分类名称，右侧展示独立的「减少、数量、增加」控件。
+- 默认分类说明放在分类名称下方，使用次要文字样式，不使用额外卡片。
+- 自定义分类同样一类一行，展示分类名称、独立数量控件，以及已有的重命名、删除操作。
+- 复用当前页面外层滚动区域，不给分类列表增加嵌套滚动条；窗口较小时由外层页面自然滚动。
+
+### 2. 默认分类说明
+
+固定使用以下中文文案，不在运行时自动改写：
+
+- 白底图：`白底主图，多角度呈现商品细节`
+- 场景图：`生活化场景展示商品使用方式`
+- 卖点图：`突出核心卖点和差异化优势`
+
+自定义分类第一版不自动生成说明，避免软件猜测用户的分类用途。
+
+### 3. 独立数量控制
+
+- 每个分类行的步进控件只修改该分类的数量。
+- 分类数量下限保持为 `0`；数量为 `0` 时禁用该行的减少按钮。
+- 默认数量继续沿用现状：白底图 `1`、场景图 `2`、卖点图 `2`。
+- 修改数量后立即刷新「合计 N 张」和「生成套图（N）」文案，并继续写入当前商品项目设置。
+- 生成任务仍严格按各分类保存的数量展开，不改变分类顺序和主图候选语义。
+
+### 4. 自定义分类行为
+
+- 新增自定义分类时默认数量保持为 `1`。
+- 重命名只修改名称，保留该分类原有数量和排序。
+- 删除只删除目标自定义分类，不影响三个默认分类及其他自定义分类。
+- 自定义分类数量与默认分类一样，在切换商品、重新打开项目和重启程序后仍能恢复。
+
+### 5. GUI 状态收敛
+
+- 移除或停用仅为旧版分类按钮服务的 `CategoryChipButton`、`active_category`、`select_category` 和共享详情计数器逻辑，避免界面存在两套数量来源。
+- 数量变化优先只刷新受影响行、合计和生成按钮；新增、重命名、删除分类时允许重建分类列表。
+- 不新增嵌套卡片、弹窗或额外确认步骤。
+
+## 验收标准
+
+- [ ] 白底图、场景图、卖点图分别占一行，不再横向并排。
+- [ ] 三个默认分类准确显示任务定义中的固定说明文案。
+- [ ] 三个默认分类初始数量仍为 `1 / 2 / 2`，且各自拥有独立的减少、数量、增加控件。
+- [ ] 操作任一分类的加减按钮只改变该分类，并立即同步合计数量和生成按钮数量。
+- [ ] 数量不能小于 `0`，为 `0` 时该行减少按钮不可用。
+- [ ] 自定义分类也是一类一行，新增默认数量为 `1`；重命名保留数量和排序；删除不影响默认分类。
+- [ ] 切换商品、重新打开项目及重启程序后，各分类数量与顺序保持正确。
+- [ ] 生成任务数量和分类分布与界面设置一致，现有生成和历史记录逻辑不受影响。
+- [ ] 在 `1180x760` 和项目支持的最小窗口尺寸下无文字、按钮或数量控件重叠，页面只使用现有外层滚动区域。
+- [ ] 不修改数据库 schema、cmhub 接口、CDP 流程及其他模块。
+
+## 验证
+
+```bash
+py -3.10 -m unittest tests.test_product_suite
+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
+```
+
+## 非目标
+
+- 不调整默认分类数量和分类业务含义。
+- 不为自定义分类自动生成说明文案。
+- 不修改图片生成模型、提示词、计费、并发或下载流程。
+- 不修改数据库、API、CDP 或其他标签页。
+
+## 执行记录