daily_publish/docs/api.md

日报分发平台 API 文档

本文档面向人工阅读和 AI Agent 调用。接口均 REST 风格，JSON 格式（除文件下载外）。

---

基础信息

本地开发: http://localhost:37821 Docker 部署: http://<服务器IP>:41733（前端代理到后端）

Docker 部署时，前端（41733）会自动将 /api/* 和 /uploads/* 请求转发到后端，无需单独访问后端端口。

认证: 当前接口均无需认证（开放接口）

---

1. 项目管理

1.1 获取所有项目

请求

GET /api/projects

Python

import requests
resp = requests.get("http://192.168.31.240:41733/api/projects")
print(resp.json())

curl

curl http://192.168.31.240:41733/api/projects

响应 200 OK

[
  {
    "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

{
  "name": "项目名称",
  "description": "项目描述"
}

Python

import requests
resp = requests.post(
    "http://192.168.31.240:41733/api/projects",
    json={"name": "新项目", "description": "描述"}
)
print(resp.json())

curl

curl -X POST http://192.168.31.240:41733/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"新项目","description":"描述"}'

响应 201 Created

{
  "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

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

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

import requests
requests.delete("http://192.168.31.240:41733/api/projects/1")

curl

curl -X DELETE http://192.168.31.240:41733/api/projects/1

响应 204 No Content（成功无返回体）

---

2. 报告管理

2.1 获取项目下的报告列表

请求

GET /api/reports?projectId={projectId}

Python

import requests
resp = requests.get("http://192.168.31.240:41733/api/reports?projectId=1")
print(resp.json())

curl

curl "http://192.168.31.240:41733/api/reports?projectId=1"

响应 200 OK

[
  {
    "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

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

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

{
  "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

import requests
resp = requests.get("http://192.168.31.240:41733/api/reports/1")
data = resp.json()
print(data['fileContent'])  # HTML/MD 文件的原文内容

curl

curl http://192.168.31.240:41733/api/reports/1

响应 200 OK

{
  "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

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

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

import requests
requests.delete("http://192.168.31.240:41733/api/reports/1")

curl

curl -X DELETE http://192.168.31.240:41733/api/reports/1

响应 204 No Content

---

3. 健康检查

请求

GET /actuator/health

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 是否正确）