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

涉及页面

人力资源 > 员工管理列表页（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）
新增：员工导入弹窗（含下载模板、上传文件、展示导入结果）

业务流程与数据带入

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

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 时手机号已存在的员工会被更新，否则记为失败

响应：

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