发送验证码

1. 接口定位

• 接口名称: 发送验证码
• 所属域: client/account
• 业务目标: 为注册、登录、重置密码下发验证码（短信或邮箱）

2. 请求定义

• Method: POST
• Path: /account/code/send
• Content-Type: 推荐 application/json（服务端按 JSON body 解析，当前未对该请求头做强校验）
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 无
• 幂等性: 非幂等（会触发验证码发送与落库）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
usedFor	是	int32	验证码用途：1 注册，2 重置密码，3 登录
invitationCode	否	string	邀请码；当系统配置要求注册必须邀请码时必填
deviceID	否	string	设备 ID
platform	否	int32	平台 ID，用于记录验证码平台来源
areaCode	条件必填	string	手机区号；使用手机号方案时必填，如 +86
phoneNumber	条件必填	string	手机号；使用手机号方案时必填
email	条件必填	string	邮箱；使用邮箱方案时必填

usedFor 用途映射

usedFor	用途	前置条件	必填字段
1	注册	需校验 IP 策略、邀请码配置	areaCode+phoneNumber 或 email
2	重置密码	账号必须已注册	areaCode+phoneNumber 或 email
3	登录	账号必须已注册	areaCode+phoneNumber 或 email

字段约束

• email 为空时，areaCode 与 phoneNumber 必须同时提供。
• email 非空时，按邮箱格式校验。
• areaCode 若不带 +，服务端会自动补齐再做数字校验。

4. 响应结构

通用响应包裹

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

data 字段

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

5. 业务规则

• usedFor = 1（注册）时:
  • 先校验注册是否允许（含 IP 相关策略）。
  • 若配置开启“注册需要邀请码”，则校验 invitationCode。
• usedFor = 2/3（重置密码/登录）时:
  • 必须先确认手机号或邮箱已注册，否则返回账号不存在错误。
• 发送通道选择:
  • email 非空走邮件通道。
  • 否则走短信通道。
• 频控:
  • 按账号在时间窗口内统计发送次数，超限返回发送过于频繁。
• IP 处理:
  • API 层会用真实客户端 IP 覆盖请求体中的 ip 字段。

6. 错误码与失败场景

错误码	场景	典型报错
1001	usedFor 非 1/2/3	used unknown
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
1001	注册要求邀请码但未传	invitation code is empty
1004	登录/重置时账号未注册	AccountNotFound（可能附带 phone unregistered/email unregistered）
20005	单位时间发送次数超限	VerifyCodeSendFrequently
20003	邮件通道未启用却走邮箱发送	email verification code is not enabled
20004	短信通道未启用却走短信发送	mobile phone verification code is not enabled

7. 示例

fetch 请求示例

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

请求示例（JSON）

{
  "usedFor": 1,
  "invitationCode": "A7F9Q2",
  "deviceID": "ios-iphone15-001",
  "platform": 5,
  "areaCode": "+86",
  "phoneNumber": "13800138000"
}

成功响应示例

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

失败响应示例

{
  "errCode": 1002,
  "errMsg": "ArgsError",
  "errDlt": "used unknown"
}

8. 时序流程

1. 校验请求参数与验证码用途是否合法。
2. 按用途执行账号前置检查（如注册策略、账号是否已注册、邀请码规则）。
3. 根据手机号或邮箱选择发送通道并生成验证码。
4. 执行发送频率控制并保存验证码记录。
5. 发送成功后返回统一成功响应。

9. 变更记录

• 2026-03-31: 首版发布，包含完整的字段定义、业务规则、错误场景，以及 curl 示例和 usedFor 用途映射。