docs/tasks/T-690.md

---
id: T-690
title: 商品套图统一商品ID校验与生成前提交
phase: 7
deps: [T-688, T-689]
status: DONE
created: 2026-07-22
---

## 问题 / 背景

商品套图已用正式商品ID拉取原图后，点击「生成套图」会使商品ID输入框失焦并触发 `editingFinished`。当前失焦回调单独用 `str.isdigit()` 校验，但生成入口和控件状态保存又直接把输入框原文写回任务状态。输入中含有不可见格式字符、网址片段或其他非数字字符时，界面会显示“商品ID只能输入数字”，同时生成前仍可能覆盖已绑定项目的 `state.item_id`，造成已拉取原图的商品上下文和输入状态不一致。

## 方案

### 1. 统一正式商品ID规范化与校验

- 在 `app/image_studio.py` 提供唯一的商品ID规范化与正式ID判定：去除首尾空白及 Unicode 格式控制字符后，仅接受 ASCII 数字；空值仅可用于临时项目。
- 商品套图的商品ID输入框增加数字输入约束，减少键入或粘贴时的无效字符；服务层规范化与校验仍是最终依据，不依赖 GUI validator。
- 非法输入保留在输入框并以中文提示“商品ID只能输入数字”，不得改变已绑定项目、任务状态、原图、job 或生成结果。

### 2. 统一提交入口

- 抽出可返回成功/失败的“提交当前商品ID”方法，集中处理：规范化、草稿绑定、切换商品确认、已有项目载入、控件错误样式及上下文刷新。
- `editingFinished`、拉取蝦皮主图、添加本地图片和开始生成均复用该方法；生成入口在保存其它控件或创建 job 前先提交校验，失败立即中止。
- `_save_controls_to_state()` 不再绕过提交入口直接覆盖 `state.item_id`。用户尚未确认的输入在切换任务或点击其它操作时不得污染当前项目状态。

### 3. 兼容与反馈

- 已绑定且商品ID未变化时，点击生成或拉取不重复弹出“切换商品”确认，也不出现商品ID告警。
- 合法修改商品ID继续沿用既有确认语义；用户取消、项目冲突或绑定失败后恢复已提交商品ID。
- 去除不可见格式字符后若成为有效数字，自动以规范化数字继续操作；包含其它字符的商品ID一律阻断，并保持中文可行动提示。

## 验收要点

- 已绑定正式商品并已拉取原图时，点击「生成套图」不再误报“商品ID只能输入数字”，当前项目ID、原图和生成上下文保持不变。
- 含零宽格式字符的有效数字会被规范化并可正常提交；网址、字母、连字符等非数字输入会阻断拉取、添加和生成，不覆盖既有 `state.item_id`、项目或 job。
- 输入合法新商品ID时仍显示既有切换确认；取消后恢复旧商品ID，确认后才切换项目。
- 临时项目仍可在商品ID为空时添加本地图片；输入正式数字后仍须确认绑定草稿。
- 自动验证：
  - `py -3.10 -m unittest tests.test_image_studio tests.test_product_suite tests.test_product_suite_gui`
  - `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`

## 边界（不改什么）

- 不改 SQLite schema、历史项目、生成任务状态、计费、图片下载或 cmhub 调用。
- 不改蝦皮 CDP 拉取、生成套图的实际提示词、轮询或导出逻辑。
- 不修改①至⑤模块的商品ID输入逻辑；本任务只统一商品套图（⑥）的已有项目绑定和生成前提交链路。

## 执行记录

- 2026-07-22 完成。
- `app/image_studio.py` 新增 `normalize_item_id_input()`，清除首尾空白和 Unicode 格式控制字符；`is_formal_item_id()` 改为仅接受 ASCII 数字。项目查询、创建和草稿绑定同步使用该规范化逻辑，避免不可见字符形成不同项目键。
- `ProductSuiteTab` 的商品ID输入框增加数字 validator，并抽出 `_commit_item_id()` 作为唯一提交入口。失焦、添加本地原图、拉取蝦皮主图和开始生成都会先规范化、校验、处理草稿绑定或商品切换确认；`_save_controls_to_state()` 不再直接覆写 `state.item_id`，因此非法输入不会污染已绑定项目上下文。
- 已绑定商品ID未变时，点击生成会继续原流程且不重复弹出切换确认；零宽格式字符会被自动清除。非数字、切换取消、项目冲突或绑定失败均保留已提交商品ID与项目，不创建 worker 或 job。
- 已同步 `docs/04-architecture.md`、`docs/routes.md`、`docs/api.md`。新增服务层测试覆盖格式字符和 ASCII 数字判定，新增 GUI 测试覆盖已绑定项目的零宽字符规范化、非法生成入口阻断与取消切换恢复。
- 验证通过：`py -3.10 -m unittest tests.test_image_studio tests.test_product_suite tests.test_product_suite_gui`（107项）、`py -3.10 -m unittest discover -s tests`（674项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。离屏 PySide6 有字体目录/插件告警，但无测试失败。
-											docs(tasks): add product suite item id validation task
										
										
											2026-07-22 18:07:34 +08:00
+								---
 								id: T-690
 								title: 商品套图统一商品ID校验与生成前提交
 								phase: 7
 								deps: [T-688, T-689]
