279 lines
7.9 KiB
Markdown
279 lines
7.9 KiB
Markdown
# 公开定时任务 API
|
||
|
||
本文档描述用于对接外部系统的**公开只读**定时任务接口，以及配套的公开网页入口。所有 `/api/public/*` 接口都**无需登录**，可以直接调用。
|
||
|
||
> ⚠️ 任何接入这套接口的系统需要确认：暴露 task / run 列表与正文是符合贵方业务安全要求的。如果不希望全员可见，请走带鉴权的 `/api/scheduled-tasks/*`。
|
||
|
||
---
|
||
|
||
## 1. 基础信息
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 网关基址（开发） | `http://localhost:8001` |
|
||
| 网关基址（生产） | 部署到 Nginx 后通常是 `https://<你的域名>` |
|
||
| 公开 API 前缀 | `/api/public/scheduled-tasks` |
|
||
| 鉴权 | **无需**鉴权（白名单在 `auth_middleware._PUBLIC_PATH_PREFIXES`） |
|
||
| 编码 | 请求 / 响应均为 UTF-8，响应类型 `application/json`（下载除外） |
|
||
| 错误响应 | 标准 FastAPI 错误体 `{"detail": "..."}`；HTTP 状态码 `404 / 400 / 500` 等 |
|
||
|
||
公开网页页面：
|
||
|
||
```
|
||
#/public/scheduled-tasks/<task_id>
|
||
```
|
||
|
||
例如 `https://<你的域名>/#/public/scheduled-tasks/8f1d8b9c-...`。
|
||
左侧列出该任务所有执行记录，默认打开第一条；右侧默认渲染 Markdown 正文，点击 Tab 可以查看“结果文件”或“元数据”，点击左侧任意记录右侧内容会跟随切换。
|
||
|
||
---
|
||
|
||
## 2. 接口列表
|
||
|
||
### 2.1 列出全部定时任务
|
||
|
||
```
|
||
GET /api/public/scheduled-tasks
|
||
```
|
||
|
||
**Query 参数**
|
||
|
||
| 名称 | 类型 | 必填 | 默认 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `search` | string | 否 | — | 任务名模糊匹配（不区分大小写） |
|
||
| `limit` | int | 否 | 200 | 单页数量，1–500 |
|
||
| `offset` | int | 否 | 0 | 偏移量，配合 `limit` 分页 |
|
||
|
||
**响应**
|
||
|
||
```json
|
||
{
|
||
"total": 12,
|
||
"limit": 200,
|
||
"offset": 0,
|
||
"tasks": [
|
||
{
|
||
"task_id": "8f1d8b9c-...",
|
||
"name": "每日舆情简报",
|
||
"schedule_text": "每天 09:00",
|
||
"cron_expr": "0 9 * * *",
|
||
"timezone": "Asia/Shanghai",
|
||
"enabled": true,
|
||
"next_run_at": "2026-05-21T01:00:00+00:00",
|
||
"last_run_at": "2026-05-20T01:00:12+00:00",
|
||
"last_status": "succeeded",
|
||
"published": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> 已脱敏：`user_id`、`creator_email`、`prompt`、`scheduler_thread_id`、`execution_context` 等私有字段不会出现在公开响应里。
|
||
|
||
### 2.2 获取单个任务元数据
|
||
|
||
```
|
||
GET /api/public/scheduled-tasks/{task_id}
|
||
```
|
||
|
||
**响应**：与上面 `tasks[]` 的元素结构一致；任务不存在返回 `404`。
|
||
|
||
### 2.3 列出某任务的所有执行记录
|
||
|
||
```
|
||
GET /api/public/scheduled-tasks/{task_id}/runs
|
||
```
|
||
|
||
**Query 参数**
|
||
|
||
| 名称 | 类型 | 必填 | 默认 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `limit` | int | 否 | 50 | 最近执行数量，1–200 |
|
||
|
||
**响应**
|
||
|
||
```json
|
||
{
|
||
"task": { "task_id": "...", "name": "...", "schedule_text": "...", "timezone": "...", "enabled": true },
|
||
"total": 7,
|
||
"runs": [
|
||
{
|
||
"id": "run-uuid-...",
|
||
"task_id": "8f1d8b9c-...",
|
||
"scheduled_for": "2026-05-20T01:00:00+00:00",
|
||
"started_at": "2026-05-20T01:00:01+00:00",
|
||
"finished_at": "2026-05-20T01:00:12+00:00",
|
||
"status": "succeeded",
|
||
"error": null,
|
||
"retry_count": 0,
|
||
"result": {
|
||
"title": "2026-05-20 舆情简报",
|
||
"content": "# 简报\n\n...",
|
||
"format": "markdown",
|
||
"files": [
|
||
{ "index": 0, "name": "report.md", "mime_type": "text/markdown", "kind": "markdown", "size": 4321 }
|
||
],
|
||
"created_at": "2026-05-20T01:00:12+00:00"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
> 已脱敏：返回的 `files[]` 不包含服务器绝对路径；客户端通过下标 `index` 调用文件接口。
|
||
|
||
### 2.4 获取单条执行记录
|
||
|
||
```
|
||
GET /api/public/scheduled-tasks/runs/{run_id}
|
||
```
|
||
|
||
返回单条 run 数据（结构同 2.3 中的 `runs[]` 元素）。
|
||
|
||
### 2.5 获取单个结果文件的内容（可预览文本直接内联）
|
||
|
||
```
|
||
GET /api/public/scheduled-tasks/runs/{run_id}/files/{file_index}
|
||
```
|
||
|
||
`file_index` 来自 `run.result.files[].index`。
|
||
|
||
**响应**
|
||
|
||
```json
|
||
{
|
||
"index": 0,
|
||
"name": "report.md",
|
||
"mime_type": "text/markdown",
|
||
"kind": "markdown",
|
||
"size": 4321,
|
||
"previewable": true,
|
||
"content": "# 简报\n\n..."
|
||
}
|
||
```
|
||
|
||
二进制文件 `previewable=false`、`content=null`，请走 2.6 下载。
|
||
|
||
### 2.6 下载单个结果文件
|
||
|
||
```
|
||
GET /api/public/scheduled-tasks/runs/{run_id}/files/{file_index}/download
|
||
```
|
||
|
||
返回原始文件二进制流，附带 `Content-Disposition: attachment` 头部。
|
||
|
||
### 2.7 打包下载整个执行结果
|
||
|
||
```
|
||
GET /api/public/scheduled-tasks/runs/{run_id}/download
|
||
```
|
||
|
||
- 如果该 run **没有附加文件**：直接返回 `result.md`（UTF-8 BOM）。
|
||
- 如果有 ≥ 1 个附加文件：返回 ZIP，里面包含：
|
||
- `result.md` — 标题 + 正文 Markdown
|
||
- 每个生成文件原样
|
||
|
||
---
|
||
|
||
## 3. 调用示例
|
||
|
||
### curl
|
||
|
||
```bash
|
||
# 列出全部任务
|
||
curl -s "https://<domain>/api/public/scheduled-tasks?limit=50"
|
||
|
||
# 查看任务的执行记录
|
||
curl -s "https://<domain>/api/public/scheduled-tasks/<task_id>/runs"
|
||
|
||
# 下载某次执行
|
||
curl -L -o report.zip \
|
||
"https://<domain>/api/public/scheduled-tasks/runs/<run_id>/download"
|
||
```
|
||
|
||
### Python
|
||
|
||
```python
|
||
import requests
|
||
|
||
base = "https://<domain>/api/public/scheduled-tasks"
|
||
|
||
tasks = requests.get(f"{base}", params={"limit": 100, "search": "舆情"}).json()
|
||
for task in tasks["tasks"]:
|
||
runs = requests.get(f"{base}/{task['task_id']}/runs", params={"limit": 5}).json()
|
||
for run in runs["runs"]:
|
||
if run.get("result"):
|
||
print(task["name"], run["id"], run["result"]["title"])
|
||
print(run["result"]["content"][:200])
|
||
```
|
||
|
||
### 直接嵌入 iframe
|
||
|
||
```html
|
||
<iframe src="https://<domain>/#/public/scheduled-tasks/<task_id>"
|
||
style="width:100%;height:800px;border:0"></iframe>
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 状态码
|
||
|
||
| 状态码 | 含义 |
|
||
|---|---|
|
||
| 200 | 成功 |
|
||
| 400 | 参数错误（如 `limit` 超出范围） |
|
||
| 404 | 任务 / 执行 / 文件 不存在 |
|
||
| 5xx | 网关 / 后台错误 |
|
||
|
||
---
|
||
|
||
## 5. 字段映射快查
|
||
|
||
### `task` 字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `task_id` | string | 任务 ID |
|
||
| `name` | string | 任务名 |
|
||
| `schedule_text` | string | 人类可读的执行计划 |
|
||
| `cron_expr` | string | 规范化的 cron 表达式 |
|
||
| `timezone` | string | 时区 |
|
||
| `enabled` | bool | 是否启用 |
|
||
| `next_run_at` | string | null | 下次执行时间（ISO 8601） |
|
||
| `last_run_at` | string | null | 上次执行时间 |
|
||
| `last_status` | string | null | 上次执行状态（`succeeded` / `failed` / `running` / `pending` / `…`） |
|
||
| `published` | bool | 是否被发布到广场 |
|
||
|
||
### `run` 字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `id` | string | 执行 ID |
|
||
| `task_id` | string | 所属任务 ID |
|
||
| `scheduled_for` | string | 原定执行时间 |
|
||
| `started_at` | string | null | 实际开始时间 |
|
||
| `finished_at` | string | null | 完成 / 失败时间 |
|
||
| `status` | string | `pending` / `running` / `succeeded` / `failed` |
|
||
| `error` | string | null | 失败描述 |
|
||
| `retry_count` | int | null | 重试次数 |
|
||
| `result` | object | null | 执行结果（见下） |
|
||
|
||
### `result` 字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `title` | string | 结果标题 |
|
||
| `content` | string | 主体 Markdown / 文本 |
|
||
| `format` | string | `markdown` / `text` / `json` / `mixed` |
|
||
| `files[]` | array | 附加文件元数据，含 `index / name / mime_type / kind / size` |
|
||
| `created_at` | string | 结果生成时间 |
|
||
|
||
---
|
||
|
||
## 6. 实现位置
|
||
|
||
- 路由实现：[`app/gateway/routers/public_scheduled_tasks.py`](../app/gateway/routers/public_scheduled_tasks.py)
|
||
- 公开 URL 白名单：[`app/gateway/auth_middleware.py`](../app/gateway/auth_middleware.py) 中的 `_PUBLIC_PATH_PREFIXES`
|
||
- 前端公开页面：[`frontend-web/src/pages/PublicScheduledTaskPage.tsx`](../../../frontend-web/src/pages/PublicScheduledTaskPage.tsx)
|
||
- 路由注册：[`frontend-web/src/App.tsx`](../../../frontend-web/src/App.tsx) `/#/public/scheduled-tasks/:taskId`
|