261 lines
4.7 KiB
Markdown
261 lines
4.7 KiB
Markdown
# 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": "/uploads/covers/1/abc123.jpg", // 相对路径，访问时需加域名
|
||
"reportCount": 3,
|
||
"todayNewReports": 1
|
||
}
|
||
]
|
||
```
|
||
|
||
> `coverImage` 字段为相对路径，完整访问地址为 `https://www.1415243231.top/uploads/covers/1/abc123.jpg`
|
||
|
||
---
|
||
|
||
### 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`
|
||
|
||
---
|
||
|
||
## 静态资源路径说明
|
||
|
||
`coverImage` 字段为后端存储的相对路径，需拼接完整 URL 才能在浏览器中访问：
|
||
|
||
| 字段 | 相对路径示例 | 完整访问地址 |
|
||
|------|------------|------------|
|
||
| coverImage | `/uploads/covers/1/abc.jpg` | `https://www.1415243231.top/uploads/covers/1/abc.jpg` |
|
||
|
||
---
|
||
|
||
## 错误响应格式
|
||
|
||
所有错误返回 `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())
|
||
```
|