cfc/docs/flows/task-management-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 阶段一[阶段一：任务创建]
        P1["🏠 家长/规划师端：创建任务页"]:::page
        P1 -->|"选择创建方式"| P1_choice{"手动创建 / 模板 / AI推荐 / 训练方案"}:::page

        P1_choice -->|"手动创建"| P1a["🏠 填写任务表单"]:::page
        P1a -->|"标题, 描述, 执行人, 积分, 截止时间, 需审核, 分类"| A1["🔗 POST /api/tasks/create"]:::api
        A1 -->|"创建任务DTO"| S1["⚙️ TaskService.createTask()"]:::service
        S1 -->|"写入一条任务记录"| D1["📦 tasks 表"]:::data

        P1_choice -->|"从模板"| P1b["🏠 选择任务模板"]:::page
        P1b -->|"模板ID"| S1

        P1_choice -->|"AI推荐"| P1c["🏠 AI任务建议页"]:::page

        P1_choice -->|"训练方案下发"| P1d["📋 规划师端：选择训练方案"]:::page
        P1d -->|"方案ID, 孩子ID"| A1

        P1a -->|"获取可选小游戏"| A1a["🔗 POST /api/tasks/minigame-options"]:::api
        A1a -->|""| S1a["⚙️ MiniGameService.getEnabledGames()"]:::service
        S1a -->|"已启用小游戏列表"| D2["📦 mini_games 表"]:::data
    end

    %% ================================================================
    %% 阶段二：任务执行
    %% ================================================================
    subgraph 阶段二[阶段二：任务执行]
        D1 -->|"孩子ID"| P2["🏠 孩子端：今日任务页"]:::page
        P2 -->|"获取今日任务"| A2["🔗 POST /api/tasks/today"]:::api
        A2 -->|"childId, category(可选)"| S2["⚙️ TaskService.getTodayTasks()"]:::service
        S2 -->|"今日任务列表"| D1

        P2 -->|"选择任务"| P2_choice{"普通任务 / 小游戏 / 家长任务"}:::page

        P2_choice -->|"普通任务"| P2a["🏠 执行并提交"]:::page
        P2a -->|"任务ID, childId, 照片"| A3["🔗 POST /api/tasks/{id}/complete"]:::api
        A3 -->|"任务ID, childId, photoUrl"| S3["⚙️ TaskService.completeTask()"]:::service
        S3 -->|"更新任务状态=completed, 发放积分"| D1

        P2_choice -->|"小游戏"| P2b["🏠 玩小游戏并提交成绩"]:::page
        P2b -->|"任务ID, childId, 完成时间, 得分"| A4["🔗 POST /api/tasks/{id}/complete-minigame"]:::api
        A4 -->|"任务ID, childId, completionTime, score"| S4["⚙️ TaskService.completeMinigameTask()"]:::service
        S4 -->|"更新任务状态, 记录游戏成绩"| D1

        P2_choice -->|"家长任务"| P2c["📱 家长端：完成任务"]:::page
        P2c -->|"任务ID"| A5["🔗 POST /api/tasks/{id}/complete-parent"]:::api
        A5 -->|"任务ID, 用户ID"| S5["⚙️ TaskService.completeParentTask()"]:::service
        S5 -->|"更新任务状态"| D1

        P2a -->|"完成后判断"| CHECK{"需要审核?"}:::page
        CHECK -->|"是"| P2d["🏠 进入待审核列表"]:::page
        CHECK -->|"否"| P2e["🏠 任务完成（直接通过）"]:::page

        P2 -->|"获取家长今日任务"| A6["🔗 POST /api/tasks/today-parent"]:::api
        A6 -->|"用户ID"| S6["⚙️ TaskService.getTodayParentTasks()"]:::service
        S6 -->|"家长任务列表"| D1
    end

    %% ================================================================
    %% 阶段三：任务审核
    %% ================================================================
    subgraph 阶段三[阶段三：任务审核]
        D1 -->|"家长ID/需审核标记"| P3["🏠 家长/规划师端：待审核页"]:::page
        P3 -->|"获取待审核列表"| A7["🔗 POST /api/tasks/pending-review"]:::api
        A7 -->|"用户ID"| S7["⚙️ TaskService.getPendingReviewTasks()"]:::service
        S7 -->|"待审核任务列表"| D1

        P3 -->|"审核单个任务"| A8["🔗 POST /api/tasks/{id}/review"]:::api
        A8 -->|"任务ID, {approved, comment, points}"| S8["⚙️ TaskService.reviewTask()"]:::service
        S8 -->|"通过: 发放能量/积分; 驳回: 退回待修改"| D1

        P3 -->|"删除任务"| A9["🔗 POST /api/tasks/{id}"]:::api
        A9 -->|"任务ID, 用户ID"| S9["⚙️ TaskService.deleteTask()"]:::service
        S9 -->|"更新任务状态=已删除"| D1
    end

    %% ================================================================
    %% 阶段四：规划师批量管理
    %% ================================================================
    subgraph 阶段四[阶段四：规划师批量管理]
        D1 -->|"关联家庭"| P4["📋 规划师端：任务管理首页"]:::page
        P4 -->|"获取关联家庭"| A10["🔗 POST /api/guide/families/bound-families"]:::api
        A10 -->|"规划师ID, role"| S10["⚙️ GuideFamilyTaskController.getBoundFamilies()"]:::service
        S10 -->|"家庭列表（含待审核数）"| D3["📦 users（teacher_family_ids）"]:::data

        P4 -->|"家庭概览"| A11["🔗 POST /api/guide/families/{familyId}/overview"]:::api
        A11 -->|"规划师ID, familyId"| S11["⚙️ GuideFamilyTaskController.getFamilyTaskOverview()"]:::service
        S11 -->|"孩子任务概览（今日/待审核/总计）"| D1

        P4 -->|"孩子任务列表"| A12["🔗 POST /api/guide/families/{familyId}/children/{childId}/tasks"]:::api
        A12 -->|"familyId, childId, 分页, status"| S12["⚙️ TaskService.getTaskHistoryByFamilyMember()"]:::service
        S12 -->|"分页任务列表"| D1

        P4 -->|"待审核列表（孩子）"| A13["🔗 POST /api/guide/families/{familyId}/children/{childId}/pending-review"]:::api
        A13 -->|"familyId, childId"| S13["⚙️ TaskService.getPendingReviewTasksForFamilyMember()"]:::service
        S13 -->|"待审核任务列表"| D1

        P4 -->|"审核任务"| A14["🔗 POST /api/guide/families/{familyId}/tasks/{taskId}/review"]:::api
        A14 -->|"familyId, taskId, approved, comment"| S14["⚙️ TaskService.reviewTask()"]:::service
        S14 -->|"通过/驳回"| D1

        P4 -->|"批量审核"| A15["🔗 POST /api/guide/families/{familyId}/tasks/batch-review"]:::api
        A15 -->|"familyId, taskIds[], approved"| S15["⚙️ GuideFamilyTaskController.batchReviewTasks()"]:::service
        S15 -->|"逐条调用reviewTask"| D1

        P4 -->|"修改任务"| A16["🔗 POST /api/guide/families/{familyId}/tasks/{taskId}"]:::api
        A16 -->|"familyId, taskId, 标题/描述/积分/截止/状态"| S16["⚙️ GuideFamilyTaskController.updateTask()"]:::service
        S16 -->|"更新任务字段"| D1

        P4 -->|"删除任务"| A17["🔗 POST /api/guide/families/{familyId}/tasks/{taskId}/delete"]:::api
        A17 -->|"familyId, taskId"| S17["⚙️ GuideFamilyTaskController.deleteTask()"]:::service
        S17 -->|"任务状态=已取消"| D1

        P4 -->|"规划师首页统计"| A18["🔗 POST /api/guide/families/dashboard-stats"]:::api
        A18 -->|"规划师ID, role"| S18["⚙️ GuideFamilyTaskController.getDashboardStats()"]:::service
        S18 -->|"家庭数, 今日完成数, 待审核数"| D1
    end

    %% ================================================================
    %% 阶段五：任务历史与提醒
    %% ================================================================
    subgraph 阶段五[阶段五：任务历史与提醒]
        D1 -->|"孩子ID"| P5["🏠 孩子/家长端：历史与提醒页"]:::page
        P5 -->|"任务历史"| A19["🔗 POST /api/tasks/history"]:::api
        A19 -->|"childId, 分页, category"| S19["⚙️ TaskService.getTaskHistory()"]:::service
        S19 -->|"分页历史任务"| D1

        P5 -->|"批量完成"| A20["🔗 POST /api/tasks/batch-complete"]:::api
        A20 -->|"用户ID, taskIds[]"| S20["⚙️ TaskService.batchComplete()"]:::service
        S20 -->|"逐条完成任务"| D1

        P5 -->|"批量删除"| A21["🔗 POST /api/tasks/batch-delete"]:::api
        A21 -->|"用户ID, taskIds[]"| S21["⚙️ TaskService.batchDelete()"]:::service
        S21 -->|"逐条删除任务"| D1

        P5 -->|"即将到期"| A22["🔗 POST /api/task-reminders/upcoming/{childId}"]:::api
        A22 -->|"childId, minutes"| S22["⚙️ TaskReminderService.getUpcomingTasks()"]:::service
        S22 -->|"指定时间内到期的任务"| D1

        P5 -->|"逾期任务"| A23["🔗 POST /api/task-reminders/overdue/{childId}"]:::api
        A23 -->|"childId"| S23["⚙️ TaskReminderService.getOverdueTasks()"]:::service
        S23 -->|"已超时未完成的任务"| D1

        P5 -->|"需要提醒"| A24["🔗 POST /api/task-reminders/reminder/{childId}"]:::api
        A24 -->|"childId"| S24["⚙️ TaskReminderService.getTasksNeedReminder()"]:::service
        S24 -->|"30分钟内到期未完成的任务"| D1

        P5 -->|"历史筛选"| A25["🔗 POST /api/task-reminders/history/filter/{childId}"]:::api
        A25 -->|"childId, status, startDate, endDate, 分页"| S25["⚙️ TaskReminderService.getTaskHistoryWithFilter()"]:::service
        S25 -->|"按条件筛选的历史任务"| D1
    end

    %% ================================================================
    %% 阶段六：统计分析
    %% ================================================================
    subgraph 阶段六[阶段六：统计分析]
        D1 -->|"孩子ID"| P6["🏠 家长/规划师端：统计页"]:::page
        P6 -->|"任务统计概览"| A26["🔗 POST /api/task-reminders/statistics/{childId}"]:::api
        A26 -->|"childId, startDate, endDate"| S26["⚙️ TaskReminderService.getTaskStatistics()"]:::service
        S26 -->|"完成率, 逾期率, 积分统计"| D1

        P6 -->|"分类统计"| A27["🔗 POST /api/task-reminders/statistics/category/{childId}"]:::api
        A27 -->|"childId"| S27["⚙️ TaskReminderService.getTaskStatsByCategory()"]:::service
        S27 -->|"按维度的任务统计"| D1

        P6 -->|"日期统计"| A28["🔗 POST /api/task-reminders/statistics/date/{childId}"]:::api
        A28 -->|"childId, days"| S28["⚙️ TaskReminderService.getTaskStatsByDate()"]:::service
        S28 -->|"近N天每日完成数"| D1

        P6 -->|"家庭统计"| A29["🔗 POST /api/task-reminders/statistics/family/{familyId}"]:::api
        A29 -->|"familyId"| S29["⚙️ TaskReminderService.getFamilyTaskStatistics()"]:::service
        S29 -->|"整个家庭的任务统计"| D1
    end

    %% ================================================================
    %% 定时任务
    %% ================================================================
    subgraph 定时[⏰ 定时任务]
        S_T1["⚙️ RepeatTaskGenerator.generateDailyTasks()"]:::service
        S_T1 -->|"每天凌晨5点, 扫描repeat_type=daily/weekly的任务模板"| D1
        S_T1 -->|"从模板创建今日任务实例"| D1
    end

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

