JSON 导入

1. 接口定位

• 接口名称: JSON 导入
• 所属域: admin/user
• 业务目标: 通过 JSON 批量导入用户，并自动触发聊天服务注册、OpenIM 建档、默认好友和默认群组导入

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
users	是	array<object>	批量导入用户列表

users 元素字段

字段	必填	类型	说明
userID	否	string	用户 ID；为空时由下游注册逻辑决定
nickname	否	string	昵称
faceURL	否	string	头像
birth	否	int64	生日，Unix 毫秒时间戳
gender	否	int32	性别
areaCode	否	string	区号
phoneNumber	否	string	手机号
email	否	string	邮箱
account	否	string	账号
password	否	string	密码；当前接口会原样透传给下游注册接口
RegisterType	否	int32	注册类型；当前接口不主动设置

字段约束

• API 层只负责把 users 解析成 RegisterUserInfo 数组。
• 批量执行前会校验 users 长度必须大于 0，否则返回 users is empty。
• 单个用户的更细粒度合法性校验，主要由下游 chat.RegisterUser 负责。

4. 响应结构

通用响应包裹

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

data 字段

• 本接口成功时返回 null。

5. 业务规则

• 仅管理员可以调用。
• API 层会先获取真实客户端 IP，并向 OpenIM 获取默认管理员 token。
• 对 users 中的每个用户，服务端按顺序执行：
  • 调用 chat.RegisterUser，并强制把 Platform 设为 constant.AdminPlatformID
  • 调用 OpenIM RegisterUser 创建 IM 用户资料
  • 查询默认好友列表，若查询成功则尝试导入默认好友，导入失败会被忽略
  • 查询默认群组列表，若查询成功则尝试邀请进默认群，邀请失败会被忽略
• 批量导入是逐个循环执行的；如果中途某个用户失败，接口会立即结束，之前已成功导入的用户不会回滚。

6. 错误码与失败场景

错误码	场景	典型报错
1001	请求 JSON 解析失败	由 ParseRequest 详细错误组成
1001	users 为空数组	users is empty
-	获取客户端 IP 失败	由 API 层返回原始错误
-	获取 OpenIM 管理员 token 失败	由 IM 调用链路返回
-	下游用户注册失败	由 chat.RegisterUser 返回
-	OpenIM 建档失败	由 OpenIM 接口返回

7. 示例

fetch 请求示例

fetch("http://localhost:10009/user/import/json", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440901",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    users: [
      {
        nickname: "alice",
        areaCode: "+86",
        phoneNumber: "13800138000",
        password: "5f4dcc3b5aa765d61d8327deb882cf99",
      },
    ],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "users": [
    {
      "nickname": "alice",
      "areaCode": "+86",
      "phoneNumber": "13800138000",
      "password": "5f4dcc3b5aa765d61d8327deb882cf99"
    }
  ]
}

成功响应示例

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

8. 时序流程

1. 中间件校验管理员 token。
2. 解析 users 请求体并获取客户端 IP。
3. 获取 OpenIM 默认管理员 token。
4. 逐个调用聊天服务注册用户。
5. 为每个成功注册的用户在 OpenIM 建档，并尝试导入默认好友和默认群组。
6. 全部完成后返回成功响应；任一步失败则中断返回错误。

9. 变更记录

• 2026-03-31: 首版发布，基于 JSON 批量导入用户的真实执行链路补全文档。