ccdi/doc/api-docs/api/员工调动记录管理API文档.md

# 员工调动记录管理 API 文档

## 概述

员工调动记录管理模块提供员工调动信息的增删改查、批量导入导出功能。

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

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

**数据表**: `ccdi_staff_transfer`

**关联表**:
- `ccdi_base_staff` - 员工基础信息表(通过staff_id关联)
- `sys_dept` - 部门表(通过dept_id_before/after关联)

---

## API 接口列表

### 1. 查询调动记录列表

**接口地址**: `GET /ccdi/staffTransfer/list`

**权限要求**: `ccdi:staffTransfer:list`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| staffId | Long | 否 | 员工ID(精确查询) |
| staffName | String | 否 | 员工姓名(模糊查询) |
| transferType | String | 否 | 调动类型(精确查询) |
| deptIdBefore | Long | 否 | 调动前部门ID |
| deptIdAfter | Long | 否 | 调动后部门ID |
| transferDateStart | Date | 否 | 调动开始日期(yyyy-MM-dd) |
| transferDateEnd | Date | 否 | 调动结束日期(yyyy-MM-dd) |
| pageNum | Integer | 否 | 页码(默认1) |
| pageSize | Integer | 否 | 每页数量(默认10) |

**响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "staffId": 1000001,
      "staffName": "张三",
      "transferType": "PROMOTION",
      "transferTypeDesc": "升职",
      "transferSubType": "正常晋升",
      "deptIdBefore": 100,
      "deptNameBefore": "技术部",
      "gradeBefore": "P5",
      "positionBefore": "工程师",
      "salaryLevelBefore": "L1",
      "deptIdAfter": 101,
      "deptNameAfter": "研发部",
      "gradeAfter": "P6",
      "positionAfter": "高级工程师",
      "salaryLevelAfter": "L2",
      "transferDate": "2026-02-10",
      "createTime": "2026-02-10 10:00:00"
    }
  ],
  "total": 1
}
```

**响应字段说明**:

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | Long | 主键ID |
| staffId | Long | 员工ID |
| staffName | String | 员工姓名(关联查询) |
| transferType | String | 调动类型代码 |
| transferTypeDesc | String | 调动类型描述 |
| transferSubType | String | 调动子类型 |
| deptIdBefore | Long | 调动前部门ID |
| deptNameBefore | String | 调动前部门名称 |
| gradeBefore | String | 调动前职级 |
| positionBefore | String | 调动前岗位 |
| salaryLevelBefore | String | 调动前薪酬等级 |
| deptIdAfter | Long | 调动后部门ID |
| deptNameAfter | String | 调动后部门名称 |
| gradeAfter | String | 调动后职级 |
| positionAfter | String | 调动后岗位 |
| salaryLevelAfter | String | 调动后薪酬等级 |
| transferDate | Date | 调动日期 |
| createTime | Date | 创建时间 |

---

### 2. 查询调动记录详情

**接口地址**: `GET /ccdi/staffTransfer/{id}`

**权限要求**: `ccdi:staffTransfer:query`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 调动记录ID |

**响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": 1,
    "staffId": 1000001,
    "staffName": "张三",
    "transferType": "PROMOTION",
    "transferSubType": "正常晋升",
    "deptIdBefore": 100,
    "deptNameBefore": "技术部",
    "gradeBefore": "P5",
    "positionBefore": "工程师",
    "salaryLevelBefore": "L1",
    "deptIdAfter": 101,
    "deptNameAfter": "研发部",
    "gradeAfter": "P6",
    "positionAfter": "高级工程师",
    "salaryLevelAfter": "L2",
    "transferDate": "2026-02-10",
    "createdBy": "admin",
    "createTime": "2026-02-10 10:00:00",
    "updatedBy": "admin",
    "updateTime": "2026-02-10 10:00:00"
  }
}
```

---

### 3. 新增调动记录

**接口地址**: `POST /ccdi/staffTransfer`

**权限要求**: `ccdi:staffTransfer:add`

**请求体** (Content-Type: application/json):

```json
{
  "staffId": 1000001,
  "transferType": "PROMOTION",
  "transferSubType": "正常晋升",
  "deptIdBefore": 100,
  "deptNameBefore": "技术部",
  "gradeBefore": "P5",
  "positionBefore": "工程师",
  "salaryLevelBefore": "L1",
  "deptIdAfter": 101,
  "deptNameAfter": "研发部",
  "gradeAfter": "P6",
  "positionAfter": "高级工程师",
  "salaryLevelAfter": "L2",
  "transferDate": "2026-02-10"
}
```

**请求字段说明**:

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| staffId | Long | 是 | 员工ID |
| transferType | String | 是 | 调动类型 |
| transferSubType | String | 否 | 调动子类型 |
| deptIdBefore | Long | 否 | 调动前部门ID |
| deptNameBefore | String | 否 | 调动前部门名称 |
| gradeBefore | String | 否 | 调动前职级 |
| positionBefore | String | 否 | 调动前岗位 |
| salaryLevelBefore | String | 否 | 调动前薪酬等级 |
| deptIdAfter | Long | 否 | 调动后部门ID |
| deptNameAfter | String | 否 | 调动后部门名称 |
| gradeAfter | String | 否 | 调动后职级 |
| positionAfter | String | 否 | 调动后岗位 |
| salaryLevelAfter | String | 否 | 调动后薪酬等级 |
| transferDate | Date | 是 | 调动日期(yyyy-MM-dd) |