端点明细

任务创建

端点	说明	端口	请求数据	响应数据
POST /api/tasks/create	创建任务	📱小程序	{childId, title, description, points, deadline, needReview, category, executorType, ...}	taskId
POST /api/tasks/minigame-options	获取可选小游戏列表	📱小程序	—	List<MiniGame>
POST /api/tasks/{id}	删除任务	📱小程序	path: id, body: —	boolean

任务执行

端点	说明	端口	请求数据	响应数据
POST /api/tasks/today	获取今日任务	📱小程序	{childId, category}	List<Task>
POST /api/tasks/today-parent	获取家长今日任务	📱小程序	—	List<Task>
POST /api/tasks/{id}/complete	完成任务	📱小程序	path: id, body: {childId, photoUrl}	{points, energy, ...}
POST /api/tasks/{id}/complete-parent	家长完成任务	📱小程序	path: id	{points, ...}
POST /api/tasks/{id}/complete-minigame	完成小游戏任务	📱小程序	path: id, body: {childId, completionTime, score}	{points, energy, score, ...}

任务审核

端点	说明	端口	请求数据	响应数据
POST /api/tasks/pending-review	获取待审核任务列表	📱小程序	— (从token取userId)	List<Task>
POST /api/tasks/{id}/review	审核任务	📱小程序	path: id, body: {approved, comment, points}	boolean

