2026-03-19 18:42:45 +08:00
|
|
|
|
# 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` | 退出登录 |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
2026-03-26 13:25:25 +08:00
|
|
|
|
## 本地开发约定（Supabase Self-Hosting）
|
|
|
|
|
|
|
|
|
|
|
|
- 环境：本地网关地址为 `http://localhost:8001`，后端通过 `SOCIAL_SUPABASE__PUBLIC_URL` 访问。
|
|
|
|
|
|
- 认证：开发机启用 SMS 测试 OTP，不走真实短信供应商。
|
|
|
|
|
|
- 默认测试账号：`SOCIAL_TEST__PHONE`（提交时需使用 E.164，即在前面补 `+`）。
|
|
|
|
|
|
- 默认测试验证码：`123456`（由本地 `auth` 服务的 `GOTRUE_SMS_TEST_OTP` 提供）。
|
|
|
|
|
|
|
|
|
|
|
|
兼容性策略：
|
|
|
|
|
|
|
|
|
|
|
|
- 对外 API 合约不变（`/otp/send`、`/phone-session`、`/sessions/*` 保持一致）。
|
|
|
|
|
|
- 仅切换验证码来源（生产/云环境真实短信，本地环境测试 OTP）。
|
|
|
|
|
|
- 前后端不需要因本地/云差异修改接口调用方式。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
2026-03-19 18:42:45 +08:00
|
|
|
|
## 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`（旧密码/短信混合登录入口）
|
