# JobData - 招聘数据采集与统计分析平台

## 变更记录 (Changelog)

| 版本 | 日期 | 说明 |
|------|------|------|
| 初始化 | 2026-03-20 | 首次生成架构文档，覆盖全部四个核心模块 |

---

## 项目愿景

JobData 是一个面向招聘市场的全栈数据采集与分析平台。系统从三大主流招聘平台（Boss 直聘、前程无忧、智联招聘）自动抓取职位与公司数据，统一存储到 ClickHouse 列式数据库，并通过 FastAPI 后端 + Vue3 前端提供数据查看、定向清洗、统计分析等能力。ECS 弹性实例管理模块支持在阿里云上按需批量启停爬虫节点。

---

## 架构总览

```
[招聘平台]          [爬虫层]                  [后端 API]            [数据库]
Boss直聘  ──►  jobs_spider/boss/     ──►                      ┌── MySQL
前程无忧  ──►  jobs_spider/qcwy/     ──►  app (FastAPI)  ──►  └── ClickHouse
智联招聘  ──►  jobs_spider/zhilian/  ──►
                                                              ▲
                                                              │
                                          web (Vue3)  ────────┘
                                          (前端页面)

ecs_full_pipeline.py  ──►  阿里云 ECS  ──►  批量启动爬虫节点
```

**核心技术栈**

| 层次 | 技术 |
|------|------|
| 后端 | Python 3.13, FastAPI 0.111, Tortoise-ORM 0.23, APScheduler |
| 数据库（业务） | MySQL（用户/权限/审计/关键词/Token） |
| 数据库（采集） | ClickHouse（职位/公司 JSON 原始数据 + 分析视图） |
| 爬虫 | requests / httpx / Playwright（Python 脚本） |
| 前端 | Vue 3.3, Vite 4, Naive UI, Pinia, ECharts |
| 基础设施 | 阿里云 ECS（按量抢占实例），APScheduler 定时任务 |

---

## 模块结构图

```mermaid
graph TD
    ROOT["(根) JobData"] --> APP["app - FastAPI 后端"]
    ROOT --> WEB["web - Vue3 前端"]
    ROOT --> SPIDER["jobs_spider - 平台爬虫"]
    ROOT --> ECS["ecs_full_pipeline.py - ECS 批量部署"]

    APP --> APP_API["app/api - 路由层"]
    APP --> APP_SVC["app/services - 业务逻辑"]
    APP --> APP_CORE["app/core - 框架核心"]
    APP --> APP_MODELS["app/models - ORM 模型"]
    APP --> APP_REPO["app/repositories - 数据仓库"]

    SPIDER --> SP_BOSS["jobs_spider/boss"]
    SPIDER --> SP_QCWY["jobs_spider/qcwy"]
    SPIDER --> SP_ZL["jobs_spider/zhilian"]

    click APP "./app/AGENTS.md" "查看 app 模块文档"
    click WEB "./web/AGENTS.md" "查看 web 模块文档"
    click SPIDER "./jobs_spider/AGENTS.md" "查看 jobs_spider 模块文档"
```

---

## 模块索引

| 模块路径 | 语言 | 职责简述 |
|----------|------|----------|
| `app/` | Python | FastAPI 后端，提供 REST API、权限管理、定时任务、数据入库与分析 |
| `web/` | Vue3/JS | 前端管理界面，数据展示、关键词管理、代理管理、数据清洗操作 |
| `jobs_spider/` | Python | 三大平台的爬虫脚本，独立运行，结果通过 HTTP 推送到后端 |
| `ecs_full_pipeline.py` | Python | 阿里云 ECS 实例批量创建/销毁/命令下发全流程脚本 |
| `reclean_qcwy_jobs.py` | Python | 前程无忧数据重清洗独立脚本 |

---

## 运行与开发

### 后端启动

```bash
# 安装依赖（pipenv）
pipenv install

# 开发模式（默认端口 9999，20 个 worker）
python run.py

# 环境变量覆盖
APP_HOST=0.0.0.0 APP_PORT=9999 UVICORN_WORKERS=4 python run.py
```

