# 系统架构

```text
Vue 3 + TS 前端
    | HTTP /api
FastAPI + Pydantic
    |-- 知识管理 API -- PostgreSQL
    |-- 问答服务
          |-- 关键词检索
          |-- Embedding 查询向量 -> pgvector 检索
          |-- 结果融合 -> 证据检查 -> LLM API
          |-- 答案 + 来源
    |-- 后台更新任务（后续）
          |-- 来源获取 -> 人工核验 -> 文本切分 -> 生成向量 -> 发布版本
```

当前后端实现健康/数据库就绪检查、来源与文档管理、知识增删改查、分页筛选、人工审核、历史快照及独立关键词检索；问答仍为占位接口。数据库由 Alembic 显式迁移并启用 pgvector，尚无向量字段、向量索引和 RAG。前端来源登记/查询已接入，实验页仍为静态原型，文档、审核、完整分页与检索页面需继续联调。

## 阶段 2 数据边界

- `sources` 登记来源名称、HTTP(S) 网址和备注；`documents` 登记所属来源、正文、分类与采集时间。
- `knowledge_items` 保留基础版本全部字段，新增可选来源/文档引用、采集时间、人工审核字段、版本和软删除状态。历史条目不强行补造来源或时间。
- `audit_events` 在同一事务中保存创建、修改、审核、失效、删除和迁移导入事件；知识快照包含当时关联的来源与文档。
- `version` 用于内容并发控制，PATCH/审核/DELETE 必须匹配读取版本；ORM 版本检查处理并发写入冲突，引用操作对来源/文档加行锁，避免与修改和删除交错。
- 修改知识或关联依据会撤销当前审核结论。未来正式检索必须同时限定 `verification_status = 'verified'` 和 `is_deleted = false`；当前管理列表不承担检索或索引发布功能。
- 文档版本通过递增版本号及完整历史快照留存；`chunks`、Embedding 模型版本与索引发布版本在检索阶段单独实现，不能把记录版本当作已实现索引切换。
- 旧库首次升级自动接管基础表，保留条目与导入快照。没有完整审核记录的旧 `verified` 状态回到待审核。启动不自动迁移，缺失或不匹配的版本会明确报错。

## 安全边界
当前无认证与权限控制，仅供本机开发；正式部署前须补充登录鉴权、接口限流、数据库迁移、密钥管理、日志脱敏、CORS 收敛和 HTTPS。

## 关键词检索基线（T06）

`POST /api/retrieval` 在同一 SQL 语料快照中筛选有效的已审核知识，读取出处和记录版本，再进行固定中文分词、标题加权 BM25 排序和原文片段截取。语料指纹覆盖本次实际参与排序的内容与出处版本；算法标识和参数独立记录。管理页的字面子串筛选继续用于管理，正式关键词基线使用专用检索接口。

新增 `retrieval_runs` 保存查询、模式、语料指纹和完整结果快照，支持分页读取及按 UUID 复核。零命中如实记录；当前依据修改后失效不会改写历史，但后续检索必须重新检查审核与父记录状态。响应耗时是本次真实读取、分词、排序及片段生成耗时，不含写日志或模型调用。

当前按知识条目检索，显示片段最长 240 字符；尚无持久化 chunks、倒排索引、Embedding、向量检索、RRF 或 RAG。全语料计算明确限制条目数及总字符数，超限报错，适用于首批小规模资料与后续对照实验准备，不能当作生产检索性能结论。