cfc/docs/flows/health-checkin-flow.md

用户使用流程图 — 健康打卡体系

端口说明: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动

分层说明: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

flowchart TD
    %% ============ 颜色定义 ============
    classDef page fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:1px
    classDef service fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
    classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
    classDef external fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:3 2
    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3

    %% ============ 角色 ============
    A0(("👤 家长/孩子")):::actor
    B0(("⚙️ 定时任务")):::actor

    %% ================================================================
    %% 阶段一：每日打卡
    %% ================================================================
    subgraph 阶段一[阶段一：每日打卡]
        direction TB

        P1["🏠 打卡首页"]:::page
        P1 -->|"查看打卡列表"| A1["🔗 POST /api/health/checkin/list"]:::api
        A1 -->|"childId, yearMonth"| S1["⚙️ HealthCheckinService.getCheckins()"]:::service
        S1 -->|"查询打卡记录"| D1["📦 health_checkins 表"]:::data

        P1 -->|"选择打卡类型"| P1_choice{"综合 / 运动 / 饮食 / 睡眠 / 喝水 / 冥想"}:::page

        P1_choice -->|"综合打卡"| A2["🔗 POST /api/daily/checkin/create"]:::api
        A2 -->|"memberId, 饮食/运动/睡眠/饮水/心情评分"| S2["⚙️ DailyCheckinService.createCheckin()"]:::service
        S2 -->|"写入一条打卡记录"| D2["📦 daily_checkin 表"]:::data

        P1_choice -->|"运动打卡"| A3["🔗 POST /api/health/exercise/create"]:::api
        A3 -->|"memberId, 运动类型, 时长, 强度"| S3["⚙️ HealthExerciseRecordMapper.insert()"]:::service
        S3 -->|"写入运动记录"| D3["📦 health_exercise_records 表"]:::data

        P1_choice -->|"饮食打卡"| A4["🔗 POST /api/health/meal/create"]:::api
        A4 -->|"memberId, 餐食类型, 食物列表, 热量"| S4["⚙️ HealthMealRecordMapper.insert()"]:::service
        S4 -->|"写入饮食记录"| D4["📦 health_meal_records 表"]:::data

        P1_choice -->|"睡眠打卡"| A5["🔗 POST /api/health/sleep/create"]:::api
        A5 -->|"memberId, 入睡/起床时间, 睡眠质量"| S5["⚙️ HealthSleepRecordMapper.insert()"]:::service
        S5 -->|"写入睡眠记录"| D5["📦 health_sleep_records 表"]:::data

        P1_choice -->|"喝水打卡"| A6["🔗 POST /api/health/water/create"]:::api
        A6 -->|"memberId, 喝水量(ml)"| S6["⚙️ HealthWaterRecordMapper.insert()"]:::service
        S6 -->|"写入喝水记录"| D6["📦 health_water_records 表"]:::data

        P1_choice -->|"冥想打卡"| A7["🔗 POST /api/health/checkin/create"]:::api
        A7 -->|"childId, behaviors=[meditation], 心情"| S7["⚙️ HealthCheckinService.createCheckin()"]:::service
        S7 -->|"写入打卡记录(含行为标签)"| D1
    end

    %% ================================================================
    %% 阶段二：打卡管理
    %% ================================================================
    subgraph 阶段二[阶段二：打卡管理与统计]
        D1 -->|"打卡记录ID"| P2["🏠 打卡详情页"]:::page
        P2 -->|"查看详情"| A8["🔗 POST /api/daily/checkin/detail"]:::api
        A8 -->|"id"| S8["⚙️ DailyCheckinService.getCheckinById()"]:::service
        S8 -->|"单条打卡完整数据"| D2

        P2 -->|"更新打卡"| A9["🔗 POST /api/daily/checkin/update"]:::api
        A9 -->|"id, 更新字段"| S9["⚙️ DailyCheckinService.updateCheckin()"]:::service
        S9 -->|"更新对应打卡记录"| D2

        P2 -->|"删除打卡"| A10["🔗 POST /api/daily/checkin/delete"]:::api
        A10 -->|"id, userId"| S10["⚙️ DailyCheckinService.deleteCheckin()"]:::service
        S10 -->|"删除打卡记录"| D2

        P2 -->|"查看统计"| A11["🔗 POST /api/health/checkin/stats"]:::api
        A11 -->|"childId"| S11["⚙️ HealthCheckinService.countCheckins()"]:::service
        S11 -->|"总打卡次数, 总能量值"| D1

        P2 -->|"运动列表"| A12["🔗 POST /api/health/exercise/list"]:::api
        A12 -->|"memberId"| S12["⚙️ HealthExerciseRecordMapper.selectList()"]:::service
        S12 -->|"运动打卡列表"| D3
    end

    %% ================================================================
    %% 阶段三：连续打卡
    %% ================================================================
    subgraph 阶段三[阶段三：连续打卡]
        D1 -->|"打卡数据"| P3["🏠 连续打卡页"]:::page
        P3 -->|"查看进度"| A13["🔗 POST /api/streak/progress/{childId}"]:::api
        A13 -->|"path: childId"| S13["⚙️ StreakService.getStreakProgress()"]:::service
        S13 -->|"连续天数, 里程碑, 积分"| D7["📦 streak_milestones + points_logs 表"]:::data

        P3 -->|"获取连续天数"| A14["🔗 POST /api/health/score/streak"]:::api
        A14 -->|"childId"| S14["⚙️ HealthScoreService.calculateStreakDays()"]:::service
        S14 -->|"当前连续打卡天数"| D_HEALTH_SCORE["📦 health_score（内存计算）"]:::data

        B0 -->|"每日凌晨检查"| A15["🔗 POST /api/streak/reset"]:::api
        A15 -->|"(定时任务触发)"| S15["⚙️ StreakService.resetStreakIfNeeded()"]:::service
        S15 -->|"中断>1天则重置连续计数"| D7
    end

    %% ================================================================
    %% 阶段四：健康积分与等级
    %% ================================================================
    subgraph 阶段四[阶段四：健康积分与等级]
        D_HEALTH_SCORE -->|"积分数据"| P4["🏠 健康积分页"]:::page
        P4 -->|"查看积分和等级"| A16["🔗 POST /api/health/score/info"]:::api
        A16 -->|"childId"| S16["⚙️ HealthLevelService.getMemberLevelInfo()"]:::service
        S16 -->|"总积分, 等级, 等级进度"| D8["📦 health_score + health_level 表"]:::data

        P4 -->|"家庭排行榜"| A17["🔗 POST /api/family/health/ranking"]:::api
        A17 -->|"familyId"| S17["⚙️ FamilyHealthScoreService.getFamilyRanking()"]:::service
        S17 -->|"家庭成员排名(积分+连续天数)"| D8
    end

    %% ================================================================
    %% 阶段五：健康时间线
    %% ================================================================
    subgraph 阶段五[阶段五：健康时间线]
        D1 -->|"打卡记录"| P5["🏠 健康时间线页"]:::page
        P5 -->|"查看健康故事"| A18["🔗 POST /api/health/timeline/list"]:::api
        A18 -->|"childId, limit"| S18["⚙️ HealthTimelineService.getTimeline()"]:::service
        S18 -->|"按时间倒序的事件列表"| D9["📦 health_timeline_events 表"]:::data
    end

    %% ================================================================
    %% 阶段六：健康预警
    %% ================================================================
    subgraph 阶段六[阶段六：健康预警]
        D1 -->|"异常打卡模式"| P6["🏠 健康预警页"]:::page
        P6 -->|"查看活跃预警"| A19["🔗 POST /api/health/alert/list"]:::api
        A19 -->|"childId"| S19["⚙️ HealthAlertService.getActiveAlerts()"]:::service
        S19 -->|"活跃预警列表"| D10["📦 health_alerts 表"]:::data

        P6 -->|"关闭预警"| A20["🔗 POST /api/health/alert/dismiss"]:::api
        A20 -->|"id"| S20["⚙️ HealthAlertService.dismiss()"]:::service
        S20 -->|"标记预警已关闭"| D10
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    A0 -.- P1
    A0 -.- P2
    A0 -.- P3
    A0 -.- P4
    A0 -.- P5
    A0 -.- P6
    B0 -.- A15

