# 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())
```