docs: 新增新用户引导与留存设计方案

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

docs/需求分析/新用户引导与留存设计方案.md

@@ -0,0 +1,386 @@
+# 新用户引导与留存设计方案
+
+**版本：** v1.0
+**日期：** 2026-08-10
+**定位：** 产品设计 + 运营方案
+**理念依据：** 《家的算法》书稿（`book/` 目录：序章 / 第2章幸福三支柱 / 第8章最小输入 / 第9章循环执行 / 第10章反馈校验 / 第13章网络效应）
+**现状依据：** cfc-frontend 小程序（100+ 页面）、cfc-backend（Spring Boot）现有代码实现
+
+---
+
+## 1. 背景与目标
+
+### 1.1 产品现状盘点（已有能力）
+
+当前系统已具备大量"引导与激励"基础设施，但彼此孤立、未串成引导链路：
+
+| 能力 | 实现位置 | 现状 |
+|------|---------|------|
+| 新手任务（6项） | `pages/profile-extra/onboarding.vue` + `OnboardingService` | 完整但入口深藏分包，无首次弹窗引导 |
+| 五维自检（15题） | `pages/family/self-check.vue` + `self-check-result.vue` | 结果页含雷达图 + **五行相生寻源建议（含"本周行动"文字）**，但建议不可一键落地 |
+| 微行动（最小输入） | `MicroActionCard` 组件 + `MicroActionService` | **无维度关联**，按"日期取模"随机推荐，与自检短板脱节 |
+| 五维能量 | `WuxingSandbox` + `EnergyService` | 实时快照，无历史趋势 |
+| 每日打卡/连续打卡 | `pages/health/daily-checkin.vue` + `StreakResetTask` | 有 streak，无里程碑奖励 |
+| 家庭排行榜/挑战/健康圈 | `FamilyHealthRanking` / `FamilyChallengeCard` / 健康圈 | 竞争型激励已具备 |
+| 微信消息推送 | `WechatService.sendTemplateMessage()` + `WechatAlertTemplateService.sendCrisisAlertToParents()` | **模板消息通道已打通**，目前仅用于健康预警，可复用 |
+| 健康报告 + AI 解读 | `pages/health/report-upload` / `report-list` + `HealthReportController` | **无"复测对比"能力**（两次报告指标对比） |
+| 会员/分销/优惠券/试用 | `pages/membership/*` + 会员/佣金/优惠券任务 | 商业闭环完整 |
+| 订阅消息 | `MemberSubscriptionService` / `SubscriptionController` | 会员订阅能力已具备 |
+
+### 1.2 书稿理念 vs 现状差距摘要
+
+| 书稿理念 | 核心主张 | 现状差距 |
+|---------|---------|---------|
+| 序章 | 从最痛的那一点开始 | 新用户动线无"诊断先行"，首页 10+ 卡片轰炸无主次 |
+| 第2章 | 改变从看见开始，看见从测量开始 | 自检已存在，但不在新用户必经路径上 |
+| 第8章 | 最小输入（20秒启动） | 微行动卡已存在，但**与维度短板脱节**、且需先有家庭成员才渲染 |
+| 第9章 | 触发→动作→奖励→信念 + 共享注意 | 触发（提醒）缺位、奖励无里程碑、**"被看见"机制空白** |
+| 第10章 | 看趋势不看单次；过程获得感 | 只有快照（能量沙盘/单次报告），**无趋势、无复测对比** |
+| 第13章 | 可复制的样本（动作极小/起点极低/结果真实） | 传播=分销拉新，**缺"真实过程故事"分享载体** |
+
+### 1.3 方案目标（指标）
+
+| 层级 | 指标 | 目标 |
+|------|------|------|
+| 激活 | 注册→完成五维自检转化率 | ≥ 60% |
+| 激活 | 注册→完成新手任务≥4项 | ≥ 50% |
+| 习惯 | 7日留存 | 较当前 +10pp |
+| 习惯 | 连续打卡≥7天用户占比 | ≥ 30% |
+| 反馈 | 月度回访（月活跃率） | 较当前 +15pp |
+| 传播 | 分享卡片生成率 | ≥ 15% 活跃用户/月 |
+
+---
+
+## 2. 核心理念：把产品做成"幸福算法"
+
+书稿定义的产品逻辑是一套**算法**：`看见 → 最小输入 → 循环 → 反馈 → 传播`。
+
+本方案将产品交互按此算法分层，每一层解决一个用户心理问题：
+
+```
+┌─────────────────────────────────────────────────┐
+│ L5 传播  网络效应  —— "我家最近在做什么"（真实故事）│
+├─────────────────────────────────────────────────┤
+│ L4 被看见 共享注意  —— 家人的点赞/见证/仪式打卡    │
+├─────────────────────────────────────────────────┤
+│ L3 反馈  反馈校验  —— 趋势图/复测对比/周报（看见在变好）│
+├─────────────────────────────────────────────────┤
+│ L2 循环  习惯回路  —— 触发提醒→最小输入→奖励→信念  │
+├─────────────────────────────────────────────────┤
+│ L1 激活  看见与测量  —— 登录引导三步：角色→自检→推荐 │
+└─────────────────────────────────────────────────┘
+```
+
+**设计总原则：**
+1. **引导优先于功能**：新用户永远先看到"下一步该做什么"，而不是功能清单
+2. **测量优先于建议**：先让用户看见自己的状态（自检/报告），再给个性化建议
+3. **过程获得感优先于结果获得感**：表扬"今天做了"，不依赖"指标变了"
+4. **家人是最大的激励**：用"被看见"代替"被监督"
+
+---
+
+## 3. L1 激活：新用户首登动线改造（P0）
+
+### 3.1 现状动线 vs 目标动线
+
+**现状（问题：无诊断先行、无主次）：**
+```
+splash(2秒) → index-home → 登录 → parent-index（10+卡片并行轰炸）
+                                        ↓
+                        用户迷茫：先点哪个？→ 流失
+```
+
+**目标动线：**
+```
+splash(2秒) → index-home → 登录
+    ↓ 首次登录（无家庭成员/无自检记录）
+引导三步（角色 → 五维自检 → 结果页）
+    ↓
+自检结果页（雷达图 + 短板维度 + "本周行动"）
+    ↓ 一键
+加入今日微行动（最小输入落地）
+    ↓
+首页（onboarding 进度条置顶，任务 1/6 → 2/6 → ...）
+```
+
+### 3.2 引导三步设计
+
+**Step 1 — 角色确认（轻量）**
+- 复用现有角色选择逻辑，页面不新增，登录后判断：
+  - 新用户（无 family、无自检记录）→ 进入引导流程
+  - 老用户 → 直进首页
+- 引导页文案遵循书稿序章：*"先别急着逛，5 分钟，看见你家的真实状态。"*
+
+**Step 2 — 五维自检（测量）**
+- 直接复用 `pages/family/self-check.vue`（15 题 / 5 分钟）
+- 作为新用户**必做的第一件事**，替代 onboarding 中"完善个人资料"（无意义任务）
+- 后端：自检完成即触发 `onboardingService.completeTask(userId, "COMPLETE_SELF_CHECK")`（新增任务类型）
+
+**Step 3 — 结果页推荐（落地）**
+- 复用 `self-check-result.vue` 的雷达图与五行相生建议
+- **新增交互**：低分维度（<6分）的"本周行动"文字建议旁，加"加入今日微行动"按钮
+- 点击后 → 创建微行动记录 → 跳转首页，首页 `MicroActionCard` 展示该行动
+
+### 3.3 后端改造点（P0）
+
+**① `micro_actions` 表新增维度关联字段**
+
+```sql
+ALTER TABLE micro_actions ADD COLUMN dimension_code VARCHAR(16) DEFAULT NULL COMMENT '五维维度编码: BODY/MIND/WISDOM/ACTION/WEALTH';
+```
+
+- `MicroAction` 实体 + `MicroActionService` 增加 `getActionByDimension(String dimensionCode)` 接口
+- 按书稿第8章"五维最小输入清单"补充/映射 5 个维度行动：
+  | 维度 | 最小输入 | code |
+  |------|---------|------|
+  | 身 | 喝一杯温水 | `DRINK_WATER` |
+  | 智 | 问一个开放题 | `OPEN_QUESTION` |
+  | 富 | 记一笔账 | `RECORD_EXPENSE` |
+  | 行 | 给想念的人发条消息 | `SEND_MESSAGE` |
+  | 心 | 一次深呼吸 | `DEEP_BREATH` |
+
+**② 自检→微行动推荐接口**
+
+```
+POST /api/micro-action/recommend-by-selfcheck
+入参: { memberId, selfCheckId }
+出参: { action, todayRecord }
+逻辑: 取自检最低分维度 → 查该维度微行动 → 若无今日记录则返回可加入
+```
+
+**③ onboarding 任务类型扩展**
+
+`OnboardingService` 增加 `COMPLETE_SELF_CHECK` 任务（奖励：积分 + 能量），并确保任务创建时机与自检完成联动。
+
+### 3.4 首页 onboarding 进度条置顶（P0）
+
+- `parent-index.vue` 顶部（Banner 之下）新增 `OnboardingProgressBar` 组件：
+  - 仅当任务未全部完成时展示：`"新手任务 2/6 · 完成所有任务领丰厚奖励 →"`
+  - 点击跳转 `pages/profile-extra/onboarding.vue`
+  - 全部完成后自动消失（避免打扰老用户）
+- 数据源：复用 `getOnboardingProgress()`（已有接口，零后端改动）
+
+### 3.5 空状态处理（P0，低成本高收益）
+
+**现状问题**：新用户无家庭成员时，`MicroActionCard`、健康预警、排行榜、挑战全部 `v-if` 不渲染，首页只剩 Banner + 自检卡 + 关系图谱（空）。
+
+**改造**：家庭成员数为 0 时，`FamilyMemberStrip` 位置替换为**"创建我的家庭"引导卡**：
+- 主按钮：`添加家庭成员`（跳 `pages/profile-extra/add-member` 或 family 添加页）
+- 副文案：*"先添加一位家庭成员，开始记录你们家的五维成长"*
+- 完成添加后自动渲染原有卡片（微行动等）
+
+---
+
+## 4. L2 循环：习惯回路（触发→动作→奖励→信念）
+
+### 4.1 触发：每日提醒（P1）
+
+复用 `WechatService.sendTemplateMessage()`（通道已打通）：
+
+| 模板 | 触发时机 | 文案 |
+|------|---------|------|
+| 微行动提醒 | 每晚 20:00（未完成今日微行动的用户） | "今天的最小输入做了吗？30 秒，完成即得能量" |
+| 连续打卡提醒 | 每晚 20:30（连续打卡 1-6 天的用户） | "已连续打卡 N 天，再坚持一下，明天有里程碑奖励" |
+
+- 订阅授权时机：完成首个微行动后弹订阅授权（高意愿时刻）
+- 后端新增 `DailyReminderScheduledTask`（参考现有 `RepurchaseReminderScheduledTask` 模式）
+
+### 4.2 动作：按维度推荐微行动（P0 联动 3.3）
+
+- `getTodayAction()` 从"日期取模随机"改为两级逻辑：
+  1. 有最近自检记录 → 按最低分维度推荐
+  2. 无自检 → 保持现有轮换逻辑
+
+### 4.3 奖励：连续打卡里程碑（P1）
+
+- 现有 `StreakResetTask` 维护 streak，新增**里程碑奖励规则**（在打卡接口内判定）：
+  | 里程碑 | 奖励 |
+  |--------|------|
+  | 连续 3 天 | 积分 + 能量 + 徽章"初露锋芒" |
+  | 连续 7 天 | 积分 + 能量 + 徽章"一周小胜" |
+  | 连续 14 天 | 积分 + 能量 + 徽章"习惯成型" |
+  | 连续 21 天 | 大额积分 + 徽章"自我掌控" + 专属分享卡解锁 |
+- 对应书稿第9章：多巴胺重塑周期（18-254 天），21 天里程碑是"信念加固"节点
+- 勋章墙 `pages/rewards/badge.vue` 已存在，直接复用展示
+
+### 4.4 家庭仪式打卡（P2）
+
+书稿第9章三大黄金时刻产品化：
+
+| 仪式 | 时间 | 打卡内容 |
+|------|------|---------|
+| 晨间三件套 | 早晨 | 喝水 / 说一件期待的事 / 出门拥抱 |
+| 餐桌分享圈 | 晚餐 | "今天有什么开心的事？"（每人一条） |
+| 睡前折返跑 | 睡前 | 陪孩子坐 5 分钟 / 说一句"辛苦了" |
+
+- 新表 `family_ritual_records`（family_id, ritual_type, date, member_ids）
+- 首页新增"今日仪式"卡片（类似微行动卡），全家人共享同一打卡目标
+- **核心机制：共享注意**——打卡后其他成员可见，形成书稿所述"知道有人跟你一起做，就不容易停"
+
+---
+
+## 5. L3 反馈：让用户"看见自己在变好"（P1）
+
+### 5.1 健康报告复测对比（P1，全项目最强获得感载体）
+
+**现状**：`report-list.vue` 无"重新上传"、无对比；报告 AI 解读为单次快照。
+
+**改造**：
+- `report-list` 每条报告新增"对比上次"入口（≥2 份报告时显示）
+- 后端：`HealthReportController` 新增 `POST /api/health/report/compare`，入参两次报告 ID
+- AI 对比输出（复用现有 AI 解读管线）：
+  - 指标级：`↑ CRP 3.2→1.8（恢复正常）`，红绿标注
+  - 总结文案：*"三个月前你担心的指标，这次都在好转。"*
+- **对应书稿第10章**：复测是"科学测量轨"的标准动作（每季度一次），也是"看见从测量开始"的最强实证
+
+### 5.2 月度五维趋势图（P1）
+
+**现状**：能量沙盘是实时快照；自检分数无历史对比。
+
+**改造**：
+- `pages/energy/detail.vue` 新增"近 3 个月趋势"tab：
+  - 数据源：自检记录（`self_check` 表）+ 能量流水按维度聚合
+  - 呈现：五维各一条折线，连点成线
+- **对应书稿第10章"每月一图"**：*"第一月的分数没有意义，意义从第二个月开始"* —— 产品文案直接采用此理念：*"连续记录 2 个月，你就能看见趋势"*
+
+### 5.3 家庭能量周报（P1）
+
+- 每周日晚 20:00 推送（复用模板消息通道）：
+  - 本周全家能量变化
+  - 打卡天数、微行动完成数
+  - "本周亮点时刻"（成员的成长记录/徽章/仪式打卡）
+- 生成逻辑：后端 `WeeklyReportScheduledTask` 聚合生成 → 渲染 H5 卡片（参考健康足迹 `pages/share/index` 的分享卡片样式）
+
+---
+
+## 6. L4 被看见：家庭协同与共享注意（P2）
+
+### 6.1 点赞/见证机制（P2）
+
+书稿第9章核心洞察：**小艾的崇拜眼神比 App 打卡记录更管用**。
+
+| 场景 | 机制 |
+|------|------|
+| 微行动完成 | 家庭成员可点赞（❤️），点赞者获得 1 能量（小额） |
+| 成长记录发布 | 家庭成员可点赞/评论 |
+| 打卡里程碑达成 | 系统自动"全家庆祝"弹层（撒花动画） |
+
+- 新表 `praise_records`（target_type, target_id, user_id, created_at）+ 点赞数聚合
+- 轻量实现：不建消息中心，仅首页"家人动态"区展示最近 3 条被赞记录
+
+### 6.2 成长记录"过程时刻"（P2）
+
+- 书稿第10章：*"孩子最需要的不是被纠正，是被看见"*
+- `pages/growth/create.vue` 新增记录类型："过程时刻"（无结果但有努力的瞬间）
+  - 引导文案：*"记下他今天'没有结果但有过程'的时刻——自己整理了书包、想五分钟才问、主动说妈妈辛苦了"*
+- 与 6.1 联动：过程时刻发布后，其他成员点赞
+
+---
+
+## 7. L5 传播：网络效应与真实故事（P2）
+
+### 7.1 过程分享卡（P2）
+
+书稿第13章：**可复制的样本 = 动作极小 + 起点极低 + 结果真实**。
+
+- `pages/share/index`（健康足迹）已存在，扩展生成"我家最近在做的事"分享卡：
+  ```
+  ┌──────────────────────────────┐
+  │  [孩子头像] 连续打卡 21 天    │
+  │  "我家最近在做的事"          │
+  │  📅 每天 1 分钟微行动         │
+  │  💧 喝水 / 📝 记一笔         │
+  │  真实记录 · 真实变化          │
+  │  [一起试试 → 生成邀请码]      │
+  └──────────────────────────────┘
+  ```
+- 分享卡点击落地：`pages/invite/join.vue`（已有）→ 绑定推荐人（onboarding 第 6 任务 `BIND_REFERRAL` 已存在）
+- **文案纪律**（书稿第13章）：不写"幸福指数飙升"，只写真实小变化
+
+### 7.2 健康圈增强（P2）
+
+- 健康圈已有排行榜（分数竞争），补充"故事流"：家庭可发布"本周做了什么"（文字+图片，参考文章中心结构）
+- 圈内互相点赞 → 呼应 6.1 点赞机制的跨家庭延伸
+
+---
+
+## 8. 数据指标体系
+
+### 8.1 北极星指标
+
+**周活跃家庭数（WAU-F）**：每周至少有一个家庭成员完成一次"记录类动作"（微行动/打卡/成长记录/自检）的家庭数。
+
+### 8.2 漏斗指标
+
+| 阶段 | 指标 | 埋点 |
+|------|------|------|
+| 注册 | 手机号登录成功 | login_success |
+| 引导 | 自检完成率 | selfcheck_complete |
+| 引导 | 微行动加入率（自检结果页） | selfcheck_add_action |
+| 激活 | 首次微行动完成 | first_micro_action |
+| 激活 | 添加首位家庭成员 | first_family_member |
+| 新手 | onboarding 任务完成 ≥4 项 | onboarding_progress |
+| 习惯 | 连续打卡 3/7/14/21 天 | streak_milestone |
+| 反馈 | 复测对比使用率 | report_compare |
+| 回访 | 周/月活跃 | wau / mau |
+| 传播 | 分享卡生成数 | share_card_create |
+
+### 8.3 埋点实现建议
+
+- 后端在关键 Service 方法内记录行为日志（现有 `PointsLog` 模式可扩展为统一 `UserActionLog`）
+- 前端 `utils/api.js` 统一上报
+
+---
+
+## 9. 实施路线图
+
+| 阶段 | 内容 | 预估工作量 | 依赖 |
+|------|------|-----------|------|
+| **P0（2周）** | ① 微行动加维度字段 + 推荐接口；② 自检→微行动一键落地；③ 首页 onboarding 进度条；④ 空状态引导卡 | 后端 2-3 天，前端 4-5 天 | 无 |
+| **P1（3周）** | ⑤ 每日提醒模板消息；⑥ 打卡里程碑奖励；⑦ 健康报告复测对比；⑧ 月度趋势图；⑨ 家庭能量周报 | 后端 5-6 天，前端 5-6 天 | 需微信模板消息类目申请（提醒/周报） |
+| **P2（3周）** | ⑩ 点赞/见证；⑪ 家庭仪式打卡；⑫ 过程时刻记录；⑬ 分享卡；⑭ 健康圈故事流 | 后端 4-5 天，前端 6-7 天 | 依赖 P1 周报卡片样式沉淀 |
+
+**里程碑验收：**
+- P0 结束：新用户注册→自检→微行动完整链路走通，激活漏斗指标上线
+- P1 结束：7 日留存数据对比上线（对照组 AB）
+- P2 结束：分享卡传播链路闭环，邀请转化率对比上线
+
+---
+
+## 10. 风险与注意事项
+
+| 风险 | 缓解 |
+|------|------|
+| 微信订阅消息频控（每周 1 次/用户） | 提醒类模板消息为一次性订阅，需在授权时一次订阅多次；频控不足时降级为小程序内红点提醒 |
+| 强制引导流失风险（自检 15 题过长） | 提供"跳过，稍后自检"；引导页文案强调 5 分钟；跳过用户首页置顶自检卡 |
+| 微行动与自检联动需数据一致 | 自检结果页"加入微行动"需幂等（同一自检结果只可加一次） |
+| 周报/复测对比依赖 AI 解读管线稳定性 | 复用现有解析管线；AI 失败时降级为纯数据对比（无总结文案） |
+| 空状态改造影响老用户体验 | 空状态仅对"无家庭成员"用户生效；有成员用户完全不受影响 |
+
+---
+
+## 附录 A：书稿五维最小输入清单（第8章原文要点）
+
+| 维度 | 最小输入 | 20秒内可完成 |
+|------|---------|:---:|
+| 身 | 喝一杯温水 | ✅ |
+| 智 | 问一个开放题（或睡前问自己一句） | ✅ |
+| 富 | 记最大一笔开销 | ✅ |
+| 行 | 给想念的人发一条消息 | ✅ |
+| 心 | 一次深呼吸（吸4秒呼6秒） | ✅ |
+
+## 附录 B：相关代码位置索引
+
+| 模块 | 文件 |
+|------|------|
+| 新手任务前端 | `cfc-frontend/pages/profile-extra/onboarding.vue` |
+| 新手任务后端 | `cfc-backend/.../service/OnboardingService.java` |
+| 五维自检 | `cfc-frontend/pages/family/self-check.vue` / `self-check-result.vue` |
+| 微行动 | `cfc-frontend/components/MicroActionCard.vue` + `cfc-backend/.../service/MicroActionService.java` + `schema.sql: micro_actions` |
+| 家长首页 | `cfc-frontend/pages/home-pages/parent-index.vue`（2043 行，改造重点） |
+| 能量沙盘 | `cfc-frontend/components/WuxingSandbox.vue` + `EnergyService.calculateFamilyEnergy()` |
+| 模板消息 | `WechatService.sendTemplateMessage()` / `WechatAlertTemplateService` |
+| 健康报告 | `pages/health/report-list.vue`（加复测对比） + `HealthReportController` |
+| 分享足迹 | `pages/share/index.vue`（扩展分享卡） |
+| 邀请落地 | `pages/invite/join.vue` + onboarding `BIND_REFERRAL` |
+| 勋章墙 | `pages/rewards/badge.vue`（里程碑徽章展示） |