# 家庭挑战使用流程梳理（现状基线 + 断点清单）

> **版本**：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 三个状态

```mermaid
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` 已取消 |