349 lines
7.9 KiB
Markdown
349 lines
7.9 KiB
Markdown
# 员工信息管理 API 文档
|
||
|
||
## 概述
|
||
|
||
员工信息管理模块提供员工及其亲属信息的增删改查、批量导入导出功能。
|
||
|
||
**基础路径**: `/dpc/employee`
|
||
|
||
**权限标识前缀**: `dpc:employee`
|
||
|
||
---
|
||
|
||
## API 接口列表
|
||
|
||
### 1. 查询员工列表
|
||
|
||
**接口地址**: `GET /dpc/employee/list`
|
||
|
||
**权限要求**: `dpc:employee:list`
|
||
|
||
**请求参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| name | String | 否 | 姓名（模糊查询） |
|
||
| tellerNo | String | 否 | 柜员号（精确查询） |
|
||
| deptId | Long | 否 | 所属部门ID |
|
||
| idCard | String | 否 | 身份证号（精确查询） |
|
||
| status | String | 否 | 状态（0=在职, 1=离职） |
|
||
| pageNum | Integer | 否 | 页码（默认1） |
|
||
| pageSize | Integer | 否 | 每页数量（默认10） |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"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 /dpc/employee/{employeeId}`
|
||
|
||
**权限要求**: `dpc:employee:query`
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| employeeId | Long | 是 | 员工ID |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"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 /dpc/employee`
|
||
|
||
**权限要求**: `dpc:employee:add`
|
||
|
||
**请求头**:
|
||
```
|
||
Content-Type: application/json
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"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 | 是 | 与员工关系 |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 编辑员工
|
||
|
||
**接口地址**: `PUT /dpc/employee`
|
||
|
||
**权限要求**: `dpc:employee:edit`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"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 为必填项。
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 删除员工
|
||
|
||
**接口地址**: `DELETE /dpc/employee/{employeeIds}`
|
||
|
||
**权限要求**: `dpc:employee:remove`
|
||
|
||
**路径参数**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| employeeIds | Long[] | 是 | 员工ID数组（逗号分隔） |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
**注意**: 删除员工时会级联删除该员工的所有亲属信息。
|
||
|
||
---
|
||
|
||
### 6. 导出员工信息
|
||
|
||
**接口地址**: `POST /dpc/employee/export`
|
||
|
||
**权限要求**: `dpc:employee:export`
|
||
|
||
**请求参数**: 与查询列表接口相同（支持筛选条件）
|
||
|
||
**响应**: Excel 文件下载
|
||
|
||
---
|
||
|
||
### 7. 下载导入模板（带字典下拉框）
|
||
|
||
**接口地址**: `POST /dpc/employee/importTemplate`
|
||
|
||
**权限要求**: 无
|
||
|
||
**功能说明**: 下载的 Excel 模板中，"状态"列会自动添加字典下拉框，方便用户选择。
|
||
|
||
**响应**: Excel 模板文件下载
|
||
|
||
**Excel 格式说明**:
|
||
|
||
**Sheet1: 员工信息**
|
||
| 姓名 | 柜员号 | 所属部门ID | 身份证号 | 电话 | 入职时间 | 状态▼ |
|
||
|------|--------|------------|----------|------|----------|------|
|
||
| 张三 | 001 | 100 | 110101199001011234 | 13800138000 | 2020-01-01 | 在职 |
|
||
|
||
**注**：带 ▼ 标记的列包含下拉框，选项来自字典 `dpc_employee_status`。
|
||
|
||
**使用 @DictDropdown 注解实现**:
|
||
- 状态字段使用 `@DictDropdown(dictType = "dpc_employee_status")` 注解
|
||
- 系统自动从 Redis 缓存读取字典数据并生成下拉框
|
||
- 下拉选项可动态更新，刷新字典缓存后生效
|
||
|
||
---
|
||
|
||
### 8. 导入员工信息
|
||
|
||
**接口地址**: `POST /dpc/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 | 配偶 |
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "恭喜您，数据已全部导入成功！共 10 条"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 操作成功 |
|
||
| 401 | 未授权，请先登录 |
|
||
| 403 | 无权限访问 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
## 业务错误信息
|
||
|
||
| 错误信息 | 说明 |
|
||
|----------|------|
|
||
| 该柜员号已存在 | 新增/编辑时柜员号重复 |
|
||
| 该身份证号已存在 | 新增/编辑时身份证号重复 |
|
||
| 姓名不能为空 | 新增时姓名为空 |
|
||
| 身份证号格式不正确 | 身份证号不符合18位国标 |
|
||
| 电话格式不正确 | 手机号不符合11位格式 |
|
||
| 状态只能填写'在职'或'离职' | 状态值不正确 |
|
||
|
||
---
|
||
|
||
## 测试账号
|
||
|
||
- 用户名: `admin`
|
||
- 密码: `admin123`
|
||
|
||
测试前请先调用 `/login/test` 接口获取 Token。
|