fix: FilePreview fileType case + Tailwind v4 gradient transparent bug
- FilePreview.vue: add normalizedFileType computed to handle backend returning uppercase HTML/MD/PPTX (fixes preview/download buttons) - FilePreview.vue: bg-gradient-to-r from-orange-500 -> bg-orange-500 (Tailwind v4 gradient + CSS variable = transparent) - ReportCard.vue: bg-gradient-to-r -> bg-orange-600 for selected state - Add .opencode/, node_modules/, dist/ to .gitignore - Initial git setup for publish project
This commit is contained in:
+403
@@ -0,0 +1,403 @@
|
||||
# 日报分发平台 API 文档
|
||||
|
||||
本文档面向人工阅读和 AI Agent 调用。接口均 REST 风格，JSON 格式（除文件下载外）。
|
||||
|
||||
---
|
||||
|
||||
## 基础信息
|
||||
|
||||
**本地开发**: `http://localhost:37821`
|
||||
**Docker 部署**: `http://<服务器IP>:41733`（前端代理到后端）
|
||||
|
||||
> Docker 部署时，前端（41733）会自动将 `/api/*` 和 `/uploads/*` 请求转发到后端，无需单独访问后端端口。
|
||||
|
||||
**认证**: 当前接口均无需认证（开放接口）
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目管理
|
||||
|
||||
### 1.1 获取所有项目
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
GET /api/projects
|
||||
```
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
resp = requests.get("http://192.168.31.240:41733/api/projects")
|
||||
print(resp.json())
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl http://192.168.31.240:41733/api/projects
|
||||
```
|
||||
|
||||
**响应** `200 OK`
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "MiniMax 日报",
|
||||
"description": "MiniMax 日报分发",
|
||||
"coverImage": null,
|
||||
"createdAt": "2026-05-24T11:23:28.734",
|
||||
"reportCount": 1,
|
||||
"todayNewReports": 1
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Long | 项目 ID |
|
||||
| name | String | 项目名称 |
|
||||
| description | String | 项目描述 |
|
||||
| coverImage | String? | 封面图片 URL，无则为 null |
|
||||
| createdAt | String | 创建时间（ISO 8601） |
|
||||
| reportCount | Integer | 该项目报告总数 |
|
||||
| todayNewReports | Integer | 今日新增报告数 |
|
||||
|
||||
---
|
||||
|
||||
### 1.2 创建项目
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST /api/projects
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Body**
|
||||
```json
|
||||
{
|
||||
"name": "项目名称",
|
||||
"description": "项目描述"
|
||||
}
|
||||
```
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
resp = requests.post(
|
||||
"http://192.168.31.240:41733/api/projects",
|
||||
json={"name": "新项目", "description": "描述"}
|
||||
)
|
||||
print(resp.json())
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl -X POST http://192.168.31.240:41733/api/projects \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"新项目","description":"描述"}'
|
||||
```
|
||||
|
||||
**响应** `201 Created`
|
||||
```json
|
||||
{
|
||||
"id": 2,
|
||||
"name": "新项目",
|
||||
"description": "描述",
|
||||
"coverImage": null,
|
||||
"createdAt": "2026-05-24T11:33:34.658",
|
||||
"reportCount": 0,
|
||||
"todayNewReports": 0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1.3 更新项目（含封面上传）
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
PUT /api/projects/{projectId}
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
**表单字段**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| name | String | 否 | 项目新名称 |
|
||||
| description | String | 否 | 项目描述 |
|
||||
| coverImage | File | 否 | 封面图片，支持 jpg/png/webp/gif |
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
resp = requests.put(
|
||||
"http://192.168.31.240:41733/api/projects/1",
|
||||
data={"name": "新名称"},
|
||||
files={"coverImage": open("cover.png", "rb")}
|
||||
)
|
||||
print(resp.json())
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl -X PUT http://192.168.31.240:41733/api/projects/1 \
|
||||
-F "name=新名称" \
|
||||
-F "coverImage=@cover.png"
|
||||
```
|
||||
|
||||
**响应** `200 OK` — 返回更新后的项目对象，字段同 1.1
|
||||
|
||||
---
|
||||
|
||||
### 1.4 删除项目
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
DELETE /api/projects/{projectId}
|
||||
```
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
requests.delete("http://192.168.31.240:41733/api/projects/1")
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl -X DELETE http://192.168.31.240:41733/api/projects/1
|
||||
```
|
||||
|
||||
**响应** `204 No Content`（成功无返回体）
|
||||
|
||||
---
|
||||
|
||||
## 2. 报告管理
|
||||
|
||||
### 2.1 获取项目下的报告列表
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
GET /api/reports?projectId={projectId}
|
||||
```
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
resp = requests.get("http://192.168.31.240:41733/api/reports?projectId=1")
|
||||
print(resp.json())
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl "http://192.168.31.240:41733/api/reports?projectId=1"
|
||||
```
|
||||
|
||||
**响应** `200 OK`
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"projectId": 1,
|
||||
"fileName": "MiniMax_Daily_2026-05-23.html",
|
||||
"fileType": "HTML",
|
||||
"filePath": "/app/uploads/1/1779622289908_MiniMax_Daily_2026-05-23.html",
|
||||
"uploadTime": "2026-05-24T11:31:29.919",
|
||||
"fileContent": null
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Long | 报告 ID |
|
||||
| projectId | Long | 所属项目 ID |
|
||||
| fileName | String | 文件名（含扩展名） |
|
||||
| fileType | String | 文件类型：`HTML` / `MD` / `PPTX` 等 |
|
||||
| filePath | String | 服务器存储路径 |
|
||||
| uploadTime | String | 上传时间（ISO 8601） |
|
||||
| fileContent | String? | 文件内容（列表中为 null，详情接口有值） |
|
||||
|
||||
---
|
||||
|
||||
### 2.2 上传报告文件
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST /api/reports
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
**表单字段**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| file | File | 是 | 报告文件本体 |
|
||||
| projectId | Long | 是 | 上传到哪个项目 ID |
|
||||
| fileType | String | 是 | 文件类型，取值：`HTML` / `MD` / `PPTX` |
|
||||
|
||||
**文件类型对应关系**
|
||||
|
||||
| fileType | 对应扩展名 | 说明 |
|
||||
|----------|-----------|------|
|
||||
| HTML | .html | 网页格式，推荐 |
|
||||
| MD | .md | Markdown 格式 |
|
||||
| PPTX | .pptx | PowerPoint 格式 |
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
resp = requests.post(
|
||||
"http://192.168.31.240:41733/api/reports",
|
||||
data={"projectId": 1, "fileType": "HTML"},
|
||||
files={"file": ("日报.html", open("日报.html", "rb"), "text/html")}
|
||||
)
|
||||
print(resp.json())
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl -X POST http://192.168.31.240:41733/api/reports \
|
||||
-F "file=@日报.html" \
|
||||
-F "projectId=1" \
|
||||
-F "fileType=HTML"
|
||||
```
|
||||
|
||||
> 注意：`requests.post(url, data={...}, files={...})` 中，`projectId` 和 `fileType` 放在 `data` 中，文件放在 `files` 中。错误示例：放在同一个 dict 中。
|
||||
|
||||
**响应** `201 Created`
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"projectId": 1,
|
||||
"fileName": "MiniMax_Daily_2026-05-23.html",
|
||||
"fileType": "HTML",
|
||||
"filePath": "/app/uploads/1/1779622289908_MiniMax_Daily_2026-05-23.html",
|
||||
"uploadTime": "2026-05-24T11:31:29.919",
|
||||
"fileContent": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.3 获取报告详情（含文件内容）
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
GET /api/reports/{reportId}
|
||||
```
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
resp = requests.get("http://192.168.31.240:41733/api/reports/1")
|
||||
data = resp.json()
|
||||
print(data['fileContent']) # HTML/MD 文件的原文内容
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl http://192.168.31.240:41733/api/reports/1
|
||||
```
|
||||
|
||||
**响应** `200 OK`
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"projectId": 1,
|
||||
"fileName": "MiniMax_Daily_2026-05-23.html",
|
||||
"fileType": "HTML",
|
||||
"filePath": "/app/uploads/1/1779622289908_MiniMax_Daily_2026-05-23.html",
|
||||
"uploadTime": "2026-05-24T11:31:29.919",
|
||||
"fileContent": "<!DOCTYPE html><html>...</html>"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.4 下载报告原始文件
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
GET /api/reports/{reportId}/download
|
||||
```
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
resp = requests.get("http://192.168.31.240:41733/api/reports/1/download")
|
||||
with open("report.html", "wb") as f:
|
||||
f.write(resp.content)
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl -o report.html http://192.168.31.240:41733/api/reports/1/download
|
||||
```
|
||||
|
||||
**响应** `200 OK`，Body 为文件的原始字节流（`application/octet-stream`）
|
||||
|
||||
---
|
||||
|
||||
### 2.5 删除报告
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
DELETE /api/reports/{reportId}
|
||||
```
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
requests.delete("http://192.168.31.240:41733/api/reports/1")
|
||||
```
|
||||
|
||||
**curl**
|
||||
```bash
|
||||
curl -X DELETE http://192.168.31.240:41733/api/reports/1
|
||||
```
|
||||
|
||||
**响应** `204 No Content`
|
||||
|
||||
---
|
||||
|
||||
## 3. 健康检查
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
GET /actuator/health
|
||||
```
|
||||
|
||||
**Python**
|
||||
```python
|
||||
import requests
|
||||
resp = requests.get("http://192.168.31.240:41733/actuator/health")
|
||||
print(resp.json()) # {"status": "UP"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 错误码
|
||||
|
||||
| HTTP 状态 | 说明 |
|
||||
|-----------|------|
|
||||
| 200 | 成功 |
|
||||
| 201 | 创建成功 |
|
||||
| 204 | 删除成功（无返回体） |
|
||||
| 400 | 参数错误（如 fileType 不支持） |
|
||||
| 404 | 项目或报告不存在 |
|
||||
| 500 | 服务器错误 |
|
||||
|
||||
常见 500 错误原因：
|
||||
- `MissingServletRequestParameterException`: 缺少必填参数（如上传时缺少 `projectId` 或 `fileType`）
|
||||
- `MultipartException`: 请求不是 multipart 格式（上传接口必须用 `multipart/form-data`）
|
||||
- `NoResourceFoundException`: 接口路径不存在（确认 URL 是否正确）
|
||||
Reference in New Issue
Block a user