diff --git a/docs/tasks/T-620.md b/docs/tasks/T-620.md new file mode 100644 index 0000000..ebbe86a --- /dev/null +++ b/docs/tasks/T-620.md @@ -0,0 +1,51 @@ +--- +id: T-620 +title: 采集略过原因可见化与结束分类汇总 +phase: 2 +deps: [T-563, T-515] +status: TODO +created: 2026-07-13 +--- + +## 问题 / 背景 + +T-563 已修复 `NO_SESSION_COOKIE`、CDP短暂异常等不确定登录状态导致同账号任务批量“略过”的问题,但①「导入采集」列表主要显示“略过”这一结果,普通用户仍需要查看运行日志或任务详情才能判断是Excel别名未匹配,还是账号明确进入登录页。采集完成弹窗也只显示成功/失败/略过总数,无法直接判断下一步应修Excel还是补登录。 + +本任务只优化略过原因的可见性和本轮汇总,不改变T-563的登录容错、账号级略过条件或CDP采集流程。 + +## 方案 + +1. 为采集略过原因定义纯逻辑分类,至少覆盖: + - `alias_unmatched`:Excel别名未匹配本地账号; + - `login_required`:明确检测到Shopee登录页,需要去④补登录; + - `other`:其它保留的略过原因。 + 分类优先使用本轮worker已知的结构化分支,不通过模糊搜索任意日志猜测;历史任务只能读取 `last_error` 时,集中在单一helper做兼容映射。 +2. ①任务列表对 `status=skipped` 的记录显示简短中文原因,例如“略过 · 别名未匹配”“略过 · 账号未登录”;单元格tooltip展示完整脱敏 `last_error`。成功、失败、待采集等现有阶段文案和语义色保持不变,不增加容易挤压商品ID/标题的宽列。 +3. `CollectWorker` 在本轮执行时累计略过原因计数,summary增加结构化 `skip_reason_counts`,但不修改SQLite schema,不改变 `status=skipped`、`stage` 或现有 `last_error` 写库语义。 +4. 采集结束弹窗在略过数大于0时追加分类摘要,例如:`略过3:别名未匹配2,账号未登录1`。账号未登录分类继续列出需要补登录的账号;别名未匹配分类提示检查Excel别名与④账号别名。略过为0时不增加空的原因段落。 +5. 运行日志继续保留逐条原因,所有界面文案使用中文;不得展示Cookie值、密码、token、完整登录态或未脱敏异常。 + +## 验收要点 + +- 别名未匹配的任务在①列表直接显示“略过 · 别名未匹配”,tooltip可看到完整原因。 +- 明确进入登录页而略过的任务显示“略过 · 账号未登录”,且结束弹窗继续提示对应账号补登录。 +- 单次或连续 `NO_SESSION_COOKIE` 仍按T-563继续尝试采集,不计入略过原因,也不会显示成账号未登录。 +- 同一批同时存在两类略过时,结束弹窗的分类数量之和等于本轮 `skipped` 总数。 +- 历史略过记录刷新列表后也能通过集中兼容helper显示合理原因;未知原因显示“略过 · 其他原因”,不隐藏完整tooltip。 +- 不改变采集任务筛选、重试、Excel回写、数据库状态、CDP选择器或账号登录判定。 + +## 测试要求 + +- 增加纯逻辑测试,覆盖三类略过原因和未知/空原因兜底。 +- 更新GUI/CollectWorker测试,覆盖列表文案、tooltip、summary分类计数、结束弹窗分类摘要,以及T-563的 `NO_SESSION_COOKIE` 不略过回归。 +- 运行 `python -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`py -3.10 -m unittest discover -s tests`、`git diff --check`。 + +## 边界(不改什么) + +- 不修改T-563登录检测重试次数、明确未登录判据或账号级略过策略。 +- 不修改CDP、Shopee选择器、采集tab前后台行为、Excel schema或SQLite schema。 +- 不把“略过”改成“失败”,不自动登录,不绕过验证码、风控或权限校验。 + +## 执行记录 + +(完成后记录实现、验证命令与结果。)