fix(boundary): 修复多库边界问题、版本管理及删除清理

多库检索与存储修复:
- RRF 融合去重改用 (collection, chunk_id) 复合键，修复同名文件结果被吞
- DocStore 存储路径加 collection 前缀，修复跨库同名切片数据覆盖
- search_multiple 去重改用复合键
- chunk_id 解析改用 rsplit 兼容下划线文件名

上传与版本管理修复:
- 同名文件上传改为覆盖模式，自动清理旧切片
- 修复首次上传不创建版本记录
- 修复覆盖上传版本号回退到 v1
- sync ADDED 分支改用动态版本号生成
- _generate_version_id 改为基于全部版本递增
- 废止/恢复操作同步 SQLite 版本记录
- mark_document_as_superseded 改为仅更新 SQLite

删除清理修复:
- 删除文档时同步清理 SQLite 版本记录和变更日志
- 删除向量库时同步清理该库所有版本记录
- cleanup 改为清理 SQLite 记录而非 ChromaDB

测试:
- test_version_management.py: 27 条版本管理单元测试
- test_edge_cases.py: 28 条边界用例测试
- test_upload_dedup.py: 5 条上传去重测试
- e2e_risk_test.py: 27 条端到端风险测试

文档:
- 新增风险边界问题修复注意事项.md（面向后端的对接文档）
- 新增向量库边界风险分析.md
- 更新多篇现有文档

docs/多向量库实现权限划分.md

@@ -42,7 +42,30 @@ Agentic RAG在正式下发检索前，加入了一层轻量级意图预判节点
 最终数据层依靠融合模块汇聚所有库的 Top-K 记录，经过全局倒排算法（RRF）以及多维分数权重融合重排，保证了隔离存储不影响任何语义搜寻与内容关联。
 
 ## 4. 相关代码路径总结
+
+### 4.1 鉴权与路由
 - **`auth/gateway.py`**：主要负责网关鉴权与鉴权路由逻辑。
-- **`knowledge/router.py`**：LLM智能知识库请求目标路由。
-- **`knowledge/manager.py`**：支持多库并发检索引擎与RRF打分融合模块。
-- **`rebuild_multi_kb.py`**：从单库直接转换为多库分治物理结构的离线迁移脚本。
+- **`knowledge/router.py`**：LLM 智能知识库请求目标路由。
+
+### 4.2 knowledge/ 核心模块（Mixin 架构）
+知识库管理器 `KnowledgeBaseManager` 采用 Mixin 组合模式，各职责拆分到独立模块：
+
+| 模块 | Mixin 类 | 职责 |
+|------|----------|------|
+| `knowledge/base.py` | — | 配置常量、数据类定义（`CollectionInfo`, `SearchResult`, `BM25Index`）、辅助函数 |
+| `knowledge/manager.py` | `KnowledgeBaseManager` | 主入口，组合所有 Mixin，提供多库并发管理与工厂方法 |
+| `knowledge/collection.py` | `CollectionMixin` | 向量库（ChromaDB Collection）的创建、删除、查询等集合管理功能 |
+| `knowledge/document.py` | `DocumentMixin` | 文档级别的管理方法，包括文档计数、文档列表、文档元信息查询 |
+| `knowledge/search.py` | `SearchMixin` | 多源融合检索：单向量库检索 + BM25 混合检索 + RRF 融合排序 + 多库并行检索 + 废止版本检测 |
+| `knowledge/permission.py` | `PermissionMixin` | 基于角色和部门的向量库访问控制，权限校验（admin / manager / user） |
+| `knowledge/processing.py` | `ProcessingMixin` | 图片/表格的智能处理：图片过滤、VLM 描述生成、表格摘要生成、原始数据存储 |
+| `knowledge/chunk.py` | `ChunkMixin` | 文档切片（Chunk）的 CRUD 操作：新增、修改、删除、分页查询切片 |
+| `knowledge/index.py` | `IndexMixin` | BM25 关键词检索索引的生命周期管理：懒加载、持久化、从向量库重建 |
+| `knowledge/document_versions.py` | `DocumentVersionQuery` | 文档版本历史查询、获取当前生效版本、版本变更日志记录 |
+
+### 4.3 辅助服务
+- **`knowledge/sync.py`**：知识库同步服务 — 使用 watchdog 监控文档目录变更，自动检测文件哈希差异并触发增量向量化。
+- **`knowledge/cleanup.py`**：文档版本自动清理 — 定期清理 superseded 状态的旧版本，控制存储成本。
+
+### 4.4 离线迁移脚本
+- **`scripts/rebuild_multi_kb.py`**：从单库直接转换为多库分治物理结构的离线迁移脚本。