新增用户

1. 接口定位

• 接口名称: Admin 服务新增用户
• 所属域: admin/account
• 业务目标: 由管理员创建聊天用户，并自动完成 IM 侧注册、默认好友导入和默认群组邀请

2. 请求定义

• Method: POST
• Path: /account/add_user
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 非幂等

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
ip	否	string	协议中存在，但 API 层不会使用；真实 IP 取自请求来源
deviceID	否	string	协议中存在，但当前 API 层不会透传到注册 RPC
platform	否	int32	协议中存在，但当前 API 层最终会强制改写为管理端平台常量
user	是	object	用户注册资料

user 字段

字段	必填	类型	说明
userID	否	string	期望用户 ID；管理员可指定，但若已存在会失败
nickname	是	string	用户昵称
faceURL	否	string	用户头像
birth	否	int64	生日时间戳
gender	否	int32	性别：0 女，1 男，2 未知
areaCode	条件必填	string	手机区号；手机号注册时必填
phoneNumber	条件必填	string	手机号；手机号注册时必填
email	条件必填	string	邮箱；邮箱注册时必填
account	条件必填	string	账号；管理员场景支持仅用账号注册
password	否	string	登录密码
RegisterType	否	int32	协议字段存在，但注册类型由服务端按账号形态自动推导，传值不会决定最终注册类型

字段约束

• user 不能为空。
• 至少要提供一种有效账号标识：email，或 areaCode + phoneNumber，或管理员场景下的 account。
• areaCode 若不带 +，服务端会自动补齐后再校验是否为数字。
• phoneNumber 必须全数字。
• email 必须满足邮箱格式。
• account 若提供，必须是纯字母数字。
• nickname 建议必传；注册用户资料会直接写入聊天用户属性与 IM 用户资料。

4. 响应结构

通用响应包裹

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

data 字段

• 成功时返回空对象。

5. 业务规则

• API 层不会直接调用 chat.AddUserAccount RPC，而是调用 chat.RegisterUser 走完整注册链路。
• API 层会读取真实客户端 IP，并覆盖请求中的 ip。
• API 层会把注册平台强制设为管理端平台常量，忽略客户端传入的 platform。
• 管理员注册用户时不会走“是否允许注册”“邀请码”“验证码”这些普通注册限制。
• 注册成功后，API 层会向 OpenIM 注册用户资料。
• 若系统中存在默认好友，会自动把这些好友导入到新用户。
• 若系统中存在默认群组，会自动邀请新用户入群。

6. 错误码与失败场景

错误码	场景	典型报错
1001	user 为空	user is empty
1001	手机号注册缺少区号或手机号	area code or phone number is empty
1001	区号不是数字	area code must be number
1001	手机号不是数字	phone number must be number
1001	邮箱格式非法	email must be right 或 invalid email
1001	账号不是字母数字	account must be alphanumeric
1001	未提供任何有效账号标识	at least one valid account is required
20003	手机号已注册	PhoneAlreadyRegister
20004	账号已注册	AccountAlreadyRegister
20014	邮箱已注册	EmailAlreadyRegister
-	指定 userID 已存在	appoint user id already register
-	OpenIM 注册、默认好友导入或默认入群失败	由后续链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10009/account/add_user", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440106",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    user: {
      nickname: "Alice",
      faceURL: "https://example.com/alice.png",
      areaCode: "+86",
      phoneNumber: "13800138000",
      account: "alice001",
      password: "User@123",
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "user": {
    "nickname": "Alice",
    "faceURL": "https://example.com/alice.png",
    "areaCode": "+86",
    "phoneNumber": "13800138000",
    "account": "alice001",
    "password": "User@123"
  }
}

成功响应示例

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

失败响应示例

{
  "errCode": 20004,
  "errMsg": "AccountAlreadyRegister",
  "errDlt": "AccountAlreadyRegister"
}

8. 时序流程

1. 中间件校验管理员 token。
2. 解析 user 并校验手机号/邮箱/账号的基本合法性。
3. API 层获取真实客户端 IP 和默认 IM 管理员 token。
4. 通过管理员身份调用注册链路创建聊天用户。
5. 将新用户同步注册到 OpenIM。
6. 自动导入默认好友并邀请默认群组。
7. 返回统一成功响应。

9. 变更记录

• 2026-03-31: 首版发布，基于 admin API registerChatUser 逻辑、聊天注册校验与 OpenIM 同步链路补全文档。