# 私有资料问答（FR-PRIV）· 原始测试计划

> 本文件为本次调整的**原始测试计划**，工程内留存（docs/PRIVATE_DOCS_TEST_PLAN.md）。
> 对应功能：客户上传 PDF 等资料 → 向量化 → 追加向量库 → 问答可检索（PRD §17 FR-PRIV-001~008）。
> 用户纪律（2026-09-07）：测试用例 100% 覆盖所调整内容；每轮测试均有过程记录（TEST_REPORT_R*.md）；
> 每轮完毕后统一修改再开新一轮，直至全部问题解决；TL 终验后把手工验收方法写入「PlantAI-new测试用例一览.xlsx」的知识库 sheet。

## 1. 调整内容范围（用例必须覆盖的全部对象）

| 层 | 内容 |
|---|---|
| vstore（P1） | chunks.py（build_chunks 切块参数/ChunkIndex upsert/remove/search/rebuild_all）、embed.py embed_batch_chunked（批量 16/并发 4/失败降级）、vault.py add/delete 钩子（chunk 失败不阻断 doc 级 + chunk_count/chunk_ok/chunk_error 返回）、api.py search-chunks/rebuild-chunks/health chunk_count、settings.py VSTORE_CHUNK_PATH、scripts/rebuild_chunks.py CLI、存量 210 条重建 |
| BFF（P2） | services/privateqa.py（ask_private：检索→去重→拼上下文→DeepSeek 短答）、routers/private_docs.py（POST /api/qa/private 三态）、schemas.py（PrivateQARequest/PrivateDocItem/PrivateDocBlock 入 Block union）、main.py 路由注册、client.py search_chunks、llm.py complete_text timeout 参数 |
| 前端（P3） | api/private.js askPrivate、chat.js _firePrivate/_appendPrivate/_flushPrivate（ask/search 两模式、retry、竞态 pending/flush、防重入）、AssistantMessage.vue private_doc 块分支、i18n/private.js、PrivateLibraryPane.vue、DocPane 空态挂载、api/docgen.js removeLibrary（204 处理） |
| 回归红线 | docgen 模板检索（doc 级 /search 逐字段一致、上传/generate/导出全链路）；QA 金标树 8091 零 diff；红线文件零 diff；BFF 编译白名单未扩大；断流崩溃场景不存在（新模块无 yield） |

## 2. 测试分层（沿用 TEST_PLAN §1）

- **L1 单元**：vstore（chunks/embed/vault 钩子）、BFF（privateqa 纯逻辑、schemas union 校验）、前端（chat store 竞态逻辑、http 封装）。
- **L2 接口**：vstore 端点（search-chunks 三态/rebuild-chunks/health）、BFF /api/qa/private 三态 + docgen library CRUD 回归。
- **L2s 部署冒烟**：vstore 明文部署重启、chunk 存量重建 CLI、BFF 编译部署重启、前端构建。
- **L3 前端**：组件测试（private_doc 块渲染、PrivateLibraryPane、竞态场景）。
- **L4 端到端**：浏览器实测 ask/search 两模式、上传→检索闭环、刷新恢复、删除联动。

## 3. 覆盖率判定（100% 的可验证判定）

1. **功能点追溯**：每个 FR-PRIV-001~008 在用例表至少 1 条用例，双向追溯完整（无孤儿用例）。
2. **调整对象追溯**：§1 表格中每个调整文件/端点/函数至少 1 条用例（chunk 索引的切块参数边界、批量嵌入失败降级、to_thread 阻塞、pending/flush 竞态、防重入、204 空体、三态信封等均为显式用例）。
3. **边界与异常**：空库检索、低分阈值（min_score=0.30 两侧）、超 top_k clamp、每文档 200 块上限、同 doc 去重（每 doc≤3 块）、12k 上下文截断、LLM 40s 超时、vstore 宕机、LLM 宕机、上传超长 PDF。
4. **回归**：docgen doc 级检索响应逐字段、QA 8091 服务零改动（git diff 空）、红线文件 diff 空。

## 4. 环境与命令约定

- 服务器：ssh -p 26518 xzq@192.168.0.175（内网）或 8.163.92.8；仓库 /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new（分支 feature/bioflow-conversation-orchestration）；部署树 /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified。
- vstore 测试：venv = /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python；pytest 跑 vstore/tests/（新增 test_chunks.py）；端点 curl http://127.0.0.1:8094。
- BFF 测试：sdk 测试沿用既有 pytest 布局（services/test_*.py 同目录）；端点 curl http://127.0.0.1:8090。
- 前端测试：ui 下 vitest（npm test；新增 tests/private_docs/）。
- 部署仅 TL 执行；agent 不 commit 不部署。

## 5. 轮次纪律（用户要求，铁律）

1. T1 按用例表逐轮执行 → 每轮产出 `docs/team/TEST_REPORT_PRIV_R{n}.md`（缺陷编号 BUG-PRIV-R{n}-{序号}：复现步骤/预期/实际/对应用例号）。
2. 每轮全部问题**统一汇总**交 A1 修复 + 自测 → 交回 T1 复测（新轮次）。
3. 缺陷分级：阻断（修复前不得进下一轮）/严重/一般/轻微（沿用 TEST_PLAN §4）。
4. 循环直至某轮缺陷数为 0 → TL 终验。

## 6. 验收方式（TL 终验清单）

1. L1/L2/L3 全绿（pytest/vitest）。
2. curl 端到端：upload→ingest(chunk_count>0)→search-chunks 命中（snippet/score）→/api/qa/private 三态→delete 联动消失→docgen /search 逐字段回归。
3. 浏览器：ask+search 两模式私有卡片并行、未命中无感、刷新恢复、管理界面删除闭环。
4. 回归：docgen 上传/generate/导出全链路；QA 金标树 git diff 空；红线文件 diff 空；白名单未扩大。
5. 手工验收测试方法写入「PlantAI-new测试用例一览.xlsx」知识库 sheet（本地 docs/ 下）。

## 7. 用例规模预估

L1 单元 ~25（vstore 12 / BFF 8 / 前端 5）；L2 接口 ~18（vstore 9 / BFF 9）；L2s 部署冒烟 ~5；L3 前端 ~8；L4 端到端 ~6。合计约 **60 条**（TL 复查以双向追溯完整为准核定精确数）。