DataOps-platform/API_DOCUMENTATION_DUPLICATE_RECORDS.md

重复记录处理API文档

概述

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

API接口列表

1. 获取重复记录列表

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

查询参数:

• status (可选): 筛选特定状态的记录
  • pending: 待处理
  • processed: 已处理
  • ignored: 已忽略

请求示例:

# 获取所有重复记录
GET /api/data-parse/get-duplicate-records

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

响应示例:

{
  "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

请求参数:

{
  "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: 忽略重复提醒，标记为已处理

请求示例:

POST /api/data-parse/process-duplicate-record/1
Content-Type: application/json

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

响应示例:

{
  "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

请求示例:

GET /api/data-parse/get-duplicate-record-detail/1

响应示例:

{
  "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. 重复记录检测流程

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

2. 重复记录处理流程

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. 批量处理: 可以通过脚本批量处理大量重复记录