# 员工信息导入 - 前端联调方案

## 涉及页面

- 人力资源 > 员工管理 列表页（`src/views/hrm/employee/index.vue`）
- 员工新增/编辑弹窗（`src/views/hrm/employee/modules/form.vue`、`src/views/hrm/employee/data.ts`）
- 员工详情（`src/views/hrm/employee/modules/detail.vue`）
- 新增：员工导入弹窗（含下载模板、上传文件、展示导入结果）

## 业务流程与数据带入

1. **下载模板** -> 前端调用 `GET /hrm/employee/import-template` 下载 Excel 模板，模板包含示例行供参考。
2. **填写模板** -> 用户按模板填写员工信息，其中"部门名称/岗位名称/用户角色"三列填**名称**（用户角色多个用中文逗号分隔），由后端自动转换为 ID。
3. **上传导入** -> 前端调用 `POST /hrm/employee/import`（multipart 表单，file + updateSupport）上传文件。
4. **展示结果** -> 后端返回导入结果（创建成功名单 / 更新成功名单 / 失败名单及原因），前端逐条展示。

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/hrm/employee/import-template` | 下载员工导入模板（含示例数据） |
| POST | `/hrm/employee/import` | 导入员工 Excel |

### 下载模板

**响应：** Excel 文件（`员工导入模板.xls`），表头如下：

| 员工姓名 | 性别 | 手机号 | 部门名称 | 岗位名称 | 用户角色 | 入职日期 | 员工状态 | 身份证号 | 出生日期 | 民族 | 婚姻状态 | 年龄 | 学历 | 政治面貌 | 邮箱 | 备注 |
|---------|------|--------|---------|---------|---------|---------|---------|---------|---------|------|---------|------|------|---------|------|------|

- 性别：填"男"/"女"（字典 `hrm_gender`，值 1/2）
- 员工状态：填"在职"/"试用"/"离职"（字典 `hrm_employee_status`，值 1/2/3）
- 用户角色：填角色名称，多个用**中文逗号**分隔（如"普通管理员,普通员工"）

### 导入员工

**请求参数（multipart/form-data）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | MultipartFile | 是 | 上传的 Excel 文件 |
| updateSupport | Boolean | 否 | 是否支持更新，默认 false。为 true 时手机号已存在的员工会被更新，否则记为失败 |

**响应：**

```json
{
  "code": 0,
  "data": {
    "createNames": ["张三", "李四"],
    "updateNames": ["王五"],
    "failureNames": {
      "赵六": "手机号已存在，请更换手机号",
      "孙七": "部门【不存在的部门】不存在"
    }
  }
}
```

**响应字段：**

| 字段 | 类型 | 说明 |
|------|------|------|
| createNames | List\<String\> | 创建成功的员工姓名数组 |
| updateNames | List\<String\> | 更新成功的员工姓名数组 |
| failureNames | Map\<String, String\> | 导入失败集合，key 为员工姓名，value 为失败原因 |

## 字段展示规则

### 导入模板（新增字段）

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 员工姓名 | 模板列 | 必填 |
| 性别 | 模板列 | 必填，默认男 |
| 手机号 | 模板列 | 必填，将作为系统登录账号 |
| 部门名称 | 模板列 | 必填，填名称，后端转 ID |
| 岗位名称 | 模板列 | 必填，填名称，后端转 ID |
| 用户角色 | 模板列 | 选填，填名称，多个用中文逗号分隔 |
| 入职日期 | 模板列 | 必填，格式 YYYY-MM-DD |
| 员工状态 | 模板列 | 必填，默认在职 |
| 身份证号 | 模板列 | 选填 |
| 出生日期 | 模板列 | 选填，格式 YYYY-MM-DD |
| 民族 | 模板列 | 选填，文本（如"汉族"） |
| 婚姻状态 | 模板列 | 选填，文本（如"已婚"） |
| 年龄 | 模板列 | 选填，数字 |
| 学历 | 模板列 | 选填，文本（如"本科"） |
| 政治面貌 | 模板列 | 选填，文本（如"中共党员"） |
| 邮箱 | 模板列 | 选填 |
| 备注 | 模板列 | 选填 |

### 新增/编辑表单（新增字段）

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 民族 | 表单 | 文本输入框 |
| 婚姻状态 | 表单 | 文本输入框 |
| 年龄 | 表单 | 数字输入框 |
| 学历 | 表单 | 文本输入框 |
| 政治面貌 | 表单 | 文本输入框 |

### 列表 / 详情 / 导出

- 新增字段为纯文本，无需字典转码，可直接展示
- 导出 Excel（`GET /hrm/employee/export-excel`）已包含上述字段列

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 手机号已存在且 updateSupport=false | 该行导入失败，原因"手机号已存在，请更换手机号" |
| 手机号已存在且 updateSupport=true | 更新该员工信息（含新增字段） |
| 部门名称 / 岗位名称填错或不存在 | 该行导入失败，原因"部门【xx】不存在" / "岗位【xx】不存在" |
| 用户角色名称填错或不存在 | 该行导入失败，原因"角色【xx】不存在" |
| 员工姓名、手机号、入职日期为空 | 该行导入失败，原因"导入字段【xx】不能为空" |
| 性别、员工状态为空 | 默认按男 / 在职处理 |
| 导入时员工编号 | 由系统自动生成，无需在模板中填写 |

## 注意事项

- 导入接口权限码为 `hrm:employee:import`，需在菜单权限中配置。
- 用户角色名称需与系统角色完全一致（精确匹配，不做模糊）。
- 同一行内，部门 / 岗位 / 角色解析失败则该行整体失败，不会部分导入。
- 导入创建员工时会同步创建系统登录账号（用户名为手机号，默认密码为手机号），请提醒使用方注意账号安全。
- 模板中示例行的部门 / 岗位 / 角色名称为示例数据，正式导入前需替换为系统中真实存在的名称。