# 重复记录处理API文档

## 概述

本文档描述了DataOps平台中用于处理名片重复记录的API接口。当系统检测到新上传的名片可能与现有记录重复时，会创建重复记录条目供管理员处理。

## API接口列表

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

**接口地址**: `GET /api/data-parse/get-duplicate-records`

**查询参数**:
- `status` (可选): 筛选特定状态的记录
  - `pending`: 待处理
  - `processed`: 已处理
  - `ignored`: 已忽略

**请求示例**:
```bash
# 获取所有重复记录
GET /api/data-parse/get-duplicate-records

# 获取待处理的重复记录
GET /api/data-parse/get-duplicate-records?status=pending
```

**响应示例**:
```json
{
  "code": 200,
  "success": true,
  "message": "获取重复记录列表成功",
  "count": 2,
  "data": [
    {
      "id": 1,
      "main_card_id": 123,
      "suspected_duplicates": [
        {
          "id": 101,
          "name_zh": "张三",
          "mobile": "13812345678",
          "hotel_zh": "北京丽思卡尔顿酒店",
          "title_zh": "总监",
          "created_at": "2024-01-15 10:30:00"
        }
      ],
      "duplicate_reason": "姓名相同但手机号码不同：张三，新手机号：13987654321",
      "processing_status": "pending",
      "created_at": "2024-01-16 09:15:00",
      "main_card": {
        "id": 123,
        "name_zh": "张三",
        "mobile": "13987654321",
        "hotel_zh": "上海丽思卡尔顿酒店",
        "title_zh": "总经理",
        "image_path": "abc123def456.jpg"
      }
    }
  ]
}
```

### 2. 处理重复记录

**接口地址**: `POST /api/data-parse/process-duplicate-record/<duplicate_id>`

**路径参数**:
- `duplicate_id`: 重复记录ID

**请求参数**:
```json
{
  "action": "merge_to_suspected|keep_main|ignore",
  "selected_duplicate_id": 101,  // 当action为merge_to_suspected时必填
  "processed_by": "admin",       // 可选
  "notes": "确认为同一人，合并记录"  // 可选
}
```

**处理动作说明**:
- `merge_to_suspected`: 合并到选中的疑似重复记录，删除主记录
- `keep_main`: 保留主记录，标记为已处理
- `ignore`: 忽略重复提醒，标记为已处理

**请求示例**:
```bash
POST /api/data-parse/process-duplicate-record/1
Content-Type: application/json

{
  "action": "merge_to_suspected",
  "selected_duplicate_id": 101,
  "processed_by": "admin",
  "notes": "确认为同一人，职位有升职，合并到原记录"
}
```

**响应示例**:
```json
{
  "code": 200,
  "success": true,
  "message": "重复记录处理成功，操作: merge_to_suspected",
  "data": {
    "duplicate_record": {
      "id": 1,
      "processing_status": "processed",
      "processed_at": "2024-01-16 14:30:00",
      "processed_by": "admin",
      "processing_notes": "确认为同一人，职位有升职，合并到原记录"
    },
    "result": {
      "id": 101,
      "name_zh": "张三",
      "mobile": "13987654321",
      "hotel_zh": "上海丽思卡尔顿酒店",
      "title_zh": "总经理",
      "image_path": "abc123def456.jpg",
      "career_path": [
        {
          "date": "2024-01-15",
          "hotel_zh": "北京丽思卡尔顿酒店",
          "title_zh": "总监",
          "image_path": "old123image456.jpg",
          "source": "business_card_creation"
        },
        {
          "date": "2024-01-16",
          "hotel_zh": "上海丽思卡尔顿酒店",
          "title_zh": "总经理",
          "image_path": "abc123def456.jpg",
          "source": "business_card_update"
        }
      ]
    }
  }
}
```

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

**接口地址**: `GET /api/data-parse/get-duplicate-record-detail/<duplicate_id>`

**路径参数**:
- `duplicate_id`: 重复记录ID

**请求示例**:
```bash
GET /api/data-parse/get-duplicate-record-detail/1
```

**响应示例**:
```json
{
  "code": 200,
  "success": true,
  "message": "获取重复记录详情成功",
  "data": {
    "id": 1,
    "main_card_id": 123,
    "suspected_duplicates": [
      {
        "id": 101,
        "name_zh": "张三",
        "name_en": "John Zhang",
        "mobile": "13812345678",
        "hotel_zh": "北京丽思卡尔顿酒店",
        "hotel_en": "The Ritz-Carlton Beijing",
        "title_zh": "总监",
        "title_en": "Director",
        "created_at": "2024-01-15 10:30:00"
      }
    ],
    "duplicate_reason": "姓名相同但手机号码不同：张三，新手机号：13987654321",
    "processing_status": "pending",
    "created_at": "2024-01-16 09:15:00",
    "main_card": {
      "id": 123,
      "name_zh": "张三",
      "name_en": "John Zhang",
      "mobile": "13987654321",
      "hotel_zh": "上海丽思卡尔顿酒店",
      "hotel_en": "The Ritz-Carlton Shanghai",
      "title_zh": "总经理",
      "title_en": "General Manager",
      "image_path": "abc123def456.jpg",
      "career_path": [
        {
          "date": "2024-01-16",
          "hotel_zh": "上海丽思卡尔顿酒店",
          "hotel_en": "The Ritz-Carlton Shanghai",
          "title_zh": "总经理",
          "title_en": "General Manager",
          "image_path": "abc123def456.jpg",
          "source": "business_card_creation"
        }
      ]
    }
  }
}
```

## 业务流程

### 1. 重复记录检测流程

```mermaid
graph TD
    A[上传新名片] --> B[AI解析名片信息]
    B --> C[检查重复记录]
    C --> D{是否发现重复?}
    D -->|否| E[创建新记录]
    D -->|是| F{姓名和手机号都相同?}
    F -->|是| G[自动更新现有记录]
    F -->|否| H[创建主记录 + 重复记录条目]
    H --> I[等待管理员处理]
```

### 2. 重复记录处理流程

```mermaid
graph TD
    A[管理员查看重复记录] --> B[选择处理方式]
    B --> C{处理动作}
    C -->|merge_to_suspected| D[合并到疑似重复记录]
    C -->|keep_main| E[保留主记录]
    C -->|ignore| F[忽略重复提醒]
    D --> G[更新目标记录信息]
    G --> H[添加职业轨迹条目]
    H --> I[删除主记录]
    E --> J[标记为已处理]
    F --> J
    I --> K[完成处理]
    J --> K
```

## 错误码说明

| HTTP状态码 | 错误码 | 说明 |
|-----------|--------|------|
| 200 | 200 | 操作成功 |
| 400 | 400 | 请求参数错误 |
| 404 | 404 | 记录不存在 |
| 500 | 500 | 服务器内部错误 |

## 注意事项

1. **权限控制**: 重复记录处理操作建议仅对管理员开放
2. **数据一致性**: 合并操作会删除主记录，请确保操作前数据备份
3. **图片路径**: 合并后的记录会使用最新的名片图片路径
4. **职业轨迹**: 合并操作会自动更新职业轨迹，包含对应的图片路径
5. **处理状态**: 一旦处理状态改为`processed`，记录不能再次处理

## 使用建议

1. **定期检查**: 建议定期查看待处理的重复记录
2. **谨慎合并**: 合并操作不可逆，请仔细核对信息再操作
3. **添加备注**: 建议在处理时添加详细的处理备注便于追溯
4. **批量处理**: 可以通过脚本批量处理大量重复记录