# REST API Contract Version all public APIs under `/api/v1`. Initial domains: auth, users/groups, knowledge-bases, documents, compiled-knowledge, search, evaluations, jobs, audit-logs, providers and MCP administration. Use OpenAPI as executable source of truth once implementation starts. Provider-specific concepts must not leak into public contracts. ## Demo v0.1 P0 DEMO-009 公开以下最小接口。`docs/demo/DEMO_SCOPE.md` 中的 `/api/*` 逻辑路径按本契约统一 版本化为 `/api/v1/*`。 `DEMO-015` 已将单文件上传切换为持久化异步 Job;`DEMO-016` 已增加批量提交和聚合查询。 | Method | Path | 行为 | |---|---|---| | `POST` | `/api/v1/documents` | multipart 单文件接收;持久化 Source、Document、Job 后返回 `202` | | `POST` | `/api/v1/ingestion-batches` | multipart `files` 多文件接收;返回批次与逐文件状态 | | `GET` | `/api/v1/ingestion-batches/{batch_id}` | 返回批次汇总和逐文件最新 Job 状态 | | `GET` | `/api/v1/documents` | 按创建时间倒序返回文档列表 | | `GET` | `/api/v1/documents/{document_id}` | 返回单个文档状态与安全错误信息 | | `DELETE` | `/api/v1/documents/{document_id}` | 直接删除向量、Metadata、解析产物和原始文件 | | `GET` | `/api/v1/jobs/{job_id}` | 返回阶段、状态、attempt、最大尝试次数和安全错误信息 | | `POST` | `/api/v1/search` | Dense Top20、Reranker、TopK、来源补全 | 上传字段名为 `file`,支持 PDF、DOCX、TXT 和 Markdown。成功返回 `202`、Document 字段及 `job_id`、`job_status=queued`、`max_attempts`;响应不等待 Parse、Clean、Chunk、Embedding 或 Index。Document 响应不暴露 `storage_key`、Provider 配置或索引实现。 Search 请求: ```json { "query": "产品A退款周期是多少?", "top_k": 5 } ``` Search 响应: ```json { "results": [ { "document_id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752", "filename": "产品A说明书.pdf", "page": 12, "section": "退款政策", "chunk_id": "76ba1c30-bff7-44e5-9989-fb8372f54f46", "content": "……", "score": 0.82, "rerank_score": 0.94 } ] } ``` 公开错误语义:请求校验失败返回 `422`,不支持的上传类型返回 `415`,文件过大返回 `413`, 文档、Job 或批次不存在返回 `404`,活动 Job 的文档删除返回 `409`,运行时 Provider 未配置返回 `503`。上游 Provider 或持久化异常只返回经过收敛的 `5xx` 信息,不回显凭证、请求正文或 厂商响应。 ## Demo Admin 客户端路由 DEMO-010 提供 `/admin/upload`、`/admin/documents` 和 `/admin/search` 三个客户端路由, `/admin` 默认展示上传页。它们是同源静态页面,不是新增业务 API,也不改变上述公开 REST 契约;所有业务操作仍调用 `/api/v1`。 ## 当前公共知识库部署边界(PLAN-002) 当前阶段所有 Document 属于同一个公共知识可见域,不新增用户、知识库或 ACL 字段,也不把 这些完整未实现能力伪装为默认放行。Admin 写接口只允许部署在企业受控网络或统一接入网关后; Ingress 是否进一步认证属于部署配置,但前端隐藏按钮或隐藏路由不构成安全控制。 集群重启、扩缩容和滚动部署不得改变本契约或要求浏览器重新注入 Provider 配置。数据库、BOS、 模型与队列凭据由服务端 Secret 提供,任何 API 响应都不得返回这些值。 DEPLOY-003 增加两个不进入 `/api/v1` OpenAPI 的运维端点:`GET /healthz` 只表示 API 进程可用; `GET /metrics` 使用 Prometheus text format 返回进程存活时间、按 HTTP method/路由模板/status 聚合的请求量和按 method/路由模板聚合的耗时。两者不得包含 Query、文件名、正文、身份、 Provider Endpoint 或凭据。响应附带安全 `X-Request-ID`,客户端提供的值只有匹配 `[A-Za-z0-9._:-]{1,64}` 时才会沿用。 ## 异步入库契约(DEMO-015~016 已实现) | Method | Path | 行为 | |---|---|---| | `POST` | `/api/v1/documents` | 已实现:单文件接收并返回 Document/Job 标识 | | `POST` | `/api/v1/ingestion-batches` | multipart 多文件接收,返回批次及逐文件 Document/Job 标识 | | `GET` | `/api/v1/ingestion-batches/{batch_id}` | 返回批次汇总和逐文件最新状态 | | `GET` | `/api/v1/jobs/{job_id}` | 已实现:返回持久化 Job 状态 | 单文件响应示意: ```json { "id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752", "filename": "退款政策.md", "media_type": "text/markdown", "size_bytes": 1024, "status": "uploaded", "error_message": null, "created_at": "2026-09-02T12:00:00Z", "updated_at": "2026-09-02T12:00:00Z", "job_id": "7adc4278-1157-4c3d-95a4-6926ad77a04e", "job_status": "queued", "max_attempts": 3 } ``` 批量字段名为 `files`,成功返回 `202`。响应示意: ```json { "batch_id": "d21f8012-4c4e-4bb4-89af-e11c0f9f470e", "status": "processing", "total_files": 2, "accepted_files": 1, "rejected_files": 1, "completed_files": 1, "created_at": "2026-09-02T12:00:00Z", "items": [ { "item_index": 0, "filename": "退款政策.md", "acceptance_status": "accepted", "document_id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752", "job_id": "7adc4278-1157-4c3d-95a4-6926ad77a04e", "job_status": "queued", "stage": null, "attempt": 0, "max_attempts": 3, "error_message": null } ] } ``` Job 公开状态为 `queued | running | retrying | succeeded | failed | cancelled`,并通过 `stage` 表示 `parsing | cleaning | chunking | embedding | indexing`。错误字段只返回有界、安全摘要。 批次状态为 `processing | completed | partial_failure | failed`;逐文件接收状态为 `pending | accepted | rejected`。批次允许逐文件部分接收/失败,不以一个文件的处理结果回滚 其他文件。文件数量、单文件大小和请求总大小分别由 `BATCH_MAX_FILES`、`MAX_UPLOAD_BYTES` 和 `BATCH_MAX_TOTAL_BYTES` 限制。数量超限返回 `413`;类型、大小或内容不合规作为该文件的 `rejected` 安全结果返回,其他合规文件继续接收。 自动重试是服务端 Job 行为,不要求客户端再次上传,也不新增公开手动重试接口。每次重试前 清理派生数据但保留原始文件和稳定的 Document ID;达到次数上限或清理失败后进入 `failed`。