cmshoppe/docs/tasks/T-662d.md

---
id: T-662d
title: 更新蝦皮商品状态后台拦截与T-659预检整合
status: DONE
phase: 7
deps: [T-662a, T-659]
created: 2026-07-18
---

# T-662d 更新蝦皮商品状态后台拦截与T-659预检整合

## 问题 / 背景

③属于线上写操作。即使用户在①选择采集所有状态，或在②明确选择生成所有状态，也不能把该选择继承为线上更新授权。商品状态是采集快照，不能取代 Shopee 执行时校验，但已知非正常状态必须在创建 `ApplyWorker` 前被拦截。

## 方案

- 本任务不新增商品状态列、下拉框或“强制更新异常商品”入口；现有批次、店铺、商品ID、任务状态和更新内容模式保持不变。
- 扩展 T-659 结构化预检，先按共享状态 helper 分组，再检查标题/封面完整性：只有 `normal` 可进入可执行集合；`unlisted/reviewing/unknown`（含历史 NULL）全部从正式更新和 dry-run 的 Worker 列表剔除。
- 预检结果分别保存：可执行、缺标题、缺封面、未上架、审核中、状态未知；同一任务只计一次总跳过，但各原因统计可分别展示。明确原因优先级，保证汇总去重稳定。
- 确认框、状态栏与本轮日志显示异常状态排除数量、分类和示例商品ID。预检排除记录不计入 worker 的成功/略过/失败，不改 stage/status/Excel。
- 内容缺失和商品异常全部剔除后没有可执行任务时，按真实主因显示中文中止文案；全部异常时不得误报「更新内容未生成」。
- 不能先因当前模型任务为空而返回通用文案；必须先读取商品状态筛选不存在时的当前基础范围并执行预检，确保全异常批次得到真实中止原因。
- 「检查本轮更新」与正式更新使用同一 planner 和计划指纹；用户确认期间 `task_id/updated_at/product_status/new_title/new_cover_path/更新模式` 变化时废弃旧计划。
- ①②弹窗选择仅影响各自本轮，③不读取或继承其范围策略。现有商品失效 toast、页面校验、账号预检、最终中文确认和 T-659 内容校验继续作为执行层防线。

## 验收标准

- [ ] 未上架、审核中、未知和历史 NULL 均不能进入正式更新或 dry-run Worker；只有 `normal` 可继续内容预检。
- [ ] ①采集所有状态或②生成所有状态不会授权③更新非正常商品。
- [ ] 确认框正确合并内容缺失与三类商品状态原因，同一任务总数不重复。
- [ ] 全异常时显示商品状态中止原因；全缺内容时仍保持 T-659 文案。
- [ ] 被排除记录不进入 `ApplyWorker`，DB、Excel 和本轮 worker 统计不变。
- [ ] T-659 三种更新模式、账号就绪、分批、停止和真实更新确认不回归。

## 测试与文档

- 纯逻辑 planner 覆盖四类状态、历史 NULL、原因优先级、去重和计划指纹。
- `tests/test_gui.py` 覆盖状态硬拦截、全异常中止、内容缺失合并、确认期数据变化、dry-run 一致性和 T-659 回归。
- 更新 `docs/routes.md`、`docs/04-architecture.md` 和 `docs/api.md`。

## 验证

```bash
py -3.10 -m unittest tests.test_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
```

## 非目标

- 不新增商品状态 UI，不根据采集快照自动修改蝦皮商品状态，不提供非正常商品强制更新入口，不做实时状态刷新。

## 执行记录

- 新增 `product_status.build_apply_plan()`：先按商品状态去重分组，仅 `normal` 进入标题/封面完整性检查；未上架、审核中、未知与历史 NULL 均不传入执行列表。
- `ApplyTab` 的「检查本轮更新」和「开始更新」共用该计划器；确认框、状态栏与本轮日志展示状态异常和内容缺失的分类排除，确认后重新核对 `task_id/updated_at/product_status/new_title/new_cover_path/更新模式` 指纹。
- `ApplyWorker` 记录预检元数据，并在执行层再次拒绝非正常商品状态，避免直接构造 Worker 绕过 GUI 预检。
- 同步更新 `docs/routes.md`、`docs/04-architecture.md`、`docs/api.md`；补充状态优先、混合排除、确认期变更和计划指纹测试。
- 验证通过：`py -3.10 -m unittest tests.test_product_status tests.test_gui`（207 项）、`py -3.10 -m unittest discover -s tests`（616 项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。