# 技术决策记录（ADR 简版）

## ADR-001 前后端分离
状态：已决定。前端 Vue 3 + TypeScript + Vite；后端 FastAPI + Pydantic。原因：团队并行开发、API 边界明确、原型可先行。

## ADR-002 数据库
状态：已决定。PostgreSQL + pgvector。原因：结构化业务数据与向量检索可统一管理。首版先实现知识表，再逐步加入版本、向量与检索日志。

## ADR-003 Embedding
状态：待评估。采用统一 Provider 接口，在开源本地模型与云端 API 间选择。严禁混用不同模型生成的向量。

## ADR-004 网络搜索与 MCP
状态：延期。首版默认使用经过审核的知识库；联网搜索作为可选扩展。优先封装已有 API，不因使用 MCP 而自研协议服务。

## ADR-005 更新策略
状态：设计确定、尚未实现。新文档版本后台生成向量，完成后原子发布；失败保留旧索引。

## ADR-006 阶段 2 知识管理

状态：已通过 PR #4 合入 `dev`。采用来源、文档、知识条目和追加式事件日志；记录版本用于并发控制，快照用于追溯。所有删除均为软删除，被有效记录引用的父记录禁止删除。依据或正文修改即回待审核；核验通过必须有来源链接、采集时间、核验人和说明。保留旧版知识创建请求及列表数组结构，新页面使用独立分页接口。当前为本机人工审核流程，认证身份、向量切分和索引发布仍属后续阶段。

## ADR-007 显式迁移与旧数据保留

状态：已通过 PR #4 合入 `dev`。以 Alembic 取代应用启动时的 `create_all`。基础迁移接管旧知识表，新增字段和表通过增量迁移完成；不推测旧数据采集时间。旧审核结论缺少完整记录时保留原快照并转待审核。迁移回滚需先备份，新增历史与审核元数据无法通过降级完整保留。

## ADR-008 可复核的中文关键词基线

状态：分支实现，待审阅。采用固定 Jieba 搜索分词及关闭 HMM 的词典模式，加入项目名称词，并使用固定停用词表。选择标题重复权重 2、正文权重 1 的 BM25 正值平滑 IDF 变体，不称为 BM25F；查询词去重，同分按知识 ID 排序。参数、分词标识、实际语料指纹及出处版本随每次结果保存，方便冻结后续实验配置。分词接口参考 [Jieba 官方说明](https://github.com/fxsjy/jieba)，BM25 基础参考 [Stanford IR 教材](https://nlp.stanford.edu/IR-book/html/htmledition/okapi-bm25-a-non-binary-model-1.html)；具体平滑公式与权重以本仓库实现和手算测试为准。

当前检索单元为已审核知识条目，在设置的容量内按请求计算，不提前实现向量切分/索引更新；超过容量明确失败。`retrieval_runs` 仅记录当时结果，不代表该条目之后仍然获得审核批准。网络搜索、模型选择和真实论文实验保持原阶段边界。


## ADR-009 服务端会话与最小角色边界

状态：Issue #5 分支实现，待审阅。使用 Argon2id 密码哈希、数据库保存摘要的随机 Cookie 会话，以及独立 CSRF 请求头与显式 Origin 白名单；不把角色或会话凭据放入浏览器持久存储。普通注册只能创建 user，管理员仅由本机隐藏密码输入命令创建。知识/来源/文档管理及检索历史限 admin，公开检索继续只使用已核验依据。完整契约与实现依据见 [AUTH_API.md](AUTH_API.md)。

为改密和会话撤销使用用户行锁与凭据版本，认证预算使用数据库原子计数；不依赖单进程内存限流。现有前端写请求同步 Cookie/CSRF 封装，页面和路由联调仍待前端完成。本分支叠加 PR #6，后续审阅需关注迁移顺序及匿名管理调用变为 401 的行为变化。