# data_parse API 接口文档

## 📖 概述

本文档提供了DataOps平台数据解析模块的所有API接口使用说明，包括名片解析、酒店职位管理、人才标签管理、知识图谱查询等功能。

**基础URL**: `http://your-domain/api/data_parse`

## 🏷️ 接口分类

- [名片解析接口](#名片解析接口)
- [酒店职位管理接口](#酒店职位管理接口)
- [酒店集团品牌管理接口](#酒店集团品牌管理接口)
- [人才标签管理接口](#人才标签管理接口)
- [知识图谱查询接口](#知识图谱查询接口)
- [重复记录处理接口](#重复记录处理接口)
- [系统工具接口](#系统工具接口)

---

## 名片解析接口

### 1. 解析名片图片

**功能**: 仅解析名片图片，提取信息但不保存到数据库

```http
POST /business-card-parse
```

#### 请求参数

| 参数名   | 类型   | 必填  | 说明                           |
| ----- | ---- | --- | ---------------------------- |
| image | File | 是   | 名片图片文件 (multipart/form-data) |

#### 响应格式

```json
{
  "code": 200,
  "success": true,
  "message": "名片图片解析成功",
  "data": {
    "name_zh": "张三",
    "name_en": "John Doe",
    "title_zh": "总经理",
    "title_en": "General Manager",
    "mobile": "13800138000",
    "phone": "021-12345678",
    "email": "john.doe@example.com",
    "hotel_zh": "上海希尔顿酒店",
    "hotel_en": "Shanghai Hilton Hotel",
    "address_zh": "上海市浦东新区...",
    "address_en": "Pudong New Area, Shanghai...",
    "postal_code_zh": "200000",
    "postal_code_en": "200000",
    "brand_zh": "希尔顿",
    "brand_en": "Hilton",
    "affiliation_zh": "希尔顿集团",
    "affiliation_en": "Hilton Group",
    "birthday": "1990-01-01",
    "residence": "上海市浦东新区张江高科技园区",
    "brand_group": "希尔顿,万豪",
    "career_path": []
  }
}
```

#### 数据字段说明

| 字段名             | 类型     | 说明                        |
| --------------- | ------ | ------------------------- |
| 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 | 英文隶属关系                    |
| birthday        | String | 生日，格式为YYYY-MM-DD         |
| residence       | String | 居住地址信息                    |
| brand_group     | String | 品牌组合，多个品牌用逗号分隔            |
| career_path     | Array  | 职业轨迹，JSON数组格式            |

#### 状态码

| 状态码 | 说明                    |
| --- | --------------------- |
| 200 | 解析成功                  |
| 400 | 请求参数错误（未上传文件、文件类型错误等） |
| 500 | 服务器错误或解析失败            |

#### 示例代码

```bash
curl -X POST \
  http://your-domain/api/data_parse/business-card-parse \
  -H 'Content-Type: multipart/form-data' \
  -F 'image=@business_card.jpg'
```

```python
import requests

url = "http://your-domain/api/data_parse/business-card-parse"
files = {'image': open('business_card.jpg', 'rb')}

response = requests.post(url, files=files)
print(response.json())
```

---

### 2. 添加名片记录

**功能**: 保存名片信息到数据库，包括重复检查、MinIO上传等完整业务逻辑

```http
POST /add-business-card
```

#### 请求参数

**方式1: JSON Body**

```json
{
   "name_zh": "张三",
    "name_en": "John Doe",
    "title_zh": "总经理",
    "title_en": "General Manager",
    "mobile": "13800138000",
    "phone": "021-12345678",
    "email": "john.doe@example.com",
    "hotel_zh": "上海希尔顿酒店",
    "hotel_en": "Shanghai Hilton Hotel",
    "address_zh": "上海市浦东新区...",
    "address_en": "Pudong New Area, Shanghai...",
    "postal_code_zh": "200000",
    "postal_code_en": "200000",
    "brand_zh": "希尔顿",
    "brand_en": "Hilton",
    "affiliation_zh": "希尔顿集团",
    "affiliation_en": "Hilton Group",
    "birthday": "1990-01-01",
    "residence": "上海市浦东新区张江高科技园区",
    "brand_group": "希尔顿,万豪",
    "career_path": []
}
```

**方式2: Form-Data**

| 参数名       | 类型     | 必填  | 说明          |
| --------- | ------ | --- | ----------- |
| card_data | String | 是   | JSON格式的名片数据 |
| image     | File   | 否   | 名片图片文件      |

#### 响应格式

**成功创建新记录**:

```json
{
  "code": 200,
  "success": true,
  "message": "名片信息保存成功。未找到同名记录，创建新记录",
  "data": {
    "id": 123,
    "name_zh": "张三",
    "name_en": "John Doe",
    "birthday": "1990-01-01",
    "residence": "上海市浦东新区张江高科技园区",
    "created_at": "2024-01-01 12:00:00",
    "image_path": "abc123.jpg",
    ...
  }
}
```

**发现疑似重复记录**:

```json
{
  "code": 202,
  "success": true,
  "message": "创建新记录成功，发现疑似重复记录待处理",
  "data": {
    "main_card": { ... },
    "duplicate_record_id": 45,
    "suspected_duplicates_count": 2,
    "processing_status": "pending"
  }
}
```

#### 状态码

| 状态码 | 说明            |
| --- | ------------- |
| 200 | 成功创建或更新记录     |
| 202 | 创建成功但发现疑似重复记录 |
| 400 | 请求参数错误        |
| 500 | 服务器错误         |

#### 示例代码

```python
# 方式1: 纯JSON
import requests

url = "http://your-domain/api/data_parse/add-business-card"
data = {
    "name_zh": "张三",
    "mobile": "13800138000",
    "hotel_zh": "上海希尔顿酒店",
    "birthday": "1990-01-01",
    "residence": "上海市浦东新区张江高科技园区"
}

response = requests.post(url, json=data)
print(response.json())

# 方式2: 包含图片文件
import json

url = "http://your-domain/api/data_parse/add-business-card"
card_data = {
    "name_zh": "张三",
    "mobile": "13800138000",
    "birthday": "1990-01-01",
    "residence": "上海市浦东新区张江高科技园区"
}

files = {'image': open('business_card.jpg', 'rb')}
data = {'card_data': json.dumps(card_data)}

response = requests.post(url, files=files, data=data)
print(response.json())
```

---

### 3. 获取所有名片记录

```http
GET /get-business-cards
```

#### 响应格式

```json
{
  "code": 200,
  "success": true,
  "message": "获取名片列表成功",
  "data": [
    {
      "id": 1,
      "name_zh": "张三",
      "name_en": "John Doe",
      "mobile": "13800138000",
      "birthday": "1990-01-01",
      "residence": "上海市浦东新区张江高科技园区",
      "created_at": "2024-01-01 12:00:00",
      ...
    }
  ]
}
```

---

### 4. 获取单个名片记录

```http
GET /get-business-card/{card_id}
```

#### 路径参数

| 参数名     | 类型      | 说明     |
| ------- | ------- | ------ |
| card_id | Integer | 名片记录ID |

#### 示例

```bash
curl http://your-domain/api/data_parse/get-business-card/123
```

---

### 5. 更新名片信息

```http
PUT /business-cards/{card_id}
```

#### 路径参数

| 参数名     | 类型      | 说明     |
| ------- | ------- | ------ |
| card_id | Integer | 名片记录ID |

#### 请求参数

```json
{
  "name_zh": "李四",
  "title_zh": "副总经理",
  "mobile": "13900139000",
  "birthday": "1985-06-15",
  "residence": "北京市朝阳区建国门外大街"
}
```

---

### 6. 删除名片记录

**功能**: 完全删除名片记录，包括PostgreSQL数据库记录、MinIO存储的图片文件和Neo4j图数据库中的相关节点和关系

```http
DELETE /delete-business-card/{card_id}
```

#### 路径参数

| 参数名     | 类型      | 说明     |
| ------- | ------- | ------ |
| card_id | Integer | 名片记录ID |

#### 删除范围

1. **PostgreSQL数据库清理**:
   - 删除 `business_cards` 表中指定ID的记录
   - 删除 `duplicate_business_cards` 表中以该ID作为 `main_card_id` 的相关记录

2. **MinIO文件存储清理**:
   - 删除与该名片记录关联的图片文件

3. **Neo4j图数据库清理**:
   - 删除 `talent` 节点中 `pg_id` 等于传入ID的节点
   - 同时删除该节点的所有关联关系 (BELONGS_TO, WORKS_FOR等)

#### 响应格式

**完全成功删除**:

```json
{
  "code": 200,
  "success": true,
  "message": "名片记录删除成功",
  "data": {
    "id": 123,
    "name_zh": "张三",
    "name_en": "John Doe",
    "mobile": "13800138000",
    "birthday": "1990-01-01",
    "residence": "上海市浦东新区张江高科技园区",
    "image_path": "abc123.jpg",
    "created_at": "2024-01-01 12:00:00",
    "status": "active"
  }
}
```

**部分成功删除**:

```json
{
  "code": 206,
  "success": true,
  "message": "名片记录删除成功，但Neo4j图数据库清理失败: 连接超时",
  "data": {
    "id": 123,
    "name_zh": "张三",
    ...
  }
}
```

#### 状态码

| 状态码 | 说明                                   |
| --- | ------------------------------------ |
| 200 | 完全成功删除所有相关数据                         |
| 206 | 部分成功 (PostgreSQL删除成功，但Neo4j删除失败)    |
| 400 | 参数错误（无效的card_id）                     |
| 404 | 未找到指定ID的名片记录                         |
| 500 | 删除操作失败                               |

#### 示例代码

```bash
curl -X DELETE \
  http://your-domain/api/data_parse/delete-business-card/123
```

```python
import requests

url = "http://your-domain/api/data_parse/delete-business-card/123"
response = requests.delete(url)
print(response.json())
```

#### 注意事项

⚠️ **警告**: 此操作不可逆，删除的数据无法恢复。建议在删除前：
1. 确认要删除的记录ID正确
2. 考虑是否需要备份相关数据
3. 检查是否有其他系统依赖此记录

---

### 7. 更新名片状态

```http
PUT /update-business-cards/{card_id}/status
```

#### 请求参数

```json
{
  "status": "inactive"
}
```

#### 可选状态值

| 状态值      | 说明  |
| -------- | --- |
| active   | 激活  |
| inactive | 停用  |

---

### 8. 获取名片图片

```http
GET /business-cards/image/{image_path}
```

#### 路径参数

| 参数名        | 类型     | 说明          |
| ---------- | ------ | ----------- |
| image_path | String | MinIO中的图片路径 |

#### 示例

```bash
curl http://your-domain/api/data_parse/business-cards/image/abc123.jpg
```

---

## 酒店职位管理接口

### 1. 获取所有酒店职位

```http
GET /get-hotel-positions-list
```

#### 响应格式

```json
{
  "success": true,
  "message": "获取酒店职位列表成功",
  "data": [
    {
      "id": 1,
      "department_zh": "前厅部",
      "department_en": "Front Office",
      "position_zh": "前台经理",
      "position_en": "Front Office Manager",
      "position_abbr": "FOM",
      "level_zh": "中层",
      "level_en": "Middle Management",
      "status": "active"
    }
  ],
  "count": 50
}
```

---

### 2. 新增酒店职位

```http
POST /add-hotel-positions
```

#### 请求参数

```json
{
  "department_zh": "前厅部",
  "department_en": "Front Office",
  "position_zh": "前台经理",
  "position_en": "Front Office Manager",
  "position_abbr": "FOM",
  "level_zh": "中层",
  "level_en": "Middle Management",
  "created_by": "admin",
  "status": "active"
}
```

#### 必填字段

| 字段名           | 说明     |
| ------------- | ------ |
| department_zh | 部门中文名称 |
| department_en | 部门英文名称 |
| position_zh   | 职位中文名称 |
| position_en   | 职位英文名称 |
| level_zh      | 职级中文名称 |
| level_en      | 职级英文名称 |

#### 状态码

| 状态码 | 说明    |
| --- | ----- |
| 201 | 创建成功  |
| 400 | 参数错误  |
| 409 | 记录已存在 |
| 500 | 服务器错误 |

---

### 3. 更新酒店职位

```http
PUT /update-hotel-positions/{position_id}
```

---

### 4. 查询酒店职位

```http
GET /query-hotel-positions/{position_id}
```

---

### 5. 删除酒店职位

```http
DELETE /delete-hotel-positions/{position_id}
```

---

## 酒店集团品牌管理接口

### 1. 获取所有酒店集团品牌

```http
GET /get-hotel-group-brands-list
```

#### 响应格式

```json
{
  "success": true,
  "message": "获取酒店集团品牌列表成功",
  "data": [
    {
      "id": 1,
      "group_name_en": "Hilton Worldwide",
      "group_name_zh": "希尔顿集团",
      "brand_name_en": "Hilton Hotels & Resorts",
      "brand_name_zh": "希尔顿酒店",
      "positioning_level_en": "Luxury",
      "positioning_level_zh": "奢华",
      "status": "active"
    }
  ],
  "count": 25
}
```

---

### 2. 新增酒店集团品牌

```http
POST /add-hotel-group-brands
```

#### 请求参数

```json
{
  "group_name_en": "Marriott International",
  "group_name_zh": "万豪国际",
  "brand_name_en": "The Ritz-Carlton",
  "brand_name_zh": "丽思卡尔顿",
  "positioning_level_en": "Luxury",
  "positioning_level_zh": "奢华"
}
```

---

## 人才标签管理接口

### 1. 创建人才标签

```http
POST /create-talent-tag
```

#### 请求参数

```json
{
  "name": "酒店管理",
  "category": "人才技能",
  "description": "具备酒店运营管理经验",
  "status": "active"
}
```

---

### 2. 获取人才标签列表

```http
GET /get-talent-tag-list
```

#### 响应格式

```json
{
  "success": true,
  "message": "获取人才标签列表成功",
  "data": [
    {
      "id": 123,
      "name": "酒店管理",
      "en_name": "Hotel Management",
      "category": "人才技能",
      "description": "具备酒店运营管理经验",
      "status": "active",
      "time": "2024-01-01 12:00:00"
    }
  ]
}
```

---

### 3. 更新人才标签

```http
PUT /update-talent-tag/{tag_id}
```

---

### 4. 删除人才标签

```http
DELETE /delete-talent-tag/{tag_id}
```

---

### 5. 获取人才标签关系

```http
GET /talent-get-tags/{talent_id}
```

#### 路径参数

| 参数名       | 类型      | 说明                |
| --------- | ------- | ----------------- |
| talent_id | Integer | 人才节点PostgreSQL ID |

#### 响应格式

```json
{
  "success": true,
  "message": "获取人才标签成功",
  "data": [
    {
      "talent": 12345,
      "tag": "酒店管理"
    },
    {
      "talent": 12345,
      "tag": "市场营销"
    }
  ]
}
```

---

### 6. 更新人才标签关系

```http
POST /talent-update-tags
```

#### 请求参数

```json
[
  {
    "talent": 12345,
    "tag": "酒店管理"
  },
  {
    "talent": 12345,
    "tag": "市场营销"
  },
  {
    "talent": 12345,
    "tag": "团队领导"
  }
]
```

#### 响应格式

```json
{
  "code": 200,
  "success": true,
  "message": "成功创建或更新了 3 个标签关系",
  "data": {
    "success_count": 3,
    "total_count": 3,
    "failed_items": []
  }
}
```

---

## 知识图谱查询接口

### 1. 查询知识图谱

```http
POST /query-kg
```

#### 请求参数

```json
{
  "query_requirement": "查找具有五星级酒店和总经理经验的人才"
}
```

#### 响应格式

```json
{
  "code": 200,
  "success": true,
  "message": "查询成功执行",
  "query": "MATCH (t:talent)-[:BELONGS_TO]->(dl:data_label) WHERE dl.name IN ['五星级酒店', '总经理'] WITH t, COLLECT(DISTINCT dl.name) AS labels WHERE size(labels) = 2 RETURN t.pg_id as pg_id, t.name_zh as name_zh, t.name_en as name_en, t.mobile as mobile, t.email as email, t.updated_at as updated_at",
  "matched_labels": ["五星级酒店", "总经理"],
  "data": [
    {
      "pg_id": 123,
      "name_zh": "张三",
      "name_en": "John Doe",
      "mobile": "13800138000",
      "email": "john.doe@example.com",
      "updated_at": "2024-01-01 12:00:00"
    }
  ]
}
```

---

## 重复记录处理接口

### 1. 获取重复记录列表

```http
GET /get-duplicate-records?status=pending
```

#### 查询参数

| 参数名    | 类型     | 可选值                         | 说明        |
| ------ | ------ | --------------------------- | --------- |
| status | String | pending, processed, ignored | 筛选特定状态的记录 |

#### 响应格式

```json
{
  "success": true,
  "message": "获取重复记录列表成功",
  "data": [
    {
      "id": 1,
      "main_card_id": 123,
      "suspected_duplicates": [
        {
          "id": 124,
          "name_zh": "张三",
          "mobile": "13900139000"
        }
      ],
      "duplicate_reason": "姓名相同但手机号码不同",
      "processing_status": "pending",
      "created_at": "2024-01-01 12:00:00",
      "main_card": { 
        "id": 123,
        "name_zh": "张三",
        "name_en": "John Doe",
        "mobile": "13800138000",
        "birthday": "1990-01-01",
        "residence": "上海市浦东新区张江高科技园区",
        "created_at": "2024-01-01 11:30:00",
        ...
      }
    }
  ],
  "count": 5
}
```

---

### 2. 处理重复记录

```http
POST /process-duplicate-record/{duplicate_id}
```

#### 路径参数

| 参数名          | 类型      | 说明                                              |
| ------------ | ------- | ----------------------------------------------- |
| duplicate_id | Integer | 名片记录ID（对应DuplicateBusinessCard表中的main_card_id字段） |

⚠️ **重要说明**: 
- 此参数为名片记录的ID（即 `BusinessCard` 表的主键）
- 系统会根据此ID查找 `DuplicateBusinessCard` 表中 `main_card_id` 字段匹配的重复记录
- 不是 `DuplicateBusinessCard` 表的主键ID

#### 请求参数

```json
{
  "action": "merge_to_suspected",
  "selected_duplicate_id": 124,
  "processed_by": "admin",
  "notes": "确认为同一人，合并记录"
}
```

#### 操作类型

| 操作                 | 说明                      |
| ------------------ | ----------------------- |
| merge_to_suspected | 合并到选中的疑似重复记录            |
| keep_main          | 保留主记录，不做合并              |
| ignore             | 忽略，标记为已处理               |

#### 响应格式

**成功处理**:

```json
{
  "code": 200,
  "success": true,
  "message": "重复记录处理成功，操作: merge_to_suspected",
  "data": {
    "duplicate_record": {
      "id": 1,
      "main_card_id": 123,
      "processing_status": "processed",
      "processed_at": "2024-01-01 15:30:00",
      "processed_by": "admin",
      "processing_notes": "确认为同一人，合并记录"
    },
    "result": {
      "id": 124,
      "name_zh": "张三",
      "name_en": "John Doe",
      "birthday": "1990-01-01",
      "residence": "上海市浦东新区张江高科技园区",
      "updated_at": "2024-01-01 15:30:00",
      ...
    }
  }
}
```

#### 状态码

| 状态码 | 说明                                     |
| --- | -------------------------------------- |
| 200 | 处理成功                                   |
| 400 | 参数错误或重复记录状态不允许处理                       |
| 404 | 未找到对应的重复记录或目标记录                        |
| 500 | 处理失败                                   |

#### 示例代码

```bash
curl -X POST \
  http://your-domain/api/data_parse/process-duplicate-record/123 \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "merge_to_suspected",
    "selected_duplicate_id": 124,
    "processed_by": "admin",
    "notes": "确认为同一人，合并记录"
  }'
```

```python
import requests

url = "http://your-domain/api/data_parse/process-duplicate-record/123"
data = {
    "action": "merge_to_suspected",
    "selected_duplicate_id": 124,
    "processed_by": "admin",
    "notes": "确认为同一人，合并记录"
}

response = requests.post(url, json=data)
print(response.json())
```

---

### 3. 获取重复记录详情

```http
GET /get-duplicate-record-detail/{duplicate_id}
```

#### 路径参数

| 参数名          | 类型      | 说明                                              |
| ------------ | ------- | ----------------------------------------------- |
| duplicate_id | Integer | 名片记录ID（对应DuplicateBusinessCard表中的main_card_id字段） |

⚠️ **重要说明**: 
- 此参数为名片记录的ID（即 `BusinessCard` 表的主键）
- 系统会根据此ID查找 `DuplicateBusinessCard` 表中 `main_card_id` 字段匹配的重复记录

#### 响应格式

```json
{
  "code": 200,
  "success": true,
  "message": "获取重复记录详情成功",
  "data": {
    "id": 1,
    "main_card_id": 123,
    "suspected_duplicates": [
      {
        "id": 124,
        "name_zh": "张三",
        "name_en": "John Doe",
        "mobile": "13900139000",
        "hotel_zh": "北京希尔顿酒店",
        "created_at": "2024-01-01 10:00:00"
      },
      {
        "id": 125,
        "name_zh": "张三",
        "name_en": "John Doe",
        "mobile": "13700137000",
        "hotel_zh": "广州万豪酒店",
        "created_at": "2024-01-01 09:00:00"
      }
    ],
    "duplicate_reason": "姓名相同但手机号码不同：张三，新手机号：13800138000，发现2条疑似重复记录",
    "processing_status": "pending",
    "created_at": "2024-01-01 12:00:00",
    "processed_at": null,
    "processed_by": null,
    "processing_notes": null,
    "main_card": {
      "id": 123,
      "name_zh": "张三",
      "name_en": "John Doe",
      "mobile": "13800138000",
      "birthday": "1990-01-01",
      "residence": "上海市浦东新区张江高科技园区",
      "hotel_zh": "上海希尔顿酒店",
      "created_at": "2024-01-01 12:00:00",
      ...
    }
  }
}
```

#### 状态码

| 状态码 | 说明        |
| --- | --------- |
| 200 | 获取成功      |
| 404 | 未找到对应的重复记录 |
| 500 | 获取失败      |

#### 示例代码

```bash
curl http://your-domain/api/data_parse/get-duplicate-record-detail/123
```

```python
import requests

url = "http://your-domain/api/data_parse/get-duplicate-record-detail/123"
response = requests.get(url)
print(response.json())
```

---

## 系统工具接口

### 1. 测试MinIO连接

```http
GET /test-minio-connection
```

#### 响应格式

```json
{
  "success": true,
  "message": "连接MinIO服务器成功，存储桶 dataops-bucket 存在",
  "config": {
    "host": "192.168.3.143:9000",
    "bucket": "dataops-bucket",
    "secure": false
  }
}
```

---

### 2. 测试数据解析

```http
POST /parse
```

#### 请求参数

```json
{
  "text": "这是测试数据"
}
```

---

### 3. 修复损坏的重复记录

**功能**: 修复 `duplicate_business_cards` 表中 `main_card_id` 为 null 的损坏记录

```http
POST /fix-broken-duplicate-records
```

#### 功能说明

此接口用于修复在处理重复记录合并操作时可能产生的数据完整性问题。当执行合并操作删除主记录时，如果外键约束处理不当，可能导致重复记录表中的 `main_card_id` 字段变成 null，违反数据库的非空约束。

#### 修复范围

- 查找所有 `main_card_id` 为 null 的损坏记录
- 删除这些损坏的记录以维护数据完整性
- 记录修复操作的详细结果

#### 响应格式

**成功修复**:

```json
{
  "code": 200,
  "success": true,
  "message": "成功修复并删除了2条损坏的重复记录",
  "data": {
    "fixed_count": 2,
    "total_broken": 2,
    "deleted_records": [
      {
        "id": 1,
        "duplicate_reason": "姓名相同但手机号码不同：洪松，新手机号：+86 ...",
        "processing_status": "processed",
        "created_at": "2025-06-10 11:35:35",
        "processed_at": "2025-06-10 16:18:53"
      }
    ]
  }
}
```

**无需修复**:

```json
{
  "code": 200,
  "success": true,
  "message": "没有发现需要修复的损坏记录",
  "data": {
    "fixed_count": 0,
    "total_broken": 0
  }
}
```

#### 状态码

| 状态码 | 说明   |
| --- | ---- |
| 200 | 修复成功 |
| 500 | 修复失败 |

#### 示例代码

```bash
curl -X POST \
  http://your-domain/api/data_parse/fix-broken-duplicate-records
```

```python
import requests

url = "http://your-domain/api/data_parse/fix-broken-duplicate-records"
response = requests.post(url)
print(response.json())
```

#### 注意事项

⚠️ **重要提醒**:
1. **不可逆操作**: 此操作会永久删除损坏的记录，无法恢复
2. **数据备份**: 建议在执行前备份 `duplicate_business_cards` 表
3. **系统维护**: 推荐在系统维护时间窗口内执行
4. **问题原因**: 通常由重复记录合并操作的外键约束处理不当引起
5. **预防措施**: 已在 `process_duplicate_record` 函数中修复了根本原因

---

## 🧪 测试数据

### 名片解析测试数据

```json
{
  "name_zh": "王经理",
  "name_en": "Manager Wang",
  "title_zh": "总经理",
  "title_en": "General Manager",
  "mobile": "13812345678",
  "phone": "021-88888888",
  "email": "wang.manager@hotelgroup.com",
  "hotel_zh": "上海国际大酒店",
  "hotel_en": "Shanghai International Hotel",
  "address_zh": "上海市黄浦区南京东路100号",
  "address_en": "100 Nanjing East Road, Huangpu District, Shanghai",
  "postal_code_zh": "200001",
  "postal_code_en": "200001",
  "brand_zh": "国际酒店集团",
  "brand_en": "International Hotel Group",
  "birthday": "1985-03-15",
  "residence": "上海市黄浦区南京西路88号",
  "brand_group": "希尔顿,万豪,洲际"
}
```

### 酒店职位测试数据

```json
{
  "department_zh": "客房部",
  "department_en": "Housekeeping",
  "position_zh": "客房部经理",
  "position_en": "Housekeeping Manager",
  "position_abbr": "HKM",
  "level_zh": "中层管理",
  "level_en": "Middle Management"
}
```

### 人才标签测试数据

```json
{
  "name": "奢华酒店经验",
  "category": "人才经验",
  "description": "具备奢华酒店运营管理经验，熟悉高端客户服务标准"
}
```

---

## 📝 注意事项

1. **认证**: 所有接口可能需要适当的认证头信息
2. **文件上传**: 图片文件建议大小不超过10MB，支持JPG、PNG格式
3. **编码**: 请求和响应均使用UTF-8编码
4. **时区**: 所有时间字段使用服务器本地时区
5. **错误处理**: 建议对所有API调用进行适当的错误处理
6. **数据删除**: 删除名片记录的操作不可逆，建议在删除前进行数据备份
7. **重复记录处理**: 处理重复记录时，`duplicate_id` 参数使用的是名片记录ID，而非重复记录表的主键ID

---

## 🔗 相关链接

- [API测试工具推荐](https://www.postman.com/)
- [cURL使用手册](https://curl.se/docs/manpage.html)
- [Python Requests库文档](https://docs.python-requests.org/)

---

*文档版本: v1.1*  
*最后更新: 2025年06月*