# 结构化测试用例（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. 双角色边界（家长↔孩子可切；**孩子端不可切回家长**；规划师可切回家长）必须全部通过，否则整体不通过。

## 文件索引

> **三类用例结构**：每个角色文件在原有「正常流」用例之后，均追加了 `## 异常流用例（派生自正常流）` 与 `## 权限流用例（派生自正常流）` 两段。异常流编号后缀 `-E`、权限流后缀 `-P`，分别从每条正常流用例派生，实现「正常流 + 异常流 + 权限流」三类闭环。
> 当前三类（功能向）合计：**正常流 237 + 异常流 237 + 权限流 237 = 711 条**；外加**非功能用例 56 条**（`## 非功能测试用例（性能/兼容/安全）` 段，编号后缀 `-N`：性能 21 / 兼容 10 / 安全 25），全仓用例总计 **767 条**（截至 2026-11-05）。**异常流已全部改造为具体故障注入用例**（废除"系统给出明确错误提示而非 500"等模板文案；guest、五维专项及 parent/child/teacher/admin/vendor/cross 全量完成，每条 -E 均为明确故障注入 + 可判定断言），五维指标变化专项见各文件「五维指标变化专项」段。已落地 **4 枚接口层可执行规格**（非功能 2 枚 + 功能 2 枚）：
> - `tests/e2e/api/nonfunc-security.spec.js`（安全类 11 用例，覆盖 TC-G-N04 / TC-P-N09·N10·N11 / TC-A-N05·N06 / TC-C-N07 / TC-X-N05·N08）：鉴权/IDOR/权限提升/XSS/上传校验。
> - `tests/e2e/api/nonfunc-perf-compat.spec.js`（性能/兼容类 5 活动用例 + 2 跳过待业务夹具/压测授权，覆盖 TC-G-N02·N03 / TC-A-N04 / TC-P-N02 / TC-X-N01·N02·N07）：限流稳定性/多端 UA 兼容/并发隔离/响应时间基线。
> - `tests/e2e/api/butler-fallback.spec.js`（TC-B-06，4 活动用例 + 1 设计态；覆盖 AI 教练 Fallback 契约）：门禁两态契约（FREE 拦截须为 46003/46004 且文案可自助解决、非 5xx）／放行态结构完整（answer/conversationId/recommendations/tasks）／降级态须带 degraded·fallback 标记（**已知缺口探针**：当前实现 answer 置空但无标记）／连续 10 次无非预期业务码／AI 故障不拖垮家庭接口。
> - `tests/e2e/api/human-butler-workorder.spec.js`（TC-H-01，4 活动用例 + 1 fixme；覆盖真人管家承接与并发守卫）：串行重放审核须被 pending 守卫拒绝且不重复建档／并发审核档案唯一（乐观锁探针）／未认证管家不可分配成员／分配生效且重复分配幂等（管家侧恰好见 1 次）／AI 升级工单接口未实现，以 fixme 记录期望契约。
> 可直接 `npx playwright test -c playwright.config.api.js --project=desktop` 执行，提升接口层可执行覆盖率。剩余性能/兼容类用例（前端渲染、真实压测）因 CFC-ENV-001 远程无 SPA 与需 execute 档联网授权，保留为文档化设计。

| 文件 | 覆盖角色 | 正常流范围 | 异常流 / 权限流 |
|------|----------|------------|------------------|
| `guest.md` | 游客 | TC-G-01~12 | TC-G-NN-E / TC-G-NN-P（各 12 条） |
| `parent.md` | 家长 | TC-P-01~93 | TC-P-NN-E / TC-P-NN-P（各 93 条，含五维变化专项 SC-P-87~93） |
| `child.md` | 孩子 | TC-C-01~25 | TC-C-NN-E / TC-C-NN-P（各 25 条，含五维变化专项 SC-C-24~25） |
| `teacher.md` | 规划师 | TC-T-01~32 | TC-T-NN-E / TC-T-NN-P（各 32 条，含五维变化专项 SC-T-30~32） |
| `admin.md` | 运营 | TC-A-01~26（A-24 空号） | TC-A-NN-E / TC-A-NN-P（各 25 条，含五维变化专项 SC-A-25~26） |
| `vendor.md` | 服务商 | TC-S-01~11 | TC-S-NN-E / TC-S-NN-P（各 11 条） |
| `cross-role-e2e.md` | 跨角色 | TC-X-01~22 | TC-X-NN-E / TC-X-NN-P（各 22 条，9 列格式，含五维变化专项 SC-X-19~21、CF 值预估专项 SC-X-22） |
| `butler.md` | AI 成长教练（AI 管家） | TC-B-01~12（空号 03、08，实编 10） | TC-B-NN-E / TC-B-NN-P（各 10 条，9 列格式） |
| `human-butler.md` | 真人管家 | TC-H-01~07 | TC-H-NN-E / TC-H-NN-P（各 7 条，9 列格式） |

---

## 双向追踪矩阵（2026-11-10）

> **`tests/TRACEABILITY-MATRIX.md`** 是「需求 ↔ SC ↔ TC」双向追溯主表，以编号级扫描为单一事实源。本文上方「文件索引 / 通过标准」中的合计（767 条，截至 2026-11-05）为**历史口径**；当前实测唯一 TC 编号 **842 条**（正常 282 / 异常 249 / 权限 243 / 非功能 58 / 深挖 10），241 个 SC 三流齐全 **241/241**。历史台账存在多套互相矛盾的数字，一律以主矩阵为准。

本轮新增 15 条用例（3 个专项段）：

| 专项段 | 文件 | 覆盖 SC | 编号 |
|---|---|---|---|
| 成就与成长历史专项 | `parent.md` | SC-P-94 / 95 / 96 | TC-P-94~96（各含 -E / -P） |
| 睡眠打卡配置驱动专项 | `child.md` | SC-C-26 | TC-C-26 / -E / -P |
| 睡眠情况选项后台维护专项 | `admin.md` | SC-A-27 | **TC-A-27-S / -S-E / -S-P** |

> ⚠️ `TC-A-27*` 三流已被 S-cfc-68「团队分润/提现审核」占用，与 SC-A-27 语义无关；本轮用 `-S` 后缀避开冲突，**未改动任何既有 TC**。编号重排需主理人裁决，登记于主矩阵 G-2。