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）	本批新增：含五要素 + 修复建议
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。