# 员工亲属关系导入 API 文档

## 概述

员工亲属关系导入模块提供员工亲属关系的批量导入功能。

**基础路径**: `/ccdi/staffFmyRelation`

**权限标识前缀**: `ccdi:staffFmyRelation`

**数据表**: `ccdi_cust_fmy_relation`

**关联表**:

- `ccdi_base_staff` - 员工基础信息表(通过id_card关联)

---

## API 接口

### 1. 异步导入员工亲属关系

**接口地址**: `POST /ccdi/staffFmyRelation/importData`

**权限要求**: `ccdi:staffFmyRelation:import`

**请求参数**: FormData

| 参数名           | 类型      | 必填 | 说明                  |
|---------------|---------|----|---------------------|
| file          | File    | 是  | Excel文件             |
| updateSupport | Boolean | 否  | 是否更新已存在的记录(默认false) |

**响应示例**:

```json
{
  "code": 200,
  "msg": "导入任务已提交,正在后台处理",
  "data": {
    "taskId": "abc123-def456-ghi789",
    "status": "PROCESSING",
    "message": "导入任务已提交,正在后台处理"
  }
}
```

**导入流程**:

1. 上传Excel文件
2. 后台立即返回taskId
3. 使用taskId轮询查询导入状态
4. 导入完成后查看失败记录(如有)

**导入验证规则**:

导入时会验证以下字段：

| 字段名     | 验证规则                             | 错误提示                                |
|---------|----------------------------------|-------------------------------------|
| 员工身份证号  | 必须在员工信息表(ccdi_base_staff)中存在     | "第N行: 身份证号[XXX]不存在于员工信息表中，请先添加员工信息" |
| 关系类型    | 不能为空，必须在字典中存在                    | "第N行: 关系类型不能为空"                     |
| 关系人姓名   | 不能为空                             | "第N行: 关系人姓名不能为空"                    |
| 关系人证件类型 | 不能为空                             | "第N行: 关系人证件类型不能为空"                  |
| 关系人证件号码 | 不能为空                             | "第N行: 关系人证件号码不能为空"                  |
| 手机号码1   | 如果填写，必须为有效手机号                    | "第N行: 手机号码1格式不正确"                   |
| 手机号码2   | 如果填写，必须为有效手机号                    | "第N行: 手机号码2格式不正确"                   |
| 性别      | 如果填写，必须是"男"、"女"、"其他"或"M"、"F"、"O" | "第N行: 性别只能是：男、女、其他 或 M、F、O"         |

**性能优化**:

- 采用批量预验证方式，仅1次数据库查询身份证号存在性
- 批量查询已存在的身份证号+关系人证件号码组合，避免重复导入

---

### 2. 查询导入状态

**接口地址**: `GET /ccdi/staffFmyRelation/importStatus/{taskId}`

**权限要求**: `ccdi:staffFmyRelation:import`

**路径参数**:

| 参数名    | 类型     | 必填 | 说明     |
|--------|--------|----|--------|
| taskId | String | 是  | 导入任务ID |

**响应示例**:

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "taskId": "abc123-def456-ghi789",
    "status": "COMPLETED",
    "total": 100,
    "successCount": 95,
    "failureCount": 5,
    "message": "导入完成"
  }
}
```

**状态说明**:

| 状态              | 说明   |
|-----------------|------|
| PENDING         | 等待处理 |
| PROCESSING      | 处理中  |
| SUCCESS         | 全部成功 |
| PARTIAL_SUCCESS | 部分成功 |
| FAILED          | 处理失败 |

---

### 3. 查询导入失败记录

**接口地址**: `GET /ccdi/staffFmyRelation/importFailures/{taskId}`

**权限要求**: `ccdi:staffFmyRelation:import`

**路径参数**:

| 参数名    | 类型     | 必填 | 说明     |
|--------|--------|----|--------|
| taskId | String | 是  | 导入任务ID |

**响应示例**:

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "personId": "999999999999999999",
      "relationType": "父亲",
      "relationName": "张三",
      "relationCertType": "身份证",
      "relationCertNo": "110101195501017890",
      "errorMessage": "第2行: 身份证号[999999999999999999]不存在于员工信息表中，请先添加员工信息",
      "rowNumber": 2
    }
  ]
}
```

**失败记录字段说明**:

| 字段名              | 类型      | 说明      |
|------------------|---------|---------|
| personId         | String  | 员工身份证号  |
| relationType     | String  | 关系类型    |
| relationName     | String  | 关系人姓名   |
| relationCertType | String  | 关系人证件类型 |
| relationCertNo   | String  | 关系人证件号码 |
| errorMessage     | String  | 错误信息    |
| rowNumber        | Integer | Excel行号 |

---

## Excel 模板字段说明

| 字段名     | 是否必填 | 说明          |
|---------|------|-------------|
| 员工身份证号  | 是    | 必须在员工信息表中存在 |
| 关系类型    | 是    | 下拉选择字典      |
| 关系人姓名   | 是    | 不能为空        |
| 性别      | 否    | 下拉选择字典      |
| 出生日期    | 否    | 日期格式        |
| 关系人证件类型 | 是    | 下拉选择字典      |
| 关系人证件号码 | 是    | 不能为空        |
| 手机号码1   | 否    | 手机号格式       |
| 手机号码2   | 否    | 手机号格式       |
| 微信名称1-3 | 否    | 自由输入        |
| 详细联系地址  | 否    | 自由输入        |
| 关系详细描述  | 否    | 自由输入        |
| 生效日期    | 否    | 日期格式        |
| 失效日期    | 否    | 日期格式        |
| 备注      | 否    | 自由输入        |

---

## 错误码说明

| 错误码 | 说明    |
|-----|-------|
| 200 | 操作成功  |
| 401 | 未授权   |
| 403 | 无权限   |
| 500 | 服务器错误 |

---

## 更新日志

**2026-02-11**:

- 新增员工身份证号存在性校验
- 优化导入性能，采用批量预验证方式