docs: update agent and UI protocol documentation
- 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
This commit is contained in:
@@ -0,0 +1,116 @@
|
||||
# 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`(旧密码/短信混合登录入口)
|
||||
Reference in New Issue
Block a user