cmshoppe/docs/tasks/T-620.md

---
id: T-620
title: 采集略过原因可见化与结束分类汇总
phase: 2
deps: [T-563, T-515]
status: DONE
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。
- 不把“略过”改成“失败”，不自动登录，不绕过验证码、风控或权限校验。

## 执行记录

- 2026-07-13：新增 `app/collect_skip.py` 集中处理历史略过原因分类、阶段短文案、分类计数归一化和结束摘要；明确 `NO_SESSION_COOKIE` 归入未知兼容类型，不作为账号未登录依据。
- 2026-07-13：①列表阶段列显示“略过 · 别名未匹配 / 账号未登录 / 其他原因”，tooltip展示脱敏完整原因；未新增列，也未修改数据库字段。
- 2026-07-13：`CollectWorker` 按现有别名未匹配、采集前明确未登录、采集中明确掉登录三个结构化分支累计 `skip_reason_counts`；采集结束弹窗增加分类摘要和对应处理指引。
- 2026-07-13：增加纯逻辑、表格历史记录、Worker分类汇总、结束弹窗及T-563 `NO_SESSION_COOKIE` 回归测试。为隔离工作区其它未提交改动，在仅含T-620差异的干净worktree验证：`python -m ruff check app tests main.py`、`py -3.10 -m compileall app main.py`、`py -3.10 -m unittest discover -s tests`（424项通过）、`git diff --check`，结果全部通过。