cmshoppe/docs/tasks/T-552.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-552	任务失败原因带上失败步骤（①②③ 阶段/状态列可见）	7	T-207 T-523	TODO	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 不加字段）。

执行记录

（做完在此记录：改了哪些文件、跑的验证命令与结果、决策）