# 负责人缓存与名单参考

> 适用场景：负责人名单查询、负责人缓存刷新、`--assignee` 过滤、以及 `references/assignees.json` 的异常排查。

## 缓存文件

- 负责人缓存固定写在 `references/assignees.json`。
- 缓存 payload 由 `version`、`saved_at`、`owners` 组成；`owners` 中每项是 `{name, owner_id}`。
- 这是运行时缓存数据文件，不是手写文档；不要重命名、迁移或改语义。

## 普通抓取时的缓存策略

- 普通抓取开始前，会先尝试复用当天已生成的 `references/assignees.json`。
- 若缓存不存在、为空、日期不是今天，脚本会自动刷新一次负责人缓存。
- 若刷新失败但本地缓存仍可用，抓取会回退到本地缓存，并附带 warning；若连缓存都没有，则无法依赖 owner_id 精准过滤。
- 同一天内后续普通抓取不再重复点击负责人下拉列表，除非缓存被删除、损坏或过期。

## 只查看负责人名单

只看负责人名单时，运行：

```powershell
python -X utf8 scripts\scrape_inquiries.py --list-assignees
```

- 该命令会优先尝试刷新缓存，然后输出负责人名单。
- 若刷新成功，返回 JSON 中的 `status` 为 `ok`，并包含 `count` 与 `assignees`。
- 若刷新失败，会退回到本地缓存，返回 `status: "fallback"` 和 warning。
- 该命令不运行完整询盘抓取，不写入 `inquiries.json`。
- 若用户请求仅为“查看业务员名单”，可直接读取 `references/assignees.json` 中的 `owners` 数组；需要最新名单时再运行上面的命令。

## `--assignee` 过滤行为

- 抓取时会先从缓存里查找唯一匹配的 `owner_id`。
- 缓存匹配要求唯一；精确匹配和包含匹配都会参与，如果命中多个候选，就不会直接使用 URL owner 过滤。
- 若缓存未命中，会尝试在页面内点击目标业务员，再从 URL 的 `search.owner` 解析 `owner_id`。
- 若仍拿不到 `owner_id`，脚本会退回客户端文本过滤，并给出“结果可能不完整”的 warning。
- 高级时间范围默认不把 owner 过滤直接拼进 advanced-time URL；此时即使识别到 `owner_id`，也可能退回本地负责人文本过滤。历史窗口细则见 `references/advance_time.md`。

## 缓存刷新实现约束

- 刷新缓存时，脚本会点击列表页 `.filter-owner`，读取 `.aui-dropdown-menu .aui-menu-item` 的可见文本，去空、去重并过滤 `All`。
- 对每个业务员会点击一次，从 URL 的 `search.owner` 解析 `owner_id`；不要依赖 DOM 中不稳定的 `widget-xx`。
- 新缓存会覆盖写回 `references/assignees.json`，以反映负责人新增、删除或 ID 变化。

## 异常排查与恢复

- 若用户发现人数与网页不符、`owner_id` 缺失、姓名重复或缓存内容明显异常，先删除 `references/assignees.json`，再重新执行 `--list-assignees`。
- 若命令返回 fallback，优先看 warning，再判断是否需要重新打开页面、重新登录或手动清空缓存。
- 不要在缓存可疑时直接把旧缓存当成最终真相；要么刷新成功，要么明确说明当前结果来自本地缓存。
