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

> 变更日期：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 里定位到具体行：

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

## 业务规则

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

## 注意事项

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