117 lines
1.7 KiB
Markdown
117 lines
1.7 KiB
Markdown
|
# 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`（旧密码/短信混合登录入口）
|