cmshoppe/docs/tasks/T-634.md

id, title, status, phase, deps, created

id	title	status	phase	deps	created
T-634	商品套图结构配置改为纵向独立计数行	DONE	7	T-622 T-631	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 流程及其他模块。

验证

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 全部通过。