congsh/dataClean
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
778ccefb220dc7730833dfa4571ee0307167c683
dataClean/API.md
T

435 lines
10 KiB
Markdown
Raw Normal View History

feat: 任务进度实时展示、接口测试、暗色主题重构及多项 bug 修复
2026-06-14 15:14:40 +08:00
# dataClean 接口文档
> 服务地址：`http://<host>:7331`
> 所有 `/api/*` 接口（除 `/health`）在配置了 `API_TOKEN` 时需要在请求头携带 `Authorization: Bearer <token>`。
## 目录
- [鉴权](#鉴权)
- [健康检查](#健康检查)
- [文章接口](#文章接口)
- [简报接口](#简报接口)
- [分类体系接口](#分类体系接口)
- [任务接口](#任务接口)
- [任务进度](#任务进度)
- [接口连通性测试](#接口连通性测试)
- [配置管理接口](#配置管理接口)
- [仪表盘统计](#仪表盘统计)
- [错误码](#错误码)
---
## 鉴权
若服务端配置了 `API_TOKEN`，除 `/health` 外所有接口需要在请求头携带：
```
Authorization: Bearer <API_TOKEN>
```
未携带或 token 无效时返回 `401` / `403`。未配置 `API_TOKEN` 时不启用鉴权（仅建议内网使用）。
---
## 健康检查
### `GET /health`
服务存活探针，无需鉴权。
**响应**
```json
{ "status": "ok", "service": "dataClean" }
```
---
## 文章接口
### `GET /api/articles`
分页查询加工后的文章，支持按日期、分类、标签过滤。
**查询参数**
| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `date` | string | 否 | - | 日期 `YYYY-MM-DD`，按 `fetched_at` 过滤当天 |
| `category` | string | 否 | - | 精确分类名 |
| `tag` | string | 否 | - | 标签名（JSON 数组精确匹配） |
| `representative_only` | bool | 否 | `false` | 仅返回重复组代表文章 |
| `limit` | int | 否 | `50` | 1–200 |
| `offset` | int | 否 | `0` | 分页偏移 |
**响应** `ArticleListOut`
```json
{
"total": 200,
"items": [
{
"id": 1,
"rk_article_id": 28124,
"title": "文章标题",
"link": "https://...",
"feed_title": "来源",
"category": "科技",
"tags": ["AI", "芯片"],
"heat_score": 45.2,
"importance_score": 60.0,
"duplication_score": 25.0,
"composite_score": 52.56,
"ai_summary": "AI 生成的摘要",
"is_representative": false,
"published_at": "2026-06-13T13:48:42"
}
]
}
```
### `GET /api/articles/{article_id}`
获取单篇文章详情。
**路径参数** `article_id`：int
**响应** `ArticleOut`（同上 items 元素）
**错误** `404` 文章不存在
---
## 简报接口
### `GET /api/briefs`
列出每日简报（按日期倒序）。
**查询参数** `limit`：int，默认 30，范围 1–100
**响应** `List[BriefOut]`
```json
[
{
"id": 1,
"brief_date": "2026-06-13",
"total_articles": 200,
"unique_articles": 150,
"by_category": { "科技": [{...}], "财经": [{...}] },
"markdown_path": "/app/data/briefs/2026-06-13/daily-brief.md"
}
]
```
### `GET /api/briefs/{date}`
获取指定日期简报。
**路径参数** `date`：string，`YYYY-MM-DD`
**响应** `BriefOut`　**错误** `404` 简报不存在
### `POST /api/briefs/{date}/regenerate`
强制重新生成指定日期简报。同步执行（需持任务锁）。
**响应**
```json
{ "message": "简报已重新生成", "data": { ... } }
```
**错误** `409` 已有任务执行中
---
## 分类体系接口
### `GET /api/taxonomy`
列出分类/标签/打分规则。
**查询参数** `kind`：string，可选，过滤类型：`category` / `tag` / `heat_rule` / `importance_rule` / `duplication_rule`
**响应** `List[TaxonomyOut]`
```json
[
{
"id": 1,
"name": "科技",
"kind": "category",
"description": "人工智能、芯片、互联网等",
"keywords": ["AI", "芯片", "大模型"],
"weight": 1.0,
"created_by_ai": true
}
]
```
### `POST /api/taxonomy/bootstrap`
初始化或强制重建分类体系（后台异步执行）。
**查询参数** `force`：bool，默认 `false`。`true` 时清空后重建。
**响应**（立即返回）
```json
{ "message": "taxonomy 初始化已开始", "task_key": "bootstrap_taxonomy" }
```
**错误** `409` 已有任务执行中。可通过 [`GET /api/tasks/progress`](#任务进度) 查看 `bootstrap_taxonomy` 进度。
---
## 任务接口
所有任务接口均为**后台异步执行**：提交后立即返回 `task_key`，任务在线程池执行，通过[进度接口](#任务进度)轮询。
任务全局互斥（共享 `_task_lock`）：同一时刻仅一个任务运行。
### `POST /api/tasks/summarize`
拉取 rssKeeper 最近 24 小时文章，为无摘要/短摘要文章生成 AI 摘要。
**响应**
```json
{ "message": "摘要任务已开始", "task_key": "summarize" }
```
**错误** `409` 已有任务执行中
### `POST /api/tasks/tag-score-dedup`
对当天文章执行：分类打标 → 去重 → 打分（三阶段，进度合并显示）。
**响应**
```json
{ "message": "分类/去重/打分任务已开始", "task_key": "tag_score_dedup" }
```
### `POST /api/tasks/brief`
生成当天每日简报（force 重新生成）。
**响应**
```json
{ "message": "简报生成任务已开始", "task_key": "generate_daily_brief" }
```
---
## 任务进度
### `GET /api/tasks/progress`
返回所有任务的实时进度快照（前端每 ~1.5 秒轮询）。
**响应**
```json
{
"summarize": {
"status": "running",
"stage": "生成摘要",
"current": 75,
"total": 200,
"message": null,
"started_at": "2026-06-13T14:30:00+00:00",
"updated_at": "2026-06-13T14:32:15+00:00",
"finished_at": null,
"trigger": "manual"
},
"tag_score_dedup": { "status": "idle", "stage": "", "current": 0, "total": 0, "message": null, "started_at": null, "updated_at": null, "finished_at": null, "trigger": null },
"generate_daily_brief": { "..." : "同上结构" },
"bootstrap_taxonomy": { "..." : "同上结构" }
}
```
**字段说明**
| 字段 | 说明 |
|------|------|
| `status` | `idle` / `running` / `success` / `error` |
| `stage` | 当前阶段文案（如「生成摘要」「LLM 生成分类体系」） |
| `current` / `total` | 进度计数，`total=0` 时为阶段型任务（用 indeterminate 进度条） |
| `message` | 附加信息或错误详情（`status=error` 时为错误信息） |
| `started_at` / `finished_at` | ISO 8601 时间戳 |
| `trigger` | `manual`（手动触发）/ `scheduled`（定时触发） |
### `POST /api/tasks/progress/reset`
重置指定任务的进度为 idle（清除终态显示）。
**查询参数** `task_key`：string，必填
**响应** `{ "message": "已重置" }`
---
## 接口连通性测试
### `POST /api/test-connection`
测试 rssKeeper 与 LLM API 连通性，返回状态与延迟。每个测试使用独立短超时客户端（10 秒、0 重试）。
**响应** `ConnectionTestResponse`
```json
{
"rss_keeper": {
"name": "rssKeeper",
"status": "ok",
"latency_ms": 26.0,
"error": null
},
"llm": {
"name": "LLM",
"status": "ok",
"latency_ms": 6871.4,
"error": null
}
}
```
`status` 为 `error` 时 `error` 字段含失败原因，`latency_ms` 为 `null`。
---
## 配置管理接口
> 配置修改保存到数据库，部分配置（调度间隔等）需重启服务生效。
### `GET /api/settings`
列出所有可编辑配置。敏感项（`OPENAI_API_KEY` / `API_TOKEN`）返回脱敏值。
**响应** `List[SettingOut]`
```json
[
{
"key": "OPENAI_API_KEY",
"value": "sk-c...2R_8",
"description": "LLM API Key",
"is_sensitive": true,
"is_masked": true,
"updated_at": "2026-06-13T..."
}
]
```
### `PUT /api/settings/{key}`
更新单个配置项。
**请求体**
```json
{ "value": "新值" }
```
**响应** `{ "message": "配置已保存，重启服务后生效" }`　**错误** `400` 无效配置项
### `PUT /api/settings`
批量更新配置。
**请求体**
```json
{ "settings": { "OPENAI_MODEL": "gpt-4o-mini", "OPENAI_TIMEOUT": "60" } }
```
**响应** `{ "message": "配置已保存，重启服务后生效" }`　**错误** `400` 列出无效配置项
### `POST /api/settings/reset`
将所有配置重置为环境变量默认值。
**响应** `{ "message": "配置已重置为环境变量默认值，重启服务后生效" }`
### 可编辑配置清单
| key | 说明 | 敏感 |
|-----|------|------|
| `RSSKEEPER_BASE_URL` | rssKeeper 服务地址 | 否 |
| `OPENAI_API_KEY` | LLM API Key | 是 |
| `OPENAI_BASE_URL` | LLM API 基础地址 | 否 |
| `OPENAI_MODEL` | LLM 模型名 | 否 |
| `OPENAI_TIMEOUT` | LLM 调用超时（秒） | 否 |
| `OPENAI_MAX_RETRIES` | LLM 最大重试次数 | 否 |
| `SUMMARIZE_INTERVAL_MINUTES` | 摘要任务间隔（分钟） | 否 |
| `TAG_SCORE_INTERVAL_MINUTES` | 分类/打分/去重任务间隔（分钟） | 否 |
| `DAILY_BRIEF_HOUR` | 每日简报生成小时 | 否 |
| `DAILY_BRIEF_MINUTE` | 每日简报生成分钟 | 否 |
| `TITLE_SIMILARITY_THRESHOLD` | 标题相似度阈值 | 否 |
| `CONTENT_SIMILARITY_THRESHOLD` | 内容相似度阈值 | 否 |
| `MAX_AI_SUMMARY_LENGTH` | AI 摘要最大长度 | 否 |
| `MIN_ORIGINAL_SUMMARY_LENGTH` | 原始摘要最小长度 | 否 |
| `BRIEF_TOP_N_PER_CATEGORY` | 简报每分类显示文章数 | 否 |
| `LOG_LEVEL` | 日志级别 | 否 |
| `API_TOKEN` | API 鉴权 Token（空则不启用） | 是 |
| `CORS_ALLOWED_ORIGINS` | CORS 允许来源（逗号分隔） | 否 |
---
## 仪表盘统计
### `GET /api/stats`
返回仪表盘统计与下次定时任务时间。
**响应** `StatsOut`
```json
{
"total_articles": 200,
"today_articles": 50,
"ai_summarized": 180,
"categories": 12,
"tags": 43,
"duplicate_groups": 5,
"briefs": 1,
"next_jobs": {
"fetch_and_summarize": "2026-06-13T17:39:13+08:00",
"tag_score_deduplicate": "2026-06-14T16:39:13+08:00",
"generate_daily_brief": "2026-06-14T08:00:00+08:00"
}
}
```
---
## 错误码
| 状态码 | 含义 | 触发场景 |
|--------|------|----------|
| `200` | 成功 | 正常请求 |
| `400` | 参数错误 | 无效配置项 / 请求体格式错误 |
| `401` | 未认证 | 未携带 Authorization 头（启用了鉴权时） |
| `403` | 鉴权失败 | token 无效 |
| `404` | 资源不存在 | 文章/简报不存在 |
| `409` | 冲突 | 已有任务正在执行（任务全局互斥） |
| `422` | 校验失败 | 响应模型序列化失败等 |
| `500` | 服务器错误 | 内部异常 |
## 定时任务
服务启动后由 APScheduler 自动注册（时区 `Asia/Shanghai`）：
| Job ID | 触发方式 | 默认 |
|--------|----------|------|
| `bootstrap_taxonomy` | 启动时一次（DateTrigger） | taxonomy 为空时生成 |
| `fetch_and_summarize` | 间隔 | 每 60 分钟 |
| `tag_score_deduplicate` | 间隔 | 每 1440 分钟（24 小时） |
| `generate_daily_brief` | Cron | 每日 08:00 |
间隔参数可通过[配置接口](#配置管理接口)修改，修改后需重启服务生效。
Reference in New Issue Copy Permalink