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)

响应示例:

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

响应示例:

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

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

响应示例:

{
  "code": 200,
  "msg": "新增成功"
}

---

4. 修改调动记录

接口地址: PUT /ccdi/staffTransfer

权限要求: ccdi:staffTransfer:edit

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

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

请求字段说明:

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

响应示例:

{
  "code": 200,
  "msg": "修改成功"
}

---

5. 删除调动记录

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

权限要求: ccdi:staffTransfer:remove

路径参数:

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

响应示例:

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

响应示例:

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

导入流程:

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

导入验证规则:

导入时会验证以下字段：

字段名	验证规则	错误提示
员工ID	必须在员工信息表(ccdi_base_staff)中存在	"第N行: 员工ID XXX 不存在"
调动前部门ID	必须在部门表(sys_dept)中存在	"第N行: 调动前部门ID XXX 不存在"
调动后部门ID	必须在部门表(sys_dept)中存在	"第N行: 调动后部门ID XXX 不存在"
调动日期	必须符合yyyy-MM-dd格式	"第N行: 调动日期格式不正确"

性能优化:

• 采用批量预验证方式，仅1次数据库查询员工ID存在性
• 从2次遍历优化为1次遍历，提升导入性能

---

9. 查询导入状态

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

权限要求: ccdi:staffTransfer:import

路径参数:

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

响应示例:

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

响应示例:

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

---

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

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

权限要求: 无特殊要求

请求参数:

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

响应示例:

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