README字段说明

README.md

@@ -151,32 +151,116 @@ uv run import_excel_jobs.py --file /path/to/jobs.xlsx --sheet Sheet1 --source @e
 
 ## 7. 数据库表与字段含义
 
-### 7.1 原始层
+### 7.1 `messages`（原始消息）
 
-- `messages`
-  - 原始消息正文、媒体补充文本、来源、消息时间
-  - 唯一键：`(source, message_id)`
-- `sync_state`
-  - 每个 source 的抓取游标
+唯一键：`uk_source_message (source, message_id)`
 
-### 7.2 清洗层
+| 字段 | 类型 | 含义 | 备注 |
+|---|---|---|---|
+| `id` | BIGINT, PK, AUTO_INCREMENT | 本地行主键 | 清洗增量以此为游标来源 |
+| `source` | VARCHAR(255), NOT NULL | 数据来源标识 | 如 `@DeJob_official` |
+| `chat_id` | BIGINT, NULL | Telegram chat id | 可空 |
+| `message_id` | BIGINT, NOT NULL | Telegram 消息 id | 在同一 source 下唯一 |
+| `content` | LONGTEXT | 原始正文 | 含媒体补充文本/结构化片段 |
+| `date` | DATETIME, NOT NULL | 消息发布时间 | 统一按 UTC 入库 |
+| `created_at` | DATETIME, NOT NULL | 入库时间 | 默认 `CURRENT_TIMESTAMP` |
 
