# 浠艾福（Care Family / XAF）测试资产总览

> 本目录存放与「软件测试」相关的全部资产。本批新增的 **用户使用场景 + 结构化测试用例** 基于
> 项目需求（`AGENTS.md`）、设计（`docs/superpowers/api/API_REFERENCE.md`）与当前实现（后端 Controller、
> 小程序前端页面、LangGraph AI 服务）编写，按用户角色组织。

## 目录结构

| 路径 | 内容 | 用途 |
|------|------|------|
| `BLACKBOX-TEST-PLAN.md` | 黑盒测试方案（6 角色功能矩阵 + 用例明细） | 既有：黑盒测试总纲 |
| `e2e/` | Playwright 可执行规格（`*.spec.js`，按 `roles/{admin,child,parent,teacher}` 组织） | 既有：自动化端到端用例 |
| `data/` | 种子数据与初始化 SQL | 测试数据 |
| **`user-scenarios/`** | **按角色的用户使用场景（叙事式）** | 本批新增：从真实用户视角描述「怎么用」 |
| **`test-cases/`** | **按角色的结构化测试用例 + 跨角色端到端用例** | 本批新增：可手动/自动执行的测试用例 |
| `test-cases/deep-dive-*.md` | **模块级代码深挖（测评预约 / 方案激活拆任务幂等）** | 本批新增：基于源码的边界/缺陷分析 |
| `defects/` | **缺陷单（代码级 + live 验证，CFC-AP-001~008 / CFC-EN-001 等）** | 本批新增：含五要素 + 修复建议；`DEFECT-TEST-RECORD.md` 为统一缺陷测试记录（汇总 12 项 + 测试执行记录） |
| `e2e/assessment-appointment-functional.spec.js` + `playwright.config.func.js` | **自包含功能/权限规格（去 globalSetup）** | 本批新增：测试自写种子数据，规避外部种子库依赖 |

## 资产关系

```
需求/设计 (AGENTS.md, API_REFERENCE.md)
        │
        ▼
 user-scenarios/   ── 用户故事 & 使用场景（"作为 X，我想 Y，以便 Z"）
        │  （一个场景可派生多个用例）
        ▼
 test-cases/       ── 结构化用例（前置/步骤/预期/优先级/类型/关联场景）
        │  （与可执行规格对应）
        ▼
 e2e/*.spec.js     ── 机器可执行的 Playwright 实现
```

- `user-scenarios/` 回答「产品为谁、解决什么、典型的一天怎么用」；
- `test-cases/` 回答「怎么验证它真的能工作、边界在哪、失败长什么样」；
- 两者与既有 `e2e/` 代码一一对应，手工 QA 与自动化共用同一套口径。

## 用户角色（统一口径）

依据 `AGENTS.md` 与黑盒方案，覆盖 6 类角色：

| 角色 | 关键标识 | 能力边界要点 |
|------|----------|--------------|
| 游客 Guest | 未登录 | 仅能浏览引流页/商城/文章；访问业务页被拦截 |
| 家长 Parent | `family_members.userId` 非空 + openid；家庭管理员 | 可管理家庭/成员、下发任务、申请测评、上传报告、生成方案；**可切换孩子视角** |
| 孩子 Child | `memberType=login`（能登录）/ `local`（不能登录，由家长代管） | 执行任务/小游戏/打卡/创建心愿；**直接登录的孩子端不能切回家长端** |
| 成长规划师 Teacher | `role=teacher` | 绑定家庭、代传报告、审核/激活方案、录入测评、可切回家长视角 |
| 平台运营 Admin | 管理端账号 | 全量数据/审核/配置/迁移；不碰业务闭环 |
| 商品服务商 Vendor | 入驻并通过审核 | 发布商品、处理订单（发货/核销） |

> 双角色铁律（来自 `AGENTS.md`）：家长可切换查看孩子视角；**直接登录的孩子端不能切换到家长端**；
> 规划师可切回家长视角。所有涉及切换的用例必须覆盖该边界。

## 设计约束（编写/执行用例时务必遵守）

- 统一 `@PostMapping`；响应 `Result<T>{code,message,data}`；JWT `Authorization: Bearer {token}`。
- 角色校验在 Controller 内读取 `@RequestAttribute("role")` 手动判断。
- AI 能力统一走 LangGraph（`cfc-langgraph:9000`，生产 `ai.etotem.com.cn`），Java 侧经 `AiGateway`（熔断+超时+Fallback）；禁止绕过。
- 测试模式：`wechat.test-mode: true` 跳过微信 API，使用模拟数据。
- 已废弃接口标记 `410 Gone`，用例不得依赖废弃路径（如 `/api/family/user/switch-mode` 应改用 `/api/family/member/switch`）。

## 如何参与

