t

tests/user-scenarios/08-butler.md

@@ -0,0 +1,210 @@
+# 健康管家（Butler）应用场景
+
+> 角色标签：`butler`；场景编号：`SC-B-01~12`；关联用例：`TC-B-01~12`（待补，见 `../test-cases/butler.md`）。
+>
+> **角色定位**：AI 健康管家（health-coach）是面向家庭的**主动式 AI 智能体**。以**家长为触达入口**、**孩子健康数据为底座**、**成长规划师为专业出口**。职责不止被动问答，更承担主动提醒/预警、报告智能解读、个性化推荐、健康简报、转接规划师、家庭健康聚合等主动服务。
+>
+> **边界澄清**：管家 ≠ 孩子端 AI 对话（`SC-C-13`，孩子视角，走 `AIChatController`）。管家不以孩子视角登录，仅在家长端触达，底层消费 `POST /api/ai/health-coach/send`。
+>
+> **家长端入口**：见 `02-parent.md` 的 **SC-P-49**（已收敛为管家入口引用，保留编号与 P0）。本文是管家角色完整能力谱系。
+
+## 业务域 A：对话与咨询
+
+### 场景 B-01：健康管家对话咨询（SC-B-01）
+
+**用户故事**：作为家长，我想随时问健康管家「孩子便秘吃什么/怎么调理」，以便获得基于知识库的回答。
+
+- **角色**：家长（管家主入口）
+- **前置条件**：已登录；AI 服务可用（LangGraph 或 Fallback）。
+- **主流程**
+  1. 进入 AI 对话（健康管家）→ `POST /api/ai/health-coach/send`。
+  2. 返回基于知识库的回答，可含产品/任务推荐。
+  3. 多轮上下文连续（会话级记忆）。
+- **异常/边界**：LangGraph 不可用时 `AiGateway` Fallback 兜底；敏感问题不泄露隐私。
+- **关联需求/设计**：`AIChatController` `/api/ai/*`；LangGraph RAG/对话。家长端入口见 `02-parent.md` SC-P-49。
+- **关联用例**：TC-B-01（待补）
+
+---
+
+## 业务域 B：主动服务 · 提醒与预警
+
+### 场景 B-02：主动健康提醒（SC-B-02）
+
+**用户故事**：作为家长，我希望管家按用药/饮水/作息/测评到期等节点主动提醒，以免遗漏关键事项。
+
+- **角色**：家长（触达）/ 孩子（数据对象）
+- **前置条件**：已配置提醒项（手动或方案派生）；消息推送通道可用。
+- **主流程**
+  1. 提醒项到期/到点 → 管家触发提醒生成。
+  2. 推送至家长（必要时孩子端只读可见）。
+  3. 家长点击可跳转对应任务/预约/报告。
+- **异常/边界**：免打扰时段不推送（关键安全提醒除外）；重复提醒去重（同一事项不重复推）；仅本家庭成员可见，越权家庭不可触达。
+- **关联需求/设计**：消息服务 / 提醒调度 🟡（`/api/notify/*`）。关联 SC-P-65 通知设置。
+- **关联用例**：TC-B-02（待补）
+
+### 场景 B-03：异常指标预警（SC-B-03）
+
+**用户故事**：作为家长，我希望孩子五维能量或健康报告出现异常时，管家主动预警并给出可执行的建议。
+
+- **角色**：家长
+- **前置条件**：已有五维能量/健康报告数据；阈值规则已配置。
+- **主流程**
+  1. 指标越阈值（如某维度骤降、报告风险项命中）→ 管家识别异常。
+  2. 主动推送预警 + 行动建议（复查/饮食/就医提示）。
+  3. 家长确认/忽略，状态回写。
+- **异常/边界**：静默策略（短时间内同类异常不重复打扰，合并推送）；阈值可配；误报可由家长忽略并反馈；无数据不误报。
+- **关联需求/设计**：监控/阈值引擎 🟡（关联 `EnergyRuleEngine` / `HealthReportController`）。关联 SC-P-17/SC-P-91。
+- **关联用例**：TC-B-03（待补）
+
+---
+
+## 业务域 C：报告智能解读
+
+### 场景 B-04：健康报告智能解读（SC-B-04）
+
+**用户故事**：作为家长，我希望管家把专业报告翻译成人话，并关联五维给出行动建议，便于理解孩子健康。
+
+- **角色**：家长
+- **前置条件**：孩子已有健康报告（已入库，见 SC-P-23/SC-P-91）。
+- **主流程**
+  1. 家长选择报告 → 发起解读。
+  2. 管家输出通俗语言解读 + 五维关联 + 行动建议。
+  3. 可追问（见 SC-B-11）或一键采纳建议为任务（见 SC-B-07）。
+- **异常/边界**：无报告不解读（提示先上传）；解读不超出报告范围（不杜撰指标）；敏感数据脱敏展示；报告类型不一致时提示。
+- **关联需求/设计**：报告解析中台 / `HealthReportController` 🟡（关联 SC-P-20~23）。
+- **关联用例**：TC-B-04（待补）
+
+### 场景 B-11：报告细节追问（SC-B-11）
+
+**用户故事**：作为家长，我希望就报告中的具体细节（某菌种、某风险项）继续追问，管家基于该报告上下文回答。
+
+- **角色**：家长
+- **前置条件**：已对该报告发起过解读（SC-B-04）；报告上下文在会话内可追溯。
+- **主流程**
+  1. 家长针对报告细节提问。
+  2. 管家基于该报告结构化数据 + 知识库给出定向回答。
+  3. 多轮深入到具体指标。
+- **异常/边界**：追问超出报告范围时明确提示「报告未涵盖」；脱离报告上下文的泛问回退到通用咨询（SC-B-01）；不泄露其他成员报告。
+- **关联需求/设计**：`AIChatController` 报告上下文注入 🟡。
+- **关联用例**：TC-B-11（待补）
+
+---
+
+## 业务域 D：个性化推荐
+
+### 场景 B-07：个性化任务/饮食推荐（SC-B-07）
+
+**用户故事**：作为家长，我希望管家根据孩子五维短板或报告，自动推荐任务、心愿、饮食，减少我自己规划的负担。
+
+- **角色**：家长
+- **前置条件**：已有五维能量/健康报告作为推荐依据。
+- **主流程**
+  1. 分析孩子五维短板 / 报告风险。
+  2. 生成任务/心愿/饮食推荐清单。
+  3. 推送家长；家长可一键采纳为正式任务或心愿。
+- **异常/边界**：无报告时降级为通用推荐（提示依据不足）；推荐可一键采纳（采纳后落 `TaskController`/`WishController`）；重复推荐幂等；过敏/忌口自动排除（关联 SC-P-28）。
+- **关联需求/设计**：任务/心愿/饮食推荐系统 🟡（关联 SC-P-10/SC-P-13/SC-P-26）。
+- **关联用例**：TC-B-07（待补）
+
+---
+
+## 业务域 E：健康简报
+
+### 场景 B-08：每日/每周健康简报（SC-B-08）
+
+**用户故事**：作为家长，我希望管家定期汇总全家健康摘要，让我一眼掌握近期变化。
+
+- **角色**：家长
+- **前置条件**：家庭成员已有能量/报告/任务/方案数据。
+- **主流程**
+  1. 定时（日/周）聚合全家健康数据。
+  2. 生成摘要（五维变化、待办、预警、进展）。
+  3. 推送家长。
+- **异常/边界**：数据缺失项降级展示（不报错/不白屏）；推送频率可配（关联 SC-P-65）；空数据家庭给出引导而非空简报。
+- **关联需求/设计**：报告/成长聚合 🟡（关联 `GrowthController`/`EnergyController`）。
+- **关联用例**：TC-B-08（待补）
+
+---
+
+## 业务域 F：连接成长规划师
+
+### 场景 B-09：管家转接成长规划师（SC-B-09）
+
+**用户故事**：作为家长，当管家识别到需专业干预的信号时，我希望它引导我转接成长规划师，而不是给不了专业结论。
+
+- **角色**：家长
+- **前置条件**：已绑定成长规划师（关联 SC-T-02）；或提示先绑定。
+- **主流程**
+  1. 管家识别专业信号（如持续异常、方案分歧、报告高风险）。
+  2. 引导家长预约/发消息给绑定规划师。
+  3. 生成预约（关联 SC-P-36）或消息（关联 SC-X-11），转接留痕。
+- **异常/边界**：未绑定规划师时提示先绑定（关联 SC-P-32）；转接动作留审计；不代规划师给出诊断结论。
+- **关联需求/设计**：预约/消息服务 🟡（关联 `AssessmentAppointmentController` / 消息服务）。
+- **关联用例**：TC-B-09（待补）
+
+### 场景 B-12：同步规划师建议主动服务（SC-B-12）
+
+**用户故事**：作为家长，当规划师方案生效后，我希望管家据此主动跟进（打卡提醒、进度提示），而不是我手动盯。
+
+- **角色**：家长
+- **前置条件**：规划师方案已激活（关联 SC-P-46/SC-T-05）；管家可读取方案任务。
+- **主流程**
+  1. 方案激活后，管家同步方案任务与节奏。
+  2. 按节奏主动推送打卡提醒/进度提示。
+  3. 异常停滞时提示家长关注。
+- **异常/边界**：方案未激活不触发；方案变更后管家重同步；家长可暂停管家跟进；仅本家庭任务可见。
+- **关联需求/设计**：成长计划/任务服务 🟡（关联 `GrowthPlanController`/`GrowthTaskService`）。
+- **关联用例**：TC-B-12（待补）
+
+---
+
+## 业务域 G：家庭健康看板
+
+### 场景 B-10：家庭健康看板（管家聚合视图）（SC-B-10）
+
+**用户故事**：作为家长，我希望管家一屏聚合全家五维、任务、报告、方案，快速掌握整体健康状态。
+
+- **角色**：家长
+- **前置条件**：家庭成员已有能量/报告/任务/方案数据。
+- **主流程**
+  1. 打开家庭健康看板。
+  2. 管家聚合展示成员五维能量、近期报告、进行中任务/方案、预警项。
+  3. 点击任意卡片下钻。
+- **异常/边界**：仅本家庭成员可见；数据缺失降级展示（不报错）；越权家庭 403。
+- **关联需求/设计**：家庭天盘/仪表板 🟡（关联 SC-P-68 家庭天盘 / SC-T-16 客户总览）。
+- **关联用例**：TC-B-10（待补）
+
+---
+
+## 业务域 H：安全与韧性
+
+### 场景 B-05：敏感问题拦截与隐私保护（SC-B-05）
+
+**用户故事**：作为平台，我需要保证管家对违规/敏感问题拒答、且不泄露家庭成员隐私。
+
+- **角色**：系统（横切）
+- **前置条件**：内容安全策略/敏感词库已配置。
+- **主流程**
+  1. 用户提问命中敏感词/违规类别 → 管家拒答并给出合规提示。
+  2. 越权询问（查询非本家庭成员数据）→ 拒答。
+- **异常/边界**：敏感词命中即拦截（关联 SC-A-13/SC-T-28 内容安全）；不泄露内部错误详情；不返回 500。
+- **关联需求/设计**：内容安全 / `AIChatController`。
+- **关联用例**：TC-B-05（待补）
+
+### 场景 B-06：LangGraph 不可用 Fallback（SC-B-06）
+
+**用户故事**：作为用户，当 AI 底层（LangGraph）故障时，我仍能用管家的基础能力，而不是白屏或报错。
+
+- **角色**：系统（横切）
+- **前置条件**：`AiGateway` 熔断/超时机制就绪。
+- **主流程**
+  1. LangGraph 不可达/超时 → `AiGateway` 触发 Fallback。
+  2. 管家降级到规则/模板/FAQ 兜底回答。
+  3. 明确提示「AI 服务降级中」。
+- **异常/边界**：降级提示明确；超时熔断不阻塞主流程；不返回 500；恢复后自动切回 LangGraph。
+- **关联需求/设计**：`AiGateway`（熔断+超时+Fallback）；关联 SC-P-40/SC-P-49 的 Fallback 口径。
+- **关联用例**：TC-B-06（待补）
+
+---
+
+**派生用例**：`test-cases/butler.md` TC-B-01~12（**待补**——按 `README.md` 维护约定，新增场景应同步补用例；本期先定场景 `SC-B-01~12` 与关联用例占位，TC 编写作为下一轮任务）。