2026-08-06-family-challenge-flow-design.md 10 KB
家庭挑战使用流程梳理（现状基线 + 断点清单）
版本：v1.0 日期：2026-08-06 状态：已确认，作为后续实现计划的基线 范围：只描述家庭挑战（
family_challenge）；圈子挑战（circle_challenge）不在本文档范围内 读者：产品 / 运营 / 新入职业务同学；开发同学作为基线参照 基准：按当前代码事实撰写，每项标注实现状态（🟢已实现 / 🟡半实现 / 🔴未实现）；"未来期望"单列一节，不与现状混淆 证据截止：2026-08-06（以cfc-backend/cfc-frontend当前代码为准）
1. 背景与目标
家庭挑战是 cfc（XAF）产品中"五维能量"体系下的家庭共同行动机制：通过设定带奖励的目标任务（全员打卡、运动、健康周等），让家庭成员共同完成。
现状一句话：挑战由家长在小程序手动创建 / 编辑 / 删除；打卡与奖励发放目前未接通——见 §4.3 / §6 / §7。
为什么梳理：
- 功能已有多端实现，但没有一份流程文档，产品 / 运营讲不清现状
- 存在已实现但无人调用（打卡前端入口缺失）、已实现但触发不全（到期自动结算缺失）、完全未实现（奖励发放）三类状态，需要一份基线文档区分
- 后续开发（补打卡 / 补奖励 / 补权限）需要一份"现状基线"
成功标准：产品 / 运营同事读完本文档，不看代码也能复述：哪些功能能用、哪些不能用、每个功能在哪个端、数据怎么流转。
2. 关键概念
| 概念 | 定义 | 状态 |
|---|---|---|
| 挑战 | 家庭共同完成的目标任务，含起止日期与奖励配置 | 🟢 已实现 |
| 挑战模板 | 预定义的挑战样例（标题/类型/目标/时长/奖励），是创建的"配方" | 🟢 已实现（7 种，含自定义） |
| 挑战类型 | full_checkin 全员打卡 / sports 运动PK / health_week 健康周 / reading 阅读 / no_screen 无屏幕 / gratitude 感恩日记 / custom 自定义 |
🟢 已实现 |
| 目标模式 | aggregate 集体总合目标（全家人合计达到目标值）/ all_members 全员个人目标（每个成员都达到目标值） |
🟢 已实现 |
| 进度 | 每个成员在某挑战下的累计达标数值 | 🟢 已实现（后端累计逻辑存在） |
| 打卡 | 成员主动上报完成动作，累加进度 | 🟡 半实现：后端接口有、前端无入口 |
| 结算 | 挑战到期后判定完成情况 | 🟡 半实现：仅打卡触发，无到期自动结算 |
| 奖励 | 能量点（rewardPoints）+ 成就徽章（rewardBadge） | 🔴 未实现：仅展示数字，无发放逻辑 |
| 状态 | active 进行中 / completed 已完成 / cancelled 已取消 |
🟢 已实现（三态） |
3. 角色与权限（现状）
家长（parent）
| 能力 | 状态 | 说明 |
|---|---|---|
| 查看本家庭活跃 / 历史挑战列表 | 🟢 已实现 | GET list / history |
| 查看每个成员的进度 | 🟢 已实现 | 卡片组件展示 |
| 手动发起挑战（选模板 + 自定义标题/目标/时长/奖励） | 🟢 已实现 | challenge-manage.vue + create 接口 |
| 编辑 / 删除（软删 cancelled）自己创建的挑战 | 🟢 已实现 | update / delete 接口 |
| 进入"管理"页 | 🟢 已实现 | 家长首页 → "管理 →" |
| 修改成员进度 | 🔴 未实现 | 家长端无此 UI；且后端无权限校验可被绕过（见 §7 #4） |
孩子（child）
| 能力 | 状态 | 说明 |
|---|---|---|
| 查看本家庭活跃 / 历史挑战列表 | 🟢 已实现 | 与家长同 API |
| 打卡 | 🟡 半实现 | 后端接口存在，前端无打卡按钮 |
| 查看自己的历史奖励 | 🔴 未实现 | 奖励未实现 |
| 权限隔离（只能打卡自己） | 🔴 未实现 | 无角色校验，孩子可调管理接口 |
规划师（teacher）
- 🔴 不参与家庭挑战（无相关代码）
权限边界一句话（现状）：无角色检查——所有挑战接口任何登录角色可调；"孩子只能打卡自己"等约束未落地。
4. 挑战生命周期（现状）
4.1 挑战从哪里来（重要修正）
| 途径 | 状态 | 证据 |
|---|---|---|
| 家长手动创建 | 🟢 已实现 | createChallenge 接口 + challenge-manage.vue 创建弹窗 |
| 后端按月自动创建 | 🔴 未实现 | autoCreateChallenges(familyId) 方法存在，但 Controller / 定时任务均无调用方——仅 CircleChallengeService 有同名的圈子版自用 |
⚠️ 结论：挑战只能由家长手动创建。产品若宣传"系统按月自动派发挑战"，当前不成立。
4.2 三个状态
stateDiagram-v2
[*] --> active: 家长手动创建
active --> completed: 打卡触发结算判定（达成或到期）
active --> cancelled: 家长删除（软删）
completed --> [*]: 进入历史列表
cancelled --> [*]: 从活跃列表消失
| 状态 | 含义 | 进入方式 |
|---|---|---|
active |
进行中，卡片展示在活跃列表 | 家长手动创建 |
completed |
已完成，进入历史列表 | 打卡时 checkAndSettle 判定达成或已到期 |
cancelled |
已取消，从活跃列表消失 | 家长删除（软删，保留记录） |
4.3 结算规则（现状）
- 🟡 触发点：仅"打卡更新进度"时执行
checkAndSettle - 🟡 判定：
aggregate全家合计 ≥ 目标 /all_members每成员 ≥ 目标；或endDate已过 - 🔴 到期无打卡 = 永不结算（
settleChallenge()无调用方） - 🔴 奖励发放不存在——结算只改状态，能量点 / 徽章不落账
5. 家长动线（现状）
入口：家长首页（parent-index）→ "家庭挑战"区块 → 卡片列表 + "管理 →"
卡片上看到（FamilyChallengeCard）：
- 标题、状态徽标（进行中 / 已完成）、描述
- 目标模式：
aggregate显示全家总进度条 /all_members显示成员列表（含 ✓ 完成标记） - 时长、截止日期、奖励分数（
+50分等，仅展示）
管理页可做（challenge-manage.vue）：
- 🟢 查看模板列表（7 种）
- 🟢 创建：选模板 / 自定义标题、目标模式、目标值、奖励分、时长
- 🟢 编辑自己创建的 active 挑战
- 🟢 删除自己创建的 active 挑战（软删）
家长不可做（现状）：
- 🔴 无"打卡"操作（卡片无按钮）
- 🔴 无"取消"菜单（删除即软删，无独立取消态）
- 🔴 无通知 / 无复盘
6. 孩子动线（现状）
入口：孩子的身维度首页（index-home）→ 同一 FamilyChallengeCard 组件
卡片上看到：与家长端视觉一致（标题 / 状态 / 进度 / 奖励分），无打卡按钮
孩子可做：
- 🟢 查看挑战列表与进度
- 🟡 打卡 —— 现状前端无入口（后端
/progress存在但无人调用）
孩子不可做（现状）：
- 🔴 打卡（无 UI）
- 🔴 查看奖励（未实现）
- 🔴 权限隔离（无角色校验，理论上可调管理接口）
两端差异一句话（现状）：两端看到的东西几乎一样，都只能看不能"做"——家长多了"管理"页，孩子连打卡都没有。
7. 现状问题清单（后续实现计划的输入）
| # | 问题 | 影响 | 状态 |
|---|---|---|---|
| 1 | 打卡无前端入口：api.js 有 updateChallengeProgress，无页面调用 |
孩子无法参与 | 🟡 半实现 |
| 2 | 到期不自动结算：settleChallenge() 无调用方 |
到期挑战停留在 active | 🟡 半实现 |
| 3 | 奖励未发放：结算只改状态 | 能量点 / 徽章不落账 | 🔴 未实现 |
| 4 | 无角色检查：list / progress / create / update / delete 均无角色校验 | 任何角色可调管理接口；孩子可刷任意成员进度 | 🔴 未实现 |
| 5 | 前端展示 bug：FamilyChallengeCard 将 cancelled 也显示为"已完成" |
已删挑战显示为完成 | 🔴 未修复 |
| 6 | 无每日限次：updateProgress 可无限叠加 |
可刷进度 | 🔴 未实现 |
| 7 | 后端 autoCreate 无调用方：方法存在但无人调用 | 宣传的"自动派发"不成立 | 🔴 未实现 |
8. 未来期望（明确标注"非现状"）
本节是产品方向，不代表当前可用；实现需另起 spec + plan。
| 能力 | 说明 |
|---|---|
| 孩子打卡 UI | 卡片加"打卡"按钮 + 打卡表单 + 反馈 |
| 到期自动结算 | 定时任务 / 查询时惰性结算 |
| 奖励发放 | 结算时能量点入账 + 徽章授予（对接 EnergyService） |
| 每日限次 | 同挑战每日 1 次打卡 |
| 通知 | 开始前 / 即将到期 / 结算完成推送 |
| 权限 | 角色校验：仅家长可管理，仅本人可打卡 |
| 复盘 | 完成率 / 坚持天数 / 成长轨迹 |
| 规划师视角 | 另起 spec |
9. 附录
A. 数据表
| 表名 | 用途 |
|---|---|
family_challenge |
挑战主表（含 creatorId） |
family_challenge_progress |
成员进度表 |
circle_challenge |
圈子挑战（不在本文档范围） |
B. API 清单（现状）
| 路径 | 用途 | 前端是否调用 |
|---|---|---|
POST /api/health/challenge/list |
活跃列表 | ✅ |
POST /api/health/challenge/history |
历史 | ✅ |
POST /api/health/challenge/progress |
打卡进度 | ❌ 无页面调用 |
POST /api/health/challenge/templates |
模板列表 | ✅ |
POST /api/health/challenge/create |
创建 | ✅ |
POST /api/health/challenge/update/{id} |
编辑 | ✅ |
POST /api/health/challenge/delete/{id} |
删除 | ✅ |
C. 术语表
| 术语 | 定义 |
|---|---|
| 挑战 | 家庭共同完成的目标任务，含起止日期与奖励 |
| 挑战模板 | 预定义的挑战配方，可选用或自定义 |
| 挑战类型 | 全员打卡 / 运动PK / 健康周 / 阅读 / 无屏幕 / 感恩日记 / 自定义 |
| 目标模式 | aggregate 全家合计 / all_members 每人目标 |
| 进度 | 成员在某挑战下的累计达标数值 |
| 打卡 | 成员主动上报完成动作（累加进度） |
| 结算 | 挑战到期后判定完成情况 + 发放奖励 |
| 奖励 | 能量点（rewardPoints）+ 成就徽章（rewardBadge） |
| 状态 | active 进行中 / completed 已完成 / cancelled 已取消 |