# 日报分发平台 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": "..." } ``` --- ### 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 是否正确）