注册

1. 接口定位

• 接口名称: 注册
• 所属域: client/account
• 业务目标: 创建新的 Chat 账户，并在需要时同步生成 Chat Token 与 IM Token

2. 请求定义

• Method: POST
• Path: /account/register
• Content-Type: 推荐 application/json（服务端按 JSON body 解析，当前未对该请求头做强校验）
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: CheckAdminOrNil，支持管理员已登录代注册与普通用户免登录注册两种入口
• 幂等性: 非幂等（会创建用户、写入业务表，并触发 IM 注册）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	否	string	管理员代注册时可传；普通用户注册可不传

Body 参数

字段	必填	类型	说明
invitationCode	否	string	邀请码；系统配置要求注册必须邀请码时必填
verifyCode	条件必填	string	普通用户注册时必填；管理员代注册可跳过
deviceID	否	string	设备 ID
platform	是	int32	客户端平台 ID
autoLogin	否	bool	是否在注册成功后返回可直接登录的 token
user	是	object	注册用户信息对象

user 对象字段

字段	必填	类型	说明
userID	条件必填	string	用户 ID；管理员可指定，普通用户不得指定，未传时系统自动生成
nickname	是	string	昵称
faceURL	否	string	头像 URL
birth	否	int64	出生时间戳（毫秒）
gender	否	int32	性别
areaCode	条件必填	string	手机区号；手机号注册方案时必填
phoneNumber	条件必填	string	手机号；手机号注册方案时必填
email	条件必填	string	邮箱；邮箱注册方案时必填
account	否	string	账号名；若传入，必须为字母数字组合，且会登记为登录凭证
password	否	string	密码；允许为空，但为空时无法直接使用密码登录

字段约束

• user 必填，且 user.nickname 必填。
• platform 必须是合法客户端平台值。
• 注册主体必须提供邮箱，或同时提供 areaCode + phoneNumber。
• account 若传入，必须为字母数字组合。
• email 若传入，必须满足邮箱格式。
• 普通用户注册时:
  • 受系统 allowRegister 开关控制。
  • 不允许自定义 user.userID。
  • 必须通过 IP 注册策略检查。
  • 在配置要求邀请码时必须提供可用邀请码。
  • 必须通过验证码校验。
• 管理员代注册时:
  • 可跳过 allowRegister、IP 注册限制、邀请码和验证码校验。
  • 可指定目标 user.userID。

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
userID	string	新建用户 ID
chatToken	string	Chat 登录令牌；仅 autoLogin = true 时返回有效值
imToken	string	IM 令牌；仅 autoLogin = true 时返回有效值

5. 业务规则

• 接口会先做注册信息唯一性检查，覆盖手机号、账号名、邮箱三类登录凭证。
• 普通用户注册时，会依次执行注册开关、IP 策略、邀请码、验证码校验。
• 未显式指定 userID 时，系统会自动生成 10 位数字用户 ID，并最多尝试 20 次避免冲突。
• 注册成功后会写入注册记录、账户记录、属性记录和凭证记录。
• API 层会继续向 OpenIM 注册用户资料，并尝试导入默认好友、默认群组。
• autoLogin = true 时，服务端生成 chatToken，API 层再生成 imToken。
• autoLogin = false 时，仍返回 userID，但两个 token 为空字符串。

6. 错误码与失败场景

错误码	场景	典型报错
1001	user 为空或 nickname 为空	user is nil / Nickname is nil
1001	platform 非法	platform is invalid
1001	缺少手机号或邮箱主体	AreaCode is empty / PhoneNumber is empty
1001	区号或手机号格式非法	area code must be number / phone number must be number
1001	account 非字母数字	account must be alphanumeric
1001	邮箱格式非法	invalid email
1001	配置要求邀请码但未传	invitation code is empty
1002	普通用户注册被全局关闭	register user is disabled
1002	普通用户尝试指定 userID	only admin can set user id
20003	手机号已注册	PhoneAlreadyRegister
20004	账号名已注册	AccountAlreadyRegister
20006	验证码错误	VerifyCodeNotMatch
20007	验证码过期或不存在	VerifyCodeExpired
20008	验证码尝试次数超限	VerifyCodeMaxCount
20009	验证码已被使用	VerifyCodeUsed
20010	邀请码已被使用	InvitationCodeUsed
20011	邀请码不存在	InvitationNotFound
20012	IP 注册策略禁止当前请求	Forbidden
20014	邮箱已注册	EmailAlreadyRegister

7. 示例

fetch 请求示例

fetch("http://localhost:10008/account/register", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    invitationCode: "A7F9Q2",
    verifyCode: "123456",
    deviceID: "ios-iphone15-001",
    platform: 5,
    autoLogin: true,
    user: {
      nickname: "Alice",
      faceURL: "https://example.com/avatar.png",
      areaCode: "+86",
      phoneNumber: "13800138000",
      account: "alice001",
      password: "P@ssw0rd",
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "invitationCode": "A7F9Q2",
  "verifyCode": "123456",
  "deviceID": "ios-iphone15-001",
  "platform": 5,
  "autoLogin": true,
  "user": {
    "nickname": "Alice",
    "faceURL": "https://example.com/avatar.png",
    "areaCode": "+86",
    "phoneNumber": "13800138000",
    "account": "alice001",
    "password": "P@ssw0rd"
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "imToken": "im-token-value",
    "chatToken": "chat-token-value",
    "userID": "2817364510"
  }
}

失败响应示例

{
  "errCode": 20012,
  "errMsg": "Forbidden",
  "errDlt": ""
}

8. 时序流程

1. 解析请求并填充真实客户端 IP。
2. 预检查用户是否已在 Chat 或 IM 侧存在异常残留数据。
3. 校验注册主体唯一性与字段合法性。
4. 若为普通用户注册，执行注册开关、IP 策略、邀请码、验证码校验。
5. 生成或校验目标用户 ID。
6. 写入注册、账户、属性、凭证等业务数据。
7. 同步向 OpenIM 注册用户。
8. 导入默认好友与默认群组。
9. 若启用自动登录，签发 Chat Token 与 IM Token。
10. 返回统一成功响应。

9. 变更记录

• 2026-03-31: 首版发布，补齐管理员代注册与普通注册的差异、邀请码与 IP 策略、自动登录返回结构。