- 新增场景：在 `user-scenarios/<role>.md` 追加「用户故事 + 场景」，并同步在 `test-cases/<role>.md` 增加用例。
- 新增用例：遵循 `test-cases/README.md` 字段规范，标注关联场景与关联需求。
- 自动化映射：用例 `TC-xxx` 与 `e2e/roles/<role>/*.spec.js` 同名场景对应。

## 执行：自包含功能测试规格（无需外部种子库）

既有 `playwright.config.js` 的 `globalSetup`（db.js）会连接 `192.168.16.251` 重置/种子化测试库；若当前环境对该库不可达（Access denied），整套 e2e 无法启动。为此新增**自包含规格**，测试自己通过 API 写入种子数据（如 `direct-register` 自注册），不依赖外部种子库：

```bash
cd d:/cfc/tests
# 依赖：已 npm install 且已 npx playwright install chromium
npx playwright test tests/e2e/assessment-appointment-functional.spec.js \
  -c playwright.config.func.js --project=api
# 可选：指向本地后端
PW_BASE_URL=http://127.0.0.1:9082 npx playwright test \
  tests/e2e/assessment-appointment-functional.spec.js -c playwright.config.func.js
```

- 覆盖：TC-DV-03/05/06/07（无需种子的权限/异常用例，实测 5 passed）；TC-DV-09/01 依赖已有预约，需注入 `QUOTA_ID` / `APPOINTMENT_ID` 环境变量，否则按设计跳过。
- 真实后端码值约定：成功 `code=200`，业务错误 `code=500`（见 `common/Result.java`）。
- 缺陷与深挖：详见 `defects/DEFECTS-assessment-appointment.md`（F1–F8）与 `test-cases/deep-dive-*.md`。

## 执行：API 级 e2e（远程后端，2026-10-30 新增）

远程环境 `http://cfc.iwintrue.com` **只部署后端 API（Spring Boot），未托管前端 SPA**——访问任意路径（含 `/`）均返回白标 404 页。因此原 DOM 型 e2e（`page.goto('/#/pages/...')` + 选择器等待）在远程**必然全部超时失败**，与业务实现无关。为此建立 **API 级 e2e**：断言 `/api/*` 的响应码与数据结构，不依赖前端。

```bash
cd d:/cfc/tests
npx playwright test -c playwright.config.api.js --project=desktop
```

| 资产 | 说明 |
|---|---|
| `playwright.config.api.js` | 独立配置：无 `globalSetup`、独立 `outputDir`（`.api-artifacts`）、`testMatch` 仅匹配 `e2e/api/**`、用例级超时 180s |
| `e2e/helpers/api.js` | 共享助手：`registerRole`（`/api/auth/direct-register` 自注册，不依赖种子库/前端登录）、`apiPost`（统一 POST 封装，60s 超时 + 非 JSON 响应回退 HTTP 码） |
| `e2e/api/api-smoke.spec.js` | 链路自检：自注册 → 核心接口 → 越权 403 |
| `e2e/api/family-member-api.spec.js` | 家庭成员管理（13 例，镜像 DOM 版 10 场景 + 边界/特征化） |
| `e2e/api/energy-api.spec.js` | 能量系统收支（10 例，含五维维度断言） |
| `e2e/api/contact-api.spec.js` | 联系人管理（6 例） |
| `e2e/api/article-api.spec.js` | 文章管理（7 例） |

**实测基线：37 passed / 3 skipped（fixme，阻塞于真实缺陷）/ 47s**，同批场景在 DOM 型 e2e 上为 10 通过 / 32 失败。

**约定与注意事项**：
- 一律不回显 token / 手机号等敏感信息（`apiPost` 返回结构化结果，断言只取 `code` / `message` / `data`）。
- 自注册手机号必须严格 11 位匹配 `^1[3-9]\d{9}$`，否则返回「手机号格式不正确」。
- `POST /api/family/member/add` **冷启动首调约 16s**（后续 1.5s），故 API 超时放宽至 60s、用例超时 180s（见 CFC-ENV-002）。
- 被真实缺陷阻塞的用例用 `test.fixme()` 标记（保留「期望正确行为」的断言），并配套一条**特征化用例**锁定当前缺陷行为——缺陷修复后特征化用例会失败，提示移除 fixme。

**本次实测发现的缺陷**：见 `defects/DEFECTS-api-remote-findings.md`；全部 12 项缺陷的统一汇总与测试执行记录见 `defects/DEFECT-TEST-RECORD.md`。
| 编号 | 缺陷 | 严重度 | 优先级 |
|---|---|---|---|
| CFC-EN-001 | `/api/energy/grant` 返回 500「服务器内部错误」（后端未捕获异常） | 高 | P0 |
| CFC-FM-001 | `/api/family/member/update` 更新 nickname 返回成功但未生效（gender/birthday 正常） | 中 | P1 |
| CFC-ENV-001 | 远程未托管前端 SPA，DOM 型 e2e 全面不可用 | 中 | P1 |
| CFC-ENV-002 | `member/add` 冷启动首调约 16s | 低 | P2 |