# 爬虫管理台（/admin/spider）设计

日期：2026-10-25
状态：已与需求方确认，待实现

## 背景

后台把「抓取任务」和「入库任务」拆成两个页面，但它们其实是同一条流水线的上下游：

```
spider 抓图 → POST /ingest → ingest_jobs 队列 → 后端 worker 下载/写库 → brand_runways + images
                  ↑ 抓取进度写 crawl_tasks                    ↑ 入库结果写 ingest_jobs.outcome/note
```

分开放导致排障时要在两页之间跳，且任何一页都看不全「现在到底在干什么」。

同时存在两个问题：

1. **小批量模式**（`max_shows=3`）让「入队」这件事语义含糊，实际使用时总是想全量。
2. **跳过判定太粗**：只要某场秀已入库 ≥10 张就整场跳过。如果当初只成功抓到 12 张（其余失败），
   剩下的图永远补不上。

## 目标

1. 入队只有一个语义：**全量**。
2. 跳过判定改为**覆盖率**：入库张数接近应有张数才跳过，缺得多就补抓。
3. 用一页只读的「爬虫管理」替代原两个页面，能看清当前在抓什么、队列有多长、最近入库结果。
4. 卡死任务 5 分钟自动回收，不依赖人工点「重试」。

## 决策

| 决策 | 结论 | 理由 |
|---|---|---|
| 页面形态 | 一条流水线看全（状态条 + 正在抓 + 待抓队列 + 最近入库） | 两表本就是一条链路，合并不需要改数据模型 |
| 操作能力 | 纯只读 | 抓取卡死由租约自动回收；入库失败多为不可恢复的数据问题 |
| 场次上限 | 后台入口全部移除，入队恒为全量 | 用户明确只保留全量模式 |
| 跳过判定 | 覆盖率（允许缺 5 张） | 个别图在 Vogue 侧永久 404，要求一张不差会导致整场无限重抓 |
| 抓取租约 | 900s → 300s，且「有心跳就不回收」 | 单纯缩短会误回收长任务；心跳是现成的存活信号 |

## 设计

### 1. 全量抓取

- `brands.html`：删除批量入队的「每品牌场次上限」下拉、删除单品牌按钮里的 `hidden maxShows=3`。
- `CrawlBulk` / `CrawlEnqueue` 不再读取 `maxShows`，入队固定传 0。
- `crawl_tasks.max_shows` 列保留：历史任务仍按原值渲染，新任务恒为 0。
- spider `serve` 用任务里的 `max_shows`（恒 0 = 全量）；`vogue` 子命令的 `-s` 仅留作本地调试。

### 2. 覆盖率判定

**数据**

- `brand_runways` 新增 `expected_images int not null default 0`：本场秀应有图片数。
- `RunwayIngest` 新增 `expected_images`（spider 侧已知，日志里的「共 N 张图」）。
- ingest 处理时写入：`expected_images = max(旧值, 载荷值)`，避免重抓变少时退化。

**接口**

`GET /admin/internal/shows/covered` 每项返回 `{year, season, collection_type, images, expected}`。

**判定（spider 侧）**

```
if expected > 0:  跳过条件 = images >= expected - 5
else:             跳过条件 = images >= 10        (历史数据无 expected)
```

- 余量 5：缺 1~5 张视为完整。少了再补抓是整场重下（内容寻址无法只补缺的），代价高。
- 缺超过 5 张才补抓，补抓后 `expected_images` 可能更新，逐步收敛。

### 3. 页面 `/admin/spider`

**① 状态条**

```
爬虫 在线 · 正在抓 1 个 · 队列 3 个 · 待入库 2 条
```

- 在线判定：存在 running 任务且最近心跳 < 10 分钟 → 在线；
  running 但心跳 ≥ 10 分钟 → `可能卡住`；无 running → `空闲`。

**② 正在抓**（`crawl_tasks.status = running`）

| 品牌 | 进度 | 当前场次 | 心跳 |
|---|---|---|---|
| Amiri | 12/47 场 + 进度条 | Fall 2021 Menswear（24/38 张） | 8 秒前 |

心跳 > 10 分钟整行标黄。

**③ 待抓队列**（`status = queued`）：品牌 / 入队时间 / 已等待。

**④ 最近入库结果**（`ingest_jobs` 最近 50 条，`kind='crawl'`）

| 时间 | 品牌 | 场次 | 结果 |
|---|---|---|---|
| 23:12 | Amiri | Fall 2019 Menswear | 新建 34 张图 |
| 23:10 | Celine | Spring 2020 RTW | 已存在跳过 |
| 23:08 | Gucci | Fall 2020 RTW | 失败：图片下载超时 |

场次标题直接取 `payload::json->>'title_en'`，结果取 `outcome` + `note`，无需改表。

**轮询**：`GET /admin/spider/live` 每 4 秒，返回 ①②③ 三块的结构化数据；④ 不轮询（历史不会变）。

### 4. 租约改 300 秒 + 心跳存活

```sql
WHERE status = 'running' AND locked_at > 0
  AND locked_at      < ?
  AND coalesce(progress_at, 0) < ?
```

两个时间点都取 `now - 300`。心不断 → 永不回收；真卡住 → 5 分钟回收。
`CrawlStuckTimeoutSec` 由 900 改为 300。

### 5. 删除项

- 页面与模板：`/admin/crawl`、`/admin/ingest-jobs`
- 路由：`CrawlList`、`CrawlLive`、`CrawlBulk`、`CrawlRetry`、`CrawlCancel`、`CrawlDelete`、
  `IngestJobs`、`IngestJobRetry`
- 导航：两项合并为一个「爬虫」
- 入队接口 `/admin/crawl/brands/:uid` → 改名 `/admin/spider/brands/:uid`（品牌页按钮同步改）

保留：品牌页的「抓取状态 / 上次抓取 / 更新记录」（品牌维度，不是爬虫维度）。

## 测试

- 渲染测试：`/admin/spider` 三区块、轮询锚点、卡住样式。
- 单元测试：
  - 覆盖率判定：`expected>0 缺≤5 跳过`、`缺>5 补抓`、`expected=0 回落 10 张`
  - 租约回收 SQL：有心跳不回收（集成测试落地时验证）
- 手动验证：Celine 全量重跑应只补抓缺图场次；新品牌全量抓取进度可见。

## 风险

- 全量抓取一个品牌可能数小时，若 spider 进程被杀，已入库的场次会被跳过，只重抓当前场次——可接受。
- 覆盖率依赖 spider 上报；老数据 `expected_images = 0` 时退回 10 张阈值，行为与现在一致。
- 只读页面意味着入库 `failed` 任务无法在界面上恢复，需改库处理（已确认接受）。