5.2 KiB
技术决策记录（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 官方说明，BM25 基础参考 Stanford IR 教材；具体平滑公式与权重以本仓库实现和手算测试为准。
当前检索单元为已审核知识条目，在设置的容量内按请求计算，不提前实现向量切分/索引更新；超过容量明确失败。retrieval_runs 仅记录当时结果，不代表该条目之后仍然获得审核批准。网络搜索、模型选择和真实论文实验保持原阶段边界。
ADR-009 服务端会话与最小角色边界
状态：Issue #5 分支实现，待审阅。使用 Argon2id 密码哈希、数据库保存摘要的随机 Cookie 会话，以及独立 CSRF 请求头与显式 Origin 白名单；不把角色或会话凭据放入浏览器持久存储。普通注册只能创建 user，管理员仅由本机隐藏密码输入命令创建。知识/来源/文档管理及检索历史限 admin，公开检索继续只使用已核验依据。完整契约与实现依据见 AUTH_API.md。
为改密和会话撤销使用用户行锁与凭据版本，认证预算使用数据库原子计数；不依赖单进程内存限流。现有前端写请求同步 Cookie/CSRF 封装，页面和路由联调仍待前端完成。本分支叠加 PR #6，后续审阅需关注迁移顺序及匿名管理调用变为 401 的行为变化。
ADR-010 切分快照与显式发布
状态：T05 分支实现，待审阅。先对当前有效审核语料构建带原文偏移/哈希/出处的 chunks，再以独立的发布请求切换指针。固定 Unicode 字符窗口配置留存在版本中，关键词接口继续按条目运行，防止未经评估就改变实验口径。
为当前小规模语料选择统一数据库行锁：应用目录写入、构建、发布串行，发布同时校验代数、目录修订和语料指纹；失败回滚全部更新，旧版本保留为历史。任何成功目录写入保守地使旧索引过期，历史不能视作当前有效依据。实现、容量与后续并发扩展边界见 INDEX_API.md。
ADR-011 同粒度 chunk 排序与等权 RRF
状态：后端分支实现，待审阅。基于已合入的向量快照，新增正文 BM25 的 chunk 基线，与向量模式使用同一文本发布及分类范围；保留条目关键词接口作为独立口径。两路候选各限 candidate_k，使用从 1 起的排名、固定 k=60、等权倒数排名融合，缺席一路贡献为零。保存候选全排名、原始分数、两路贡献和配置，确保实验准备可复核；不把 BM25 与余弦原始分数直接相加。
公式与常数参考 RRF 原论文，本项目尚未依据核验领域问题集调优。同步精确计算限制 2000 chunks，固定配置、版本一致性、历史兼容与回滚见 HYBRID_API.md。