tg_crawl/README.md

# jobs_robots

本项目用于采集 Telegram 招聘数据并进行结构化清洗，当前统一使用 MySQL。

## 1. 当前流程

1. `main.py`
- 从 `config.json` 读取数据源、时间窗口、限频、MySQL 配置。
- 爬取 Telegram 消息，写入 MySQL `messages`。
- 维护每个来源的增量游标到 `sync_state`。

2. `clean_to_structured.py`
- 从 MySQL `messages` 增量读取新增消息（按 `messages.id` + `clean_state` 检查点）。
- 按来源规则清洗（`@DeJob_official` 有专用规则，其他走通用规则）。
- 仅保留招聘类数据，写入 MySQL `structured_jobs`。

3. `run_daily_incremental.sh`
- 每日调度入口。
- 运行前自动更新 `config.json` 时间窗口（滚动窗口）。
- 依次执行 `main.py` 和 `clean_to_structured.py`。

## 2. 数据库表

### 2.1 原始层

- `messages`
  - 原始消息存储（`source + message_id` 唯一）
- `sync_state`
  - Telegram 增量抓取游标

### 2.2 清洗层

- `structured_jobs`
  - 结构化岗位数据（`source + message_id` 唯一）
- `clean_state`
  - 清洗增量检查点（`pipeline_name -> last_message_row_id`）

## 2.3 字段级数据字典（详细）

### messages（Telegram 原始消息）

- `id`（BIGINT, PK, 自增）  
  含义：MySQL 行主键，清洗增量检查点使用这个字段。  
  示例：`530812`

- `source`（VARCHAR）  
  含义：消息来源标识（频道/群组），通常是 `@xxx`。  
  示例：`@DeJob_official`

- `chat_id`（BIGINT, 可空）  
  含义：Telegram 实体 ID。  
  示例：`-1001234567890`

- `message_id`（BIGINT）  
  含义：该 source 内部的消息 ID。  
  约束：与 `source` 组成唯一键。

- `content`（LONGTEXT, 可空）  
  含义：抓取到的消息正文（含非文本补充段，如 `MEDIA_JSON`）。  
  示例：招聘 markdown 文本 + `[MEDIA_TYPE] ...`

- `date`（DATETIME）  
  含义：消息时间（UTC）。  
  示例：`2026-02-26 09:31:10`

- `created_at`（DATETIME）  
  含义：该条记录写入数据库时间。  

### sync_state（抓取增量状态）

- `source`（VARCHAR, PK）  
  含义：来源标识，与 `messages.source` 对应。

- `last_message_id`（BIGINT）  
  含义：该来源已抓取到的最大 message_id。  
  用途：下次抓取时只拉 `message_id > last_message_id`。

- `updated_at`（DATETIME）  
  含义：该来源游标最近更新时间。

### structured_jobs（清洗后结构化岗位）

- `id`（BIGINT, PK, 自增）  
  含义：结构化表主键。

- `source`（VARCHAR）  
  含义：来源标识。  
  示例：`@DeJob_official`

- `source_channel`（VARCHAR, 可空）  
  含义：来源品牌/渠道归类。  
  示例：`DeJob`

- `parser_name`（VARCHAR）  
  含义：使用的解析器名称。  
  示例：`dejob_official` / `generic`

- `parser_version`（VARCHAR）  
  含义：解析器版本号，用于规则演进追踪。  
  示例：`v1`

- `chat_id`（BIGINT, 可空）  
  含义：原始 Telegram chat_id。

- `message_id`（BIGINT）  
  含义：原始消息 ID（source 内）。  
  约束：与 `source` 组成唯一键。

- `message_date`（DATETIME）  
  含义：原始消息时间（UTC）。

- `job_type`（VARCHAR, 可空）  
  含义：岗位类型标记。当前仅保留 `招聘`。  
  示例：`招聘`

- `company_name`（VARCHAR, 可空）  
  含义：公司/项目方名称。  
  示例：`88EX`

- `industry_tags_json`（JSON）  
  含义：行业/赛道标签数组。  
  示例：`[\"CEX\",\"Infra\"]`

- `company_intro`（LONGTEXT, 可空）  
  含义：公司简介文本。

- `company_url`（TEXT, 可空）  
  含义：公司官网/介绍页链接。

- `work_mode`（VARCHAR）  
  含义：办公模式。  
  枚举：`remote | onsite | hybrid | unknown`

- `job_nature`（VARCHAR）  
  含义：用工性质。  
  枚举：`full_time | part_time | contract | intern | freelance | unknown`

- `job_location_text`（VARCHAR, 可空）  
  含义：主地点文本（首个地点）。

- `job_location_tags_json`（JSON, 可空）  
  含义：地点标签数组。无地点时为 `NULL`（不是空数组）。

