02-parent.md 10 KB

用户使用场景 · 家长(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. 进入家庭模块 → 创建家庭(名称「测试家庭1」)。
    2. 系统生成唯一邀请码 + 邀请二维码(令牌 + 落地页)。
    3. 角色升级为「家庭管理员」,进入家庭首页。
  • 异常/边界:家庭名重复/为空 → 400 + 字段提示;重复创建家庭按业务规则限制。
  • 关联需求/设计:FamilyInviteController /api/family/invite/generate;cfclub 家庭邀请二维码特性。
  • 关联用例:TC-P-01

场景 P-2:邀请成员并维护家庭关系图

用户故事:作为家长,我想邀请爷爷加入并用关系标签管理成员,以便家庭结构清晰。

  • 角色:家长
  • 前置条件:家庭已创建;爷爷 C 微信/手机号可用。
  • 主流程
    1. 分享邀请码/二维码给 C → C 通过 register-with-invite 加入。
    2. 在成员管理添加成员资料(姓名/关系/生日/性别)。
    3. 用 RelationshipPicker 选择关系类型;编辑时将 C 的关系改为「外公」。
    4. 家庭关系图节点与关系标签同步更新。
  • 异常/边界:关系类型不存在 → 选择器不显示该项;删除成员前若有代管数据需确认。
  • 关联需求/设计:FamilyMembersController /api/family/member/*;关系类型 CRUD 在管理端(Web RelationshipTypes.vue)。
  • 关联用例:TC-P-02, TC-P-03, TC-P-04

场景 P-3:双角色切换(家长 ↔ 孩子视角)

用户故事:作为家长,我想临时以孩子视角查看 TA 的界面与数据,以便确认孩子端的体验。

  • 角色:家长
  • 前置条件:家庭含孩子 B(能登录或不能登录用户)。
  • 主流程
    1. 个人中心 → 切换视角 → 选择孩子 B。
    2. 界面切换为孩子端布局,数据隔离为 B 的视角。
    3. 切回家长端需二次校验(密码)。
  • 异常/边界:孩子端不能切回家长(登录即孩子视角,无家长入口);切换时若 B 为 local(无登录),数据由家长代管可见。
  • 关联需求/设计:POST /api/family/member/switch(替代已废弃 /api/family/user/switch-mode);双角色铁律。
  • 关联用例:TC-P-15

场景 P-4:创建任务并下发给孩子、审批完成

用户故事:作为家长,我想给孩子布置每日任务并在完成后给积分,以便培养习惯。

  • 角色:家长
  • 前置条件:家庭含孩子 B。
  • 主流程
    1. 创建任务(标题「睡前阅读」/ 成员 B / 积分 10 / 频率每日)。
    2. 任务出现在 B 的任务列表,状态「待执行」。
    3. B 完成后提交 → 家长端出现待审批。
    4. 家长「通过」→ B 积分 +N 并生成流水;「驳回」→ 退回重做。
  • 异常/边界:重复提交完成不重复发分;任务频率/截止日期边界。
  • 关联需求/设计:TaskController /api/tasks;积分 PointsController /api/points。
  • 关联用例:TC-P-05, TC-P-06

场景 P-5:心愿的创建—审批—兑换闭环

用户故事:作为家长,我想让孩子提心愿、我审批并扣积分兑换,以便激励正向行为。

  • 角色:家长(审批方)/ 孩子(创建方)
  • 前置条件:孩子 B 已创建心愿「买乐高」。
  • 主流程
    1. B 创建心愿(名称 + 所需积分)→ 进入家长待审批列表。
    2. 家长「通过」→ 扣除对应积分、进入兑换流程;「驳回」→ 心愿失效。
    3. 兑换成功,积分流水正确。
  • 异常/边界:积分不足时兑换被拦截;驳回后不可再兑换。
  • 关联需求/设计:WishController /api/wishes、RewardController /api/rewards。
  • 关联用例:TC-P-07

场景 P-6:查看五维能量与健康指数

用户故事:作为家长,我想一眼看到全家五维能量分配,以便掌握健康结构。

  • 角色:家长
  • 前置条件:家庭已有任务/打卡等能量产生记录。
  • 主流程
    1. 进入「身/心/智/行/富」维度首页。
    2. 展示家庭健康指数与五维能量分配,数值合理(总和=100%)。
    3. 查看能量流水(来源/时间)。
  • 异常/边界:能量比例配置错误导致不为 100% → 报警/修复;无数据时展示空态而非 500。
  • 关联需求/设计:EnergyController /api/energy;五维能量按比例分配。
  • 关联用例:TC-P-08

场景 P-7:申请测评(完整订单闭环)

用户故事:作为家长,我想为孩子预约专业测评,以便获得个性化方案。

  • 角色:家长
  • 前置条件:已绑定规划师 T;孩子 B 在家庭中。
  • 主流程
    1. 申请测评 → 选择孩子 B + 测评类型 + 规划师 T。
    2. 系统对 B 做孩子快照(时间点数据)。
    3. 支付环节完成 → 生成测评订单。
    4. 状态流转:已支付 → 待安排 → 已预约。
  • 异常/边界:未选规划师/未支付 → 订单不进入待安排;支付失败回滚。
  • ⚠️ 口径修正(来自 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 对应报告)。
  • 主流程
    1. 上传 PDF(POST /api/media/upload 公开 + 报告解析入口)。
    2. 系统识别为 gut_flora 类型 → 三阶段:上传 → 解析预览 → 确认入库。
    3. 报告列表出现该报告,展示菌群健康分/平衡/多样性、菌种明细、疾病风险。
    4. 七维健康评分刷新。
  • 异常/边界:非募极生物报告 → 提示「请确认是募极生物肠道菌群报告」;解析失败进入未知聚类待运营自学习。
  • 关联需求/设计:健康报告 PDF 上传与解析(cfclub);/api/admin/report-parser/types 已注册 gut_flora。
  • 关联用例:TC-P-10, TC-P-11

场景 P-9:基于报告生成饮食推荐

用户故事:作为家长,我想根据菌群报告得到可吃/慎吃清单,以便安排一日三餐。

  • 角色:家长
  • 前置条件:P-8 报告已入库。
  • 主流程
    1. 打开「身 → 饮食推荐」。
    2. 按菌群报告生成食材推荐指数,展示可吃/慎吃食物列表。
  • 异常/边界:无报告时无推荐;推荐随报告更新而刷新。
  • 关联需求/设计:饮食推荐系统(前端 + 后端);基于报告数据。
  • 关联用例:TC-P-12

场景 P-10:生成 AI 健康方案并送审/发布

用户故事:作为家长,我想一键生成个性化健康方案,以便规划师审核后激活执行。

  • 角色:家长
  • 前置条件:孩子 B 已有报告;部分功能需购买会员解锁。
  • 主流程
    1. 选孩子 B + 目标「基于菌群检测报告的个性化健康管理方案」。
    2. 调用 LangGraph(AiGateway 转发)→ 生成 overview + 营养/饮食/运动三板块。
    3. 可逐板块重新生成/确认。
    4. 保存/提交 → 进入「已提交(待规划师审核)」或按配置直接发布。
  • 异常/边界:未购买会员点击生成 → 提示购买;AI 超时/Fallback → 友好提示而非 500。
  • 关联需求/设计:AI 统一走 LangGraph(9000),Java 经 AiGateway(熔断+超时+Fallback);禁绕。
  • 关联用例:TC-P-13, TC-P-14, TC-P-16

场景 P-11:AI 健康管家对话

用户故事:作为家长,我想随时问健康管家孩子便秘吃什么,以便获得基于知识库的回答。

  • 角色:家长
  • 前置条件:已登录。
  • 主流程
    1. 进入 AI 对话(健康管家)→ POST /api/ai/health-coach/send。
    2. 返回基于知识库的回答,可含产品/任务推荐。
    3. 多轮上下文连续。
  • 异常/边界:LangGraph 不可用时 AiGateway Fallback 兜底;敏感问题不泄露隐私。
  • 关联需求/设计:AIChatController /api/ai/*;LangGraph RAG/对话。
  • 关联用例:TC-P-18

场景 P-12:查看积分流水与成长档案

用户故事:作为家长,我想核对积分明细和孩子成长记录,以便了解进展。

  • 角色:家长
  • 前置条件:已有任务/打卡/兑换记录。
  • 主流程
    1. 个人中心 → 积分明细(来源/变更/余额)。
    2. 成长记录页展示孩子成长轨迹。
    3. 时间格式统一 yyyy-MM-dd HH:mm:ss。
  • 异常/边界:积分与流水总额一致;删除/回退操作有对应负流水。
  • 关联需求/设计:PointsController、GrowthController /api/growth。
  • 关联用例:TC-P-17