# get-parsed-talents 接口使用说明书

## 接口概述

`get-parsed-talents` 接口用于获取解析人才记录列表，支持按状态过滤查询。该接口返回 `parsed_talents` 数据库表中的记录，按创建时间倒序排列。

## 基本信息

- **接口名称**: get-parsed-talents
- **HTTP方法**: GET
- **访问路径**: `/get-parsed-talents`
- **接口描述**: 获取解析人才记录列表，支持状态过滤
- **数据来源**: `parsed_talents` 数据库表

## 请求参数

### 查询参数 (Query Parameters)

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| status | string | 否 | null | 状态过滤参数，如果为空则查询所有记录 |

### 参数说明

- **status**: 用于过滤特定状态的记录
  - 可选值: `"待审核"`, `"已入库"`, `"已拒绝"`, `"active"`, `"inactive"` 等
  - 如果参数为空或不传，则返回所有状态的记录
  - 参数值不区分大小写，但建议使用标准状态值

## 响应格式

### 成功响应 (200 OK)

```json
{
    "success": true,
    "message": "成功获取 X 条解析人才记录",
    "data": [
        {
            "id": 1,
            "name_zh": "张三",
            "name_en": "Zhang San",
            "title_zh": "总经理",
            "title_en": "General Manager",
            "mobile": "13800138000",
            "phone": "010-12345678",
            "email": "zhangsan@example.com",
            "hotel_zh": "北京希尔顿酒店",
            "hotel_en": "Beijing Hilton Hotel",
            "address_zh": "北京市朝阳区建国门外大街1号",
            "address_en": "1 Jianguomenwai Street, Chaoyang District, Beijing",
            "postal_code_zh": "100020",
            "postal_code_en": "100020",
            "brand_zh": "希尔顿",
            "brand_en": "Hilton",
            "affiliation_zh": "希尔顿酒店集团",
            "affiliation_en": "Hilton Hotels & Resorts",
            "image_path": "minio/talents/zhangsan.jpg",
            "career_path": [
                {
                    "date": "2024-01-15",
                    "hotel_zh": "北京希尔顿酒店",
                    "hotel_en": "Beijing Hilton Hotel",
                    "title_zh": "总经理",
                    "title_en": "General Manager",
                    "image_path": "minio/talents/zhangsan.jpg",
                    "source": "webpage_extraction"
                }
            ],
            "brand_group": "希尔顿集团",
            "birthday": "1980-05-15",
            "residence": "北京市朝阳区",
            "age": 44,
            "native_place": "北京市",
            "origin_source": [
                {
                    "task_type": "webpage_talent",
                    "minio_path": "minio/webpage/zhangsan.md",
                    "source_date": "2024-01-15 14:30:25"
                }
            ],
            "talent_profile": "资深酒店管理专家，拥有15年酒店管理经验...",
            "task_id": "task_001",
            "task_type": "webpage_talent",
            "created_at": "2024-01-15T14:30:25",
            "updated_at": "2024-01-15T14:30:25",
            "updated_by": "system",
            "status": "待审核"
        }
    ],
    "count": 1
}
```

### 错误响应 (500 Internal Server Error)

```json
{
    "success": false,
    "message": "获取解析人才记录失败: 数据库连接错误",
    "data": [],
    "count": 0
}
```

## 响应字段说明

### 顶层字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| success | boolean | 请求是否成功 |
| message | string | 响应消息 |
| data | array | 人才记录数组 |
| count | integer | 记录总数 |

### 人才记录字段 (data 数组中的对象)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | integer | 记录唯一标识符 |
| name_zh | string | 中文姓名 |
| name_en | string | 英文姓名 |
| title_zh | string | 中文职位 |
| title_en | string | 英文职位 |
| mobile | string | 手机号码 |
| phone | string | 固定电话 |
| email | string | 电子邮箱 |
| hotel_zh | string | 中文酒店名称 |
| hotel_en | string | 英文酒店名称 |
| address_zh | string | 中文地址 |
| address_en | string | 英文地址 |
| postal_code_zh | string | 中文邮政编码 |
| postal_code_en | string | 英文邮政编码 |
| brand_zh | string | 中文品牌名称 |
| brand_en | string | 英文品牌名称 |
| affiliation_zh | string | 中文隶属关系 |
| affiliation_en | string | 英文隶属关系 |
| image_path | string | 图片文件路径 |
| career_path | array | 职业轨迹数组 |
| brand_group | string | 品牌组合 |
| birthday | string | 生日 (YYYY-MM-DD格式) |
| residence | string | 居住地 |
| age | integer | 年龄 |
| native_place | string | 籍贯 |
| origin_source | array | 原始资料记录数组 |
| talent_profile | string | 人才档案描述 |
| task_id | string | 解析任务ID |
| task_type | string | 解析任务类型 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
| updated_by | string | 更新人 |
| status | string | 记录状态 |

### career_path 数组字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| date | string | 职业记录日期 |
| hotel_zh | string | 中文酒店名称 |
| hotel_en | string | 英文酒店名称 |
| title_zh | string | 中文职位 |
| title_en | string | 英文职位 |
| image_path | string | 相关图片路径 |
| source | string | 数据来源 |

### origin_source 数组字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| task_type | string | 任务类型 |
| minio_path | string | MinIO存储路径 |
| source_date | string | 数据来源时间 |

## 使用示例

### 1. 查询所有记录

