cfc/docs/flows/growth-task-flow.md

用户使用流程图 — 成长任务

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

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

核心概念

成长任务 (GrowthTask) 是孩子每日可执行的系统预设任务，分为两种类型：

• 每日任务 (DAILY)：每日重置进度，如"阅读30分钟""运动打卡"
• 新人任务 (NEWBIE)：一次性任务，如"完善个人资料""首次邀请"
• AI动态任务 (AI_GENERATED)：由AI对话会话生成的自定义任务

任务执行后记录在 growth_task_log 表中，完成可领取积分+五维能量奖励。

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

    %% ============ 角色 ============
    ROLE_CHILD(("👶 孩子")):::actor
    ROLE_PARENT(("👤 家长")):::actor
    ROLE_SYSTEM(("⚙️ 系统自动")):::actor

    %% ================================================================
    %% 阶段一：任务列表与领取
    %% ================================================================
    subgraph 阶段一[阶段一：任务列表与执行]
        P1["🏠 小程序：成长任务页"]:::page
        P1 -->|"查看任务列表"| A1["🔗 POST /api/growth-task/list"]:::api
        A1 -->|"userId, type(DAILY/NEWBIE), dimension(可选)"| S1["⚙️ GrowthTaskService.getTaskList()"]:::service
        S1 -->|"查询已启用任务+今日/历史进度"| D1["📦 growth_task 表（任务定义）"]:::data
        S1 -->|"查询该用户的进度日志"| D2["📦 growth_task_log 表（进度）"]:::data

        D1 -->|"任务列表含进度"| P1a{"任务状态"}:::page
        P1a -->|"未开始/进行中"| P1b["🏠 执行任务页"]:::page
        P1b -->|"完成任务目标"| A2["⚙️ 系统：自动更新进度"]:::api
        A2 -->|"userId, taskKey, increment"| S2["⚙️ GrowthTaskService.updateProgress()"]:::service
        S2 -->|"新增或更新进度记录, 达标则标记completed"| D2

        P1a -->|"已完成·未领取"| P1c["🏠 领取奖励弹窗"]:::page
        P1c -->|"领取奖励"| A3["🔗 POST /api/growth-task/claim"]:::api
        A3 -->|"userId, taskLogId"| S3["⚙️ GrowthTaskService.claimReward()"]:::service
        S3 -->|"标记claimed=1"| D2
        S3 -->|"发放积分"| D_POINTS["📦 积分流水（PointsService）"]:::data
        S3 -->|"发放五维能量"| D_ENERGY["📦 能量流水（EnergyService）"]:::data

        P1a -->|"已完成·已领取"| P1d["🏠 已领取（不可重复）"]:::page
        P1a -->|"AI动态任务"| P1e["🏠 AI动态任务页"]:::page
        P1e -->|"接受任务"| A4["🔗 POST /api/growth-task/accept-dynamic"]:::api
        A4 -->|"userId, taskId"| S4["⚙️ GrowthTaskService（返回任务信息）"]:::service
        S4 -->|"查询AI生成的任务详情"| D1
    end

    %% ================================================================
    %% 阶段二：新人初始化（系统自动）
    %% ================================================================
    subgraph 阶段二[阶段二：新人注册初始化]
        ROLE_SYSTEM -->|"新用户注册成功"| P2["⚙️ 系统：新人任务初始化"]:::page
        P2 -->|"触发initNewbieTasks"| A5["⚙️ OnboardingService.initForUser()"]:::api
        A5 -->|"userId"| S5["⚙️ GrowthTaskService.initNewbieTasks()"]:::service
        S5 -->|"查询所有NEWBIE类型任务"| D1
        S5 -->|"为每个任务创建初始进度记录"| D2
    end

    %% ================================================================
    %% 阶段三：AI动态任务创建（系统自动）
    %% ================================================================
    subgraph 阶段三[阶段三：AI会话生成动态任务]
        ROLE_SYSTEM -->|"AI对话中产生任务建议"| P3["⚙️ 系统：AI任务生成"]:::page
        P3 -->|"调用createDynamicTask"| A6["⚙️ AIChatService → GrowthTaskService"]:::api
        A6 -->|"userId, title, description, dimension, rewardPoints, conversationId"| S6["⚙️ GrowthTaskService.createDynamicTask()"]:::service
        S6 -->|"写入类型=AI_GENERATED的任务"| D1
    end

    %% ================================================================
    %% 阶段四：后台任务管理（管理员/规划师）
    %% ================================================================
    subgraph 阶段四[阶段四：任务配置管理]
        P4["🖥 管理后台：成长任务管理页"]:::page
        P4 -->|"CRUD成长任务"| A7["🔗 管理端：任务配置接口"]:::api
        A7 -->|"任务定义字段"| S7["⚙️ 管理端配置逻辑"]:::service
        S7 -->|"增删改查成长任务"| D1
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    ROLE_CHILD -.- P1
    ROLE_CHILD -.- P1b
    ROLE_CHILD -.- P1c
    ROLE_CHILD -.- P1e
    ROLE_PARENT -.- P1
    ROLE_PARENT -.- P4

