d7c8bec287
- Create 01-01-SUMMARY.md with implementation details and interface contracts - STATE.md: advance to plan 2, record metrics, add decisions from plan 01 - ROADMAP.md: update phase 1 plan progress (1/2 plans complete) - REQUIREMENTS.md: mark ARCH-01, ARCH-02, QUAL-04, QUAL-05 complete - crawler_core/__init__.py: preserve linter-added try/except ImportError guard
138 lines
6.9 KiB
Markdown
138 lines
6.9 KiB
Markdown
# 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)*
|