# 用户使用流程图 — 任务管理

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

```mermaid
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`匹配 |