修改目录
This commit is contained in:
202
assets/api-docs/api/员工亲属关系导入API文档.md
Normal file
202
assets/api-docs/api/员工亲属关系导入API文档.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# 员工亲属关系导入 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**:
|
||||
|
||||
- 新增员工身份证号存在性校验
|
||||
- 优化导入性能，采用批量预验证方式
|
||||
Reference in New Issue
Block a user