**响应示例**:
```json
{
  "code": 200,
  "msg": "新增成功"
}
```

---

### 4. 修改调动记录

**接口地址**: `PUT /ccdi/staffTransfer`

**权限要求**: `ccdi:staffTransfer:edit`

**请求体** (Content-Type: application/json):

```json
{
  "id": 1,
  "staffId": 1000001,
  "transferType": "PROMOTION",
  "transferSubType": "破格晋升",
  "deptIdAfter": 101,
  "deptNameAfter": "研发部",
  "gradeAfter": "P6",
  "positionAfter": "高级工程师",
  "salaryLevelAfter": "L2",
  "transferDate": "2026-02-10"
}
```

**请求字段说明**:

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 调动记录ID |
| 其他字段 | - | 否 | 同新增接口,所有字段均为可选 |

**响应示例**:
```json
{
  "code": 200,
  "msg": "修改成功"
}
```

---

### 5. 删除调动记录

**接口地址**: `DELETE /ccdi/staffTransfer/{ids}`

**权限要求**: `ccdi:staffTransfer:remove`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | String | 是 | 调动记录ID数组,逗号分隔(例: 1,2,3) |

**响应示例**:
```json
{
  "code": 200,
  "msg": "删除成功"
}
```

---

### 6. 导出调动记录

**接口地址**: `POST /ccdi/staffTransfer/export`

**权限要求**: `ccdi:staffTransfer:export`

**请求参数**: 同查询接口(支持按条件筛选导出)

**响应**: Excel文件(attachment)

---

### 7. 下载导入模板

**接口地址**: `POST /ccdi/staffTransfer/importTemplate`

**权限要求**: 无特殊要求

**响应**: Excel模板文件(带字典下拉框)

**模板字段说明**:

| 字段名 | 是否必填 | 说明 |
|--------|---------|------|
| 员工工号 | 是 | 员工ID |
| 调动类型 | 是 | 下拉选择字典 |
| 调动子类型 | 否 | 自由输入 |
| 调动前部门 | 否 | 自由输入 |
| 调动前职级 | 否 | 自由输入 |
| 调动前岗位 | 否 | 自由输入 |
| 调动前薪酬等级 | 否 | 自由输入 |
| 调动后部门 | 否 | 自由输入 |
| 调动后职级 | 否 | 自由输入 |
| 调动后岗位 | 否 | 自由输入 |
| 调动后薪酬等级 | 否 | 自由输入 |
| 调动日期 | 是 | 格式: yyyy-MM-dd |

---

### 8. 异步导入调动记录

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

**权限要求**: `ccdi:staffTransfer: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. 导入完成后查看失败记录(如有)

---

### 9. 查询导入状态

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

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

**路径参数**:

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

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

**状态说明**:

| 状态 | 说明 |
|------|------|
| PENDING | 等待处理 |
| PROCESSING | 处理中 |
| COMPLETED | 处理完成 |
| FAILED | 处理失败 |

---

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

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

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

**路径参数**:

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

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Integer | 否 | 页码(默认1) |
| pageSize | Integer | 否 | 每页数量(默认10) |

**响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "rowNum": 5,
      "staffId": "1000001",
      "transferType": "PROMOTION",
      "errorMsg": "员工ID不存在",
      "rawData": "原始数据..."
    }
  ],
  "total": 5
}
```

---

### 11. 获取员工列表(下拉选择)

**接口地址**: `GET /ccdi/staffTransfer/staffList`

**权限要求**: 无特殊要求

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | String | 否 | 员工姓名(模糊查询,用于下拉搜索) |

**响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "staffId": 1000001,
      "name": "张三",
      "deptId": 100,
      "deptName": "技术部"
    },
    {
      "staffId": 1000002,
      "name": "李四",
      "deptId": 101,
      "deptName": "研发部"
    }
  ]
}
```

---

## 数据字典

### 调动类型 (ccdi_transfer_type)

| 字典值 | 显示值 | CSS类 |
|--------|--------|-------|
| PROMOTION | 升职 | primary |
| DEMOPTION | 降职 | danger |
| LATERAL | 平调 | info |
| ROTATION | 轮岗 | warning |
| SECONDMENT | 借调 | default |
| DEPARTMENT_CHANGE | 部门调动 | success |
| POSITION_CHANGE | 职位调整 | primary |
| RETURN | 返岗 | info |
| TERMINATION | 离职 | danger |
| OTHER | 其他 | default |

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 401 | 未授权,请先登录 |
| 403 | 无权限访问 |
| 500 | 服务器内部错误 |

---

## 注意事项

1. **日期格式**: 所有日期字段使用 `yyyy-MM-dd` 格式
2. **分页**: 列表接口支持分页,默认每页10条
3. **权限**: 所有接口(除获取员工列表)都需要登录认证
4. **导入**: 导入功能采用异步处理,需轮询查询状态
5. **字典**: 调动类型字段使用字典管理,便于扩展
6. **关联查询**: 列表接口会自动关联查询员工姓名和部门名称
7. **审计字段**: 创建人、创建时间、更新人、更新时间由系统自动填充

---

## 更新日志

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-02-10 | 初始版本,完成基础CRUD和导入导出功能 |

---

## 联系方式

如有问题,请联系开发团队或提交Issue。