qzl
e4e995854d
- 新增忘记密码页面与重置密码确认流程（前端+后端） - 修复注册验证码页登录跳转路由 - 新增用户搜索API（按邮箱查询） - 简化infra脚本，统一为app.sh - 补充密码重置与用户API测试覆盖 - 更新runtime文档与AGENTS配置
5.7 KiB
5.7 KiB
Runtime API Routes
本文档记录所有 HTTP API 端点。修改路由时必须同步更新此文档。
格式说明
- Request/Response 使用 JSON 格式
- 错误响应使用 RFC 7807
application/problem+json - 所有端点前缀:
/api/v1
Auth
POST /auth/verifications
创建验证码（注册发起）。
Request:
{
"username": "string (3-30 chars)",
"email": "string (email)",
"password": "string (min 6 chars)",
"redirect_to": "string? (optional)"
}
Response: 202 Accepted
{
"email": "user@example.com"
}
Errors:
- 422: 请求参数无效
- 429: 请求过于频繁
POST /auth/verifications/resend
重发验证码。
Request:
{
"email": "string (email)"
}
Response: 204 No Content
Errors:
- 422: 请求参数无效
- 429: 请求过于频繁
POST /auth/verifications/verify
验证码校验。
Request:
{
"email": "string (email)",
"token": "string (6 digits)"
}
Response: 200 OK
{
"access_token": "string",
"refresh_token": "string",
"expires_in": 3600,
"token_type": "bearer",
"user": {
"id": "string",
"email": "string"
}
}
Errors:
- 401: 验证码无效或已过期
- 422: 请求参数无效
- 429: 请求过于频繁
POST /auth/sessions
登录（创建会话）。
Request:
{
"email": "string (email)",
"password": "string (min 6 chars)"
}
Response: 200 OK
{
"access_token": "string",
"refresh_token": "string",
"expires_in": 3600,
"token_type": "bearer",
"user": {
"id": "string",
"email": "string"
}
}
Errors:
- 401: 邮箱或密码错误
- 422: 请求参数无效
- 429: 请求过于频繁
POST /auth/sessions/refresh
刷新 Token。
Request:
{
"refresh_token": "string"
}
Response: 200 OK
{
"access_token": "string",
"refresh_token": "string",
"expires_in": 3600,
"token_type": "bearer",
"user": {
"id": "string",
"email": "string"
}
}
Errors:
- 401: 无效的 refresh token
- 422: 请求参数无效
DELETE /auth/sessions
登出（删除会话）。
Request:
{
"refresh_token": "string"
}
Response: 204 No Content
Errors:
- 422: 请求参数无效
POST /auth/password-reset
发送密码重置验证码。
Request:
{
"email": "string (email)",
"redirect_to": "string? (optional)"
}
Response: 204 No Content
Errors:
- 422: 请求参数无效
- 429: 请求过于频繁
POST /auth/password-reset/confirm
验证 recovery 验证码并完成改密。
Request:
{
"email": "string (email)",
"token": "string (6 digits)",
"new_password": "string (min 6 chars)"
}
Response: 204 No Content
Errors:
- 401: 验证码无效或已过期
- 422: 请求参数无效
- 429: 请求过于频繁
GET /auth/users
按邮箱查询用户（需要认证）。
Query Parameters:
email: string (required)
Response: 200 OK
{
"id": "string",
"email": "string",
"created_at": "string (ISO 8601)",
"email_confirmed_at": "string? (ISO 8601)"
}
Errors:
- 403: 无权限访问
- 404: 用户不存在
- 422: 请求参数无效
Users
GET /users/me
获取当前用户信息（需要认证）。
Response: 200 OK
{
"id": "string",
"username": "string",
"avatar_url": "string?",
"bio": "string?"
}
Errors:
- 401: 未认证
PATCH /users/me
更新当前用户信息（需要认证）。
Request:
{
"username": "string? (3-30 chars)",
"avatar_url": "string? (URL)",
"bio": "string? (max 200 chars)"
}
Response: 200 OK
{
"id": "string",
"username": "string",
"avatar_url": "string?",
"bio": "string?"
}
Errors:
- 401: 未认证
- 422: 请求参数无效
POST /users/search
搜索用户（需要认证）。
支持两种查询模式：
- 用户名查询：模糊匹配，返回最多 20 个结果
- 邮箱查询：精确匹配，返回 0 或 1 个结果
查询类型自动识别：包含 @ 符号视为邮箱查询。
Request:
{
"query": "string (1-100 chars)"
}
Response: 200 OK
[
{
"id": "string",
"username": "string",
"avatar_url": "string?",
"bio": "string?"
}
]
Errors:
- 401: 未认证
- 503: Auth 服务不可用（仅邮箱查询）
- 422: 请求参数无效
Agent Chat
POST /agent-chats
运行 Agent 对话（需要认证）。
Request:
{
"message": "string (1-8000 chars)",
"session_id": "string? (UUID)"
}
Response: 200 OK
{
"session_id": "string (UUID)",
"output": "string",
"events": [
{
"type": "string",
"run_id": "string?",
"message_id": "string?",
"delta": "string?",
"tool_name": "string?",
"result": "string?",
"output": "string?",
"error": "string?"
}
]
}
Errors:
- 401: 未认证
- 422: 请求参数无效
Infra
GET /infra/health
检查基础设施健康状态。
Response: 200 OK
{
"status": "healthy" | "unhealthy",
"services": {
"redis": {
"status": "healthy" | "unhealthy",
"latency_ms": 0
}
}
}
GET /health
检查服务健康状态。
Response: 200 OK
{
"status": "ok"
}
Error Response Format (RFC 7807)
所有错误响应使用 application/problem+json 格式：
{
"type": "about:blank",
"title": "Unauthorized",
"status": 401,
"detail": "验证码无效或已过期",
"instance": "/api/v1/auth/verifications/verify"
}
前端应优先读取 detail 字段显示给用户。