cmshoppe/docs/tasks/T-662.md

id, title, status, phase, deps, created

id	title	status	phase	deps	created
T-662	商品状态采集与三模块状态过滤	TODO	7	T-659	2026-07-18

T-662 商品状态采集与三模块状态过滤

问题 / 背景

①导入采集的商品ID列表中可能混有异常状态商品（未上架、审核中等）。当前链路只在采集阶段拦截「页面打不开」级别的失效商品（app/editor.py:454 PRODUCT_UNAVAILABLE_TEXT_MARKERS：已删除/已下架/无权限等）；编辑页仍能打开的「未上架」「审核中」商品会正常采集入库 → ②照常消耗点数生成 → ③更新无意义或有触发重新审核的风险。

tasks 表没有蝦皮侧商品状态字段，①②③均无法按状态过滤。

用户已提供两份编辑页状态横幅的真实 HTML 样本（docs/html/未上架商品提示.html、docs/html/审核中商品提示 .html），确认状态以 Shopee EDS 组件结构化暴露，CDP 抓取前置验证已基本完成。

需求定稿

1. 采集阶段从商品编辑页读取商品状态并落库（快照语义）。
2. ①导入采集：任务列表增加状态列与状态筛选；采集汇总报告异常状态条数。
3. ②AI生成：生成候选默认排除异常状态商品，不为其消耗点数；确认信息说明排除数量。
4. ③更新蝦皮：更新候选默认排除异常状态商品；跳过统计并入 T-659 的确认弹窗模式。
5. 历史数据无状态记为「未知」，默认不排除；重新采集即可补齐/刷新状态。

实现方案

1. 状态检测契约（依据 HTML 样本）

编辑页状态横幅结构（两样本一致）：

.eds-alert.eds-alert--warning
  ├─ .eds-alert-title   ← 状态判定锚点（文本）
  └─ .eds-alert-desc    ← 补充说明（存诊断）

• 判定以 .eds-alert-title 的归一化文本（trim + 繁简兼容）为准，白名单匹配：
  • 審核中 / 审核中（样本尾部有空格，必须 trim）→ 审核中；
  • 您的商品未上架 → 未上架（样本 desc「您的商品已被您下架。」为卖家自主下架；平台强制下架 desc 不同，原文落库后日后可细分）。
• 无已识别横幅 → 在售。
• 纪律：
  • 禁止依赖 data-v-* 属性（Vue scoped-CSS 构建哈希，发版即变）；只用 eds-alert/eds-alert-title 设计系统类名 + 文本白名单；
  • eds-alert--warning 是通用组件，编辑页可能有无关警告（如图片质量建议）——未识别的横幅不改变状态，但 title 原文写入状态原文字段供日后扩白名单（如违规/禁卖，暂无样本）；
  • 状态检测失败（DOM 查询异常等）不使采集失败，记「未知」并写日志；
  • 现有 PRODUCT_UNAVAILABLE_TEXT_MARKERS 失效检测保留不动，作为③执行层最后防线。

2. 数据模型（additive 迁移）

• tasks 表新增可空列：
  • product_status TEXT——枚举：在售/未上架/审核中/未知（NULL 视同「未知」）；
  • product_status_note TEXT——横幅 title+desc 原文（诊断与日后细分）；
  • product_status_at TEXT——快照时间（ISO 8601）。
• 采集成功时写入三列；重新采集覆盖刷新（快照语义：状态可能过期，以最近采集为准）。
• 迁移幂等，旧库直接升级；历史行三列为 NULL。

3. 采集抓取（app/editor.py::collect()）

• 在编辑页已加载后、抓取旧标题旧封面的同一会话内，按第 1 节契约读取状态横幅（一次 DOM 查询，不增加页面跳转）。
• 采集步骤回调与日志包含状态结果；采集汇总新增「异常状态 N 条（未上架 x / 审核中 y）」。
• 实现时把检测契约与两份 HTML 样本作为证据登记进 docs/04-architecture.md 第七节「CDP 已验证事实」。

4. ①导入采集（app/gui/tabs/collect.py）

