# 数据解析 API 文档

本文档描述了数据解析模块的 API 接口，包括通用数据解析和名片解析功能。所有接口均采用 RESTful 风格，返回 JSON 格式的响应。

## 基础路径

所有 API 接口的基础路径为：`/api/parse`

## 1. 通用数据解析接口

### 1.1 解析数据

**接口地址**：`/parse`

**请求方法**：POST

**功能描述**：测试用的数据解析接口，目前没有实际使用。

**请求参数**：

请求体为 JSON 格式，具体格式取决于实际使用场景。

**返回结果**：

```json
{
  "status": "success",
  "message": "Data parsed successfully",
  "data": {} // 解析后的数据
}
```

**错误码**：

| HTTP 状态码 | 错误描述           |
|---------|----------------|
| 400     | No data provided |
| 500     | 内部服务器错误       |

## 2. 名片解析接口

### 2.1 解析名片图片

**接口地址**：`/business-card-parse`

**请求方法**：POST

**功能描述**：处理上传的名片图片，提取名片中的信息，并保存到数据库。

**请求参数**：

Content-Type: multipart/form-data

| 参数名   | 参数类型 | 必须 | 描述   |
|-------|------|----|----|
| image | file | 是  | 名片图片 |

**返回结果**：

成功时返回：

```json
{
  "success": true,
  "message": "名片解析成功",
  "data": {
    "id": 1,
    "name_zh": "张三",
    "name_en": "Zhang San",
    "title_zh": "项目经理",
    "title_en": "Project Manager",
    "mobile": "13800138000",
    "phone": "010-12345678",
    "email": "zhangsan@example.com",
    "hotel_zh": "某酒店",
    "hotel_en": "Some Hotel",
    "address_zh": "北京市朝阳区某街某号",
    "address_en": "Some Street, Chaoyang District, Beijing",
    "postal_code_zh": "100000",
    "postal_code_en": "100000",
    "brand_zh": "某品牌",
    "brand_en": "Some Brand",
    "affiliation_zh": "某集团",
    "affiliation_en": "Some Group",
    "image_path": "unique-filename.jpg",
    "career_path": [],
    "brand_group": "",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": null,
    "updated_by": "system",
    "status": "active"
  }
}
```

**错误码**：

| HTTP 状态码 | 错误描述       | 错误消息            |
|---------|------------|-----------------|
| 400     | 请求参数错误     | 未上传图片           |
| 400     | 请求参数错误     | 未选择文件           |
| 400     | 请求参数错误     | 上传的文件不是图片       |
| 500     | 服务器内部错误    | 名片解析失败: {错误信息}  |
| 500     | 服务器内部错误    | OCR无法从图像中提取文本   |
| 500     | 服务器内部错误    | 保存名片信息到数据库失败    |

### 2.2 更新名片信息

**接口地址**：`/business-cards/<int:card_id>`

**请求方法**：PUT

**功能描述**：更新已有名片记录的信息。

**路径参数**：

| 参数名      | 参数类型 | 描述    |
|----------|------|-------|
| card_id  | int  | 名片记录ID |

**请求参数**：

请求体为 JSON 格式，可包含以下字段（所有字段都是可选的）：

```json
{
  "name_zh": "张三",
  "name_en": "Zhang San",
  "title_zh": "高级项目经理",
  "title_en": "Senior Project Manager",
  "mobile": "13800138000",
  "phone": "010-12345678",
  "email": "zhangsan@example.com",
  "hotel_zh": "某酒店",
  "hotel_en": "Some Hotel",
  "address_zh": "北京市朝阳区某街某号",
  "address_en": "Some Street, Chaoyang District, Beijing",
  "postal_code_zh": "100000",
  "postal_code_en": "100000",
  "brand_zh": "某品牌",
  "brand_en": "Some Brand",
  "affiliation_zh": "某集团",
  "affiliation_en": "Some Group",
  "career_path": [{"company": "XX公司", "position": "经理"}],
  "brand_group": "品牌A,品牌B",
  "updated_by": "user"
}
```

**返回结果**：

成功时返回：

```json
{
  "success": true,
  "message": "名片信息已更新",
  "data": {
    // 更新后的完整名片信息对象
  }
}
```

**错误码**：

| HTTP 状态码 | 错误描述    | 错误消息                    |
|---------|---------|-------------------------|
| 400     | 请求参数错误  | 请求数据为空                  |
| 404     | 资源不存在   | 未找到ID为{card_id}的名片记录    |
| 500     | 服务器内部错误 | 更新名片信息失败: {错误信息}        |

### 2.3 获取所有名片列表

**接口地址**：`/get-business-cards`

**请求方法**：GET

**功能描述**：获取系统中所有的名片记录列表。

**请求参数**：无

**返回结果**：

成功时返回：

```json
{
  "success": true,
  "message": "获取名片列表成功",
  "data": [
    {
      // 名片1的完整信息对象
    },
    {
      // 名片2的完整信息对象
    }
    // ...更多名片对象
  ]
}
```

**错误码**：

| HTTP 状态码 | 错误描述    | 错误消息              |
|---------|---------|-------------------|
| 500     | 服务器内部错误 | 获取名片列表失败: {错误信息}  |

