cmshoppe/docs/tasks/T-634.md

---
id: T-634
title: 商品套图结构配置改为纵向独立计数行
status: DONE
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 或其他标签页。

## 执行记录
- 2026-07-16：新增 `SuiteCategoryRow`，三个默认分类改为各占一行，准确显示固定用途说明与独立的减少/数量/增加控件；自定义分类同样独占一行并显示改名、删除操作。
- 2026-07-16：移除 `CategoryChipButton`、`active_category`、`select_category` 和共享详情计数器。普通数量变化只更新目标行、合计和生成按钮；新增、改名、删除时重建分类行，数量下限为 0 且减少按钮在 0 时禁用。
- 2026-07-16：生成期间统一禁用各分类步进器及自定义分类编辑；保留原有分类顺序、默认 `1/2/2`、项目设置持久化和生成 job 展开语义。
- 2026-07-16：补充纵向布局、固定说明、独立计数、0 下限、生成中禁用、自定义分类增删改、任务切换和项目重载测试；`1180x760` 离屏截图确认三行说明与控件无重叠，页面继续使用既有外层滚动区。
- 验证：当前工作区 `tests.test_product_suite_gui` 11 项、`tests.test_product_suite` 4 项通过，ruff、compileall、`git diff --check` 通过；基于 T-610 提交创建隔离 worktree 后，全仓 ruff、compileall、501 项 unittest 和 `git diff --check` 全部通过。