端点明细

每日打卡

端点	说明	端口	请求数据	响应数据
POST /api/health/checkin/list	获取打卡列表	📱小程序	{childId, yearMonth}	List<HealthCheckin>
POST /api/health/checkin/create	创建打卡记录	📱小程序	{childId, checkinDate, behaviors, note, mood}	HealthCheckin
POST /api/health/checkin/delete	删除打卡记录	📱小程序	{id}	{success}
POST /api/health/checkin/stats	打卡统计	📱小程序	{childId}	{totalCheckins, totalEnergy}
POST /api/daily/checkin/list	获取综合打卡列表	📱小程序	{memberId}	List<DailyHealthCheckin>
POST /api/daily/checkin/detail	获取打卡详情	📱小程序	{id}	DailyHealthCheckin
POST /api/daily/checkin/create	创建综合打卡	📱小程序	{memberId, checkinDate, dietScore, exerciseScore, sleepScore, waterIntake, moodScore, ...}	DailyHealthCheckin
POST /api/daily/checkin/update	更新打卡	📱小程序	{id, ...更新字段}	DailyHealthCheckin
POST /api/daily/checkin/delete	删除打卡	📱小程序	{id, userId}	{success}

专项打卡

端点	说明	端口	请求数据	响应数据
POST /api/health/exercise/list	运动打卡列表	📱小程序	{memberId}	List<HealthExerciseRecord>
POST /api/health/exercise/create	创建运动打卡	📱小程序	{memberId, exerciseType, duration, intensity, ...}	HealthExerciseRecord
POST /api/health/meal/list	饮食打卡列表	📱小程序	{memberId}	List<HealthMealRecord>
POST /api/health/meal/create	创建饮食打卡	📱小程序	{memberId, mealType, foods, calories, ...}	HealthMealRecord
POST /api/health/sleep/list	睡眠打卡列表	📱小程序	{memberId}	List<HealthSleepRecord>
POST /api/health/sleep/create	创建睡眠打卡	📱小程序	{memberId, sleepTime, wakeTime, quality, ...}	HealthSleepRecord
POST /api/health/water/list	喝水打卡列表	📱小程序	{memberId}	List<HealthWaterRecord>
POST /api/health/water/create	创建喝水打卡	📱小程序	{memberId, waterIntake, ...}	HealthWaterRecord