-											fix(product-suite): validate item id before generation
										
										
											2026-07-22 18:14:50 +08:00
+								status: DONE
-											docs(tasks): add product suite item id validation task
										
										
											2026-07-22 18:07:34 +08:00
+								created: 2026-07-22
 								---
 								## 问题 / 背景
 								商品套图已用正式商品ID拉取原图后，点击「生成套图」会使商品ID输入框失焦并触发 `editingFinished`。当前失焦回调单独用 `str.isdigit()` 校验，但生成入口和控件状态保存又直接把输入框原文写回任务状态。输入中含有不可见格式字符、网址片段或其他非数字字符时，界面会显示“商品ID只能输入数字”，同时生成前仍可能覆盖已绑定项目的 `state.item_id`，造成已拉取原图的商品上下文和输入状态不一致。
 								## 方案
 								### 1. 统一正式商品ID规范化与校验
 								- 在 `app/image_studio.py` 提供唯一的商品ID规范化与正式ID判定：去除首尾空白及 Unicode 格式控制字符后，仅接受 ASCII 数字；空值仅可用于临时项目。
 								- 商品套图的商品ID输入框增加数字输入约束，减少键入或粘贴时的无效字符；服务层规范化与校验仍是最终依据，不依赖 GUI validator。
 								- 非法输入保留在输入框并以中文提示“商品ID只能输入数字”，不得改变已绑定项目、任务状态、原图、job 或生成结果。
 								### 2. 统一提交入口
 								- 抽出可返回成功/失败的“提交当前商品ID”方法，集中处理：规范化、草稿绑定、切换商品确认、已有项目载入、控件错误样式及上下文刷新。
 								- `editingFinished`、拉取蝦皮主图、添加本地图片和开始生成均复用该方法；生成入口在保存其它控件或创建 job 前先提交校验，失败立即中止。
 								- `_save_controls_to_state()` 不再绕过提交入口直接覆盖 `state.item_id`。用户尚未确认的输入在切换任务或点击其它操作时不得污染当前项目状态。
 								### 3. 兼容与反馈
 								- 已绑定且商品ID未变化时，点击生成或拉取不重复弹出“切换商品”确认，也不出现商品ID告警。
 								- 合法修改商品ID继续沿用既有确认语义；用户取消、项目冲突或绑定失败后恢复已提交商品ID。
 								- 去除不可见格式字符后若成为有效数字，自动以规范化数字继续操作；包含其它字符的商品ID一律阻断，并保持中文可行动提示。
 								## 验收要点
 								- 已绑定正式商品并已拉取原图时，点击「生成套图」不再误报“商品ID只能输入数字”，当前项目ID、原图和生成上下文保持不变。
 								- 含零宽格式字符的有效数字会被规范化并可正常提交；网址、字母、连字符等非数字输入会阻断拉取、添加和生成，不覆盖既有 `state.item_id`、项目或 job。
 								- 输入合法新商品ID时仍显示既有切换确认；取消后恢复旧商品ID，确认后才切换项目。
 								- 临时项目仍可在商品ID为空时添加本地图片；输入正式数字后仍须确认绑定草稿。
 								- 自动验证：
 								  - `py -3.10 -m unittest tests.test_image_studio tests.test_product_suite tests.test_product_suite_gui`
 								  - `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`
 								## 边界（不改什么）
 								- 不改 SQLite schema、历史项目、生成任务状态、计费、图片下载或 cmhub 调用。
 								- 不改蝦皮 CDP 拉取、生成套图的实际提示词、轮询或导出逻辑。
 								- 不修改①至⑤模块的商品ID输入逻辑；本任务只统一商品套图（⑥）的已有项目绑定和生成前提交链路。
 								## 执行记录
-											fix(product-suite): validate item id before generation
										
										
											2026-07-22 18:14:50 +08:00
+								- 2026-07-22 完成。
 								- `app/image_studio.py` 新增 `normalize_item_id_input()`，清除首尾空白和 Unicode 格式控制字符；`is_formal_item_id()` 改为仅接受 ASCII 数字。项目查询、创建和草稿绑定同步使用该规范化逻辑，避免不可见字符形成不同项目键。
 								- `ProductSuiteTab` 的商品ID输入框增加数字 validator，并抽出 `_commit_item_id()` 作为唯一提交入口。失焦、添加本地原图、拉取蝦皮主图和开始生成都会先规范化、校验、处理草稿绑定或商品切换确认；`_save_controls_to_state()` 不再直接覆写 `state.item_id`，因此非法输入不会污染已绑定项目上下文。
 								- 已绑定商品ID未变时，点击生成会继续原流程且不重复弹出切换确认；零宽格式字符会被自动清除。非数字、切换取消、项目冲突或绑定失败均保留已提交商品ID与项目，不创建 worker 或 job。
 								- 已同步 `docs/04-architecture.md`、`docs/routes.md`、`docs/api.md`。新增服务层测试覆盖格式字符和 ASCII 数字判定，新增 GUI 测试覆盖已绑定项目的零宽字符规范化、非法生成入口阻断与取消切换恢复。
 								- 验证通过：`py -3.10 -m unittest tests.test_image_studio tests.test_product_suite tests.test_product_suite_gui`（107项）、`py -3.10 -m unittest discover -s tests`（674项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。离屏 PySide6 有字体目录/插件告警，但无测试失败。