# 员工信息管理 API 文档

## 概述

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

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

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

**重要更新**: 自2026-02-05起,员工ID(employeeId)作为柜员号使用,为7位数字,手动输入,唯一不可重复。

---

## API 接口列表

### 1. 查询员工列表

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

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

**请求参数**:

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

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "employeeId": 1000001,
      "name": "张三",
      "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(柜员号,7位数字)        |
| name       | 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}`

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

**路径参数**:

| 参数名        | 类型   | 必填 | 说明        |
|------------|------|----|-----------|
| employeeId | Long | 是  | 员工ID(柜员号) |

**响应示例**:

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "employeeId": 1000001,
    "name": "张三",
    "deptId": 100,
    "idCard": "110101199001011234",
    "phone": "13800138000",
    "hireDate": "2020-01-01",
    "status": "0",
    "statusDesc": "在职",
    "createTime": "2026-01-28 10:00:00"
  }
}
```

---

### 3. 新增员工

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

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

**请求头**:

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

**请求体**:

```json
{
  "employeeId": 1000001,
  "name": "张三",
  "deptId": 100,
  "idCard": "110101199001011234",
  "phone": "13800138000",
  "hireDate": "2020-01-01",
  "status": "0"
}
```

**字段说明**:

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

**响应示例**:

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

---

### 4. 编辑员工

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

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

**请求体**:

```json
{
  "employeeId": 1000001,
  "name": "张三",
  "deptId": 100,
  "idCard": "110101199001011234",
  "phone": "13800138000",
  "hireDate": "2020-01-01",
  "status": "0"
}
```

**字段说明**: 与新增接口相同,employeeId 为必填项,编辑时不可修改柜员号。

**响应示例**:

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

---

### 5. 删除员工

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

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

**路径参数**:

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

**响应示例**:

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

---

### 6. 导出员工信息

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

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

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

**响应**: Excel 文件下载

---

### 7. 下载导入模板(带字典下拉框)

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

**权限要求**: 无

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

**响应**: Excel 模板文件下载

**Excel 格式说明**:

**Sheet1: 员工信息**
| 姓名* | 柜员号* | 所属部门ID* | 身份证号* | 电话* | 入职时间 | 状态▼* |
|------|--------|------------|----------|------|----------|------|
| 张三 | 1000001 | 100 | 110101199001011234 | 13800138000 | 2020-01-01 | 在职 |

**注**:

- 带 * 标记的列为必填项(姓名、柜员号、所属部门、身份证号、电话、状态)
- 带 ▼ 标记的列包含下拉框,选项来自字典 `ccdi_employee_status`

**使用 @DictDropdown 注解实现**:

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

---

### 8. 导入员工信息

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

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

**请求参数**:

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

**Excel 格式**:

**Sheet1: 员工信息**
| 姓名* | 柜员号* | 所属部门ID* | 身份证号* | 电话* | 入职时间 | 状态* |
|------|--------|------------|----------|------|----------|------|
| 张三 | 1000001 | 100 | 110101199001011234 | 13800138000 | 2020-01-01 | 在职 |

**说明**:

- ***标记为必填项**: 姓名、柜员号、所属部门、身份证号、电话、状态**
- 柜员号: 7位数字,必填,唯一
- 所属部门: 必须填写有效的部门ID
- 电话: 必须填写11位手机号
- 入职时间: 选填,格式为 yyyy-MM-dd

**响应示例**:

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

---

## 错误码说明

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

## 业务错误信息

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

---

## 测试账号

- 用户名: `admin`
- 密码: `admin123`

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