dataClean/API.md

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

服务存活探针，无需鉴权。

响应

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

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

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

强制重新生成指定日期简报。同步执行（需持任务锁）。

响应

{ "message": "简报已重新生成", "data": { ... } }

错误 409 已有任务执行中

---

分类体系接口

GET /api/taxonomy

列出分类/标签/打分规则。

查询参数 kind：string，可选，过滤类型：category / tag / heat_rule / importance_rule / duplication_rule

响应 List[TaxonomyOut]

[
  {
    "id": 1,
    "name": "科技",
    "kind": "category",
    "description": "人工智能、芯片、互联网等",
    "keywords": ["AI", "芯片", "大模型"],
    "weight": 1.0,
    "created_by_ai": true
  }
]

POST /api/taxonomy/bootstrap

初始化或强制重建分类体系（后台异步执行）。

查询参数 force：bool，默认 false。true 时清空后重建。

响应（立即返回）

{ "message": "taxonomy 初始化已开始", "task_key": "bootstrap_taxonomy" }

错误 409 已有任务执行中。可通过 GET /api/tasks/progress 查看 bootstrap_taxonomy 进度。

---

任务接口

所有任务接口均为后台异步执行：提交后立即返回 task_key，任务在线程池执行，通过进度接口轮询。

任务全局互斥（共享 _task_lock）：同一时刻仅一个任务运行。

POST /api/tasks/summarize

拉取 rssKeeper 最近 24 小时文章，为无摘要/短摘要文章生成 AI 摘要。

响应

{ "message": "摘要任务已开始", "task_key": "summarize" }

错误 409 已有任务执行中

POST /api/tasks/tag-score-dedup

对当天文章执行：分类打标 → 去重 → 打分（三阶段，进度合并显示）。

响应

{ "message": "分类/去重/打分任务已开始", "task_key": "tag_score_dedup" }

POST /api/tasks/brief

生成当天每日简报（force 重新生成）。

响应

{ "message": "简报生成任务已开始", "task_key": "generate_daily_brief" }

---

任务进度

GET /api/tasks/progress

返回所有任务的实时进度快照（前端每 ~1.5 秒轮询）。

响应

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

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

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

更新单个配置项。

请求体

{ "value": "新值" }

响应 { "message": "配置已保存，重启服务后生效" }　错误 400 无效配置项

PUT /api/settings

批量更新配置。

请求体

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

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

间隔参数可通过配置接口修改，修改后需重启服务生效。