# 员工信息管理 API 文档

## 概述

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

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

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

---

## API 接口列表

### 1. 查询员工列表

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

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

**请求参数**:

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

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "employeeId": 1,
      "name": "张三",
      "tellerNo": "001",
      "orgNo": "1001",
      "idCard": "110101199001011234",
      "phone": "13800138000",
      "hireDate": "2020-01-01",
      "status": "0",
      "statusDesc": "在职",
      "createTime": "2026-01-28 10:00:00"
    }
  ],
  "total": 1
}
```

---

### 2. 查询员工详情

**接口地址**: `GET /dpc/employee/{employeeId}`

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

**路径参数**:

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

**响应示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "employeeId": 1,
    "name": "张三",
    "tellerNo": "001",
    "orgNo": "1001",
    "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",
  "orgNo": "1001",
  "idCard": "110101199001011234",
  "phone": "13800138000",
  "hireDate": "2020-01-01",
  "status": "0",
  "relatives": [
    {
      "relativeName": "李四",
      "relativeIdCard": "110101199001011235",
      "relativePhone": "13800138001",
      "relationship": "配偶"
    }
  ]
}
```

**字段说明**:

| 字段名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| name | String | 是 | 姓名 | 最大100字符 |
| tellerNo | String | 是 | 柜员号 | 最大50字符，唯一 |
| orgNo | String | 否 | 所属机构号 | 最大50字符 |
| 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",
  "orgNo": "1001",
  "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 模板文件下载

---

### 8. 导入员工信息

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

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

**请求参数**:

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

**Excel 格式**:

**Sheet1: 员工信息**
| 姓名 | 柜员号 | 所属机构号 | 身份证号 | 电话 | 入职时间 | 状态 |
|------|--------|------------|----------|------|----------|------|
| 张三 | 001 | 1001 | 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。