### 2.4 获取单个名片记录

**接口地址**：`/get-business-card/<int:card_id>`

**请求方法**：GET

**功能描述**：根据ID获取单个名片的详细信息。

**路径参数**：

| 参数名      | 参数类型 | 描述    |
|----------|------|-------|
| card_id  | int  | 名片记录ID |

**请求参数**：无

**返回结果**：

成功时返回：

```json
{
  "code": 200,
  "success": true,
  "message": "获取名片记录成功",
  "data": {
    "id": 1,
    "name_zh": "张三",
    "name_en": "Zhang San",
    "title_zh": "项目经理",
    "title_en": "Project Manager",
    "mobile": "13800138000",
    "phone": "010-12345678",
    "email": "zhangsan@example.com",
    "hotel_zh": "某酒店",
    "hotel_en": "Some Hotel",
    "address_zh": "北京市朝阳区某街某号",
    "address_en": "Some Street, Chaoyang District, Beijing",
    "postal_code_zh": "100000",
    "postal_code_en": "100000",
    "brand_zh": "某品牌",
    "brand_en": "Some Brand",
    "affiliation_zh": "某集团",
    "affiliation_en": "Some Group",
    "image_path": "unique-filename.jpg",
    "career_path": [],
    "brand_group": "",
    "created_at": "2023-01-01 12:00:00",
    "updated_at": null,
    "updated_by": "system",
    "status": "active"
  }
}
```

**错误码**：

| HTTP 状态码 | 错误描述    | 错误消息                    |
|---------|---------|-------------------------|
| 404     | 资源不存在   | 未找到ID为{card_id}的名片记录    |
| 500     | 服务器内部错误 | 获取名片记录失败: {错误信息}        |

**使用示例**：

```bash
# 使用curl获取ID为1的名片记录
curl -X GET http://localhost:5500/api/data_parse/get-business-card/1
```

**使用说明**：

1. 该接口用于查询单个名片的详细信息，支持前端应用展示名片详情页面。
2. 接口返回的数据结构与更新接口一致，包含名片的所有字段信息。
3. 如需同时获取该名片关联的标签信息，可以配合`/talent-get-tags/{talent_id}`接口使用。
4. 对于不存在的名片ID，接口将返回404状态码。
5. 接口支持前端分页应用，可先使用列表接口获取所有名片ID，再通过此接口获取详细信息。

### 2.5 更新名片状态

**接口地址**：`/update-business-cards/<int:card_id>/status`

**请求方法**：PUT

**功能描述**：更新名片的状态（激活或禁用）。

**路径参数**：

| 参数名      | 参数类型 | 描述    |
|----------|------|-------|
| card_id  | int  | 名片记录ID |

**请求参数**：

```json
{
  "status": "active" // 可选值: "active" 或 "inactive"
}
```

**返回结果**：

成功时返回：

```json
{
  "success": true,
  "message": "名片状态已更新为: active",
  "data": {
    // 更新后的完整名片信息对象
  }
}
```

**错误码**：

| HTTP 状态码 | 错误描述    | 错误消息                          |
|---------|---------|-------------------------------|
| 400     | 请求参数错误  | 请求数据为空或缺少status字段             |
| 400     | 请求参数错误  | 无效的状态值: {状态值}，必须为 active 或 inactive |
| 404     | 资源不存在   | 未找到ID为{card_id}的名片记录          |
| 500     | 服务器内部错误 | 更新名片状态失败: {错误信息}              |

### 2.6 获取名片图片

**接口地址**：`/business-cards/image/<path:image_path>`

**请求方法**：GET

**功能描述**：从 MinIO 存储中获取名片图片。

**路径参数**：

| 参数名         | 参数类型   | 描述           |
|-------------|--------|--------------|
| image_path  | string | MinIO中的图片路径  |

**返回结果**：

成功时返回图片的二进制数据流，Content-Type 根据图片类型设置。

**错误码**：

| HTTP 状态码 | 错误描述    | 错误消息                |
|---------|---------|---------------------|
| 500     | 服务器内部错误 | MinIO客户端初始化失败       |
| 404     | 资源不存在   | 获取图片失败: {错误信息}      |

## 数据模型

### 名片模型 (BusinessCard)

| 字段名            | 类型       | 描述        |
|----------------|----------|-----------|
| 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     | Text     | 中文地址      |
| address_en     | Text     | 英文地址      |
| postal_code_zh | String   | 中文邮政编码    |
| postal_code_en | String   | 英文邮政编码    |
| brand_zh       | String   | 中文品牌名称    |
| brand_en       | String   | 英文品牌名称    |
| affiliation_zh | String   | 中文隶属关系    |
| affiliation_en | String   | 英文隶属关系    |
| image_path     | String   | MinIO中存储的路径 |
| career_path    | JSON     | 职业轨迹      |
| brand_group    | String   | 品牌组合      |
| created_at     | DateTime | 创建时间      |
| updated_at     | DateTime | 更新时间      |
| updated_by     | String   | 更新者       |
| status         | String   | 状态        |