用户使用场景 · 家长(Parent)
来源:AGENTS.md(双角色、五维能量、测评订单、家庭邀请二维码、成员关系编辑、健康报告主链路、饮食推荐、LangGraph AI)、API_REFERENCE.md、cfc-frontend/pages/*、黑盒方案 P-01~P-18。
关联用例:test-cases/parent.md(TC-P-01~TC-P-18 及跨角色 E2E)。
场景 P-1:创建家庭并生成邀请入口
用户故事:作为家庭第一人,我想创建家庭并邀请其他成员,以便全家共用一套健康/成长管理。
- 角色:家长(创建者即家庭管理员)
- 前置条件:已登录(默认 parent)。
- 主流程
- 进入家庭模块 → 创建家庭(名称「测试家庭1」)。
- 系统生成唯一邀请码 + 邀请二维码(令牌 + 落地页)。
- 角色升级为「家庭管理员」,进入家庭首页。
- 异常/边界:家庭名重复/为空 → 400 + 字段提示;重复创建家庭按业务规则限制。
- 关联需求/设计:
FamilyInviteController /api/family/invite/generate;cfclub 家庭邀请二维码特性。
- 关联用例:TC-P-01
场景 P-2:邀请成员并维护家庭关系图
用户故事:作为家长,我想邀请爷爷加入并用关系标签管理成员,以便家庭结构清晰。
- 角色:家长
- 前置条件:家庭已创建;爷爷 C 微信/手机号可用。
- 主流程
- 分享邀请码/二维码给 C → C 通过
register-with-invite 加入。
- 在成员管理添加成员资料(姓名/关系/生日/性别)。
- 用
RelationshipPicker 选择关系类型;编辑时将 C 的关系改为「外公」。
- 家庭关系图节点与关系标签同步更新。
- 异常/边界:关系类型不存在 → 选择器不显示该项;删除成员前若有代管数据需确认。
- 关联需求/设计:
FamilyMembersController /api/family/member/*;关系类型 CRUD 在管理端(Web RelationshipTypes.vue)。
- 关联用例:TC-P-02, TC-P-03, TC-P-04
场景 P-3:双角色切换(家长 ↔ 孩子视角)
用户故事:作为家长,我想临时以孩子视角查看 TA 的界面与数据,以便确认孩子端的体验。
- 角色:家长
- 前置条件:家庭含孩子 B(能登录或不能登录用户)。
- 主流程
- 个人中心 → 切换视角 → 选择孩子 B。
- 界面切换为孩子端布局,数据隔离为 B 的视角。
- 切回家长端需二次校验(密码)。
- 异常/边界:孩子端不能切回家长(登录即孩子视角,无家长入口);切换时若 B 为
local(无登录),数据由家长代管可见。
- 关联需求/设计:
POST /api/family/member/switch(替代已废弃 /api/family/user/switch-mode);双角色铁律。
- 关联用例:TC-P-15
场景 P-4:创建任务并下发给孩子、审批完成
用户故事:作为家长,我想给孩子布置每日任务并在完成后给积分,以便培养习惯。
- 角色:家长
- 前置条件:家庭含孩子 B。
- 主流程
- 创建任务(标题「睡前阅读」/ 成员 B / 积分 10 / 频率每日)。
- 任务出现在 B 的任务列表,状态「待执行」。
- B 完成后提交 → 家长端出现待审批。
- 家长「通过」→ B 积分 +N 并生成流水;「驳回」→ 退回重做。
- 异常/边界:重复提交完成不重复发分;任务频率/截止日期边界。
- 关联需求/设计:
TaskController /api/tasks;积分 PointsController /api/points。
- 关联用例:TC-P-05, TC-P-06
场景 P-5:心愿的创建—审批—兑换闭环
用户故事:作为家长,我想让孩子提心愿、我审批并扣积分兑换,以便激励正向行为。
- 角色:家长(审批方)/ 孩子(创建方)
- 前置条件:孩子 B 已创建心愿「买乐高」。
- 主流程
- B 创建心愿(名称 + 所需积分)→ 进入家长待审批列表。
- 家长「通过」→ 扣除对应积分、进入兑换流程;「驳回」→ 心愿失效。
- 兑换成功,积分流水正确。
- 异常/边界:积分不足时兑换被拦截;驳回后不可再兑换。
- 关联需求/设计:
WishController /api/wishes、RewardController /api/rewards。
- 关联用例:TC-P-07
场景 P-6:查看五维能量与健康指数
用户故事:作为家长,我想一眼看到全家五维能量分配,以便掌握健康结构。
- 角色:家长
- 前置条件:家庭已有任务/打卡等能量产生记录。
- 主流程
- 进入「身/心/智/行/富」维度首页。
- 展示家庭健康指数与五维能量分配,数值合理(总和=100%)。
- 查看能量流水(来源/时间)。
- 异常/边界:能量比例配置错误导致不为 100% → 报警/修复;无数据时展示空态而非 500。
- 关联需求/设计:
EnergyController /api/energy;五维能量按比例分配。
- 关联用例:TC-P-08
场景 P-7:申请测评(完整订单闭环)
用户故事:作为家长,我想为孩子预约专业测评,以便获得个性化方案。
- 角色:家长
- 前置条件:已绑定规划师 T;孩子 B 在家庭中。
- 主流程
- 申请测评 → 选择孩子 B + 测评类型 + 规划师 T。
- 系统对 B 做孩子快照(时间点数据)。
- 支付环节完成 → 生成测评订单。
- 状态流转:已支付 → 待安排 → 已预约。
- 异常/边界:未选规划师/未支付 → 订单不进入待安排;支付失败回滚。
- ⚠️ 口径修正(来自
test-cases/deep-dive-assessment-appointment.md):真实实现为 订单 → 额度 → 预约 三段式。AssessmentOrder(pending→paid) 支付成功后生成「测评额度 AssessmentQuota」;POST /api/assessment/appointment/create 会先消耗一条额度,额度不足/过期直接报错、不落预约。「孩子快照」与「录入结果触发方案」在 AssessmentResult/DanAssessment 链路,不在预约创建环节。故完整闭环应为:购买套餐 → 订单 paid → 获得额度 → 创建预约(消耗额度) → 规划师确认/完成 → 录入结果生成方案。
- 关联需求/设计:
AssessmentAppointmentController /api/assessment/appointment/*、AssessmentOrder(pending/paid/cancelled/refunded)。
- 关联用例:TC-P-09、TC-DV-01~10(见深挖文档)
场景 P-8:上传健康报告 PDF 并自动解析(主链路起点)
用户故事:作为家长,我想上传孩子的肠道菌群报告,以便系统自动解析出健康分与推荐。
- 角色:家长
- 前置条件:持有募极生物肠道菌群报告 PDF(样例
530010234-侯.json 对应报告)。
- 主流程
- 上传 PDF(
POST /api/media/upload 公开 + 报告解析入口)。
- 系统识别为
gut_flora 类型 → 三阶段:上传 → 解析预览 → 确认入库。
- 报告列表出现该报告,展示菌群健康分/平衡/多样性、菌种明细、疾病风险。
- 七维健康评分刷新。
- 异常/边界:非募极生物报告 → 提示「请确认是募极生物肠道菌群报告」;解析失败进入未知聚类待运营自学习。
- 关联需求/设计:健康报告 PDF 上传与解析(cfclub);
/api/admin/report-parser/types 已注册 gut_flora。
- 关联用例:TC-P-10, TC-P-11
场景 P-9:基于报告生成饮食推荐
用户故事:作为家长,我想根据菌群报告得到可吃/慎吃清单,以便安排一日三餐。
- 角色:家长
- 前置条件:P-8 报告已入库。
- 主流程
- 打开「身 → 饮食推荐」。
- 按菌群报告生成食材推荐指数,展示可吃/慎吃食物列表。
- 异常/边界:无报告时无推荐;推荐随报告更新而刷新。
- 关联需求/设计:饮食推荐系统(前端 + 后端);基于报告数据。
- 关联用例:TC-P-12
场景 P-10:生成 AI 健康方案并送审/发布
用户故事:作为家长,我想一键生成个性化健康方案,以便规划师审核后激活执行。
- 角色:家长
- 前置条件:孩子 B 已有报告;部分功能需购买会员解锁。
- 主流程
- 选孩子 B + 目标「基于菌群检测报告的个性化健康管理方案」。
- 调用 LangGraph(
AiGateway 转发)→ 生成 overview + 营养/饮食/运动三板块。
- 可逐板块重新生成/确认。
- 保存/提交 → 进入「已提交(待规划师审核)」或按配置直接发布。
- 异常/边界:未购买会员点击生成 → 提示购买;AI 超时/Fallback → 友好提示而非 500。
- 关联需求/设计:AI 统一走 LangGraph(9000),Java 经
AiGateway(熔断+超时+Fallback);禁绕。
- 关联用例:TC-P-13, TC-P-14, TC-P-16
场景 P-11:AI 健康管家对话
用户故事:作为家长,我想随时问健康管家孩子便秘吃什么,以便获得基于知识库的回答。
- 角色:家长
- 前置条件:已登录。
- 主流程
- 进入 AI 对话(健康管家)→
POST /api/ai/health-coach/send。
- 返回基于知识库的回答,可含产品/任务推荐。
- 多轮上下文连续。
- 异常/边界:LangGraph 不可用时
AiGateway Fallback 兜底;敏感问题不泄露隐私。
- 关联需求/设计:
AIChatController /api/ai/*;LangGraph RAG/对话。
- 关联用例:TC-P-18
场景 P-12:查看积分流水与成长档案
用户故事:作为家长,我想核对积分明细和孩子成长记录,以便了解进展。
- 角色:家长
- 前置条件:已有任务/打卡/兑换记录。
- 主流程
- 个人中心 → 积分明细(来源/变更/余额)。
- 成长记录页展示孩子成长轨迹。
- 时间格式统一
yyyy-MM-dd HH:mm:ss。
- 异常/边界:积分与流水总额一致;删除/回退操作有对应负流水。
- 关联需求/设计:
PointsController、GrowthController /api/growth。
- 关联用例:TC-P-17