# doc-service 接口说明

> 面向 AI Agent 的文档托管服务调用指南。Agent 可将生成的报告、分析结果发布为公开可访问的页面链接，再将链接返回给用户。

---

## 1. 服务概述

`doc-service` 是一个轻量级文档托管服务，支持上传 **HTML** 或 **Markdown** 文档，系统返回一个 8 位短链接（pageKey），通过该链接可直接在浏览器访问/渲染文档内容。

**典型工作流（Agent 调用）：**

```
Agent 生成报告内容（HTML 或 Markdown）
    ↓
POST /doc-service/api/md-page/uploadContent  （携带 token）
    ↓
获取返回值中的 viewUrl
    ↓
将 viewUrl 告知用户，用户直接在浏览器打开
```

---

## 2. 服务地址

**公网地址：** `https://www.doc-service.cn`

所有接口均以此地址为前缀，例如：

```
https://www.doc-service.cn/doc-service/api/md-page/uploadContent
https://www.doc-service.cn/doc-service/view/md-page/{pageKey}
```

> 上传接口返回的 `viewUrl` 字段已包含完整可访问链接，无需手动拼接。

---

## 3. 鉴权说明

| 操作 | 是否需要鉴权 | Header |
|------|------------|--------|
| 上传（upload） | **需要** | `Authorization: Bearer {token}` |
| 删除（delete） | **需要** | `Authorization: Bearer {token}` |
| 访问（view） | **不需要** | 无，任何人可直接访问 |

**获取 token：** 发邮件至 dingdongchaoxiao@gmail.com 申请，注明用途，管理员将生成并提供专属 token。

获得 token 后，所有需鉴权的接口在 Header 中添加：

```
Authorization: Bearer <your_token>
```

> token 长期有效，由管理员统一管理，可按需禁用或重新生成。

---

## 4. 接口清单

### HTML 文档

| 接口 | 方法 | 路径 | 鉴权 |
|------|------|------|------|
| 上传 HTML 字符串 | POST | `/doc-service/api/html-page/uploadContent` | Bearer token |
| 上传 HTML 文件 | POST | `/doc-service/api/html-page/uploadFile` | Bearer token |
| 访问 HTML 页面 | GET  | `/doc-service/view/html-page/{pageKey}` | 无需 |
| 删除 HTML 页面 | POST | `/doc-service/api/html-page/delete` | Bearer token |

### Markdown 文档

| 接口 | 方法 | 路径 | 鉴权 |
|------|------|------|------|
| 上传 MD 字符串 | POST | `/doc-service/api/md-page/uploadContent` | Bearer token |
| 上传 MD 文件 | POST | `/doc-service/api/md-page/uploadFile` | Bearer token |
| 访问 MD 渲染页 | GET  | `/doc-service/view/md-page/{pageKey}` | 无需 |
| 访问 MD 源码 | GET  | `/doc-service/view/md-source/{pageKey}` | 无需 |
| 删除 MD 页面 | POST | `/doc-service/api/md-page/delete` | Bearer token |

---

## 5. 接口参数详情

### 5.1 uploadContent（上传内容字符串）

**路径：**
- HTML：`POST /doc-service/api/html-page/uploadContent`
- MD：`POST /doc-service/api/md-page/uploadContent`

**Query 参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `title` | String | 否 | 文档标题，默认 `未命名文档_时间戳` |
| `expireHours` | Integer | 否 | 有效期小时数，默认 `8760`（365 天） |

**请求体：** 文档内容字符串，`Content-Type: text/plain`

