# Auth 协议（手机号 OTP）

本文档定义 `/api/v1/auth` 的手机号验证码认证协议。

Base URL: `/api/v1/auth`

---

## 手机号格式

- 统一使用 E.164：`^\+[1-9]\d{7,14}$`
- 前端必须提供国家/地区码选择，提交时拼接为完整 E.164（例如：`+14155552671`、`+8613812345678`）
- 后端只做安全归一化（去空白和常见分隔符），不推断或补全国家码

---

## 端点

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/otp/send` | 发送短信验证码 |
| POST | `/phone-session` | 验证码登录/注册（同一路由） |
| POST | `/sessions/refresh` | 刷新会话 |
| DELETE | `/sessions` | 退出登录 |

---

## 1) POST `/otp/send`

发送验证码，不区分登录和注册场景。

### Request

```json
{
  "phone": "+14155552671"
}
```

### Response

`204 No Content`

---

## 2) POST `/phone-session`

验证码校验成功后返回会话。

- 若手机号已存在：直接登录
- 若手机号不存在：自动创建账号后登录

### Request

```json
{
  "phone": "+14155552671",
  "token": "123456"
}
```

### Response

```json
{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 3600,
  "token_type": "bearer",
  "user": {
    "id": "uuid",
    "phone": "+14155552671"
  }
}
```

---

## 3) POST `/sessions/refresh`

### Request

```json
{
  "refresh_token": "..."
}
```

### Response

同 `/phone-session` 会话响应。

---

## 4) DELETE `/sessions`

### Request

```json
{
  "refresh_token": "..."
}
```

### Response

`204 No Content`

---

## 已移除端点

- `POST /verifications`
- `POST /verify`
- `POST /resend`
- `POST /sessions`（旧密码/短信混合登录入口）