# 通用数据路由API使用指南

## 概述

通用数据路由系统提供了一个统一的API接口，可以根据数据类型和平台自动将数据路由到对应的ClickHouse表中进行存储。这个系统支持所有主要的招聘平台（Boss直聘、前程无忧、智联招聘）和数据类型（职位、公司）。

## 核心特性

- **统一接口**: 所有平台的数据都通过相同的API接口处理
- **自动路由**: 根据数据类型和平台自动选择对应的存储表
- **重复检查**: 支持自动重复数据检查，避免数据冗余
- **批量处理**: 支持单条和批量数据处理
- **异步处理**: 支持异步后台任务处理大量数据
- **数据预处理**: 自动进行字段映射和数据转换

## API端点

### 基础路径
```
/api/v1/universal
```

### 主要端点

1. **存储单条数据**: `POST /data/store`
2. **批量存储数据**: `POST /data/batch-store`
3. **异步存储单条数据**: `POST /data/store-async`
4. **异步批量存储数据**: `POST /data/batch-store-async`
5. **获取支持的平台**: `GET /platforms`

### 平台特定便捷端点

- `POST /boss/job` - Boss直聘职位数据
- `POST /boss/company` - Boss直聘公司数据
- `POST /qcwy/job` - 前程无忧职位数据
- `POST /qcwy/company` - 前程无忧公司数据
- `POST /zhilian/job` - 智联招聘职位数据
- `POST /zhilian/company` - 智联招聘公司数据

## 数据类型和平台

### 支持的平台
- `boss` - Boss直聘
- `qcwy` - 前程无忧
- `zhilian` - 智联招聘

### 支持的数据类型
- `job` - 职位数据
- `company` - 公司数据

### 默认重复检查字段

| 平台 | 职位数据 | 公司数据 |
|------|----------|----------|
| boss | encrypt_job_id | encrypt_id |
| qcwy | job_id | company_id |
| zhilian | job_id | company_id |

## 使用示例

### 1. 存储Boss直聘职位数据

```json
POST /api/v1/universal/data/store
Content-Type: application/json

{
    "data": {
        "securityId": "abc123",
        "jobBaseInfoVO": {
            "encryptJobId": "job_encrypt_123",
            "jobId": 12345,
            "positionName": "Python开发工程师",
            "locationName": "北京",
            "lowSalary": 15000,
            "highSalary": 25000,
            "jobDesc": "负责后端开发工作..."
        },
        "bossBaseInfoVO": {
            "encryptBossId": "boss_encrypt_456",
            "bossId": 67890,
            "bossName": "张经理"
        },
        "brandComInfoVO": {
            "brandName": "某科技公司",
            "industryName": "互联网",
            "scaleName": "100-499人"
        }
    },
    "data_type": "job",
    "platform": "boss",
    "check_duplicate": true,
    "duplicate_key": "encrypt_job_id"
}
```

### 2. 批量存储前程无忧职位数据

```json
POST /api/v1/universal/data/batch-store
Content-Type: application/json

{
    "data_list": [
        {
            "job_name": "Java开发工程师",
            "brand_name": "某互联网公司",
            "job_addr": "上海",
            "salary_desc": "15k-25k",
            "job_desc": "负责Java后端开发..."
        },
        {
            "job_name": "前端开发工程师",
            "brand_name": "某科技公司",
            "job_addr": "深圳",
            "salary_desc": "12k-20k",
            "job_desc": "负责前端页面开发..."
        }
    ],
    "data_type": "job",
    "platform": "qcwy",
    "check_duplicate": true
}
```

### 3. 使用便捷端点存储数据

```json
POST /api/v1/universal/boss/job
Content-Type: application/json

{
    "securityId": "abc123",
    "jobBaseInfoVO": {
        "encryptJobId": "job_encrypt_789",
        "positionName": "产品经理",
        "locationName": "杭州"
    },
    "brandComInfoVO": {
        "brandName": "某电商公司",
        "industryName": "电子商务"
    }
}
```

### 4. 异步批量处理大量数据

```json
POST /api/v1/universal/data/batch-store-async
Content-Type: application/json

{
    "data_list": [
        // ... 大量数据
    ],
    "data_type": "job",
    "platform": "zhilian",
    "check_duplicate": true
}
```

## 响应格式

### 成功响应

```json
{
    "code": 200,
    "message": "数据存储成功",
    "data": {
        "success": true,
        "message": "数据存储成功",
        "duplicate": false,
        "result": true
    },
    "platform": "boss",
    "data_type": "job"
}
```

### 重复数据响应

```json
{
    "code": 400,
    "message": "数据已存在",
    "data": {
        "success": false,
        "message": "数据已存在",
        "duplicate": true,
        "existing_id": 12345
    },
    "platform": "boss",
    "data_type": "job"
}
```

### 批量处理响应

```json
{
    "code": 200,
    "message": "批量处理完成: 成功 8 条，失败 1 条，重复 1 条",
    "data": {
        "total": 10,
        "success": 8,
        "failed": 1,
        "duplicate": 1,
        "errors": [
            {
                "index": 5,
                "error": "缺少必要字段"
            }
        ]
    },
    "platform": "qcwy",
    "data_type": "job"
}
```

### 异步处理响应

```json
{
    "code": 202,
    "message": "数据已加入异步处理队列",
    "platform": "zhilian",
    "data_type": "job"
}
```

## 数据预处理

系统会根据不同平台自动进行数据预处理：

### Boss直聘数据预处理
- 从嵌套的VO对象中提取字段
- 映射到标准的数据库字段
- 保留原始数据在`raw_data`字段中

### 前程无忧数据预处理
- 直接映射字段名
- 处理数组类型字段
- 标准化日期格式

### 智联招聘数据预处理
- 处理复杂的嵌套结构
- 提取关键信息字段
- 转换数据类型

## 错误处理

### 常见错误码

- `400` - 请求参数错误或数据已存在
- `500` - 服务器内部错误
- `202` - 异步处理已接受

### 错误响应示例

```json
{
    "detail": "数据存储失败: 缺少必要字段 'encrypt_job_id'"
}
```

## 最佳实践

1. **使用重复检查**: 始终启用重复检查以避免数据冗余
2. **批量处理**: 对于大量数据，使用批量接口提高效率
3. **异步处理**: 对于非实时需求，使用异步接口避免超时
4. **错误处理**: 妥善处理API返回的错误信息
5. **数据验证**: 在发送前验证数据的完整性

## 监控和日志

系统会自动记录以下信息：
- 数据处理成功/失败统计
- 重复数据检测结果
- 处理时间和性能指标
- 错误详情和堆栈信息

可以通过应用日志查看详细的处理信息。

## 迁移指南

### 从平台特定API迁移

如果你之前使用平台特定的API（如`/api/v1/boss/job`），可以：

1. **继续使用便捷端点**: 使用`/api/v1/universal/boss/job`等便捷端点
2. **迁移到通用端点**: 使用`/api/v1/universal/data/store`通用端点
3. **逐步迁移**: 先测试新接口，确认无误后再完全迁移

### 数据格式兼容性

新的通用API完全兼容现有的数据格式，无需修改数据结构。