重置密码

1. 接口定位

• 接口名称: 重置密码
• 所属域: client/account
• 业务目标: 在忘记密码场景下，通过验证码校验后重置账户密码

2. 请求定义

• Method: POST
• Path: /account/password/reset
• Content-Type: 推荐 application/json（服务端按 JSON body 解析，当前未对该请求头做强校验）
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 无
• 幂等性: 非幂等（会修改密码并删除已消费验证码）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
areaCode	条件必填	string	手机区号；手机号重置方案时必填
phoneNumber	条件必填	string	手机号；手机号重置方案时必填
email	条件必填	string	邮箱；邮箱重置方案时必填
verifyCode	是	string	验证码
password	是	string	新密码

字段约束

• password 必填。
• verifyCode 必填。
• email 为空时，areaCode 与 phoneNumber 必须同时提供。
• email 非空时，按邮箱格式校验。
• 对手机号方案，如果只传 areaCode 或只传 phoneNumber，会直接失败。
• 建议 areaCode 使用与发送验证码时一致的值，推荐显式使用 +86 这类完整格式。

4. 响应结构

通用响应包裹

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

data 字段

• 本接口成功时返回空对象（无业务字段）。

5. 业务规则

• 服务端先校验验证码，再执行密码更新。
• 验证码校验通过后，会按手机号或邮箱查找对应登录凭证。
• 密码更新与验证码删除在同一业务流程内执行，避免验证码被再次使用。
• 本接口只负责重置密码，不会自动签发新的 Chat Token 或 IM Token。
• 调用方若希望用户继续使用，应在重置成功后引导其重新登录。

6. 错误码与失败场景

错误码	场景	典型报错
1001	password 为空	password is empty / password must be set
1001	verifyCode 为空	VerifyCode is empty
1001	手机号方案只传了区号或号码	area code and phone number must set together
1001	邮箱格式非法	Email is invalid
1004	验证码通过后仍找不到账户凭证	RecordNotFoundError
20006	验证码错误	VerifyCodeNotMatch
20007	验证码过期或不存在	VerifyCodeExpired
20008	验证码尝试次数超限	VerifyCodeMaxCount
20009	验证码已被使用	VerifyCodeUsed

7. 示例

fetch 请求示例

fetch("http://localhost:10008/account/password/reset", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "user@example.com",
    verifyCode: "123456",
    password: "N3wP@ssw0rd",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "email": "user@example.com",
  "verifyCode": "123456",
  "password": "N3wP@ssw0rd"
}

成功响应示例

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

失败响应示例

{
  "errCode": 20007,
  "errMsg": "VerifyCodeExpired",
  "errDlt": ""
}

8. 时序流程

1. 解析请求并校验手机号、邮箱、验证码和新密码字段。
2. 按手机号或邮箱定位验证码账户。
3. 校验验证码是否存在、是否过期、是否已被使用、是否超出次数限制。
4. 根据手机号或邮箱查找登录凭证。
5. 更新目标用户密码。
6. 删除本次已消费验证码。
7. 返回统一成功响应。

9. 变更记录

• 2026-03-31: 首版发布，补充了验证码消费规则、账户缺失时的实际错误语义，以及区号格式注意事项。