Skip to content

api-spec.md

Latest commit

 

History

History
145 lines (99 loc) · 9.89 KB

api-spec.md

File metadata and controls

145 lines (99 loc) · 9.89 KB
Raw

接口清单（api-spec，人类可读）

文档版本 撰写日期 对应规范 对应 PRD
V1.0 2026-06-17 docs/openapi.yaml（OpenAPI 3.1） PRD V1.5 四大模块

本清单是 docs/openapi.yaml 的人类可读版，字段与后端 app/schemas/ 严格一致。除标注「公开」外，所有接口均需 Authorization: Bearer <JWT>。SSE 接口返回 text/event-stream，帧格式见 docs/design-rag-citation.md 与 openapi.yaml 内 description。

0. 四大模块 → 接口 总览

模块（PRD） 子域 接口数 关键接口
基础设施（鉴权/健康） auth, health 5 注册、登录、当前用户、健康检查
① AI 前沿资讯流（见微） feed 3 GET /api/feed、收藏入库、手动刷新
② 开源项目深度解剖（知著） analyze, tasks 2 + 3 POST /api/analyze/github、任务进度 SSE
③ 技术站点熔炼炉（重构） analyze, tasks （复用②） POST /api/analyze/site、任务进度 SSE
④ 智能技术知识库（鉴真） search, chat, kb 1 + 1 + 12 语义搜索、RAG 问答 SSE、文件夹/文档/配额管理

模块②③共用 analyze + tasks（同一套异步任务 + SSE 进度机制）。下面按子域列详表。

1. 鉴权 auth

方法 路径 鉴权 请求体 响应体 说明 PRD
POST /api/auth/register 公开 RegisterIn{email, password(6-128), display_name?} TokenOut{access_token, token_type, expires_in} 注册并返回令牌 四-数据安全
POST /api/auth/login 公开 LoginIn{email, password, enc?} TokenOut 登录；enc=true 时 password 为 RSA 密文 四-数据安全（密码加密传输）
GET /api/auth/pubkey 公开 — PubKeyOut{public_key} 取 RSA 公钥供前端加密密码 五-数据安全（HTTPS + 加密）
GET /api/auth/me Bearer — UserOut{id, email, plan, display_name, tenant_id} 当前登录用户 四-数据隔离（tenant_id）

2. AI 前沿资讯流 feed（模块①·见微）

方法 路径 鉴权 请求体 响应体 说明 PRD
GET /api/feed Bearer query: limit?(≤50) FeedListOut{items[FeedItem], total, updated_at} 读 Redis 环形列表最新 50 条，时间倒序瀑布流 2.1.3 / 2.1.4
POST /api/feed/refresh Bearer — TaskCreatedOut{task_id, status} 手动触发 6h 抓取任务（限流，复用定时任务） 2.1.1
POST /api/feed/{id}/favorite Bearer — FavoriteOut{document_id, status, task_id} 收藏并入库 Qdrant；不占解析配额，计文档配额 2.1.4 / 2.4.1

FeedItem 字段：id, title_zh, title_en, summary_zh, source, source_url, thumbnail_url, published_at, tags[], is_fresh, favorited（强制留源 source_url；thumbnail_url 为 MinIO 预签名英文原网页缩略图）。

3. 深度解析 analyze（模块②知著 / ③重构）

方法 路径 鉴权 请求体 响应体 说明 PRD
POST /api/analyze/github Bearer GithubAnalyzeIn{url} TaskCreatedOut{task_id, status} 异步：GraphQL 拉档案/依赖/目录树 → reasoning 档万字报告 → 入库；3-5min，经 SSE 跟进；free 版每月 3 次 2.2.1–2.2.6
POST /api/analyze/site Bearer SiteAnalyzeIn{url, format=md|ppt} TaskCreatedOut 异步：BFS 爬取（≤3 层）→ 层级 MD / reveal.js+PPTX → 入库 2.3.1–2.3.4

两接口均秒级返回 task_id，重活进 Celery，前端用 §4 的 tasks 接口轮询/订阅进度。配额超限返回 402（free 版每月解析 3 次，见 core/plans.py）。

4. 任务 tasks（异步进度，模块②③共用）

方法 路径 鉴权 请求体 响应体 说明 PRD
GET /api/tasks Bearer query: type?, status?, limit? TaskListOut{items[TaskOut], total} 当前租户任务列表 四-性能时效
GET /api/tasks/{id} Bearer — TaskOut{id, type, status, stage, progress, error, result_doc_id, created_at} 单任务详情（轮询） 四-性能时效
GET /api/tasks/{id}/stream Bearer — SSE text/event-stream 进度流：{type:progress|done|error, stage, progress, status, result_doc_id?} 2.2 / 2.3（分阶段进度反馈）

TaskOut.type ∈ github\|site\|ingest\|feed；status ∈ pending\|running\|success\|failed；stage 如 抓取/解析/撰写/入库；progress 0–100。

5. 语义搜索 search（模块④·鉴真）

