编辑 | blame | 历史 | 原始文档

用户导入模板列名变更 - 联调方案

变更日期:2026-10-16 模块:系统管理 → 用户管理

背景

用户下载的导入模板里,账号列的表头是「登录名称」,而页面和接口校验里都叫「用户账号」,
用户拿到模板后找不到「用户账号」这一列,填错列后导入 100% 失败(逐行提示「用户账号不能为空」)。
本次统一列名,并补齐用户实际需要的列。

涉及页面

  • 系统管理 → 用户管理 → 导入用户(下载导入模板 / 导入)

接口

方法 路径 说明
GET /system/user/get-import-template 下载导入模板(列名、列顺序有变更)
POST /system/user/import 导入用户(失败明细的 key 格式有变更)

GET /system/user/get-import-template

模板列(顺序即列顺序):

列 表头 必填 说明
A 用户账号 是 4-30 位数字、字母(原表头「登录名称」)
B 用户昵称 否 最多 30 个字符(原表头「用户名称」)
C 部门 否 填部门名称;也兼容填部门编号。留空表示暂不归属部门
D 岗位 是 填岗位名称;多个岗位用「、」分隔,如:普工、班组长。岗位需先在系统管理 → 岗位中维护
E 用户邮箱 否 格式非法或重复时报错,可留空
F 手机号码 否 11 位手机号,可留空
G 用户性别 否 填字典标签:男 / 女
H 账号状态 否 填字典标签:开启 / 停用;留空默认开启
I 初始密码 否 4-16 位;留空时使用系统配置的初始密码

POST /system/user/import

响应结构不变,仅 failureUsernames 的 key 由「用户名」改为「第 N 行「用户名」」,
便于用户在 Excel 里定位到具体行:

{
  "code": 0,
  "data": {
    "createUsernames": ["zhangsan"],
    "updateUsernames": [],
    "failureUsernames": {
      "第 3 行「lisi」": "「岗位」列填写的岗位「车间主任」不存在,请先在「系统管理 → 岗位」中维护,或改成已存在的岗位名称"
    }
  }
}

业务规则

场景 规则
岗位 与页面上新增用户保持一致,导入时必填;导入成功后会同步写入用户-岗位关联,导入出来的用户可以直接在页面上编辑保存
部门 / 岗位名称不存在 该行失败,提示里给出名称和下一步动作
部门重名 该行失败,提示改填部门编号
部门 / 岗位已停用 该行失败,提示先启用
账号已存在且未勾选「是否覆盖」 该行失败,提示勾选覆盖或改账号
已存在且勾选「是否覆盖」 更新该用户的部门、岗位、邮箱、手机号、性别、状态,**不修改其密码**
覆盖时「账号状态」留空 保持原状态不变

注意事项

  • 列名变了,旧模板(表头还是「登录名称 / 用户名称 / 部门编号」)不能再使用,需要重新下载模板;
    旧模板导入会逐行提示「用户账号必须填写」,不会静默导入成错误数据。
  • 失败明细可能上百条,前端以弹窗(弹窗内列表可滚动)展示,成功后仍用轻提示。