social-app/docs/runtime/runtime-route.md

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)",
  "invite_code": "string? (8 chars, 排除易混淆字符 0/1/I/L/O)"
}

Response: 202 Accepted

{
  "email": "user@example.com"
}

邀请码说明：

• 可选字段，不填则注册不受影响
• 格式：8 位字母数字组合，排除易混淆字符 (0, 1, I, L, O)
• 注册时传入有效邀请码会建立邀请关系并增加邀请码使用次数
• 无效邀请码（不存在/已禁用/已过期/已达上限）不会阻断注册成功

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: 请求参数无效

---

Schedule Items

POST /schedule-items

创建日历事项（需要认证）。

Request:

{
  "title": "string (1-255 chars, required)",
  "description": "string? (max 2000 chars)",
  "start_at": "string (ISO 8601 datetime, required)",
  "end_at": "string? (ISO 8601 datetime)",
  "timezone": "string? (default: UTC)",
  "metadata": {
    "color": "#FF6B6B",
    "location": "会议室A",
    "notes": "记得带身份证",
    "attachments": [],
    "version": 1
  }
}

Response: 201 Created

{
  "id": "uuid",
  "title": "string",
  "description": "string?",
  "start_at": "string",
  "end_at": "string?",
  "timezone": "string",
  "metadata": {},
  "status": "active",
  "source_type": "manual",
  "created_at": "string",
  "updated_at": "string"
}

Errors:

• 400: end_at 早于 start_at
• 401: 未认证
• 503: 服务不可用

---

GET /schedule-items

按时间范围查询日历事项列表（需要认证）。

Query Parameters:

• start_at: ISO 8601 date/datetime（查询范围起始）
• end_at: ISO 8601 date/datetime（查询范围结束）

Response: 200 OK

[
  {
    "id": "uuid",
    "title": "string",
    "start_at": "string",
    "end_at": "string?",
    "timezone": "string",
    "status": "active"
  }
]

Errors:

• 400: end_at 早于 start_at
• 401: 未认证

---

GET /schedule-items/{id}

获取单个日历事项详情（需要认证）。

Response: 200 OK

Errors:

• 401: 未认证
• 404: 事项不存在

---

PATCH /schedule-items/{id}

更新日历事项（需要认证）。

Request: 支持 title/description/start_at/end_at/timezone/metadata/status 部分更新

Response: 200 OK

Errors:

• 401: 未认证
• 404: 事项不存在

---

DELETE /schedule-items/{id}

删除日历事项（软删除，需要认证）。

Response: 204 No Content

Errors:

• 401: 未认证
• 404: 事项不存在

---

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 字段显示给用户。