初始化2

2026-04-08 17:10:58 +08:00
commit 4986d90eb9
532 changed files with 112617 additions and 0 deletions
--- a/public/docs/api-reference.md
+++ b/public/docs/api-reference.md
@@ -0,0 +1,189 @@
+# REST API 完整参考
+
+> 200+ 标准接口文档，覆盖用户、内容、AI、支付等全部模块。
+
+## 📚 API 概览
+
+**基础 URL：** `https://api.websopy.com/v1`
+
+**认证方式：** Bearer Token
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_KEY" \
+     https://api.websopy.com/v1/user/profile
+```
+
+## 📋 端点列表
+
+### 用户管理 `/user`
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/user/profile` | 获取当前用户信息 |
+| PUT | `/user/profile` | 更新用户信息 |
+| GET | `/user/settings` | 获取用户设置 |
+| PUT | `/user/settings` | 更新用户设置 |
+| POST | `/user/avatar` | 上传头像 |
+
+### 项目管理 `/projects`
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/projects` | 列出项目 |
+| POST | `/projects` | 创建项目 |
+| GET | `/projects/:id` | 获取项目详情 |
+| PUT | `/projects/:id` | 更新项目 |
+| DELETE | `/projects/:id` | 删除项目 |
+| GET | `/projects/:id/members` | 获取项目成员 |
+| POST | `/projects/:id/members` | 添加成员 |
+
+### 文件存储 `/storage`
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/storage/files` | 列出文件 |
+| POST | `/storage/upload` | 上传文件 |
+| GET | `/storage/files/:id` | 获取文件信息 |
+| DELETE | `/storage/files/:id` | 删除文件 |
+| GET | `/storage/files/:id/download` | 下载文件 |
+
+### AI 功能 `/ai`
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| POST | `/ai/chat` | 发送对话请求 |
+| POST | `/ai/chat/stream` | 流式对话 |
+| GET | `/ai/sessions` | 列出会话 |
+| POST | `/ai/sessions` | 创建会话 |
+| GET | `/ai/sessions/:id` | 获取会话详情 |
+| DELETE | `/ai/sessions/:id` | 删除会话 |
+| POST | `/ai/knowledge` | 创建知识库 |
+| POST | `/ai/knowledge/:id/documents` | 添加文档 |
+
+### 支付 `/payments`
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/payments/orders` | 列出订单 |
+| POST | `/payments/orders` | 创建订单 |
+| GET | `/payments/orders/:id` | 订单详情 |
+| POST | `/payments/checkout` | 创建结算会话 |
+| GET | `/payments/subscriptions` | 订阅列表 |
+
+## 🔍 请求与响应
+
+### 请求头
+
+```http
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+Accept: application/json
+X-Request-ID: unique-request-id
+```
+
+### 分页
+
+```http
+GET /projects?page=2&limit=20
+```
+
+响应包含分页信息：
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "limit": 20,
+    "total": 100,
+    "total_pages": 5
+  }
+}
+```
+
+### 排序
+
+```http
+GET /projects?sort=created_at&order=desc
+```
+
+### 过滤
+
+```http
+GET /projects?status=active&category=ai
+```
+
+## 📝 错误处理
+
+### 错误码
+
+| 状态码 | 错误码 | 说明 |
+|--------|--------|------|
+| 400 | `INVALID_REQUEST` | 请求参数错误 |
+| 401 | `UNAUTHORIZED` | 未认证或 Token 无效 |
+| 403 | `FORBIDDEN` | 无权限访问 |
+| 404 | `NOT_FOUND` | 资源不存在 |
+| 429 | `RATE_LIMITED` | 请求过于频繁 |
+| 500 | `SERVER_ERROR` | 服务器内部错误 |
+
+### 错误响应格式
+
+```json
+{
+  "error": {
+    "code": "INVALID_REQUEST",
+    "message": "参数 'name' 不能为空",
+    "details": {
+      "field": "name",
+      "constraint": "required"
+    }
+  }
+}
+```
+
+## 🔧 使用示例
+
+### JavaScript/TypeScript
+
+```typescript
+const response = await fetch('https://api.websopy.com/v1/projects', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    name: '我的项目',
+    description: '项目描述'
+  })
+})
+
+const data = await response.json()
+console.log(data)
+```
+
+### Python
+
+```python
+import requests
+
+response = requests.post(
+    'https://api.websopy.com/v1/projects',
+    headers={
+        'Authorization': f'Bearer {api_key}',
+        'Content-Type': 'application/json'
+    },
+    json={
+        'name': '我的项目',
+        'description': '项目描述'
+    }
+)
+
+data = response.json()
+print(data)
+```
+
+---
+
+**上一步：** [Webhook 事件接入](./webhook.md)  
+**下一步：** [RAG 知识库搭建](./rag.md)