ccdi/doc/api/员工信息管理API文档.md

员工信息管理 API 文档

概述

员工信息管理模块提供员工及其亲属信息的增删改查、批量导入导出功能。

基础路径: /ccdi/employee

权限标识前缀: dpc:employee

---

API 接口列表

1. 查询员工列表

接口地址: GET /ccdi/employee/list

权限要求: dpc:employee:list

请求参数:

参数名	类型	必填	说明
name	String	否	姓名（模糊查询）
tellerNo	String	否	柜员号（精确查询）
deptId	Long	否	所属部门ID
idCard	String	否	身份证号（精确查询）
status	String	否	状态（0=在职, 1=离职）
pageNum	Integer	否	页码（默认1）
pageSize	Integer	否	每页数量（默认10）

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "employeeId": 1,
      "name": "张三",
      "tellerNo": "001",
      "deptId": 100,
      "deptName": "总部",
      "idCard": "110101199001011234",
      "phone": "13800138000",
      "hireDate": "2020-01-01",
      "status": "0",
      "statusDesc": "在职",
      "createTime": "2026-01-28 10:00:00"
    }
  ],
  "total": 1
}

响应字段说明:

字段名	类型	说明
employeeId	Long	员工ID
name	String	姓名
tellerNo	String	柜员号
deptId	Long	所属部门ID
deptName	String	所属部门名称（关联 sys_dept 表）
idCard	String	身份证号
phone	String	电话
hireDate	Date	入职时间
status	String	状态（0=在职, 1=离职）
statusDesc	String	状态描述
createTime	Date	创建时间

---

2. 查询员工详情

接口地址: GET /ccdi/employee/{employeeId}

权限要求: dpc:employee:query

路径参数:

参数名	类型	必填	说明
employeeId	Long	是	员工ID

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "employeeId": 1,
    "name": "张三",
    "tellerNo": "001",
    "deptId": 100,
    "idCard": "110101199001011234",
    "phone": "13800138000",
    "hireDate": "2020-01-01",
    "status": "0",
    "statusDesc": "在职",
    "createTime": "2026-01-28 10:00:00",
    "relatives": [
      {
        "relativeId": 1,
        "employeeId": 1,
        "relativeName": "李四",
        "relativeIdCard": "110101199001011235",
        "relativePhone": "13800138001",
        "relationship": "配偶"
      }
    ]
  }
}

---

3. 新增员工

接口地址: POST /ccdi/employee

权限要求: dpc:employee:add

请求头:

Content-Type: application/json
Authorization: Bearer {token}

请求体:

{
  "name": "张三",
  "tellerNo": "001",
  "deptId": 100,
  "idCard": "110101199001011234",
  "phone": "13800138000",
  "hireDate": "2020-01-01",
  "status": "0",
  "relatives": [
    {
      "relativeName": "李四",
      "relativeIdCard": "110101199001011235",
      "relativePhone": "13800138001",
      "relationship": "配偶"
    }
  ]
}

字段说明:

字段名	类型	必填	说明	校验规则
name	String	是	姓名	最大100字符
tellerNo	String	是	柜员号	最大50字符，唯一
deptId	Long	否	所属部门ID
idCard	String	是	身份证号	18位，符合国标，唯一
phone	String	否	电话	11位手机号
hireDate	Date	否	入职时间	yyyy-MM-dd
status	String	是	状态	0=在职, 1=离职
relatives	Array	否	亲属列表

亲属对象字段:

字段名	类型	必填	说明
relativeName	String	是	亲属姓名
relativeIdCard	String	否	亲属身份证号
relativePhone	String	否	亲属手机号
relationship	String	是	与员工关系

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

---

4. 编辑员工

接口地址: PUT /ccdi/employee

权限要求: dpc:employee:edit

请求体:

{
  "employeeId": 1,
  "name": "张三",
  "tellerNo": "001",
  "deptId": 100,
  "idCard": "110101199001011234",
  "phone": "13800138000",
  "hireDate": "2020-01-01",
  "status": "0",
  "relatives": [
    {
      "relativeName": "李四",
      "relativeIdCard": "110101199001011235",
      "relativePhone": "13800138001",
      "relationship": "配偶"
    }
  ]
}

字段说明: 与新增接口相同，employeeId 为必填项。

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

---

5. 删除员工

接口地址: DELETE /ccdi/employee/{employeeIds}

权限要求: dpc:employee:remove

路径参数:

参数名	类型	必填	说明
employeeIds	Long[]	是	员工ID数组（逗号分隔）

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

注意: 删除员工时会级联删除该员工的所有亲属信息。

---

6. 导出员工信息

接口地址: POST /ccdi/employee/export

权限要求: dpc:employee:export

请求参数: 与查询列表接口相同（支持筛选条件）

响应: Excel 文件下载

---

7. 下载导入模板（带字典下拉框）

接口地址: POST /ccdi/employee/importTemplate

权限要求: 无

功能说明: 下载的 Excel 模板中，"状态"列会自动添加字典下拉框，方便用户选择。

响应: Excel 模板文件下载

Excel 格式说明:

Sheet1: 员工信息

姓名	柜员号	所属部门ID	身份证号	电话	入职时间	状态▼
张三	001	100	110101199001011234	13800138000	2020-01-01	在职

注：带 ▼ 标记的列包含下拉框，选项来自字典 ccdi_employee_status。

使用 @DictDropdown 注解实现:

• 状态字段使用 @DictDropdown(dictType = "ccdi_employee_status") 注解
• 系统自动从 Redis 缓存读取字典数据并生成下拉框
• 下拉选项可动态更新，刷新字典缓存后生效

---

8. 导入员工信息

接口地址: POST /ccdi/employee/importData

权限要求: dpc:employee:import

请求参数:

参数名	类型	必填	说明
file	File	是	Excel 文件
updateSupport	Boolean	否	是否更新已存在数据（默认false）

Excel 格式:

Sheet1: 员工信息

姓名	柜员号	所属部门ID	身份证号	电话	入职时间	状态
张三	001	100	110101199001011234	13800138000	2020-01-01	在职

Sheet2: 亲属信息（可选）

员工身份证号	亲属姓名	亲属身份证号	亲属手机号	与员工关系
110101199001011234	李四	110101199001011235	13800138001	配偶

响应示例:

{
  "code": 200,
  "msg": "恭喜您，数据已全部导入成功！共 10 条"
}

---

错误码说明

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

业务错误信息

错误信息	说明
该柜员号已存在	新增/编辑时柜员号重复
该身份证号已存在	新增/编辑时身份证号重复
姓名不能为空	新增时姓名为空
身份证号格式不正确	身份证号不符合18位国标
电话格式不正确	手机号不符合11位格式
状态只能填写'在职'或'离职'	状态值不正确

---

测试账号

• 用户名: admin
• 密码: admin123

测试前请先调用 /login/test 接口获取 Token。