# client-phone-binding Specification

## ADDED Requirements

### Requirement: A4 发送验证码接口

系统 MUST 提供无认证验证码接口 `POST /api/c/v1/auth/send-code`，并复用现有验证码服务。

- HTTP Method + Path: `POST /api/c/v1/auth/send-code`
- 请求体字段：
  - `phone` string，MUST，手机号
  - `scene` string，MUST，业务场景（`bind_phone` / `change_phone_old` / `change_phone_new`）
- 响应体字段：
  - `cooldown_seconds` int，MUST，本次发送后的冷却秒数
- 错误码：
  - `1006` 参数错误
  - `1003` 请求过于频繁（触发任一限流）
  - `1050` 短信发送失败

#### Scenario: 发送成功
- **WHEN** 手机号格式合法且未触发限流
- **THEN** 系统 SHALL 发送验证码并返回冷却时间

### Requirement: A4 限频规则

系统 SHALL 对 A4 实施三层限频：手机号 60 秒冷却、同 IP 每小时 20 次、同手机号每日 10 次。

#### Scenario: 60 秒内重复发送
- **WHEN** 同一手机号在 60 秒冷却内再次请求
- **THEN** 系统 MUST 返回 `1003`

#### Scenario: 同 IP 超过小时阈值
- **WHEN** 同一 IP 在 1 小时内发送次数超过 20
- **THEN** 系统 MUST 返回 `1003`

#### Scenario: 同手机号超过日阈值
- **WHEN** 同一手机号在当日发送次数超过 10
- **THEN** 系统 MUST 返回 `1003`

### Requirement: A5 首次绑定手机号接口

系统 MUST 提供需认证接口 `POST /api/c/v1/auth/bind-phone`，仅允许首次绑定。

- HTTP Method + Path: `POST /api/c/v1/auth/bind-phone`
- 请求体字段：
  - `phone` string，MUST，新手机号
  - `code` string，MUST，验证码
- 响应体字段：
  - `phone` string，MUST，已绑定手机号
  - `bound_at` string，MUST，绑定时间
- 错误码：
  - `1001` 缺失认证令牌
  - `1002` 认证令牌无效
  - `1006` 参数错误
  - `1035` 验证码错误或过期
  - `1037` 手机号已被绑定
  - `1038` 已绑定手机号不可重复绑定

#### Scenario: 首次绑定成功
- **WHEN** 客户已登录、验证码正确且手机号未被占用
- **THEN** 系统 SHALL 完成手机号首次绑定并返回绑定信息

#### Scenario: 已绑定用户再次调用绑定
- **WHEN** 当前客户已存在绑定手机号
- **THEN** 系统 MUST 返回 `1038`

### Requirement: A6 换绑手机号接口

系统 MUST 提供需认证接口 `POST /api/c/v1/auth/change-phone`，并执行旧手机号与新手机号双验证码校验。

- HTTP Method + Path: `POST /api/c/v1/auth/change-phone`
- 请求体字段：
  - `old_phone` string，MUST，旧手机号
  - `old_code` string，MUST，旧手机号验证码
  - `new_phone` string，MUST，新手机号
  - `new_code` string，MUST，新手机号验证码
- 响应体字段：
  - `phone` string，MUST，换绑后的手机号
  - `changed_at` string，MUST，换绑时间
- 错误码：
  - `1001` 缺失认证令牌
  - `1002` 认证令牌无效
  - `1006` 参数错误
  - `1035` 验证码错误或过期
  - `1037` 新手机号已被绑定
  - `1039` 旧手机号不匹配

#### Scenario: 换绑成功
- **WHEN** 登录客户提交正确旧/新验证码且新手机号未占用
- **THEN** 系统 SHALL 更新绑定手机号为新手机号

#### Scenario: 旧手机号校验失败
- **WHEN** `old_phone` 与当前客户绑定手机号不一致或 `old_code` 错误
- **THEN** 系统 MUST 拒绝换绑并返回对应错误码