端点明细

成长任务

端点	说明	端口	请求数据	响应数据
POST /api/growth-task/list	获取成长任务列表含进度	📱小程序	{type(DAILY/NEWBIE), dimension(可选)}	List<任务+进度信息>
POST /api/growth-task/claim	领取已完成任务的奖励	📱小程序	{taskLogId}	{msg: "领取成功"/错误原因}
POST /api/growth-task/accept-dynamic	接受AI动态任务	📱小程序	{taskId}	{id, title, description, dimension, rewardPoints}

系统触发

功能	说明	端口	触发条件	行为
initNewbieTasks()	初始化新人成长任务	⚙️系统自动	新用户注册成功	为每个NEWBIE类型任务创建GrowthTaskLog
updateProgress()	更新任务进度	⚙️系统自动	其他功能模块调用	进度达标后自动标记completed=1
createDynamicTask()	AI生成动态任务	⚙️系统自动	AI会话产出任务建议	写入type=AI_GENERATED的GrowthTask

数据实体关系

erDiagram
    GrowthTask ||--o{ GrowthTaskLog : "一个任务多个用户日志"
    Child ||--o{ GrowthTaskLog : "一个孩子多条日志"

    GrowthTask {
        Long id PK
        string type "DAILY/NEWBIE/AI_GENERATED"
        string title "任务标题"
        string description "任务描述"
        int rewardPoints "奖励积分"
        int rewardEnergy "奖励能量"
        int targetValue "目标值（如30分钟）"
        string taskKey "唯一业务Key"
        string dimension "五维维度"
        int enabled "是否启用"
        string sourceConversationId "AI会话ID"
    }

    GrowthTaskLog {
        Long id PK
        Long userId FK
        Long taskId FK
        int progress "当前进度"
        int completed "0/1 是否完成"
        int claimed "0/1 是否领取"
        string date "日期(yyyy-MM-dd)"
    }

完整性分析

#	维度	评估	说明
1	流程完整性	✅ 完整	覆盖任务列表加载→进度更新→奖励领取全链路，以及新人初始化、AI动态任务生成、后台配置共4个阶段
2	异常路径	⚠️ 部分覆盖	已领取不可重复领取、进度未达标不可领取、任务不存在等均在Service层有校验；AI任务taskId不存在的错误处理已覆盖
3	端点覆盖	✅ 完整	3个API端点全部映射到流程图中，System调用的3个内部方法也已列出
4	角色覆盖	✅ 完整	孩子(执行任务/领取奖励)、家长(查看任务进度)、系统自动(初始化/进度更新/AI生成)均已覆盖；管理员可通过管理端配置任务
5	数据实体	✅ 完整	growth_task表(任务定义)、growth_task_log表(用户进度日志)、PointsService/EnergyService的积分和能量流水均在图中映射
6	一致性	✅ 与代码一致	所有端点路径与GrowthTaskController中的@PostMapping匹配，Service方法名与GrowthTaskService源码一致