任务历史与批量操作

端点	说明	端口	请求数据	响应数据
POST /api/tasks/history	获取任务历史	📱小程序	{childId, page, size, category}	Page<Task>
POST /api/tasks/batch-complete	批量完成任务	📱小程序	{taskIds[]}	boolean
POST /api/tasks/batch-delete	批量删除任务	📱小程序	{taskIds[]}	boolean

任务提醒与筛选

端点	说明	端口	请求数据	响应数据
POST /api/task-reminders/reminder/{childId}	获取需提醒任务（30分钟到期）	📱小程序	path: childId	List<Task>
POST /api/task-reminders/upcoming/{childId}	即将到期任务	📱小程序	path: childId, body: {minutes}	List<Task>
POST /api/task-reminders/overdue/{childId}	逾期任务	📱小程序	path: childId	List<Task>
POST /api/task-reminders/history/filter/{childId}	带筛选的历史任务	📱小程序	path: childId, body: {status, startDate, endDate, page, size}	{tasks, total, ...}

统计分析

端点	说明	端口	请求数据	响应数据
POST /api/task-reminders/statistics/{childId}	任务统计概览	📱小程序	path: childId, body: {startDate, endDate}	{total, completed, overdue, completionRate, ...}
POST /api/task-reminders/statistics/category/{childId}	按分类统计	📱小程序	path: childId	List<{category, count, completed, ...}>
POST /api/task-reminders/statistics/date/{childId}	按日期统计	📱小程序	path: childId, body: {days}	List<{date, count, ...}>
POST /api/task-reminders/statistics/family/{familyId}	家庭任务统计	📱小程序	path: familyId	{totalTasks, completedTasks, ...}

