From ffbad8e64d2f74fb831f2d242e70067b9b040351 Mon Sep 17 00:00:00 2001 From: chengma Date: Wed, 8 Jul 2026 11:00:29 +0800 Subject: [PATCH] docs(tasks): add T-552 include failed step in task last_error (P0) Co-Authored-By: Claude Opus 4.8 --- docs/tasks/T-552.md | 46 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/tasks/T-552.md diff --git a/docs/tasks/T-552.md b/docs/tasks/T-552.md new file mode 100644 index 0000000..45af5dd --- /dev/null +++ b/docs/tasks/T-552.md @@ -0,0 +1,46 @@ +--- +id: T-552 +title: 任务失败原因带上失败步骤（①②③ 阶段/状态列可见） +phase: 7 +deps: [T-207, T-523] +status: TODO +created: 2026-07-08 +--- + +## 问题 / 背景 + +①导入采集（及②③）列表里任务失败时，阶段/状态列只显示「失败」，操作员**看不出卡在哪一步**（打开商品页 / 页面就绪 / 读标题 / 读封面 / 下载封面 / 写库 / 回写Excel）。 + +- 失败**步骤信息其实已被采集**：T-207 把 `step=preflight/open_product/wait_ready/read_title/read_cover/download_cover/db_write/excel_write_back` 记进了 `run_log_events`。 +- 但 `db.mark_failed(task_id, phase, error)` 里 `phase` 只是粗粒度（collect/generate/apply），`error` 只是原始消息；`tasks.last_error` 不含步骤。 +- ① 阶段列的 tooltip 已经在显示 `last_error`，但只有消息、没有步骤 → 要知道哪步得去翻「采集运行日志」逐条对，摩擦大。 + +这是"数据有、但没暴露在失败发生处"的可见性问题，不是要重新采集数据。 + +## 方案（P0：prepend 步骤到 last_error，最小改动） + +让失败的 `last_error` 带上**中文步骤**，例如「读封面失败：图片超过大小上限」「打开商品页失败：CDP 端口无响应」。 + +- **worker**（`app/gui/workers.py` 的 `CollectWorker`，及②③对应 worker）：失败时 worker 已知当前 step（T-207 在逐任务追踪），把该 step 传给失败写库。 +- **db**（`app/db.py` `mark_failed`）：把中文步骤 **prepend 到 `last_error`**（不改 schema），存成 `「<步骤中文>失败：<原因>」`；step 已是中文/已知失败步骤时避免重复前缀。 +- **step→中文映射**（放一处共用，如 worker 或 db helper）：`preflight→预检 / open_product→打开商品页 / wait_ready→页面就绪 / read_title→读标题 / read_cover→读封面 / download_cover→下载封面 / db_write→写库 / excel_write_back→回写Excel`；未知 step 用原值兜底。 +- **展示**：①②③ 的阶段/状态列 tooltip 已显示 `last_error`（含步骤后即自动可见）；阶段列文案可选显示「失败·<步骤>」（能从 last_error 派生就派生，不额外加列）。 +- 三个模块共用同一套 step→中文 + prepend 逻辑，一次覆盖①②③"失败看不出哪步"。 + +> 备注：更结构化的做法是新增 `tasks.last_error_step` 字段（便于阶段列内联显示/上色），但需 schema 迁移；本任务按 P0 走 prepend，`last_error_step` 作为后续可选增强，双击看完整步骤链（run_log_events 按 task_id 过滤）也作为后续 P1。 + +## 验收要点 + +- 采集/生成/更新任一步失败后，`tasks.last_error` 以「<中文步骤>失败：<原因>」开头。 +- ①②③ 失败行悬停 tooltip 能看到"是哪一步失败 + 原因"，无需翻运行日志。 +- step→中文映射覆盖上述所有步骤，未知 step 不崩、用原值。 +- 已带步骤前缀的 error 不重复加前缀。 +- 单测：`tests/test_db.py` 断言 `mark_failed` 带 step 时 `last_error` 前缀正确、无 step 时保持原样；`tests/test_gui.py` 断言失败行 tooltip 含步骤文案（至少①覆盖，②③视改动补充）。 + +## 边界（不改什么） + +只改 `mark_failed` 的 step 前缀 + worker 传 step + 模型 tooltip/阶段文案 + 单测；不改采集/生成/更新执行流程、`run_log_events` 结构（T-207 保留）、CDP/Shopee 交互、Excel、DB schema（P0 不加字段）。 + +## 执行记录 + +（做完在此记录：改了哪些文件、跑的验证命令与结果、决策）