# Roadmap: JobData 爬虫交互重构

**Project:** JobData 爬虫交互重构
**Core Value:** 基于关键词驱动爬虫抓取职位数据，可靠入库 ClickHouse，定时完成公司信息采集同步
**Created:** 2026-03-21
**Granularity:** Standard (5-8 phases)

---

## Phases

- [ ] **Phase 1: 共享核心包** - 提取 crawler_core/ 可安装共享包，统一基类和基础设施
- [ ] **Phase 2: Boss 直聘重写** - 基于 crawler_core 重写 Boss 直聘爬虫客户端
- [ ] **Phase 3: 前程无忧 & 智联重写** - 基于 crawler_core 重写前程无忧和智联招聘爬虫客户端
- [ ] **Phase 4: 后端 & 外部脚本接入** - 后端 facade 桥接 + 外部脚本迁移 + 废弃老框架
- [ ] **Phase 5: 数据管道优化** - 入库去重、公司清洗流程优化、公司招聘信息写入
- [ ] **Phase 6: 质量 & 前端** - 数据解析测试覆盖、前端监控和数据清洗页面优化

---

## Phase Details

### Phase 1: 共享核心包
**Goal:** crawler_core/ 可安装共享包就位，三平台开发可以统一基于它展开
**Depends on:** Nothing (first phase)
**Requirements:** ARCH-01, ARCH-02, QUAL-01, QUAL-04, QUAL-05
**Success Criteria** (what must be TRUE):
  1. `pip install -e ./crawler_core` 可成功安装，`from crawler_core import BaseFetcher` 可正常导入
  2. 三大平台的签名算法已迁入 crawler_core/ 并通过单元测试（pytest 绿色）
  3. BaseFetcher/BaseSearcher 基类定义完整，提供模板方法供子类实现
  4. loguru 日志格式统一，tenacity 重试装饰器可开箱即用
  5. 旧爬虫（jobs_spider/）仍正常运行，未被改动（feature flag 隔离）
**Plans:** 1/2 plans executed
Plans:
- [x] 01-01-PLAN.md — Package scaffold: pyproject.toml + HTTPClient (tenacity + logging) + BaseFetcher/BaseSearcher + Pipfile deps
- [ ] 01-02-PLAN.md — Sign algorithms: port BossSign/Job51Sign/ZhilianSign to crawler_core/ + unit tests (pytest)

### Phase 2: Boss 直聘重写
**Goal:** Boss 直聘爬虫完全基于 crawler_core 运行，旧实现可安全停用
**Depends on:** Phase 1
**Requirements:** ARCH-03, QUAL-03
**Success Criteria** (what must be TRUE):
  1. Boss 直聘爬虫继承 BaseFetcher/BaseSearcher，不含内联签名或 HTTP 样板代码
  2. 针对 Boss HTTP 层的 mock/respx 测试通过，覆盖正常响应和错误响应
  3. 使用 Boss 新客户端运行一次真实关键词抓取，职位数据成功返回（手动验证）
  4. 反爬机制保留：随机延迟 10-20s、代理轮换、TLS 指纹伪装均正常工作
**Plans:** TBD

### Phase 3: 前程无忧 & 智联重写
**Goal:** 前程无忧和智联招聘爬虫完全基于 crawler_core 运行，三平台统一使用新基类
**Depends on:** Phase 1
**Requirements:** ARCH-04, ARCH-05
**Success Criteria** (what must be TRUE):
  1. 前程无忧爬虫继承 BaseFetcher/BaseSearcher，不含内联签名或 HTTP 样板代码
  2. 智联招聘爬虫继承 BaseFetcher/BaseSearcher，不含内联签名或 HTTP 样板代码
  3. 两平台各自运行一次真实关键词抓取，职位数据成功返回（手动验证）
  4. 三平台新客户端的代码结构一致，新平台可参照模板快速实现
**Plans:** TBD

### Phase 4: 后端 & 外部脚本接入
**Goal:** 后端 facade 和外部脚本均使用 crawler_core，老框架 jobs_spider/ 完成历史使命并下线
**Depends on:** Phase 2, Phase 3
**Requirements:** ARCH-06, ARCH-07, ARCH-08
**Success Criteria** (what must be TRUE):
  1. 后端 app/services/crawler/ facade 通过 asyncio.to_thread() 调用三平台新客户端，无同步阻塞
  2. spiderJobs/ 外部脚本导入 crawler_core 替代内联代码，功能等价
  3. jobs_spider/ 目录已标记废弃或删除，无生产流量指向旧代码
  4. 定时任务和手动触发的爬虫均通过新路径正常运行（后端日志可验证）