规划师批量管理

端点	说明	端口	请求数据	响应数据
POST /api/guide/families/bound-families	获取关联家庭列表	📋规划师端	— (从token取userId+role)	List<{familyId, familyName, childrenCount, pendingReviewCount}>
POST /api/guide/families/{familyId}/overview	家庭任务概览	📋规划师端	path: familyId	{children[], totalPendingReview, totalCompleted, totalOverdue}
POST /api/guide/families/{familyId}/children/{childId}/tasks	孩子任务列表(分页)	📋规划师端	path: familyId, childId, body: {page, size, status}	Page<Task>
POST /api/guide/families/{familyId}/children/{childId}/pending-review	待审核任务列表	📋规划师端	path: familyId, childId	List<Task>
POST /api/guide/families/{familyId}/tasks/{taskId}/review	审核任务	📋规划师端	path: familyId, taskId, body: {approved, comment}	boolean
POST /api/guide/families/{familyId}/tasks/batch-review	批量审核	📋规划师端	path: familyId, body: {taskIds[], approved}	{successCount, failCount}
POST /api/guide/families/{familyId}/tasks/{taskId}	修改任务	📋规划师端	path: familyId, taskId, body: {title, description, points, deadline, status}	boolean
POST /api/guide/families/{familyId}/tasks/{taskId}/delete	删除任务	📋规划师端	path: familyId, taskId	boolean
POST /api/guide/families/dashboard-stats	规划师首页统计	📋规划师端	—	{totalFamilies, todayCompletedTasks, pendingReviewTasks}

完整性分析

#	维度	评估	说明
1	流程完整性	✅ 完整	覆盖任务创建（手动/模板/AI/训练方案）、执行（普通/小游戏/家长任务）、审核、规划师批量管理、历史与提醒、统计分析6个阶段，路径完整
2	异常路径	⚠️ 部分覆盖	审核驳回退回待修改、逾期任务、小游戏成绩异常等已在图中体现；定时任务中模板不存在等错误由Service层处理
3	端点覆盖	✅ 完整	29个端点全部映射到流程图中，与代码实际暴露的TaskController、TaskReminderController、GuideFamilyTaskController一致
4	角色覆盖	✅ 完整	家长(parent)创建/审核任务、孩子(child)执行任务、规划师(teacher)批量管理/审核均已覆盖；定时任务(⚙️系统自动)生成重复任务包含在图中
5	数据实体	✅ 完整	tasks表、mini_games表、users表（teacher_family_ids）均在图中映射
6	一致性	✅ 与代码一致	所有端点路径与实际Controller（TaskController、TaskReminderController、GuideFamilyTaskController）中的@PostMapping匹配