**请求**:
```
GET /get-parsed-talents
```

**响应**:
```json
{
    "success": true,
    "message": "成功获取 150 条解析人才记录",
    "data": [...],
    "count": 150
}
```

### 2. 查询待审核记录

**请求**:
```
GET /get-parsed-talents?status=待审核
```

**响应**:
```json
{
    "success": true,
    "message": "成功获取 25 条解析人才记录",
    "data": [...],
    "count": 25
}
```

### 3. 查询已入库记录

**请求**:
```
GET /get-parsed-talents?status=已入库
```

**响应**:
```json
{
    "success": true,
    "message": "成功获取 120 条解析人才记录",
    "data": [...],
    "count": 120
}
```

### 4. 查询已拒绝记录

**请求**:
```
GET /get-parsed-talents?status=已拒绝
```

**响应**:
```json
{
    "success": true,
    "message": "成功获取 5 条解析人才记录",
    "data": [...],
    "count": 5
}
```

## 前端集成示例

### JavaScript (使用 fetch)

```javascript
// 获取所有记录
async function getAllParsedTalents() {
    try {
        const response = await fetch('/get-parsed-talents');
        const data = await response.json();
        
        if (data.success) {
            console.log(`获取到 ${data.count} 条记录`);
            return data.data;
        } else {
            console.error('获取失败:', data.message);
            return [];
        }
    } catch (error) {
        console.error('请求失败:', error);
        return [];
    }
}

// 获取特定状态的记录
async function getParsedTalentsByStatus(status) {
    try {
        const response = await fetch(`/get-parsed-talents?status=${encodeURIComponent(status)}`);
        const data = await response.json();
        
        if (data.success) {
            console.log(`获取到 ${data.count} 条 ${status} 状态的记录`);
            return data.data;
        } else {
            console.error('获取失败:', data.message);
            return [];
        }
    } catch (error) {
        console.error('请求失败:', error);
        return [];
    }
}

// 使用示例
getAllParsedTalents().then(talents => {
    console.log('所有人才记录:', talents);
});

getParsedTalentsByStatus('待审核').then(talents => {
    console.log('待审核人才记录:', talents);
});
```

### JavaScript (使用 axios)

```javascript
import axios from 'axios';

// 获取所有记录
async function getAllParsedTalents() {
    try {
        const response = await axios.get('/get-parsed-talents');
        const { success, data, count, message } = response.data;
        
        if (success) {
            console.log(`获取到 ${count} 条记录`);
            return data;
        } else {
            console.error('获取失败:', message);
            return [];
        }
    } catch (error) {
        console.error('请求失败:', error);
        return [];
    }
}

// 获取特定状态的记录
async function getParsedTalentsByStatus(status) {
    try {
        const response = await axios.get('/get-parsed-talents', {
            params: { status }
        });
        const { success, data, count, message } = response.data;
        
        if (success) {
            console.log(`获取到 ${count} 条 ${status} 状态的记录`);
            return data;
        } else {
            console.error('获取失败:', message);
            return [];
        }
    } catch (error) {
        console.error('请求失败:', error);
        return [];
    }
}
```

### React Hook 示例

```javascript
import { useState, useEffect } from 'react';

function useParsedTalents(status = null) {
    const [talents, setTalents] = useState([]);
    const [loading, setLoading] = useState(false);
    const [error, setError] = useState(null);

    useEffect(() => {
        const fetchTalents = async () => {
            setLoading(true);
            setError(null);
            
            try {
                const url = status 
                    ? `/get-parsed-talents?status=${encodeURIComponent(status)}`
                    : '/get-parsed-talents';
                    
                const response = await fetch(url);
                const data = await response.json();
                
                if (data.success) {
                    setTalents(data.data);
                } else {
                    setError(data.message);
                }
            } catch (err) {
                setError('请求失败: ' + err.message);
            } finally {
                setLoading(false);
            }
        };

        fetchTalents();
    }, [status]);

    return { talents, loading, error };
}

// 使用示例
function TalentList() {
    const { talents, loading, error } = useParsedTalents('待审核');

    if (loading) return <div>加载中...</div>;
    if (error) return <div>错误: {error}</div>;

    return (
        <div>
            <h2>待审核人才列表 ({talents.length})</h2>
            {talents.map(talent => (
                <div key={talent.id}>
                    <h3>{talent.name_zh}</h3>
                    <p>职位: {talent.title_zh}</p>
                    <p>酒店: {talent.hotel_zh}</p>
                    <p>状态: {talent.status}</p>
                </div>
            ))}
        </div>
    );
}
```

## 注意事项

1. **分页处理**: 当前接口返回所有匹配的记录，如果数据量很大，建议前端实现分页显示
2. **状态值**: 建议使用标准状态值，如 `"待审核"`, `"已入库"`, `"已拒绝"`
3. **错误处理**: 始终检查 `success` 字段，处理可能的错误情况
4. **数据格式**: 日期时间字段使用 ISO 8601 格式
5. **空值处理**: 某些字段可能为 `null` 或空字符串，前端需要适当处理
6. **字符编码**: 中文字段使用 UTF-8 编码

## 状态码说明

| HTTP状态码 | 说明 |
|-----------|------|
| 200 | 请求成功 |
| 500 | 服务器内部错误 |

## 更新日志

- **v1.0.0** (2024-01-15): 初始版本，支持基本查询和状态过滤功能

## 联系方式

如有问题或建议，请联系开发团队。