-- `structured_jobs`
-  - 清洗后结构化岗位数据
-  - 唯一键：`(source, message_id)`
-  - 关键字段：
-    - `source`, `source_channel`
-    - `company_name`, `position_name`
-    - `work_mode`（`remote|onsite|hybrid|unknown`）
-    - `job_nature`（`full_time|part_time|contract|intern|freelance|unknown`）
-    - `job_location_text`, `job_location_tags_json`（无地点为 `NULL`）
-    - `apply_email`, `apply_telegram`, `job_source_url`
-    - `salary_raw`, `salary_currency`, `salary_min`, `salary_max`, `salary_period`
-    - `body_text`, `raw_content`, `cleaned_at`
-- `clean_state`
-  - 清洗检查点
-- `internship_jobs_raw`
-  - Excel 导入时保留的实习原始数据
+### 7.2 `sync_state`（抓取增量状态）
+
+主键：`source`
+
+| 字段 | 类型 | 含义 | 备注 |
+|---|---|---|---|
+| `source` | VARCHAR(255), PK | 来源标识 | 对应 `messages.source` |
+| `last_message_id` | BIGINT, NOT NULL | 已抓取到的最大 message_id | 抓取增量游标 |
+| `updated_at` | DATETIME, NOT NULL | 状态更新时间 | 自动更新 |
+
+### 7.3 `structured_jobs`（清洗后岗位）
+
+唯一键：`uk_source_message (source, message_id)`
+
+| 字段 | 类型 | 含义 | 备注 |
+|---|---|---|---|
+| `id` | BIGINT, PK, AUTO_INCREMENT | 结构化主键 | 内部主键 |
+| `source` | VARCHAR(255), NOT NULL | 来源标识 | 如 `@DeJob_official` |
+| `source_channel` | VARCHAR(255), NULL | 来源渠道归一名 | 如 `DeJob` |
+| `parser_name` | VARCHAR(64), NOT NULL | 解析器名称 | 如 `dejob_official` |
+| `parser_version` | VARCHAR(32), NOT NULL | 解析器版本 | 规则演进追踪 |
+| `chat_id` | BIGINT, NULL | 原始 chat id | 可空 |
+| `message_id` | BIGINT, NOT NULL | 原始消息 id | 与 `source` 组成唯一键 |
+| `message_date` | DATETIME, NOT NULL | 原始消息时间 | UTC |
+| `job_type` | VARCHAR(64), NULL | 岗位类型 | 目前主要是 `招聘` |
+| `company_name` | VARCHAR(255), NULL | 公司名 | 清洗后的公司名 |
+| `industry_tags_json` | JSON, NOT NULL | 行业标签数组 | 例如 `["CEX"]` |
+| `company_intro` | LONGTEXT, NULL | 公司简介 | 可空 |
+| `company_url` | TEXT, NULL | 公司官网/主页 | 可空 |
+| `work_mode` | VARCHAR(32), NOT NULL | 办公模式 | `remote/onsite/hybrid/unknown` |
+| `job_nature` | VARCHAR(32), NOT NULL | 用工性质 | `full_time/part_time/contract/intern/freelance/unknown` |
+| `job_location_text` | VARCHAR(255), NULL | 主地点文本 | 可空 |
+| `job_location_tags_json` | JSON, NULL | 地点标签数组 | 无地点时为 `NULL` |
+| `employment_type_raw` | TEXT, NULL | 原始合作方式文本 | 用于回溯 |
+| `position_name` | VARCHAR(255), NULL | 岗位主名称 | 可空 |
+| `position_tags_json` | JSON, NOT NULL | 岗位标签数组 | 例如 `["运营"]` |
+| `salary_raw` | TEXT, NULL | 原始薪资文本 | 可空 |
+| `salary_currency` | VARCHAR(16), NULL | 薪资币种 | 如 `USD` |
+| `salary_min` | BIGINT, NULL | 薪资下限 | 解析值 |
+| `salary_max` | BIGINT, NULL | 薪资上限 | 解析值 |
+| `salary_period` | VARCHAR(16), NULL | 薪资周期 | `month/year/day` |
+| `responsibilities_json` | JSON, NOT NULL | 岗位职责数组 | 可为空数组 |
+| `requirements_json` | JSON, NOT NULL | 岗位要求数组 | 可为空数组 |
+| `apply_email` | VARCHAR(255), NULL | 投递邮箱 | 可空 |
+| `apply_telegram` | VARCHAR(255), NULL | TG 联系方式 | 可空 |
+| `job_source_url` | TEXT, NULL | 职位详情链接 | 清洗后可用链接 |
+| `body_text` | LONGTEXT, NOT NULL | 清洗后的正文 | 去除技术元信息 |
+| `raw_content` | LONGTEXT, NOT NULL | 原始内容快照 | 审计/回刷使用 |
+| `cleaned_at` | DATETIME, NOT NULL | 最近清洗时间 | 自动更新 |
+
+### 7.4 `clean_state`（清洗增量状态）
+
+主键：`pipeline_name`
+
+| 字段 | 类型 | 含义 | 备注 |
+|---|---|---|---|
+| `pipeline_name` | VARCHAR(128), PK | 清洗流程名 | 当前 `structured_cleaner_v1` |
+| `last_message_row_id` | BIGINT, NOT NULL | 已处理到的 `messages.id` | 清洗增量游标 |
+| `updated_at` | DATETIME, NOT NULL | 状态更新时间 | 自动更新 |
+
+### 7.5 `internship_jobs_raw`（实习原始导入表）
+
+唯一键：`uk_internship_fingerprint (fingerprint)`
+
+| 字段 | 类型 | 含义 | 备注 |
+|---|---|---|---|
+| `id` | BIGINT, PK, AUTO_INCREMENT | 主键 | 内部主键 |
+| `source` | VARCHAR(255), NOT NULL | 数据来源 | 默认 `@excel_import` |
+| `fingerprint` | CHAR(64), NOT NULL | 去重指纹 | SHA-256 |
+| `source_file` | VARCHAR(512), NOT NULL | 来源文件绝对路径 | Excel 文件 |
+| `sheet_name` | VARCHAR(255), NOT NULL | 工作表名 | Excel sheet |
+| `row_number` | INT, NOT NULL | 原始行号 | Excel 行 |
+| `updated_at_raw` | VARCHAR(128), NULL | 原始更新时间文本 | 保留原值 |
+| `updated_at_utc` | DATETIME, NULL | 标准化更新时间 | 统一 UTC 格式 |
+| `industry` | VARCHAR(255), NULL | 行业字段 | 原始/轻清洗 |
+| `title` | VARCHAR(512), NULL | 岗位标题 | 从详情提取 |
+| `company` | VARCHAR(255), NULL | 公司名 | 原始/轻清洗 |
+| `employment_type` | VARCHAR(255), NULL | 用工形式原文 | 如全职/兼职/实习 |
+| `location_text` | VARCHAR(255), NULL | 地点文本 | 轻清洗 |
+| `apply_email` | VARCHAR(255), NULL | 邮箱 | 提取或原始 |
+| `job_source_url` | TEXT, NULL | 职位链接 | 从详情提取 |
+| `raw_row_json` | JSON, NOT NULL | 原始行 JSON | 全量保留 |
+| `imported_at` | DATETIME, NOT NULL | 导入时间 | 自动更新时间 |
+
+### 7.6 `cloud_sync_state`（云同步状态）
+
+主键：`pipeline_name`
+
+| 字段 | 类型 | 含义 | 备注 |
+|---|---|---|---|
+| `pipeline_name` | VARCHAR(128), PK | 同步流程名 | 当前 `local_to_cloud_mysql_v1` |
+| `last_messages_id` | BIGINT, NOT NULL | `messages` 已同步最大本地 id | 云同步游标 |
+| `last_structured_jobs_id` | BIGINT, NOT NULL | `structured_jobs` 已同步最大本地 id | 云同步游标 |
+| `last_internship_id` | BIGINT, NOT NULL | `internship_jobs_raw` 已同步最大本地 id | 云同步游标 |
+| `last_structured_sync_at` | DATETIME, NULL | 结构化更新时间窗口游标 | 补偿更新使用 |
+| `updated_at` | DATETIME, NOT NULL | 同步状态更新时间 | 自动更新 |
 
 ## 8. 日志