XLSX 导入

1. 接口定位

• 接口名称: XLSX 导入
• 所属域: admin/user
• 业务目标: 通过上传 Excel 文件批量导入用户，再执行聊天服务注册与 OpenIM 建档

2. 请求定义

• Method: POST
• Path: /user/import/xlsx
• Content-Type: multipart/form-data
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非幂等；批量导入过程中不做事务回滚

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

FormData 参数

字段	必填	类型	说明
data	是	file	Excel 文件，服务端按 sheet user 解析

模板列定义

Excel user sheet 按以下列映射：

列名	说明
user_id	用户 ID
nickname	昵称
face_url	头像
birth	生日字符串
gender	性别字符串
area_code	区号
phone_number	手机号
email	邮箱
account	账号
password	密码明文

字段约束

• 上传字段名必须是 data。
• 服务端会先把 Excel 解析为 []model.User，再逐行转换成 RegisterUserInfo。
• 每一行必须满足：
  • nickname 非空，否则 nickname is empty
  • areaCode 与 phoneNumber 非空，否则 areaCode or phoneNumber is empty
  • password 非空，否则 password is empty
  • areaCode 必须以 + 开头且后续全是数字，否则 areaCode format error
• password 会在 API 层先做 MD5，再发送给下游注册接口。
• birth 为空、无法按三段日期解析、或早于 1900 时，最终会被替换为当前时间。
• gender 使用 strconv.Atoi 解析，解析失败时会落成 0。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段

• 本接口成功时返回 null。

5. 业务规则

• 仅管理员可以调用。
• Excel 解析成功后，后续注册链路与 JSON 导入一致：逐个调用聊天服务注册、OpenIM 建档、导入默认好友和默认群组。
• 默认好友导入和默认群组邀请的执行失败会被忽略，不影响整个接口返回成功。
• 批量导入中途失败时不会回滚此前已成功导入的用户。

6. 错误码与失败场景

错误码	场景	典型报错
1001	未上传 data 文件	由 FormFile 返回原始错误
1001	Excel 解析失败	xlsx file parse error ...
1001	模板行字段不合法	nickname is empty 等
-	获取客户端 IP 失败	由 API 层返回原始错误
-	获取 OpenIM 管理员 token 失败	由 IM 调用链路返回
-	下游注册或 OpenIM 建档失败	由相应链路返回原始错误

7. 示例

fetch 请求示例

const formData = new FormData();
formData.append("data", fileInput.files[0]);

fetch("http://localhost:10009/user/import/xlsx", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440902",
    token: "eyJhbGciOi...",
  },
  body: formData,
})
  .then((res) => res.json())
  .then((data) => console.log(data));

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": null
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "areaCode format error"
}

8. 时序流程

1. 中间件校验管理员 token。
2. 读取 data 文件并解析 user sheet。
3. 逐行校验并转换为 RegisterUserInfo，同时对密码做 MD5。
4. 获取 OpenIM 默认管理员 token。
5. 逐个注册用户、OpenIM 建档，并尝试导入默认好友和默认群组。
6. 全部完成后返回成功响应；任一步失败则中断返回错误。

9. 变更记录

• 2026-03-31: 首版发布，基于 XLSX 模板解析、字段校验和导入链路补全文档。