**关键环境变量**

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `APP_HOST` | `0.0.0.0` | 监听地址 |
| `APP_PORT` | `9999` | 监听端口 |
| `UVICORN_WORKERS` | `20` | Worker 数量 |
| `CLICKHOUSE_HOST` | `121.4.126.241` | ClickHouse 地址（需修改为实际地址） |
| `CLICKHOUSE_USER` / `CLICKHOUSE_PASS` | 见 config.py | ClickHouse 认证 |
| `SMTP_HOST` / `SMTP_USER` / `SMTP_PASS` | 见 config.py | 邮件告警配置 |
| `REPORT_ENDPOINT` | 空 | 统计结果 Webhook 上报地址 |
| `RUN_MIGRATIONS_ON_STARTUP` | `True` | 是否启动时自动迁移 |
| `INITIALIZE_SEED_DATA_ON_STARTUP` | `True` | 是否启动时初始化种子数据 |

> 安全警告：`config.py` 中 `SECRET_KEY`、数据库连接串、SMTP 密码均为硬编码默认值，生产环境必须通过环境变量覆盖。

### 前端启动

```bash
cd web
pnpm install
pnpm dev        # 开发模式，默认 http://localhost:5173
pnpm build      # 构建产物到 web/dist
```

### ECS 批量爬虫部署

```bash
# 需配置阿里云凭据（环境变量或 ~/.alibabacloud/credentials）
python ecs_full_pipeline.py
```

---

## 定时任务

APScheduler 在应用启动时注册以下任务（`app/core/scheduler.py`）：

| 任务 ID | 频率 | 职责 |
|---------|------|------|
| `stats_job` | 每 6 小时 | 统计 ClickHouse 各表总量并通过邮件/Webhook 上报 |
| `ecs_full_pipeline` | 每 6 小时 | 调用 `ecs_full_pipeline.py` 批量刷新爬虫节点 |
| `ip_alert_job` | 每 10 分钟 | 检查 IP 上报异常并告警 |
| `company_cleaning_job` | 每 5 分钟 | 自动清洗待处理公司数据（collect 50 + process 30） |
| `daily_cleanup_job` | 每天 00:05 | 清理历史任务运行记录 |

所有任务通过分布式文件锁（或可选 Redis 锁）保证多 Worker 下只执行一次。

---

## 测试策略

- 当前代码库**无自动化测试文件**（缺口：单元测试、集成测试均缺失）。
- 推荐补充：
  1. `app/services/` 的 service 层单元测试（使用 `pytest` + `anyio`）
  2. `app/api/v1/` 的 API 集成测试（使用 `httpx.AsyncClient`）
  3. `jobs_spider/` 的数据解析函数单元测试

---

## 编码规范

- Python：使用 `ruff`（已在 Pipfile 中），格式化用 `black`，排序用 `isort`。
- 前端：ESLint（`@zclzone` + `@unocss` 规则集），`prettier` 格式化。
- 类型：后端强制 `pydantic` Schema 做入参校验；前端以 JS 为主（未启用严格 TS）。
- 日志：后端统一使用 `loguru`，结构化字段 `logger.info(...)` 方式输出。

---

## AI 使用指引

- 修改爬虫逻辑时，重点关注反爬机制：`SmartIPManager`、`IPAnomalyDetector` 在 `jobs_spider/boss/boos_api.py` 中实现，随机延迟至少 10 秒。
- 新增 API 路由后需同步在 `app/api/v1/__init__.py` 注册，并执行 `api_controller.refresh_api()` 更新权限表。
- ClickHouse 表结构变更在 `app/core/clickhouse_init.py` 中维护，**不走 Aerich 迁移**。
- MySQL 模型变更走 Aerich（`aerich migrate && aerich upgrade`）。
- 前端新增页面需要在 `web/src/views/{模块}/route.js` 和后端 `init_menus()` 中同步注册菜单。
- `config.py` 中已硬编码真实 MySQL/ClickHouse 连接串和 SMTP 凭据，**提交代码前务必确认不泄露敏感信息**。