- `employment_type_raw`（TEXT, 可空）  
  含义：原始“合作方式”文本，便于回溯规则。  
  示例：`🛵 合作方式：#全职 #远程 #吉隆坡`

- `position_name`（VARCHAR, 可空）  
  含义：岗位主名称。  
  示例：`社区运营`

- `position_tags_json`（JSON）  
  含义：岗位标签数组。  
  示例：`[\"社区运营\",\"运营\"]`

- `salary_raw`（TEXT, 可空）  
  含义：薪资原始字符串。  
  示例：`$1000 - $3000 / month`

- `salary_currency`（VARCHAR, 可空）  
  含义：薪资币种（已识别）。  
  示例：`USD`

- `salary_min`（BIGINT, 可空）  
  含义：薪资下限数值。

- `salary_max`（BIGINT, 可空）  
  含义：薪资上限数值。

- `salary_period`（VARCHAR, 可空）  
  含义：薪资周期。  
  枚举：`month | year | day | NULL`

- `responsibilities_json`（JSON）  
  含义：岗位职责数组（按条目拆分）。

- `requirements_json`（JSON）  
  含义：岗位要求数组（按条目拆分）。

- `apply_email`（VARCHAR, 可空）  
  含义：投递邮箱。

- `apply_telegram`（VARCHAR, 可空）  
  含义：投递 Telegram 用户名。  
  示例：`@lulu_lucky1`

- `job_source_url`（TEXT, 可空）  
  含义：岗位来源原文链接（如 DeJob 详情页）。

- `body_text`（LONGTEXT）  
  含义：清洗后的主体文本（去除部分技术元段）。

- `raw_content`（LONGTEXT）  
  含义：原始消息内容快照（用于审计/回刷）。

- `cleaned_at`（DATETIME）  
  含义：最近清洗/更新该条结构化记录的时间。

### clean_state（清洗增量状态）

- `pipeline_name`（VARCHAR, PK）  
  含义：清洗流程标识。  
  示例：`structured_cleaner_v1`

- `last_message_row_id`（BIGINT）  
  含义：已处理到的 `messages.id` 最大值。  
  用途：下次清洗只处理更大的 `messages.id`。

- `updated_at`（DATETIME）  
  含义：检查点更新时间。

## 3. 配置文件说明（config.json）

关键字段：

- `sources`: Telegram 来源列表
- `time_window.enabled`: 是否启用时间窗口
- `time_window.start` / `time_window.end`: 抓取窗口（脚本会每日自动刷新）
- `daily_window_days`: 滚动窗口天数（当前默认 `2`）
- `throttle`: 限频配置
  - `enabled`
  - `per_message_delay_sec`
  - `between_sources_delay_sec`
- `mysql`: MySQL 连接配置
  - `host`, `port`, `user`, `password`, `database`, `charset`

## 4. 运行方式

### 4.1 手动运行

```bash
uv run main.py
uv run clean_to_structured.py
```

### 4.2 每日定时（推荐）

脚本：`run_daily_incremental.sh`

示例 crontab（每天 01:10）：

```cron
10 1 * * * /home/liam/code/python/jobs_robots/run_daily_incremental.sh
```

日志文件：

- `logs/app.log`
- `logs/clean_to_structured.log`
- `logs/daily_job.log`

## 5. 增量策略

### Telegram 抓取增量

- 依据 `sync_state.last_message_id`
- 每个来源独立增量

### 清洗增量

- 依据 `clean_state.last_message_row_id`
- 每次只处理 `messages.id > checkpoint`
- 成功后更新 checkpoint

## 6. 字段约定（结构化就业类型）

`structured_jobs` 使用拆分字段，不再依赖 `employment_type_json`：

- `work_mode`: `remote | onsite | hybrid | unknown`
- `job_nature`: `full_time | part_time | contract | intern | freelance | unknown`
- `job_location_text`: 主地点文本
- `job_location_tags_json`: 地点数组（无地点为 `NULL`）
- `employment_type_raw`: 原始“合作方式”行

## 7. 常见问题

1. 为什么当天凌晨跑出来窗口看着不对？
- 当前滚动窗口按 UTC 日期更新。如果需要按本地时区（如 Asia/Shanghai）可再改。

2. 为什么清洗没有新增？
- 看 `clean_state` 检查点是否已经到最新。
- 看 `messages` 是否有新数据。

3. 为什么 MySQL 报字段超长/类型错误？
- 优先看对应脚本日志，字段已做多数保护；若仍报错，保留错误堆栈并反馈。

## 8. 协作建议

- 改规则时优先只改对应来源 parser，避免影响全局。
- 改字段前先确认 `structured_jobs` 兼容性与迁移策略。
- 所有定时行为以 `run_daily_incremental.sh` 为统一入口，避免多处调度冲突。