# API 文档总览

当前 `apidoc/` 中的文档按接口域拆分：

- [importapi.md](/www/proofdb/apidoc/importapi.md): 档案导入接口
- [adminapi.md](/www/proofdb/apidoc/adminapi.md): 管理员认证与后台维护接口
- [searchapi.md](/www/proofdb/apidoc/searchapi.md): 全文、向量、混合搜索接口
- [evidenceapi.md](/www/proofdb/apidoc/evidenceapi.md): chunk 详情与 evidence 接口

## 当前已实现接口

```http
POST /api/articles/import
POST /api/admin/login
POST /api/admin/logout
GET /api/admin/me
GET /api/admin/archives
GET /api/admin/archives/{archive_uid}
PATCH /api/admin/archives/{archive_uid}
DELETE /api/admin/archives/{archive_uid}
GET /api/admin/opensearch/status
GET /api/admin/opensearch/documents
GET /api/admin/users
POST /api/admin/users
PATCH /api/admin/users/{id}
GET /api/admin/docs
GET /api/admin/docs/{name}
GET /api/admin/scripts
GET /api/admin/scripts/{name}
POST /api/admin/scripts/run
POST /api/search/fulltext
POST /api/search/vector
POST /api/search/hybrid
GET /api/chunks/{chunk_uid}
GET /api/evidence/{chunk_uid}
```

## 当前接口分层

- 导入层：把 Markdown 档案解析为 archive / chunk，并写入 PostgreSQL。
- 管理层：管理员登录、会话识别、archives 表管理、OpenSearch 状态、用户管理、文档查看与维护脚本执行。
- 检索层：从 OpenSearch 做 BM25、向量和 hybrid 检索。
- 证据层：把 `chunk_uid` 落到 citation、页码和证据正文。

## 说明

- 搜索接口中的 `hits` 始终表示“当前请求下返回的候选结果数组”，不是数据库全量导出。
- `fulltext`、`vector`、`hybrid` 都支持 `limit`。
- `hybrid` 的 `total` 表示融合后的候选总数；更细的来源统计在 `sources` 字段中。