docs: add API documentation

2026-05-25 23:25:04 +08:00
parent 1093908e87
commit 75c3a19d2e
1 changed files with 248 additions and 0 deletions
@@ -0,0 +1,248 @@
+# AI 发布平台 API 文档
+
+> 基础 URL：`https://www.1415243231.top/api`
+>
+> 所有接口均支持 CORS（`Access-Control-Allow-Origin: *`），可直接从浏览器或任何客户端调用。
+
+---
+
+## 项目接口
+
+### GET /projects
+获取所有项目列表。
+
+**响应示例**
+```json
+[
+  {
+    "id": 1,
+    "name": "我的项目",
+    "description": "项目描述",
+    "createdAt": "2026-05-25T10:00:00",
+    "coverImage": "https://...",   // nullable
+    "reportCount": 3,
+    "todayNewReports": 1
+  }
+]
+```
+
+---
+
+### GET /projects/{id}
+获取指定项目详情。
+
+---
+
+### POST /projects
+创建项目。
+
+**请求体**
+```json
+{
+  "name": "项目名称",       // 必填
+  "description": "描述",
+  "coverImage": "base64或URL"
+}
+```
+
+**响应** `201 Created`
+
+---
+
+### PUT /projects/{id}
+更新项目（支持文件上传）。
+
+**Content-Type**: `multipart/form-data`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | String | 否 | 新名称 |
+| description | String | 否 | 新描述 |
+| coverImage | File | 否 | 封面图片 |
+
+---
+
+### DELETE /projects/{id}
+删除项目（级联删除该项目的所有报告）。
+
+**响应** `204 No Content`
+
+---
+
+## 报告接口
+
+### GET /reports/ping
+健康检查。
+
+**响应**
+```json
+{
+  "version": "v4-diag",
+  "timestamp": "2026-05-25T15:30:00Z"
+}
+```
+
+---
+
+### GET /reports?projectId={id}
+获取报告列表。可选按项目筛选。
+
+**响应示例**
+```json
+[
+  {
+    "id": 1,
+    "projectId": 1,
+    "fileName": "2026-05-25.html",
+    "fileType": "html",
+    "filePath": "/uploads/reports/1.html",
+    "uploadTime": "2026-05-25T10:00:00",
+    "fileContent": null
+  }
+]
+```
+
+---
+
+### GET /reports/{id}
+获取指定报告详情。
+
+---
+
+### POST /reports
+上传报告文件。
+
+**Content-Type**: `multipart/form-data`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file | File | 是 | 报告文件 |
+| projectId | Long | 是 | 所属项目 ID |
+| fileType | String | 是 | 文件类型：`html` `md` `pdf` `ppt` `pptx` |
+
+> 支持的文件扩展名：`.html` `.md` `.pdf` `.ppt` `.pptx`
+
+**响应** `201 Created`
+
+---
+
+### GET /reports/{id}/preview
+预览报告。以合适的 Content-Type 返回文件内容，支持内联展示。
+
+- `html` → `text/html`
+- `md` → `text/markdown`
+- `pdf` → `application/pdf`
+- `ppt/pptx` → 对应 Office 类型
+
+---
+
+### GET /reports/{id}/download
+下载报告。强制以附件形式返回原始文件。
+
+**响应头**
+```
+Content-Disposition: attachment; filename="filename.html"
+```
+
+---
+
+### GET /reports/{id}/pdf
+将报告转为 PDF 返回。目前对所有类型均适用。
+
+**响应** `application/pdf`
+
+---
+
+### PUT /reports/{id}
+更新报告元信息。
+
+**请求体**
+```json
+{
+  "fileName": "新文件名.html",
+  "fileType": "html"
+}
+```
+
+---
+
+### DELETE /reports/{id}
+删除指定报告。
+
+**响应** `204 No Content`
+
+---
+
+## 错误响应格式
+
+所有错误返回 `500 Internal Server Error`，响应体：
+
+```json
+{
+  "error": "文件名: 错误描述",
+  "type": "异常类名"
+}
+```
+
+---
+
+## 调用示例
+
+### cURL
+
+```bash
+# 创建项目
+curl -X POST https://www.1415243231.top/api/projects \
+  -H "Content-Type: application/json" \
+  -d '{"name":"我的项目","description":"测试"}'
+
+# 上传报告
+curl -X POST https://www.1415243231.top/api/reports \
+  -F "file=@./日报.html" \
+  -F "projectId=1" \
+  -F "fileType=html"
+
+# 下载报告
+curl -O https://www.1415243231.top/api/reports/1/download
+
+# 删除项目
+curl -X DELETE https://www.1415243231.top/api/projects/1
+```
+
+### JavaScript (Fetch)
+
+```js
+// 上传报告
+const formData = new FormData()
+formData.append('file', fileInput.files[0])
+formData.append('projectId', 1)
+formData.append('fileType', 'html')
+
+const res = await fetch('https://www.1415243231.top/api/reports', {
+  method: 'POST',
+  body: formData
+})
+const report = await res.json()
+```
+
+### Python (requests)
+
+```python
+import requests
+
+# 创建项目
+r = requests.post('https://www.1415243231.top/api/projects', json={
+    'name': '我的项目',
+    'description': '测试描述'
+})
+print(r.json())
+
+# 上传报告
+r = requests.post('https://www.1415243231.top/api/reports', files={
+    'file': ('日报.html', open('日报.html', 'rb'), 'text/html')
+}, data={
+    'projectId': 1,
+    'fileType': 'html'
+})
+print(r.json())
+```