From 177375a7b7e58a52b2b3b45441b032bfae37e256 Mon Sep 17 00:00:00 2001
From: evo <446796145@qq.com>
Date: Tue, 21 Jul 2026 09:35:56 +0800
Subject: [PATCH] =?UTF-8?q?docs(rag):=20=E6=9B=B4=E6=96=B0=E5=AE=8C?=
 =?UTF-8?q?=E6=95=B4=E4=BF=AE=E5=A4=8D=E4=B8=8E=E9=AA=8C=E6=94=B6=E6=8A=A5?=
 =?UTF-8?q?=E5=91=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 RAG_TEST_REPORT_2026-07-20.md | 64 +++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 RAG_TEST_REPORT_2026-07-20.md

diff --git a/RAG_TEST_REPORT_2026-07-20.md b/RAG_TEST_REPORT_2026-07-20.md
new file mode 100644
index 00000000..5fabde07
--- /dev/null
+++ b/RAG_TEST_REPORT_2026-07-20.md
@@ -0,0 +1,64 @@
+# RAG 完整修复与全量验收报告
+
+验收时间：2026-07-21（Asia/Shanghai）  
+验收对象：当前未提交工作区（保留原有改动）
+
+## 结论
+
+计划内的 1–15 项工程缺陷已完成代码修复，默认 Maven 构建已从“跳过测试”改为真实执行测试。全仓 37 个 reactor 模块测试成功，`ruoyi-chat` 49/49 通过，两个前端生产构建通过，`git diff --check` 通过。
+
+本机已运行 MySQL、Redis、MinIO 和 Weaviate 1.30.0；Milvus/Qdrant 容器以及有效的 embedding/chat/rerank provider 凭证不存在，因此这三项真实 provider/存储引擎冒烟被标记为环境限制，不影响确定性代码验收。
+
+## 1–15 项验收
+
+| # | 状态 | 修复/证据 |
+|---|---|---|
+| 1 | 通过 | Markdown/Java/字符分片的边界、空文档、超长块回归通过。 |
+| 2 | 通过 | Supervisor 每轮仅保留一个 RAG 入口，不再用已含 RAG 的 prompt 重复检索。 |
+| 3 | 通过 | 历史消息进入 Supervisor prompt，检索 query 与最终 prompt 分离。 |
+| 4 | 通过 | `fid` 稳定 ID 贯穿 DB/三种向量库/RRF，融合去重回归通过。 |
+| 5 | 通过 | aiflow vector/hybrid 复用统一检索服务；graph 明确返回不支持，不再伪装为 vector。 |
+| 6 | 通过 | 重解析改为先写新 fid、再清旧向量、最后替换 DB；失败补偿新向量；删片段/附件/库遇向量删除失败即中止。 |
+| 7 | 通过 | embedding/rerank provider 使用 prototype 实例，工厂缓存可按模型刷新，避免跨配置污染。 |
+| 8 | 通过 | `similarityThreshold` 仅用于粗召回；`rerankScoreThreshold` 仅在 rerank 真实成功后生效，回归测试通过。 |
+| 9 | 通过 | 默认配置和 Compose 统一为 Weaviate 1.30.0、`28080:8080`。 |
+| 10 | 通过 | 三种策略均使用 `embedAll`；Weaviate batch objects、Milvus `addAll`、Qdrant `addAll`。 |
+| 11 | 通过 | upload/parse/retrieval 权限保留，parse/retrieval 增加分布式防重复提交，upload 由现有知识库+文件名唯一约束兜底。 |
+| 12 | 通过 | 分隔符使用字面量语义，`|`/`.`/`*` 回归通过。 |
+| 13 | 通过 | hybrid 通道失败可降级到 vector；所有可用通道都失败时抛出明确业务异常。 |
+| 14 | 通过 | Weaviate client 稳定懒加载单例；schema 仅在已存在或创建成功后进入缓存。 |
+| 15 | 通过 | 工厂新增严格 `getStrategy(type)`，知识库 `vectorModel` 优先，空值才回退全局，非法值直接报错。 |
+
+## 其他完成项
+
+- 多知识库并行检索，按 `kid + docId + fid` 去重，统一上限和字符预算。
+- 5 分钟短 TTL 检索缓存，key 覆盖检索参数，知识数据变更主动失效。
+- rerank 仅保留 provider 实际返回的文档。
+- 知识库文档数改为 group-by 查询，消除该 N+1。
+- Milvus/Qdrant/Weaviate 的删 collection/doc/fid 语义对齐；Milvus 删库改为 drop collection。
+- MCP `npx` 根据操作系统解析，支持系统属性/环境变量覆盖。
+- `fid` 非空唯一、`doc_id varchar(32)`、租户/用户索引与可重复执行迁移脚本已提供。
+- 用户端聊天页已接入知识库列表和最小选择器。
+
+## 测试记录
+
+| 检查 | 结果 |
+|---|---|
+| `mvn -Pdev test` | 37/37 reactor 模块 SUCCESS；`ruoyi-chat` 49/49 |
+| `mvn -Pdev -pl ruoyi-modules/ruoyi-aiflow -am -DskipTests compile` | 21/21 SUCCESS |
+| `ruoyi-web: pnpm build` | SUCCESS，2621 modules transformed |
+| `ruoyi-admin: pnpm build` | SUCCESS，10/10 build tasks |
+| `git diff --check` | SUCCESS，无空白错误 |
+| Weaviate/MySQL/Redis/MinIO | Docker 服务运行，Weaviate 1.30.0 映射 28080 |
+| 三向量库 Docker 集成 | SUCCESS；Weaviate 1.30.0、Milvus 2.5.7、Qdrant 1.17.0 真实写入/检索/删除测试 3/3 通过 |
+| 真实 embedding/chat/rerank | 环境限制：当前配置为无效/占位凭证 |
+
+本轮未创建新的 `codex_rag_verify_` 持久化数据；上一轮验收数据已清理，未动现有非测试数据。
+
+## 2026-07-21 三向量库 Docker 补充验收
+
+- 启动并保留 `ruoyi-rag-milvus`、`ruoyi-rag-milvus-etcd`、`ruoyi-rag-milvus-minio`、`ruoyi-rag-qdrant`，四个容器健康检查均为 `healthy`。
+- Milvus 专用 MinIO 仅在 Docker 内网可达，没有占用宿主机 9000/9001；Milvus 映射 19530/9091，Qdrant 映射 6333/6334。
+- `ThreeVectorStoresDockerIT` 使用 32 维确定性 embedding，对三库逐一验证 batch write、vector search、fid delete、docId delete 和 drop collection，3/3 通过。
+- 首轮测试发现 Milvus `autoFlush=false` 导致批量写入后不可立即检索、元数据删除不可立即见；改为写入和删除返回前 flush 后通过。
+- 清理后 Weaviate/Qdrant 的 `CodexRagVerify*` collection 计数均为 0，Milvus collection 也由测试 finally 成功 drop；本轮未写入 MySQL 或 OSS 测试数据。