docs: add runtime route documentation and AGENTS.md rule

2026-02-26 14:37:51 +08:00
parent d635d9a5e0
commit 8e493ae7fd
3 changed files with 398 additions and 31 deletions
@@ -0,0 +1,360 @@
+# Runtime API Routes
+
+本文档记录所有 HTTP API 端点。修改路由时必须同步更新此文档。
+
+## 格式说明
+
+- Request/Response 使用 JSON 格式
+- 错误响应使用 RFC 7807 `application/problem+json`
+- 所有端点前缀: `/api/v1`
+
+## Auth
+
+### POST /auth/verifications
+
+创建验证码（注册发起）。
+
+**Request:**
+```json
+{
+  "username": "string (3-30 chars)",
+  "email": "string (email)",
+  "password": "string (min 6 chars)",
+  "redirect_to": "string? (optional)"
+}
+```
+
+**Response:** 202 Accepted
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+**Errors:**
+- 422: 请求参数无效
+- 429: 请求过于频繁
+
+---
+
+### POST /auth/verifications/resend
+
+重发验证码。
+
+**Request:**
+```json
+{
+  "email": "string (email)"
+}
+```
+
+**Response:** 204 No Content
+
+**Errors:**
+- 422: 请求参数无效
+- 429: 请求过于频繁
+
+---
+
+### POST /auth/verifications/verify
+
+验证码校验。
+
+**Request:**
+```json
+{
+  "email": "string (email)",
+  "token": "string (6 digits)"
+}
+```
+
+**Response:** 200 OK
+```json
+{
+  "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:**
+```json
+{
+  "email": "string (email)",
+  "password": "string (min 6 chars)"
+}
+```
+
+**Response:** 200 OK
+```json
+{
+  "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:**
+```json
+{
+  "refresh_token": "string"
+}
+```
+
+**Response:** 200 OK
+```json
+{
+  "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:**
+```json
+{
+  "refresh_token": "string"
+}
+```
+
+**Response:** 204 No Content
+
+**Errors:**
+- 422: 请求参数无效
+
+---
+
+### GET /auth/users
+
+按邮箱查询用户（需要认证）。
+
+**Query Parameters:**
+- `email`: string (required)
+
+**Response:** 200 OK
+```json
+{
+  "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
+```json
+{
+  "id": "string",
+  "username": "string",
+  "avatar_url": "string?",
+  "bio": "string?"
+}
+```
+
+**Errors:**
+- 401: 未认证
+
+---
+
+### PATCH /users/me
+
+更新当前用户信息（需要认证）。
+
+**Request:**
+```json
+{
+  "username": "string? (3-30 chars)",
+  "avatar_url": "string? (URL)",
+  "bio": "string? (max 200 chars)"
+}
+```
+
+**Response:** 200 OK
+```json
+{
+  "id": "string",
+  "username": "string",
+  "avatar_url": "string?",
+  "bio": "string?"
+}
+```
+
+**Errors:**
+- 401: 未认证
+- 422: 请求参数无效
+
+---
+
+### GET /users/{username}
+
+按用户名查询用户（需要认证）。
+
+**Path Parameters:**
+- `username`: string (3-30 chars, alphanumeric and underscore)
+
+**Response:** 200 OK
+```json
+{
+  "id": "string",
+  "username": "string",
+  "avatar_url": "string?",
+  "bio": "string?"
+}
+```
+
+**Errors:**
+- 401: 未认证
+- 404: 用户不存在
+- 422: 请求参数无效
+
+---
+
+## Agent Chat
+
+### POST /agent-chats
+
+运行 Agent 对话（需要认证）。
+
+**Request:**
+```json
+{
+  "message": "string (1-8000 chars)",
+  "session_id": "string? (UUID)"
+}
+```
+
+**Response:** 200 OK
+```json
+{
+  "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
+```json
+{
+  "status": "healthy" | "unhealthy",
+  "services": {
+    "redis": {
+      "status": "healthy" | "unhealthy",
+      "latency_ms": 0
+    }
+  }
+}
+```
+
+---
+
+### GET /health
+
+检查服务健康状态。
+
+**Response:** 200 OK
+```json
+{
+  "status": "ok"
+}
+```
+
+---
+
+## Error Response Format (RFC 7807)
+
+所有错误响应使用 `application/problem+json` 格式：
+
+```json
+{
+  "type": "about:blank",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "验证码无效或已过期",
+  "instance": "/api/v1/auth/verifications/verify"
+}
+```
+
+前端应优先读取 `detail` 字段显示给用户。