**返回值（外层 Result 包装）：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "success": true,
    "message": "上传成功",
    "pageKey": "x5HVJdk7",
    "viewUrl": "https://www.doc-service.cn/doc-service/view/html-page/x5HVJdk7",
    "title": "我的报告",
    "fileSize": 1024,
    "pageType": "html"
  }
}
```

**关键字段：** `data.viewUrl` 即为可直接访问的公开链接；`data.pageKey` 用于后续删除。

---

### 5.2 uploadFile（上传文件）

**路径：**
- HTML：`POST /doc-service/api/html-page/uploadFile`
- MD：`POST /doc-service/api/md-page/uploadFile`

**Multipart 参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | MultipartFile | **是** | 文件内容 |
| `title` | String | 否 | 文档标题，默认使用原始文件名 |
| `expireHours` | Integer | 否 | 有效期小时数，默认 8760 |

**返回值：** 同 uploadContent。

---

### 5.3 delete（软删除）

**路径：**
- HTML：`POST /doc-service/api/html-page/delete`
- MD：`POST /doc-service/api/md-page/delete`

**请求体（JSON body，注意不是 query 参数）：**

```json
{"pageKey": "x5HVJdk7"}
```

**Content-Type：** `application/json`

**返回值：**

```json
{"code": 200, "message": "success", "data": null}
```

> 删除为软删除，仅标记 `pageStatus=deleted`，内容保留在数据库。

---

### 5.4 view（访问页面，无需鉴权）

| 路径 | 返回内容 | Content-Type |
|------|----------|-------------|
| `/doc-service/view/html-page/{pageKey}` | 原始 HTML 内容 | `text/html` |
| `/doc-service/view/md-page/{pageKey}` | Markdown 渲染后的 HTML 页面（含内联样式） | `text/html` |
| `/doc-service/view/md-source/{pageKey}` | 原始 Markdown 文本 | `text/plain` |

**错误状态码：**
- `404`：pageKey 不存在或已被删除
- `410 Gone`：页面已过期

---

## 6. 完整调用示例（curl）

将 `<TOKEN>` 替换为实际 token。

### 上传 Markdown（Agent 最常用）

```bash
curl -X POST "https://www.doc-service.cn/doc-service/api/md-page/uploadContent?title=Analysis" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: text/plain" \
  --data-raw "# Analysis Report

## Summary
- Point 1
- Point 2

## Data Table
| Metric | Value |
|--------|-------|
| A | 100 |
| B | 200 |
"
```

返回后取 `data.viewUrl` 告知用户即可。

### 上传 HTML

```bash
curl -X POST "https://www.doc-service.cn/doc-service/api/html-page/uploadContent?title=Report" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: text/plain" \
  --data-raw "<html><body><h1>Report</h1><p>Content here.</p></body></html>"
```

### 上传文件

```bash
curl -X POST "https://www.doc-service.cn/doc-service/api/md-page/uploadFile" \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@/path/to/report.md" \
  -F "title=My Report"
```

### 访问页面（无需 token）

```bash
# Markdown 渲染为 HTML（推荐浏览器打开）
curl "https://www.doc-service.cn/doc-service/view/md-page/x5HVJdk7"

# 原始 Markdown 源码
curl "https://www.doc-service.cn/doc-service/view/md-source/x5HVJdk7"

# 原始 HTML
curl "https://www.doc-service.cn/doc-service/view/html-page/x5HVJdk7"
```

### 删除页面（JSON body）

```bash
curl -X POST "https://www.doc-service.cn/doc-service/api/html-page/delete" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"pageKey": "x5HVJdk7"}'
```

---

## 7. Agent 使用注意事项

1. **优先使用 Markdown**：`/md-page/` 接口自动渲染为带样式的 HTML 页面，呈现效果更好。
2. **title 含中文须 URL 编码**：query 参数中的中文需 URL encode（如 `%E6%8A%A5%E5%91%8A`），HTTP 库通常自动处理。
3. **delete 用 JSON body**：删除接口 body 为 `{"pageKey": "..."}` + `Content-Type: application/json`，**不是** query 参数。
4. **保存 pageKey**：上传后记录 `data.pageKey`，以便后续删除或引用。
5. **视图接口完全公开**：`/view/` 路径无需任何 header，可直接嵌入 `<iframe>` 或分享。
6. **有效期**：默认 1 年（8760 小时）；到期后访问返回 `410 Gone`。