Excel 导入导出
Excel 导入导出是 RuoYi Office 管理后台中最常见的数据维护能力。当前系统以 FastExcel 为底层读写工具，后端通过 ExcelUtils 统一输出文件、读取上传内容，前端通过 requestClient.download 和上传弹窗完成交互。
用户管理页已经内置完整示例：下载导入模板、上传 xls/xlsx、选择是否覆盖已有用户、按当前筛选条件导出用户数据。二开其它业务模块时，可以优先参考这条链路。
本地实现位置
| 层 | 位置 |
|---|---|
| PC 页面 | ruoyi-office-vben/apps/web-antd/src/views/system/user |
| PC API | ruoyi-office-vben/apps/web-antd/src/api/system/user |
| 后端 Controller | yudao-module-system-server/.../controller/admin/user/UserController.java |
| 导入 VO | UserImportExcelVO.java |
| Excel 工具 | yudao-framework/yudao-spring-boot-starter-excel/.../ExcelUtils.java |
用户导入链路
用户导入字段
用户导入模板映射到 UserImportExcelVO，字段以 Excel 表头为准。
| Excel 列 | 后端字段 | 说明 |
|---|---|---|
| 登录名称 | username | 用户账号，用于判断是否已存在 |
| 用户名称 | nickname | 用户姓名，必填 |
| 部门编号 | deptId | 必须是当前租户下存在的部门编号 |
| 用户邮箱 | email | 需要满足邮箱格式校验 |
| 手机号码 | mobile | 需要满足手机号唯一性校验 |
| 用户性别 | sex | 通过字典转换为数字值 |
| 账号状态 | status | 通过通用状态字典转换 |
导入时，后端会读取系统配置 system.user.init-password 作为初始密码。如果配置为空，导入会直接失败，避免生成不可登录账号。
覆盖与事务
AdminUserServiceImpl#importUserList 使用事务包裹导入流程。每一行会先做字段校验，再校验手机号、邮箱、部门等约束。
| 场景 | 处理方式 |
|---|---|
| 用户名不存在 | 创建用户，写入初始密码，岗位默认为空集合 |
| 用户名已存在且未开启覆盖 | 返回失败明细，不更新该用户 |
| 用户名已存在且开启覆盖 | 使用导入字段更新已有用户 |
| 部门、邮箱、手机号等校验失败 | 记录到 failureUsernames |
租户模式下，创建新用户还会校验租户账号数量上限，避免批量导入突破套餐限制。
导出链路
用户列表的“导出”会复用当前搜索条件，调用 GET /system/user/export-excel。后端将分页大小设置为 PageParam.PAGE_SIZE_NONE，查询全部匹配数据后输出 用户数据.xls。
| 功能 | 接口 | 权限标识 | 文件名 |
|---|---|---|---|
| 下载模板 | GET /system/user/get-import-template | 登录后可用 | 用户导入模板.xls |
| 导入用户 | POST /system/user/import | system:user:import | 上传文件 |
| 导出用户 | GET /system/user/export-excel | system:user:export | 用户数据.xls |
导出 VO 通常使用 RespVO，例如用户导出使用 UserRespVO。如果字段上有 @ExcelProperty、字典转换器或时间转换器，FastExcel 会按注解处理。
二开建议
- 先定义 Excel VO：导入字段不要直接复用 SaveReqVO，Excel 表头、字典转换、地区转换和业务保存字段经常不完全一致。
- 导入结果要返回明细：建议返回创建成功、更新成功、失败原因三类数据，便于运营人员修正后再次导入。
- 大批量导出要评估数据量：当前导出会关闭分页，一次性导出全部匹配数据。数据量很大时建议增加异步导出或后台任务。
- 新增用户字段要同步模板：后台用户如果增加工号、入职日期等字段，需要同步 SaveReqVO、RespVO、Excel VO、前端表单和导入模板。
排查清单
| 现象 | 排查方向 |
|---|---|
| 导入按钮不可见 | 当前账号是否拥有 system:user:import 权限 |
| 导入提示初始密码为空 | 检查系统配置 system.user.init-password |
| 性别或状态解析失败 | Excel 文案是否和字典标签一致 |
| 导入后用户无法登录 | 检查初始密码、用户状态、租户状态和账号数量上限 |
| 导出为空 | 检查当前筛选条件、部门树过滤和导出权限 |