• 任务列表增加「商品状态」列（在售/未上架/审核中/未知，异常状态用警示色）。
• 筛选条增加状态下拉：全部（默认）/在售/未上架/审核中/未知。
• 悬停或详情可见状态原文与快照时间。

5. ②AI生成（app/gui/tabs/generate.py）

• 生成候选默认排除 未上架/审核中；在售/未知 正常参与（「未知」不排除，避免历史数据全被拦）。
• 筛选条增加状态下拉（默认「排除异常状态」，可切「全部」后异常商品重新可选——用户明确要生成时不拦死）。
• 开始生成的确认/状态信息注明「已排除异常状态 N 条（示例商品ID：…）」；被排除记录不消耗点数、状态与 stage 不变。

6. ③更新蝦皮（app/gui/tabs/apply.py）

• 更新候选默认排除 未上架/审核中，并入 T-659 的「剔除 + 知情确认」框架：确认弹窗新增「跳过 N 条异常状态商品（未上架 x / 审核中 y，示例商品ID：…）」行。
• 剔除后无任务可执行时沿用 T-659 的整体中止路径，文案区分「全部为异常状态商品」的情况。
• 状态下拉同②（默认排除，可切全部）；「检查本轮更新」（dry_run）与正式更新行为一致。
• 快照过期兜底：③执行层现有商品失效检测不动；更新因商品状态失败的记录，last_error 如实记录。

验收标准

• 采集「审核中」样本结构页面 → product_status=审核中；「未上架」样本 → 未上架；无横幅 → 在售；未识别横幅 → 状态不变但原文落库。
• 状态判定不依赖 data-v-*；title 文本 trim 后繁简均可匹配。
• 状态检测异常不使采集失败，记「未知」并写日志；PRODUCT_UNAVAILABLE_TEXT_MARKERS 行为不变。
• 旧库升级迁移幂等；历史行状态显示「未知」，②③默认不排除。
• 重新采集刷新状态与快照时间。
• ①列表显示状态列与筛选；采集汇总含异常状态统计。
• ②默认不为「未上架/审核中」商品创建生成任务、不消耗点数；切「全部」后可强制生成；排除说明含条数与示例商品ID。
• ③确认弹窗含异常状态跳过统计；剔除后为 0 走 T-659 中止路径；dry_run 与正式一致。
• 被排除记录的 stage、status、Excel 均不因排除而改变。
• 状态列/筛选在 1180x760 与最小窗口尺寸不截断；全部用户可见文案为中文。
• ②③既有筛选（批次/店铺/商品ID/状态）与本状态筛选可叠加，互不破坏。

测试要求

• 纯逻辑：状态横幅解析（两份样本 HTML 的 title/desc、trim、繁简、未识别横幅、无横幅、多横幅共存取白名单命中项）。
• DB：迁移幂等、三列读写、NULL 语义、重新采集覆盖。
• ②：默认排除口径、「未知」不排除、切全部后可选、点数不消耗断言。
• ③：跳过统计文案、全异常中止、dry_run 一致性（延用 T-659 在 tests/test_gui.py 的用例框架）。
• 采集：状态检测失败降级「未知」不阻断采集。

文档同步

• docs/04-architecture.md 第七节登记「编辑页状态横幅」CDP 已验证事实（含选择器契约、两份 HTML 样本路径、data-v 禁用纪律）。
• 不修改冻结的 docs/06-tasks.md。

验证

py -3.10 -m unittest tests.test_editor_login
py -3.10 -m unittest tests.test_db
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

非目标

• 不采集/识别「已售罄」「违规/禁卖」状态（无样本；违规文案留白名单扩展口，遇实例再补）。
• 不自动删除或修改异常状态商品的记录，只过滤不改数据。
• 不在①导入阶段拦截（导入时仅有商品ID，状态未知）。
• 不做状态定时自动刷新；状态以采集快照为准，用户重新采集即刷新。
• 不修改 CDP 登录、Chrome 启动、并发与蝦皮风控相关行为。
• 不回写商品状态到 Excel（如需，另立任务）。

执行记录

• 待实现。