# 结构化测试用例（Test Cases）

> 本目录是 `user-scenarios/` 的下游：每个场景派生为「正常流 + 异常流 + 权限流」多条用例。
> 用例可直接由手工 QA 执行，也与 `../e2e/roles/<role>/*.spec.js` 的可执行规格一一对应。

## 字段规范

| 字段 | 说明 |
|------|------|
| **TC 编号** | 全局唯一，格式 `TC-<角色前缀>-<序号>`（G 游客 / P 家长 / C 孩子 / T 规划师 / A 运营 / S 服务商 / X 跨角色）。 |
| **所属场景** | 对应的 `user-scenarios/<role>.md` 场景编号（如 P-8）。 |
| **模块** | 业务域（家庭/任务/能量/测评/健康报告/方案/AI/商城/管理端…）。 |
| **角色** | 执行该用例的用户角色。 |
| **优先级** | `P0` 主链路必过 · `P1` 重要功能 · `P2` 一般 · `P3` 边缘/异常。 |
| **类型** | `功能` / `接口` / `权限` / `异常` / `性能` / `兼容`。 |
| **前置条件** | 数据/状态/账号准备。 |
| **测试步骤** | 编号步骤，必要时含接口/操作。 |
| **预期结果** | 可判定的断言；含状态码/数据/UI 表现。 |
| **关联需求/设计** | 对应 `AGENTS.md` / `API_REFERENCE.md` 条款或控制器。 |
| **对应 e2e** | 已落地的 Playwright 规格路径（如有）。 |

## 通用前置

- 测试环境部署最新后端（含种子迁移）；管理端 `http://<host>/admin/`；小程序测试号 + `wechat.test-mode: true`。
- 六类账号：游客、家长 A、孩子 B（A 子账号）、规划师 T、运营 M、服务商 V；家庭「测试家庭1」含 A + B + 爷爷 C。
- 测试报告 PDF：募极生物肠道菌群报告样例（`tests/data/` 下对应文件）。
- 每次用例前按 `tests/e2e/reset-db.sh` 或管理端还原数据，避免脏数据串扰。

## 通过标准（汇总门禁）

1. 所有 **P0** 用例（主链路、方案管理、报告上传、双角色边界）100% 通过。
2. 其余用例通过率 ≥ 95%，未通过项均有明确缺陷描述与可复现步骤。
3. 近期修复回归项（见黑盒方案第 5 节）全部通过：方案管理页白屏、成长计划页、勋章创建、供应商创建、活动审核撤回、知识库删除、长文文章、接口参数校验。
4. 双角色边界（家长↔孩子可切；**孩子端不可切回家长**；规划师可切回家长）必须全部通过，否则整体不通过。

## 文件索引

| 文件 | 覆盖角色 | 用例范围 |
|------|----------|----------|
| `guest.md` | 游客 | TC-G-01~05 |
| `parent.md` | 家长 | TC-P-01~18 + 主链路 |
| `child.md` | 孩子 | TC-C-01~09 |
| `teacher.md` | 规划师 | TC-T-01~12 |
| `admin.md` | 运营 | TC-A-01~16 |
| `vendor.md` | 服务商 | TC-S-01~03 |
| `cross-role-e2e.md` | 跨角色 | TC-X-01~08（主链路端到端） |