**Plans:** TBD

### Phase 5: 数据管道优化
**Goal:** 入库去重可靠，公司清洗流程顺畅，公司招聘信息完整写入 ClickHouse
**Depends on:** Phase 4
**Requirements:** DATA-01, DATA-02, DATA-03, DATA-04
**Success Criteria** (what must be TRUE):
  1. 同一职位 ID 在 30 天窗口内重复推送时，ClickHouse 中只保留一条记录（可通过重复入库验证）
  2. 外部脚本和后端均通过同一个 IngestService 入库，入库日志显示来源字段一致
  3. 公司清洗定时任务：ClickHouse 抽取 → 爬公司详情 → 写 MySQL，全程日志可追踪
  4. 公司招聘信息（company_jobs）成功写入 ClickHouse，前端或查询可验证数据存在
**Plans:** TBD

### Phase 6: 质量 & 前端
**Goal:** 数据解析测试覆盖到位，前端监控和清洗页面对实际运维有帮助
**Depends on:** Phase 5
**Requirements:** QUAL-02, QUAL-06, QUAL-07
**Success Criteria** (what must be TRUE):
  1. 三平台数据解析函数有单元测试，覆盖正常字段和缺字段场景（pytest 绿色）
  2. 去重逻辑有单元测试，覆盖重复 ID 和时间窗口边界场景
  3. 前端爬虫监控页面展示各平台最近抓取时间、数量趋势和错误状态
  4. 前端数据清洗页面支持查看待清洗公司列表、触发清洗、查看结果
**Plans:** TBD

---

## Progress Table

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. 共享核心包 | 1/2 | In Progress|  |
| 2. Boss 直聘重写 | 0/? | Not started | - |
| 3. 前程无忧 & 智联重写 | 0/? | Not started | - |
| 4. 后端 & 外部脚本接入 | 0/? | Not started | - |
| 5. 数据管道优化 | 0/? | Not started | - |
| 6. 质量 & 前端 | 0/? | Not started | - |

---

## Coverage Map

| Requirement | Phase | Description |
|-------------|-------|-------------|
| ARCH-01 | Phase 1 | 提取 crawler_core/ 为可安装包 |
| ARCH-02 | Phase 1 | 统一 BaseFetcher/BaseSearcher 基类 |
| ARCH-03 | Phase 2 | Boss 直聘爬虫基于 crawler_core 重写 |
| ARCH-04 | Phase 3 | 前程无忧爬虫基于 crawler_core 重写 |
| ARCH-05 | Phase 3 | 智联招聘爬虫基于 crawler_core 重写 |
| ARCH-06 | Phase 4 | 后端 facade 使用 asyncio.to_thread() 桥接 |
| ARCH-07 | Phase 4 | 外部脚本 spiderJobs/ 使用 crawler_core |
| ARCH-08 | Phase 4 | 废弃 jobs_spider/ 老框架 |
| DATA-01 | Phase 5 | 入库按唯一 ID + 30 天时间窗口去重 |
| DATA-02 | Phase 5 | 外部脚本和后端共用 IngestService |
| DATA-03 | Phase 5 | 公司信息定时清洗流程优化 |
| DATA-04 | Phase 5 | 公司招聘信息写入 ClickHouse |
| QUAL-01 | Phase 1 | 核心签名算法单元测试 |
| QUAL-02 | Phase 6 | 数据解析和去重逻辑单元测试 |
| QUAL-03 | Phase 2 | HTTP 请求层 mock/respx 测试 |
| QUAL-04 | Phase 1 | 结构化日志统一格式 |
| QUAL-05 | Phase 1 | 错误重试机制（tenacity） |
| QUAL-06 | Phase 6 | 前端爬虫监控页面优化 |
| QUAL-07 | Phase 6 | 前端数据清洗管理页面优化 |

**Coverage: 19/19 requirements mapped ✓**

---

*Roadmap created: 2026-03-21*
*Last updated: 2026-03-21 — Phase 1 plans created (01-01, 01-02)*