# TEST_PLAN.md —— 测试策略与轮次纪律

> 版本 1.0 ｜ 作者 PM ｜ 本文件由 PM 独占写入，所有开发/测试 agent **只读**
>
> 本文件定义「怎么测」。测什么以 `PRD.md` 为准，用例在 `TEST_CASES.md`（T 编写）。

---

## 1. 测试分层

| 层 | 工具 | 归属 | 覆盖对象 | 运行方式 |
|---|---|---|---|---|
| L1 后端单元 | pytest | A1/A2/A3 自测 | normalize 别名收敛、SSE 帧解析、阶段→相位映射、SQLite CRUD、错误信封 | `cd backend && pytest tests -m unit` |
| L2 后端接口 | pytest + respx（mock 上游） | T 主写，A 组配合 | 每个 BFF 接口的正常/降级/超时/重试路径 | `pytest tests -m api` |
| L2s 上游 smoke | 脚本 | T | 对真实 7920/8000/Neo4j 的最小连通验证（**不在 CI 每轮跑**，仅集成点与验收前跑一次） | `bash tests/smoke_upstreams.sh` |
| L3 前端单元 | Vitest | B 组自测 + T 补写 | stores、SSE parser、labels 映射、modes 参数集、工具函数 | `cd frontend && npx vitest run` |
| L4 前端组件 | Vitest + @vue/test-utils | B 组自测 + T 补写 | 每个组件的全部状态（默认/悬停/激活/禁用/加载/空/错误） | 同上 |
| L5 端到端 | Playwright | T | 完整流程 × 三档视口 | `npx playwright test` |
| L6 验收 | 人工 + 浏览器 | PM | 真实上游 + 视觉走查 | 见验收脚本 |

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

1. **需求追溯（主门禁）**：`PRD.md` 的 81 个 `FR-*`（FR-RESP-013 除外，为可选项）中，**每一个**在 `TEST_CASES.md` 追溯矩阵中至少映射一条 `TC-*`；同时**无孤儿 TC**（每条用例必须追溯到至少一个 FR）。双向映射完整性 = 100%。
2. **行覆盖（辅门禁）**：后端 pytest ≥85%，前端 Vitest ≥80%。未达标不能宣称 100%，但行覆盖达标**不替代**需求覆盖。

测试 agent 每轮报告首页必须给出：FR 总数 / 已覆盖 / 未覆盖清单（若不为空）。

## 3. 测试环境

| 项 | 值 |
|---|---|
| L1/L2 运行处 | 远端 `plantai-bff` conda 环境（pytest） |
| L3/L4 运行处 | 远端 `frontend/`（Vitest，Node 18） |
| L5 运行处 | 远端（Playwright chromium，headed 不强制），**或** Mac 本地通过 SSH 隧道打到远端 |
| L5 视口 | iPhone 14 390×844 ｜ iPad 768×1024 ｜ Desktop 1440×900 |
| mock 服务 | `python backend/mock/mock_server.py`，端口 8099，scenario 参数切场景 |
| 真实上游 | 7920 / 8000 / 7900 / Neo4j（按 DISCOVERY.md 选型） |

## 4. 缺陷分级

| 级别 | 定义 | 处置 |
|---|---|---|
| 阻断 Blocker | 主流程无法走通、数据损坏、崩溃 | 修复前不得进入下一轮 |
| 严重 Major | 功能错误、契约不符、数据错误 | 本轮必须修复 |
| 一般 Minor | 视觉瑕疵、次要交互问题 | 本轮修复，可批量 |
| 轻微 Trivial | 文案、间距等不影响理解 | 累积到 M6 收尾处理 |

缺陷编号：`BUG-R{n}-{序号}`，报告含复现步骤、预期/实际、截图或日志证据、对应 TC 编号。

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

1. 测试 agent **完整跑完一整轮全部用例**（L1+L2+L3+L4+L5 全量），**中途不修改任何代码**。
2. 产出 `docs/TEST_REPORT_R{n}.md`：首页统计（TC 总数 / pass / fail / 未跑 + FR 覆盖统计 + 行覆盖率）、缺陷清单（分级）、证据。
3. PM 汇总缺陷，**批量派发**给归属 agent 修复；开发 agent 只修自己文件归属内的缺陷。
4. 修复完成后进入下一轮：**再次完整跑完全部用例**（全量回归，不做增量）。
5. 循环直至：所有 TC pass + 主门禁 100% + 辅门禁达标。
6. 移交 PM 做 L6 验收。验收发现问题按第 4 级（轻微）回流或直接修复，由 PM 判定。

## 6. L5 端到端场景（必测主线）

对三档视口分别执行（各视口用例独立编号）：

1. **E2E-主流程**：新建会话 → 问答模式提问 → 流水线五相位推进 → 答案揭示（含表格）→ 来源 tab 有数据 → 图谱 tab 渲染 → 刷新后历史恢复
2. **E2E-检索模式**：检索模式提问 → 只出来源不出答案块
3. **E2E-错误与重试**：mock `scenario=error` 下提问 → 错误展示 + 重试按钮可用；`scenario=degraded` 下作曲器禁用
4. **E2E-会话管理**：新建/切换/重命名/删除/搜索过滤/分组
5. **E2E-中断**：流式中途切会话 → 原会话置 error 标注已中断
6. **E2E-主题**：深浅切换 + 刷新持久化
7. **E2E-图谱**：实体搜索 → 邻域展开 → 节点详情 → 缩放平移（移动端双指）
8. **E2E-抽取**：任务列表 → 详情展开 → 运行日志；mock 下上传 PDF
9. **E2E-响应式专项**：三档视口各自布局断言（见 PRD FR-RESP-001~004）+ 移动端专项（安全区、16px 输入、44px 触控、表格横滚、键盘适配）

## 7. 运行命令约定

```bash
# 后端（远端，plantai-bff 环境）
cd backend && pytest tests -m unit -q          # L1
cd backend && pytest tests -m api -q           # L2（respx mock）
bash tests/smoke_upstreams.sh                  # L2s 真实连通（手动触发）

# 前端（远端）
cd frontend && npx vitest run                  # L3+L4
cd frontend && npx playwright test             # L5（三档视口配置在 playwright.config.js）

# mock（开发与 L5 的 error/degraded 场景）
python backend/mock/mock_server.py             # 127.0.0.1:8099
```

## 8. 报告模板（TEST_REPORT_R{n}.md 必须包含）

1. 轮次信息：日期、被测版本、运行环境
2. 首页统计表：TC 总数/pass/fail/skip、FR 覆盖 80/80 或缺口清单、行覆盖率（后端/前端）
3. 缺陷清单表：编号 | 级别 | TC | 归属 agent | 现象 | 预期 | 证据路径
4. 上轮缺陷修复确认表：BUG 编号 | 是否修复 | 本轮对应 TC 结果
5. 遗留问题与风险