JobData/.planning/PROJECT.md

JobData 爬虫交互重构

What This Is

招聘数据采集平台的爬虫交互层重构项目。重写三个平台（Boss直聘、前程无忧、智联招聘）的爬虫代码，统一基类和共享核心逻辑，优化数据入库去重、公司信息清洗流程和前端监控页面。

Core Value

基于关键词驱动爬虫抓取职位数据，可靠地入库到 ClickHouse，并通过定时任务完成公司信息的采集和同步。

Requirements

Validated

• ✓ FastAPI 后端 REST API 框架 — existing
• ✓ 双数据库架构（MySQL + ClickHouse）— existing
• ✓ RBAC 权限管理系统 — existing
• ✓ 关键词管理（CRUD + 爬虫拉取 /keyword/available）— existing
• ✓ 数据入库管道（IngestService + Registry 模式）— existing
• ✓ 定时任务调度（APScheduler）— existing
• ✓ 公司信息定时清洗流程 — existing
• ✓ Vue3 前端管理界面 — existing
• ✓ 数据分析统计 API — existing

Active

• 统一爬虫基类：三个平台共享签名、请求、解析核心逻辑
• 重写 Boss 直聘爬虫客户端
• 重写前程无忧爬虫客户端
• 重写智联招聘爬虫客户端
• 外部脚本（jobs_spider/）和后端（app/services/crawler/）共享核心代码
• 入库时按职位唯一 ID 去重
• 公司信息爬取流程优化（ClickHouse 提取 → 爬详情 → MySQL）
• 公司招聘信息爬取并写入 ClickHouse
• 前端爬虫监控/数据清洗页面优化
• 单元测试覆盖核心逻辑
• 完善日志和错误重试机制

Out of Scope

• ECS 批量部署（ecs_full_pipeline.py）— 本次只重构爬虫逻辑本身，部署后续单独处理
• 新增爬虫平台 — 先把现有三个平台重构好
• 数据分析/统计模块重构 — 不在本次范围内
• RBAC 权限系统变更 — 保持现有

Context

现有代码库状态：

• jobs_spider/ 下三个平台的爬虫脚本有大量重复代码（签名算法、HTTP 请求、数据解析）
• app/services/crawler/ 已有统一基类 BaseFetcher/BaseSearcher（_base.py）但实现不彻底
• spiderJobs/ 是另一套爬虫框架（含 core/、platforms/、runner/），与 jobs_spider/ 功能重叠
• 数据入库已有 Registry 模式（app/services/ingest/registry.py）可复用
• 去重逻辑分散在 app/services/ingest/dedup.py 和各爬虫脚本中
• 公司清洗由 CompanyCleaner（app/services/company_cleaner.py）和 CompanyJobsSyncService 协同完成

技术栈：

• Python 3.13, FastAPI 0.111, Tortoise-ORM, clickhouse-connect
• requests/httpx 做 HTTP 请求
• Vue 3.3 + Naive UI 前端

Constraints

• 兼容性: 重构期间不能中断现有爬虫数据采集
• 共享核心: 外部脚本和后端必须用同一套签名/请求/解析代码，避免代码重复
• 数据库: ClickHouse 表结构保持不变，MySQL 模型变更走 Aerich 迁移
• 反爬: 必须保留现有反爬机制（IP 轮换、随机延迟、代理管理）

Key Decisions

Decision	Rationale	Outcome
保留两套爬虫（外部 + 后端）但共享核心	外部脚本在 ECS 上独立运行，后端内嵌用于清洗任务	— Pending
三个平台全部重写	现有代码重复太多，修修补补不如统一重写	— Pending
入库时按唯一 ID 去重	比爬取前查询更简单高效	— Pending
保持关键词拉取模式	爬虫主动请求更灵活，无需后端推送基础设施	— Pending
前端一起优化	监控页面是重构后验证的重要入口	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd:transition):

1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd:complete-milestone):

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-03-21 after initialization