连续打卡

端点	说明	端口	请求数据	响应数据
POST /api/streak/progress/{childId}	打卡进度	📱小程序	path: childId	{streakDays, milestones, points}
POST /api/streak/reset	重置中断打卡	⚙️系统自动	—	{success}

健康积分与等级

端点	说明	端口	请求数据	响应数据
POST /api/health/score/info	健康积分信息	📱小程序	{childId}	{totalScore, level, levelProgress}
POST /api/health/score/streak	连续天数	📱小程序	{childId}	Integer(连续天数)
POST /api/family/health/ranking	家庭健康排行榜	📱小程序	{familyId}	{members: [{childId, score, streakDays, rank}], totalScore}

健康时间线

端点	说明	端口	请求数据	响应数据
POST /api/health/timeline/list	健康时间线	📱小程序	{childId, limit}	List<HealthTimelineEvent>

健康预警

端点	说明	端口	请求数据	响应数据
POST /api/health/alert/list	活跃预警列表	📱小程序	{childId}	List<HealthAlert>
POST /api/health/alert/dismiss	关闭预警	📱小程序	{id}	{success}

完整性分析

#	维度	评估	说明
1	流程完整性	✅ 完整	覆盖每日打卡（6种类型）、打卡管理、连续打卡、健康积分、时间线、预警6个阶段，闭环完整
2	异常路径	⚠️ 部分覆盖	打卡中断后定时任务自动重置连续计数已覆盖；单个打卡类型缺少独立的更新/删除端点（仅综合打卡支持完整CRUD）
3	端点覆盖	✅ 完整	20个端点全部映射到流程图中，覆盖HealthCheckinController、DailyCheckinController、专项打卡控制器、StreakController、HealthScoreController、HealthTimelineController、HealthAlertController、FamilyHealthController
4	角色覆盖	⚠️ 部分覆盖	家长和孩子均可打卡，目前不区分角色权限；连续打卡重置为系统定时任务触发；无管理后台/规划师端入口
5	数据实体	✅ 完整	health_checkins、daily_checkin、health_exercise_records、health_meal_records、health_sleep_records、health_water_records、health_alerts、health_timeline_events、streak_milestones、points_logs、health_score均在图中映射
6	一致性	✅ 与代码一致	所有端点路径与实际Controller中的@PostMapping匹配