方法 路径 鉴权 请求体 响应体 说明 PRD
GET /api/search Bearer query: q, scope=all|folder|tag, folder_id?, tag?, topk? SearchOut{query, hits[SearchHit], took_ms} 向量召回 + 重排，< 1s；高亮命中段落 + 来源 2.4.3

SearchHit 字段：doc_id, chunk_id, title, source_type, source_url, snippet, score, heading_path, tags[]。scope 经 Qdrant payload 过滤（tenant_id + 可选 folder_id/tag），多租户隔离。

6. RAG 问答 chat（模块④·鉴真）

方法 路径 鉴权 请求体 响应体 说明 PRD
POST /api/chat Bearer ChatIn{query, scope=all|folder|tag, folder_id?, tag?} SSE ChatChunk 序列 流式逐字 + 行内 [n] 引用 + 防幻觉；free 版返 403（未解锁高级 RAG） 2.4.4

SSE 帧（ChatChunk{type, content, citations[]}），type ∈ token\|citations\|done\|not_found\|error：

  • token：逐字内容；citations：Citation{n, doc_id, chunk_id, title, source_url, snippet, offset} 列表；done：结束；not_found：召回为空/低于 RAG_MIN_SCORE 时回「知识库中未找到相关资料」。详见 docs/design-rag-citation.md。

7. 知识库管理 kb（模块④·鉴真）

7.1 文件夹 folders

方法 路径 鉴权 请求体 响应体 说明 PRD
GET /api/kb/folders Bearer — FolderOut[] 文件夹列表（树状导航） 2.4.5
POST /api/kb/folders Bearer FolderIn{name, parent_id?} FolderOut{id, name, parent_id} 新建文件夹 2.4.5
PATCH /api/kb/folders/{id} Bearer FolderIn{name, parent_id?} FolderOut 重命名/移动文件夹 2.4.5
DELETE /api/kb/folders/{id} Bearer — 204 删除文件夹 2.4.5

7.2 文档 documents

方法 路径 鉴权 请求体 响应体 说明 PRD
GET /api/kb/documents Bearer query: folder_id?, tag?, source_type?, sort?, page?, size? DocListOut{items[DocumentOut], total} 文档列表（文件夹/标签筛选、排序、分页） 2.4.5
POST /api/kb/documents/upload Bearer multipart{file, folder_id?} UploadOut{document_id, task_id, status} 上传 PDF/Word/TXT/MD/代码，异步解析入库 2.4.1
GET /api/kb/documents/{id} Bearer — DocumentOut 文档元数据详情 2.4.5
GET /api/kb/documents/{id}/content Bearer — DocContentOut{doc_id, title, content, format} 正文内容（阅读器渲染 + 引用跳转定位） 2.4.4 / 2.4.5
PATCH /api/kb/documents/{id} Bearer DocPatchIn{title?, folder_id?} DocumentOut 重命名（title）/ 移动（folder_id） 2.4.5
DELETE /api/kb/documents/{id} Bearer — 204 删除文档（同步清 Qdrant 向量 + 对象存储） 2.4.5
POST /api/kb/documents/{id}/share Bearer ShareIn{scope=read, ttl_hours?} ShareOut{token, url, expire_at} 创建带过期的分享链接 2.4.5

DocumentOut 字段：id, title, source_type(feed\|github\|site\|upload\|note), source_url, summary, category(资讯/开源项目/技术文档/个人笔记), status(ingesting\|ready\|failed), folder_id, tags[], size_bytes, created_at（自动打标 PRD 2.4.2）。

7.3 配额 quota

方法 路径 鉴权 请求体 响应体 说明 PRD
GET /api/kb/quota Bearer — QuotaOut{doc_count, used_bytes, plan_limit_docs, plan_limit_bytes, plan} 当前租户配额用量（-1 表示无限） 四-存储与配额 / 六-商业化

配额规则（core/plans.py）：free 500 文档/1GB/每月 3 次解析；pro 无限文档/20GB/无限解析/解锁高级 RAG；team 无限/100GB。

8. 健康检查 health

方法 路径 鉴权 请求体 响应体 说明 PRD
GET /api/health 公开 — HealthOut{status, version, deps{}} 服务及依赖（postgres/redis/qdrant/minio）连通状态 四-性能/可靠性

9. 约定与错误码

  • 鉴权：除「公开」标注外均需 Authorization: Bearer <JWT>，缺失/失效返回 401。
  • 多租户隔离：所有业务接口按 JWT 的 tenant_id 过滤（SQL + Qdrant payload 双层），跨租户不可见（PRD 四-数据安全）。
  • 配额：解析/上传/收藏入库超限返回 402；free 版调用未解锁能力（高级 RAG）返回 403。
  • 限流：高频/重操作（如 feed/refresh）触发限流返回 429。
  • 校验失败：请求体不合法返回 422（HTTPValidationError）。
  • 统一错误体：Msg{detail}（FastAPI 默认）。
  • 异步语义：/api/analyze/*、/upload、/feed/refresh 返回 202 + task_id，进度经 /api/tasks/* 跟进。

字段定义以 app/schemas/（auth/feed/analyze/task/search/chat/kb/common）与 docs/openapi.yaml 为准。