cfc/tests

浠艾福（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 自注册），不依赖外部种子库：

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/* 的响应码与数据结构，不依赖前端。

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 |