cmshoppe/docs/tasks/T-702.md

---
id: T-702
title: 修复物流校验 Toast 被误判为封面上传失败
phase: 8
deps: [T-571]
status: DONE
created: 2026-07-27
---

## 问题 / 背景

③「更新蝦皮」更新商品 `57064892919` 的封面时，页面出现物流校验提示：

- `超過物流最長邊限制`
- `此物流選項不支援較長備貨商品`

程序把第一条提示归类为图片上传错误，并返回：

`新封面上传失败：超過物流最長邊限制`

本地诊断日志显示第一次运行删除旧封面后，图片数量已由 7 恢复为 8，`cdn_count=8`、`blob_count=0`、`busy_count=0`，说明新图已经取得蝦皮 CDN 地址；程序却在识别新图和拖到第一位之前返回 `UPLOAD_PAGE_ERROR`。第二次运行又在删除第一张后，被同一残留物流提示阻断图片管理器稳定检查，未执行本次上传。

根因是 `JS_UPLOAD_STATE` 的页面 Toast 分类规则把通用词 `超過/超过` 同时当作错误语义和上传语义。`超過物流最長邊限制` 因此进入 `error_toasts`，随后同时阻断删除后的稳定等待和上传成功检测。现有回归测试只覆盖 `此物流選項不支援較長備貨商品`，没有覆盖包含 `超過` 的物流文案。

## 方案

### 1. 收紧上传 Toast 分类

- 页面 Toast 先保留在 `page_error_toasts`，用于诊断和最终提交阶段判断。
- 只有包含明确图片上传语义的错误才进入 `error_toasts`，例如图片、封面、照片、图像、上传、文件、重复及对应英文关键词。
- `超過/超过`、`格式`、`大小`、`尺寸`等通用限定词不能单独构成上传语义；例如：
  - `超過物流最長邊限制`：不是上传错误。
  - `此物流選項不支援較長備貨商品`：不是上传错误。
  - `圖片大小超過限制`：是上传错误，因为同时包含明确的图片语义。
  - `有1張重複的圖片`：仍是重复图片上传错误。
- 图片管理器内部识别到的错误继续按上传错误处理，不削弱图片格式、大小、裁剪、重复和上传队列失败的现有保护。

### 2. 统一 Python 与页面脚本的分类语义

- 在 `app/editor.py` 提供可单元测试的上传 Toast 分类函数。
- `_upload_state()` 对 CDP 返回结果做统一归一化，避免仅依赖难以直接测试的 JavaScript 正则。
- 页面脚本同步收紧上传关键词；Python 归一化作为最终分类边界，保证真实页面和测试替身采用同一规则。
- 上传成功仍以新图片取得不在上传前快照中的 `susercontent` 地址为正向证据；不改变删除第一张、等待稳定、上传、拖到第一位的既有顺序。

### 3. 提交阶段保留真实物流错误

- 本任务只阻止物流提示被错误归因到“新封面上传失败”。
- 物流提示不得被静默丢弃；若最终点击「更新」后仍被蝦皮阻止，应由提交后状态识别为商品物流资料校验失败或保留蝦皮原始提示。
- 不自动修改商品包裹尺寸、物流选项或较长备货设置，不绕过蝦皮校验。

### 4. 回归测试与文档

- 增加精确文案 `超過物流最長邊限制` 的回归测试，确认不会阻断图片管理器稳定、上传完成或拖拽。
- 覆盖图片大小超限、图片格式错误和重复图片仍被识别为上传错误。
- 同步 `docs/04-architecture.md` 第七节，明确通用限定词不能单独判定为上传错误。

## 验收要点

- [x] `超過物流最長邊限制` 和 `此物流選項不支援較長備貨商品` 只保留在 `page_error_toasts`，不进入 `error_toasts`。
- [x] 页面存在上述物流提示时，删除后的图片区域仍能进入稳定状态，新封面可上传并拖到第一位。
- [x] `圖片大小超過限制`、`圖片格式錯誤` 和 `有1張重複的圖片` 仍会中止封面上传并给出中文错误。
- [x] 新封面成功标准仍是不在上传前快照中的新 `susercontent` 地址，不把数量变化或任意 Toast 当作成功。
- [x] 最终提交遇到真实物流校验时仍能报告失败，不自动修改或绕过物流配置。
- [x] 不修改标题更新、旧封面备份校验、删除第一张、上传入口点击、拖拽排序和提交确认逻辑。
- [x] 验证通过：
  - `py -3.10 -m unittest discover -s tests -p test_editor_login.py`
  - `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`

## 边界（不改什么）

- 不自动修正商品包裹尺寸、物流渠道、备货天数或其他商品资料。
- 不改变封面删除、上传、拖拽、恢复或最终提交的业务顺序。
- 不新增 CDP 客户端、浏览器自动登录、验证码处理或风控绕过。
- 不清理或提交本地 `data/logs/`、数据库、图片和账号登录态。

## 执行记录

- 2026-07-27：根据商品 `57064892919` 的真实更新日志创建任务。确认第一次运行新封面已取得蝦皮 CDN 地址，但 `超過物流最長邊限制` 因通用关键词 `超過` 被误归类为上传错误；第二次运行又在删除后稳定检查阶段被同一物流提示阻断。
- 2026-07-27：收紧 `JS_UPLOAD_STATE` 的上传语义关键词，移除不能单独证明上传错误的格式、大小、尺寸、像素、分辨率和超过等通用词；新增 Python 侧 `_normalize_upload_state()` 作为最终分类边界，物流提示继续保留在 `page_error_toasts`，但不再进入阻断上传的 `error_toasts`。
- 2026-07-27：扩展 `FakeCoverCDP` 回归场景，覆盖真实文案 `超過物流最長邊限制`、较长备货物流提示、图片大小超限和重复图片；确认物流提示不阻断删除后稳定、上传和拖拽，明确图片错误仍会阻断。
- 2026-07-27：同步 `docs/04-architecture.md` 第七节。未改变旧封面备份、删除第一张、上传入口点击、CDN 成功判据、拖拽、前台恢复或最终提交逻辑。
- 2026-07-27：验证通过：`py -3.10 -m unittest discover -s tests -p test_editor_login.py`（65 项）、`py -3.10 -m unittest discover -s tests`（700 项）、`py -3.10 -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`git diff --check`。未执行真实商品更新，以免在未经过③批量确认边界的情况下再次删除线上第一张封面。