qzl
641d847008
- Update api-endpoints.md with new agent endpoints - Update run-agent-input.md with new input schemas - Update sse-events.md with new event types - Update ui-schema.md with schema changes
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`（旧密码/短信混合登录入口）
|