登录

1. 接口定位

• 接口名称: 登录
• 所属域: client/account
• 业务目标: 校验用户身份并返回 Chat Token 与 IM Token

2. 请求定义

• Method: POST
• Path: /account/login
• Content-Type: 推荐 application/json（服务端按 JSON body 解析，当前未对该请求头做强校验）
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 无
• 幂等性: 非幂等（会生成新 token、写入登录记录，并可能消费验证码）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	否	string	本接口无需 token

Body 参数

字段	必填	类型	说明
areaCode	条件必填	string	手机区号；手机号登录时必填
phoneNumber	条件必填	string	手机号；手机号登录时必填
email	条件必填	string	邮箱；邮箱登录时必填
account	否	string	账号名；服务端支持，但当前 HTTP 校验不允许单独使用
password	条件必填	string	密码登录时必填
verifyCode	条件必填	string	验证码登录时必填
platform	是	int32	客户端平台 ID
deviceID	否	string	设备 ID

字段约束

• platform 必填，且必须是合法客户端平台值。
• password 与 verifyCode 至少传一个。
• 若同时传 password 和 verifyCode，当前实现优先走密码登录分支。
• 必须提供邮箱，或同时提供 areaCode + phoneNumber。
• account 虽会被 服务端 登录逻辑识别，但不能单独满足当前 HTTP 层校验，不建议作为 REST 唯一登录标识。
• 手机号登录时，服务端会自动为未带 + 的 areaCode 补齐前缀后再做数字校验。

登录方式映射

登录方式	必填字段
手机号 + 密码	areaCode、phoneNumber、password、platform
邮箱 + 密码	email、password、platform
手机号 + 验证码	areaCode、phoneNumber、verifyCode、platform
邮箱 + 验证码	email、verifyCode、platform

4. 响应结构

通用响应包裹

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

data 字段结构

字段	类型	说明
userID	string	用户 ID
chatToken	string	Chat 登录令牌
imToken	string	IM 登录令牌

5. 业务规则

• 登录前会先根据手机号、邮箱或账号凭证查找用户。
• 查找到用户后，会执行登录禁止策略校验，覆盖 IP 限制、仅允许指定 IP 登录、账号封禁等规则。
• 密码登录时，服务端直接比对账户密码。
• 验证码登录时，服务端会调用统一验证码校验逻辑。
• 验证码登录成功后，会删除本次已使用验证码，避免重复使用。
• 登录成功后，服务端会签发 chatToken，并由 API 层换取 imToken。
• 服务端会记录登录时间、IP、设备 ID、平台等审计信息。

6. 错误码与失败场景

错误码	场景	典型报错
1001	未提供手机号或邮箱主体	account or phone number or email must be set / AreaCode is empty
1001	platform 非法	platform is invalid
1001	password 与 verifyCode 都未传	password or code must be set
1001	区号或手机号格式非法	area code must be number / PhoneNumber is empty
20001	密码错误	PasswordError
20002	账号不存在或未注册	AccountNotFound
20006	验证码错误	VerifyCodeNotMatch
20007	验证码过期或不存在	VerifyCodeExpired
20008	验证码尝试次数超限	VerifyCodeMaxCount
20009	验证码已被使用	VerifyCodeUsed
20012	登录被禁止	Forbidden

7. 示例

fetch 请求示例

fetch("http://localhost:10008/account/login", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    areaCode: "+86",
    phoneNumber: "13800138000",
    password: "P@ssw0rd",
    platform: 5,
    deviceID: "ios-iphone15-001",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "areaCode": "+86",
  "phoneNumber": "13800138000",
  "password": "P@ssw0rd",
  "platform": 5,
  "deviceID": "ios-iphone15-001"
}

成功响应示例

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

失败响应示例

{
  "errCode": 20001,
  "errMsg": "PasswordError",
  "errDlt": ""
}

8. 时序流程

1. 解析请求并填充真实客户端 IP。
2. 校验手机号、邮箱、平台和登录凭证字段。
3. 根据登录凭证查询用户账户。
4. 执行登录禁止策略校验。
5. 进入密码登录或验证码登录分支。
6. 生成 Chat Token。
7. 记录登录审计信息。
8. 若为验证码登录，删除已消费验证码。
9. 通过 IM 管理接口换取 IM Token。
10. 返回统一成功响应。

9. 变更记录

• 2026-03-31: 首版发布，明确了密码登录与验证码登录两种模式，并补充 account 字段在当前 REST 层的实际限制。