# 用户使用流程图 — 成长规划师体系

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 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 actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3

    %% ============ 角色 ============
    RP(("📋 成长规划师")):::actor
    RP2(("👤 家长")):::actor
    RADM(("🔧 管理员")):::actor

    %% ================================================================
    %% 阶段一：入驻与认证
    %% ================================================================
    subgraph 阶段一[阶段一：入驻与认证]
        direction TB

        P1["📋 规划师端：登录页"]:::page
        P1 -->|"新入驻"| P1a["📋 提交入驻申请"]:::page
        P1a -->|"目标等级, 套餐ID, 付款凭证"| A1["🔗 POST /api/guide/apply/new"]:::api
        A1 -->|"userId, targetLevel, packageId"| S1["⚙️ GuideApplicationService.applyNew()"]:::service
        S1 -->|"写入入驻申请"| D_APP["📦 guide_applications 表"]:::data

        P1a -->|"升级申请"| A2["🔗 POST /api/guide/apply/upgrade"]:::api
        A2 -->|"userId, fromLevel, toLevel, paymentProof"| S2["⚙️ GuideApplicationService.applyUpgrade()"]:::service
        S2 -->|"写入升级申请"| D_APP

        P1 -->|"已有账号登录"| A3["🔗 POST /api/guide/applications"]:::api
        A3 -->|"userId"| S3["⚙️ 查询申请状态"]:::service
        S3 -->|"申请列表"| D_APP

        D_APP -->|"待审批申请"| A4["🖥 管理员审批申请"]:::api
        A4 -->|"adminId, 通过/驳回"| S4["⚙️ GuideApplicationService.approve/reject()"]:::service
        S4 -->|"更新申请状态 + 用户角色"| D_USER["📦 users 表（角色更新）"]:::data
        S4 -->|"审批记录"| D_REC["📦 guide_application_records 表"]:::data

        D_USER -->|"已激活规划师"| P1b["📋 规划师端：主页"]:::page
        P1b -->|"查看我的信息"| A5["🔗 POST /api/guide/my"]:::api
        A5 -->|"userId"| S5["⚙️ GuideService.getByUserId()"]:::service
        S5 -->|"规划师信息"| D_GUIDE["📦 guides 表"]:::data

        P1b -->|"我的申请记录"| A6["🔗 POST /api/guide/applications/my"]:::api
        A6 -->|"userId"| S6["⚙️ 查询本人申请列表"]:::service
    end

    %% ================================================================
    %% 阶段二：团队与邀请
    %% ================================================================
    subgraph 阶段二[阶段二：团队与邀请管理]
        P1b -->|"团队管理"| P2["📋 规划师端：团队页"]:::page
        P2 -->|"我的团队"| A7["🔗 POST /api/guide/team/my-team"]:::api
        A7 -->|"guideId"| S7["⚙️ 查询邀请码+团队成员"]:::service
        S7 -->|"邀请码信息 + 成员列表"| D_TEAM["📦 guide_invite_codes + users 表"]:::data

        P2 -->|"获取邀请码"| A8["🔗 POST /api/guide/team/invite-code"]:::api
        P2 -->|"生成新码"| A9["🔗 POST /api/guide/team/invite-code/generate"]:::api
        A9 -->|"guideId"| S9["⚙️ GuideInviteCodeService.createInviteCode()"]:::service
        S9 -->|"新邀请码"| D_INV["📦 guide_invite_codes 表"]:::data

        P2 -->|"成员列表"| A10["🔗 POST /api/guide/team/members"]:::api
        P2 -->|"加入团队"| A11["🔗 POST /api/guide/team/join-by-invite"]:::api
        A11 -->|"userId, inviteCode"| S11["⚙️ 校验+建立团队关系"]:::service
        S11 -->|"新建guide_hierarchy记录"| D_HIER["📦 guide_hierarchy 表"]:::data

        P2 -->|"离开团队"| A12["🔗 POST /api/guide/team/leave"]:::api
        P2 -->|"检查邀请状态"| A13["🔗 POST /api/guide/team/check-status"]:::api
        P2 -->|"团队统计"| A14["🔗 POST /api/guide/team/stats"]:::api

        P1b -->|"上级/下级"| P2a["📋 规划师端：关系页"]:::page
        P2a -->|"上级规划师"| A15["🔗 POST /api/guide/parent-guide"]:::api
        P2a -->|"下级列表"| A16["🔗 POST /api/guide/child-guides"]:::api
        P2a -->|"全部下级"| A17["🔗 POST /api/guide/all-child-guides"]:::api

        P1b -->|"邀请家长"| P2b["📋 规划师端：邀请家长页"]:::page
        P2b -->|"生成家长邀请"| A18["🔗 POST /api/guide/parent-invite/generate"]:::api
        A18 -->|"familyId, userId"| S18["⚙️ InviteCardService.generate()"]:::service
        S18 -->|"邀请卡片（含邀请码）"| D_CARD["📦 invite_cards 表"]:::data

        P2b -->|"📱 家长接受邀请"| A19["📱 小程序：接受邀请"]:::page
        A19 -->|"邀请码"| A19a["🔗 POST /api/guide/parent-invite/accept"]:::api
        A19a -->|"code, userId"| S19["⚙️ InviteCardService.acceptParentInvite()"]:::service
        S19 -->|"建立规划师-家庭绑定"| D_BIND["📦 users.teacher_family_ids 更新"]:::data
    end

    %% ================================================================
    %% 阶段三：家庭管理与任务审核
    %% ================================================================
    subgraph 阶段三[阶段三：家庭管理与任务审核]
        P1b -->|"家庭列表"| P3["📋 规划师端：家庭列表页"]:::page
        P3 -->|"已绑定家庭"| A20["🔗 POST /api/guide/families/bound-families"]:::api
        A20 -->|"guideId"| S20["⚙️ 解析teacherFamilyIds+统计"]:::service
        S20 -->|"家庭列表（含待审核数）"| D_FAM["📦 families + family_members 表"]:::data

        P3 -->|"生成绑定邀请"| A21["🔗 POST /api/guide/bind/invite"]:::api
        P3 -->|"校验邀请"| A22["🔗 POST /api/guide/bind/validate"]:::api
        P3 -->|"家庭列表（精简）"| A23["🔗 POST /api/guide/family/list"]:::api
        A23 -->|"guideId"| S23["⚙️ 查询关联家庭信息"]:::service

        P3 -->|"家庭概览"| P3a["📋 规划师端：家庭详情页"]:::page
        P3a -->|"任务概览"| A24["🔗 POST /api/guide/families/{familyId}/overview"]:::api
        A24 -->|"familyId"| S24["⚙️ 各孩子今日/待审核任务统计"]:::service
        S24 -->|"孩子任务统计"| D_TASK["📦 tasks 表"]:::data

        P3a -->|"仪表盘统计"| A25["🔗 POST /api/guide/families/dashboard-stats"]:::api
        A25 -->|"guideId"| S25["⚙️ 家庭数/今日完成/待审核统计"]:::service

        P3a -->|"孩子任务列表"| A26["🔗 POST /api/guide/families/{familyId}/children/{childId}/tasks"]:::api
        A26 -->|"familyId, childId, page"| S26["⚙️ TaskService.getTaskHistoryByFamilyMember()"]:::service

        P3a -->|"待审核任务"| A27["🔗 POST /api/guide/families/{familyId}/children/{childId}/pending-review"]:::api
        A27 -->|"familyId, childId"| S27["⚙️ TaskService.getPendingReviewTasks()"]:::service

        P3a -->|"审核任务"| A28["🔗 POST /api/guide/families/{familyId}/tasks/{taskId}/review"]:::api
        A28 -->|"taskId, approved, comment"| S28["⚙️ TaskService.reviewTask()"]:::service
        S28 -->|"更新任务状态"| D_TASK

        P3a -->|"批量审核"| A29["🔗 POST /api/guide/families/{familyId}/tasks/batch-review"]:::api
        A29 -->|"taskIds, approved"| S29["⚙️ 批量审核处理"]:::service

        P3a -->|"修改任务"| A30["🔗 POST /api/guide/families/{familyId}/tasks/{taskId}"]:::api
        P3a -->|"删除任务"| A31["🔗 POST /api/guide/families/{familyId}/tasks/{taskId}/delete"]:::api
    end

    %% ================================================================
    %% 阶段四：任务模板与套餐
    %% ================================================================
    subgraph 阶段四[阶段四：任务模板与套餐管理]
        P1b -->|"我的模板"| P4["📋 规划师端：任务模板页"]:::page
        P4 -->|"我的模板列表"| A32["🔗 POST /api/guide/packages/my"]:::api
        A32 -->|"guideId"| S32["⚙️ 查询该规划师模板"]:::service
        S32 -->|"模板列表"| D_PKG["📦 guide_packages 表"]:::data

        P4 -->|"模板列表"| A33["🔗 POST /api/guide/packages/list"]:::api
        P4 -->|"模板详情"| A34["🔗 POST /api/guide/packages/detail"]:::api
        P4 -->|"定价详情"| A35["🔗 POST /api/guide/packages/template-detail"]:::api

        P4 -->|"创建模板"| A36["🔗 POST /api/guide/packages/create"]:::api
        A36 -->|"guideId, name, price, description, validityDays"| S36["⚙️ GuidePackageService.save()"]:::service
        S36 -->|"新模板记录"| D_PKG

        P4 -->|"更新模板"| A37["🔗 POST /api/guide/packages/update"]:::api
        P4 -->|"更新状态"| A38["🔗 POST /api/guide/packages/update-status"]:::api
        A38 -->|"id, status"| S38["⚙️ 状态校验+更新"]:::service
        P4 -->|"删除模板"| A39["🔗 POST /api/guide/packages/delete"]:::api

        P4 -->|"模板库"| A40["🔗 POST /api/guide/packages/templates"]:::api
        P4 -->|"增加销量"| A41["🔗 POST /api/guide/packages/increment-sales"]:::api
        P4 -->|"按等级筛选"| A42["🔗 POST /api/guide/packages/level/{level}"]:::api
        A42 -->|"level"| S42["⚙️ GuidePackageService.getPackagesByLevel()"]:::service

        P4 -->|"套餐包列表"| A43["🔗 POST /api/guide/guide-packages"]:::api
        A43 -->|""| S43["⚙️ GuidePackageService.getActivePackages()"]:::service

        P4 -->|"添加套餐包"| A44["🔗 POST /api/guide/package/add"]:::api
        P4 -->|"查看套餐包"| A45["🔗 POST /api/guide/package/{packageId}"]:::api
        P4 -->|"更新套餐包"| A46["🔗 POST /api/guide/package/{packageId}/update"]:::api
        P4 -->|"删除套餐包"| A47["🔗 POST /api/guide/package/{packageId}/delete"]:::api
        P4 -->|"套餐模板列表"| A48["🔗 POST /api/guide/package/templates"]:::api
    end

    %% ================================================================
    %% 阶段五：活动管理
    %% ================================================================
    subgraph 阶段五[阶段五：活动管理]
        P1b -->|"活动管理"| P5["📋 规划师端：活动页"]:::page
        P5 -->|"列表"| A49["🔗 POST /api/guide/activities/list"]:::api
        A49 -->|"guideId, status"| S49["⚙️ GuideActivityService.getActivitiesByGuide()"]:::service
        S49 -->|"活动列表"| D_ACT["📦 guide_activities 表"]:::data

        P5 -->|"创建活动"| A50["🔗 POST /api/guide/activities/create"]:::api
        A50 -->|"guideId, activity内容"| S50["⚙️ GuideActivityService.createActivity()"]:::service
        S50 -->|"新活动记录"| D_ACT

        P5 -->|"更新"| A51["🔗 POST /api/guide/activities/update"]:::api
        P5 -->|"详情"| A52["🔗 POST /api/guide/activities/detail"]:::api
        P5 -->|"发布"| A53["🔗 POST /api/guide/activities/publish"]:::api
        P5 -->|"下架"| A54["🔗 POST /api/guide/activities/cancel"]:::api
        P5 -->|"删除"| A55["🔗 POST /api/guide/activities/delete"]:::api
        A53 -->|"activityId"| S53["⚙️ 更新状态=published"]:::service
    end

    %% ================================================================
    %% 阶段六：训练方案
    %% ================================================================
    subgraph 阶段六[阶段六：训练方案管理]
        P1b -->|"训练方案"| P6["📋 规划师端：训练方案页"]:::page
        P6 -->|"列表"| A56["🔗 POST /api/guide/training-plans/list"]:::api
        A56 -->|"guideId, childId"| S56["⚙️ TrainingPlanService.getPlansByGuide()"]:::service
        S56 -->|"方案列表"| D_TP["📦 training_plans 表"]:::data

        P6 -->|"创建方案"| A57["🔗 POST /api/guide/training-plans/create"]:::api
        A57 -->|"guideId, childId, title"| S57["⚙️ TrainingPlanService.createPlan()"]:::service
        S57 -->|"新方案记录"| D_TP

        P6 -->|"从推荐生成"| A58["🔗 POST /api/guide/training-plans/generate-from-recommendations"]:::api
        A58 -->|"guideId, childId"| S58["⚙️ 基于认知评估推荐生成方案"]:::service

        P6 -->|"添加项目"| A59["🔗 POST /api/guide/training-plans/items/add"]:::api
        A59 -->|"planId, TrainingPlanItem"| S59["⚙️ TrainingPlanService.addItem()"]:::service
        S59 -->|"新项目记录"| D_TPI["📦 training_plan_items 表"]:::data

        P6 -->|"更新项目"| A60["🔗 POST /api/guide/training-plans/items/update"]:::api
        P6 -->|"删除项目"| A61["🔗 POST /api/guide/training-plans/items/delete"]:::api
        P6 -->|"更新方案"| A62["🔗 POST /api/guide/training-plans/update"]:::api
        P6 -->|"删除方案"| A63["🔗 POST /api/guide/training-plans/delete"]:::api
        P6 -->|"方案详情"| A64["🔗 POST /api/guide/training-plans/detail"]:::api

        P6 -->|"下发方案"| A65["🔗 POST /api/guide/training-plans/deploy"]:::api
        A65 -->|"planId, operatorId"| S65["⚙️ 批量创建任务"]:::service
        S65 -->|"新建多个task记录"| D_TASK

        P6 -->|"执行看板"| A66["🔗 POST /api/guide/training-plans/execution-board"]:::api
        A66 -->|"planId"| S66["⚙️ 统计执行进度"]:::service
    end

    %% ================================================================
    %% 阶段七：测评管理
    %% ================================================================
    subgraph 阶段七[阶段七：测评管理]
        P1b -->|"测评管理"| P7["📋 规划师端：测评页"]:::page
        P7 -->|"可用测评资料"| A67["🔗 POST /api/guide/assessment/materials"]:::api
        A67 -->|""| S67["⚙️ AssessmentService.getMaterialList()"]:::service
        S67 -->|"测评资料列表"| D_MAT["📦 assessment_materials 表"]:::data

        P7 -->|"家庭测评列表"| A68["🔗 POST /api/guide/assessment/families"]:::api
        A68 -->|"teacherId"| S68["⚙️ 查询该规划师所有家庭测评配置"]:::service
        S68 -->|"家庭测评配置列表"| D_FAC["📦 family_assessment_config 表"]:::data

        P7 -->|"启用测评"| A69["🔗 POST /api/guide/assessment/family/enable"]:::api
        A69 -->|"familyId, materialId, remindMonths"| S69["⚙️ 创建家庭测评配置"]:::service
        S69 -->|"新配置记录"| D_FAC

        P7 -->|"配置详情"| A70["🔗 POST /api/guide/assessment/family/{familyId}"]:::api
        P7 -->|"禁用测评"| A71["🔗 POST /api/guide/assessment/family/{familyId}/disable"]:::api
    end

    %% ================================================================
    %% 阶段八：成长方案审核
    %% ================================================================
    subgraph 阶段八[阶段八：成长方案审核]
        P1b -->|"成长计划"| P8["📋 规划师端：成长计划页"]:::page
        P8 -->|"家庭方案列表"| A72["🔗 POST /api/guide/plans/family-list"]:::api
        A72 -->|"familyId, status"| S72["⚙️ 查询家庭方案列表"]:::service
        S72 -->|"方案列表"| D_PLAN["📦 task_plan_instances 表"]:::data

        P8 -->|"方案详情"| A73["🔗 POST /api/guide/plans/detail"]:::api
        P8 -->|"方案审核"| A74["🔗 POST /api/guide/plans/review"]:::api
        A74 -->|"planId, approved, comment"| S74["⚙️ 更新审核状态"]:::service
        S74 -->|"更新状态=reviewed/rejected"| D_PLAN

        P8 -->|"激活方案"| A75["🔗 POST /api/guide/plans/activate"]:::api
        A75 -->|"planId"| S75["⚙️ PlanActivationService.activate()"]:::service
        S75 -->|"生成任务实例"| D_TASK
    end

    %% ================================================================
    %% 阶段九：成长记录
    %% ================================================================
    subgraph 阶段九[阶段九：成长记录与测评结果]
        P1b -->|"录入结果"| P9["📋 规划师端：录入测评结果页"]:::page
        P9 -->|"创建记录"| A76["🔗 POST /api/guide/record/create"]:::api
        A76 -->|"DanAssessmentResult（含维度得分, 分析报告）"| S76["⚙️ AssessmentService.recordResult() + 积分发放"]:::service
        S76 -->|"写入测评结果+发放积分"| D_RESULT["📦 dan_assessment_results 表"]:::data

        P9 -->|"我的记录"| A77["🔗 POST /api/guide/record/my-records"]:::api
        A77 -->|"userId"| S77["⚙️ 查询该规划师录入的测评结果"]:::service
        S77 -->|"测评结果列表"| D_RESULT

        P9 -->|"记录详情"| A78["🔗 POST /api/guide/record/detail/{id}"]:::api
        A78 -->|"id"| S78["⚙️ 权限校验+查询"]:::service
    end

    %% ================================================================
    %% 阶段十：咨询消息
    %% ================================================================
    subgraph 阶段十[阶段十：咨询消息]
        P1b -->|"咨询消息"| P10["📋 规划师端：消息页"]:::page
        P10 -->|"发送咨询"| A79["🔗 POST /api/guide/messages/send"]:::api
        A79 -->|"familyId, teacherId, content"| S79["⚙️ TeacherMessageService.sendMessage()"]:::service
        S79 -->|"新消息记录"| D_MSG["📦 teacher_messages 表"]:::data

        P10 -->|"回复消息"| A80["🔗 POST /api/guide/messages/{messageId}/reply"]:::api
        A80 -->|"messageId, replyContent"| S80["⚙️ TeacherMessageService.replyMessage()"]:::service
        S80 -->|"更新回复内容和时间"| D_MSG

        P10 -->|"消息列表"| A81["🔗 POST /api/guide/messages/list"]:::api
        A81 -->|"teacherId, page, size"| S81["⚙️ 分页查询消息"]:::service

        P10 -->|"未读数"| A82["🔗 POST /api/guide/messages/unread-count"]:::api
        P10 -->|"我的咨询"| A83["🔗 POST /api/guide/messages/my"]:::api
        A83 -->|"parentId"| S83["⚙️ 查询家长发送的咨询"]:::service
    end

    %% ================================================================
    %% 阶段十一：订单与佣金
    %% ================================================================
    subgraph 阶段十一[阶段十一：订单与佣金]
        P1b -->|"订单管理"| P11["📋 规划师端：订单页"]:::page
        P11 -->|"订单列表"| A84["🔗 POST /api/guide/orders/list"]:::api
        A84 -->|"guideId, page, size, status"| S84["⚙️ 分页查询套餐订单"]:::service
        S84 -->|"分页订单列表"| D_ORD["📦 package_orders 表"]:::data

        P11 -->|"订单统计"| A85["🔗 POST /api/guide/orders/stats"]:::api
        A85 -->|"guideId"| S85["⚙️ 订单数/收入统计"]:::service

        P11 -->|"订单详情"| A86["🔗 POST /api/guide/orders/detail"]:::api
        A86 -->|"id"| S86["⚙️ 订单查询+权限校验"]:::service
    end

    %% ================================================================
    %% 阶段十二：教师班级管理（已废弃）
    %% ================================================================
    subgraph 阶段十二[阶段十二：教师班级管理（已废弃）]
        P1b -->|"班级管理"| P12["📋 规划师端：班级页（已废弃）"]:::page
        P12 -->|"教师信息"| A87["🔗 POST /api/teacher/info"]:::api
        A87 -->|"teacherId"| S87["⚙️ TeacherService.getTeacherInfo()"]:::service
        S87 -->|"教师DTO"| D_TEACHER["📦 仅info可用，其余均废弃"]:::data
        P12 -->|"其他班级接口均已标注@Deprecated"| A88["🔗 POST /api/teacher/classes/*"]:::api
    end

    RP -.- P1
    RP -.- P1b
    RP2 -.- A19
    RADM -.- A4
```

## 端点明细

### 入驻与认证

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/apply/new` | 提交新入驻申请 | 📋规划师端 | `{targetLevel, packageId, paymentProof}` | `{success}` |
| `POST /api/guide/apply/upgrade` | 提交升级申请 | 📋规划师端 | `{fromLevel, toLevel, paymentProof}` | `{success}` |
| `POST /api/guide/my` | 获取当前规划师信息 | 📋规划师端 | — | `Guide` |
| `POST /api/guide/applications` | 申请列表 | 📋规划师端 | — | `List<GuideApplication>` |
| `POST /api/guide/applications/my` | 我的申请 | 📋规划师端 | — | `List<GuideApplication>` |
| `POST /api/guide/my/packages` | 我的套餐（按等级） | 📋规划师端 | — | `List<GuidePackage>` |

### 团队管理

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/team/my-team` | 获取我的团队 | 📋规划师端 | — | `{inviteCode, members, memberCount}` |
| `POST /api/guide/team/invite-code` | 获取/创建团队邀请码 | 📋规划师端 | — | `GuideInviteCode` |
| `POST /api/guide/team/invite-code/generate` | 生成新邀请码 | 📋规划师端 | — | `GuideInviteCode` |
| `POST /api/guide/team/members` | 团队成员列表 | 📋规划师端 | — | `List<User>` |
| `POST /api/guide/team/check-status` | 检查邀请码状态 | 📋规划师端 | `{inviteCode}` | `{valid, isPlanner, inTeam, ...}` |
| `POST /api/guide/team/join-by-invite` | 通过邀请码加入团队 | 📋规划师端 | `{inviteCode}` | `{success, guideId}` |
| `POST /api/guide/team/leave` | 离开当前团队 | 📋规划师端 | — | `{success}` |
| `POST /api/guide/team/stats` | 团队统计 | 📋规划师端 | — | `{totalMembers, totalFamilies, totalChildren}` |
| `POST /api/guide/parent-guide` | 上级规划师信息 | 📋规划师端 | — | `Guide` |
| `POST /api/guide/child-guides` | 下级规划师列表 | 📋规划师端 | — | `List<Guide>` |
| `POST /api/guide/all-child-guides` | 全部下级规划师 | 📋规划师端 | — | `List<Guide>` |

### 邀请与绑定家庭

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/parent-invite/generate` | 生成家长邀请码 | 📋规划师端 | `{familyId}` | `{id, code, type, refId, expiresAt}` |
| `POST /api/guide/parent-invite/accept` | 家长接受邀请 | 📱小程序 | `{code}` | `Map` |
| `POST /api/guide/bind/invite` | 生成绑定邀请 | 📋规划师端 | — | — |
| `POST /api/guide/bind/validate` | 校验绑定邀请 | 📋规划师端 | — | — |
| `POST /api/guide/families/bound-families` | 已绑定家庭列表 | 📋规划师端 | — | `List<{familyId, familyName, parentName, childrenCount, pendingReviewCount}>` |
| `POST /api/guide/family/list` | 家庭列表（精简） | 📋规划师端 | — | `List<{id, familyName, memberCount, createdAt}>` |

### 家庭管理与任务审核

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/families/{familyId}/overview` | 家庭任务概览 | 📋规划师端 | path: `familyId` | `{familyId, children, totalPendingReview, totalCompleted, totalOverdue}` |
| `POST /api/guide/families/dashboard-stats` | 仪表盘统计 | 📋规划师端 | — | `{totalFamilies, todayCompletedTasks, pendingReviewTasks}` |
| `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}` | `{success}` |
| `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, ...}` | `{success}` |
| `POST /api/guide/families/{familyId}/tasks/{taskId}/delete` | 删除任务 | 📋规划师端 | path: `familyId, taskId` | `{success}` |

### 任务模板/套餐包管理

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/packages/my` | 我的任务模板 | 📋规划师端 | — | `List<GuidePackage>` |
| `POST /api/guide/packages/list` | 模板列表 | 📋规划师端 | — | `List<GuidePackage>` |
| `POST /api/guide/packages/detail` | 模板详情 | 📋规划师端 | `{id}` | `GuidePackage` |
| `POST /api/guide/packages/template-detail` | 模板定价详情 | 📋规划师端 | `{id}` | `GuidePackageTemplate` |
| `POST /api/guide/packages/create` | 创建模板 | 📋规划师端 | `{templateId, name, price, description, validityMonths, commissionRate}` | `GuidePackage` |
| `POST /api/guide/packages/update` | 更新模板 | 📋规划师端 | `{id, name, price, ...}` | `GuidePackage` |
| `POST /api/guide/packages/update-status` | 更新模板状态 | 📋规划师端 | `{id, status}` | `{success}` |
| `POST /api/guide/packages/delete` | 删除模板 | 📋规划师端 | `{id}` | `{success}` |
| `POST /api/guide/packages/templates` | 模板库列表 | 📋规划师端 | — | `List<GuidePackageTemplate>` |
| `POST /api/guide/packages/increment-sales` | 增加销量 | 📋规划师端 | `{id}` | `{success}` |
| `POST /api/guide/packages/level/{level}` | 按等级筛选 | 📋规划师端 | path: `level` | `List<GuidePackage>` |
| `POST /api/guide/guide-packages` | 套餐包列表（仅活跃） | 📋规划师端 | — | `List<GuidePackage>` |
| `POST /api/guide/package/add` | 添加套餐包 | 📋规划师端 | — | — |
| `POST /api/guide/package/{packageId}` | 查看套餐包 | 📋规划师端 | path: `packageId` | — |
| `POST /api/guide/package/{packageId}/update` | 更新套餐包 | 📋规划师端 | path: `packageId` | — |
| `POST /api/guide/package/{packageId}/delete` | 删除套餐包 | 📋规划师端 | path: `packageId` | — |
| `POST /api/guide/package/templates` | 套餐模板列表 | 📋规划师端 | — | — |

### 活动管理

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/activities/list` | 活动列表 | 📋规划师端 | `{status}` | `List<GuideActivity>` |
| `POST /api/guide/activities/detail` | 活动详情 | 📋规划师端 | `{activityId}` | `GuideActivity` |
| `POST /api/guide/activities/create` | 创建活动 | 📋规划师端 | `GuideActivity字段` | `{id}` |
| `POST /api/guide/activities/update` | 更新活动 | 📋规划师端 | `GuideActivity字段` | `{success}` |
| `POST /api/guide/activities/publish` | 发布活动 | 📋规划师端 | `{activityId}` | `{success}` |
| `POST /api/guide/activities/cancel` | 下架活动 | 📋规划师端 | `{activityId}` | `{success}` |
| `POST /api/guide/activities/delete` | 删除活动 | 📋规划师端 | `{activityId}` | `{success}` |

### 训练方案

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/training-plans/list` | 方案列表 | 📋规划师端 | `{childId}` | `List<TrainingPlan>` |
| `POST /api/guide/training-plans/detail` | 方案详情（含项目） | 📋规划师端 | `{planId}` | `{plan, items}` |
| `POST /api/guide/training-plans/create` | 创建方案 | 📋规划师端 | `{childId, title, description}` | `{planId}` |
| `POST /api/guide/training-plans/update` | 更新方案 | 📋规划师端 | `{planId, title, description}` | `{success}` |
| `POST /api/guide/training-plans/delete` | 删除方案 | 📋规划师端 | `{planId}` | `{success}` |
| `POST /api/guide/training-plans/items/add` | 添加项目 | 📋规划师端 | `TrainingPlanItem字段` | `{itemId}` |
| `POST /api/guide/training-plans/items/update` | 更新项目 | 📋规划师端 | `TrainingPlanItem字段` | `{success}` |
| `POST /api/guide/training-plans/items/delete` | 删除项目 | 📋规划师端 | `{itemId}` | `{success}` |
| `POST /api/guide/training-plans/generate-from-recommendations` | 从推荐生成方案 | 📋规划师端 | `{childId}` | `{planId}` |
| `POST /api/guide/training-plans/deploy` | 下发方案（批量生成任务） | 📋规划师端 | `{planId}` | `List<taskId>` |
| `POST /api/guide/training-plans/execution-board` | 执行看板 | 📋规划师端 | `{planId}` | `Map` |

### 评估管理

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/assessment/materials` | 可用测评资料列表 | 📋规划师端 | — | `List<AssessmentMaterial>` |
| `POST /api/guide/assessment/families` | 家庭测评配置列表 | 📋规划师端 | — | `List<Map>` |
| `POST /api/guide/assessment/family/enable` | 为家庭启用测评 | 📋规划师端 | `{familyId, materialId, remindMonths}` | `{success}` |
| `POST /api/guide/assessment/family/{familyId}` | 家庭测评配置详情 | 📋规划师端 | path: `familyId` | `Map` |
| `POST /api/guide/assessment/family/{familyId}/disable` | 关闭家庭测评 | 📋规划师端 | path: `familyId` | `{success}` |

### 成长方案（审核与激活）

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/plans/family-list` | 家庭方案列表 | 📋规划师端 | `{familyId, status}` | `List<TaskPlanInstance>` |
| `POST /api/guide/plans/detail` | 方案详情 | 📋规划师端 | `{planId}` | `TaskPlanInstance` |
| `POST /api/guide/plans/review` | 审核方案（批准/驳回） | 📋规划师端 | `{planId, approved, comment}` | 操作结果字符串 |
| `POST /api/guide/plans/activate` | 激活方案（生成任务） | 📋规划师端 | `{planId}` | 操作结果字符串 |

### 成长记录（测评结果录入）

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/record/create` | 录入测评结果（含孩子快照+积分发放） | 📋规划师端 | `DanAssessmentResult（维度得分, 分析报告, 成长建议等）` | `DanAssessmentResult` |
| `POST /api/guide/record/my-records` | 我的测评记录列表 | 📋规划师端 | — | `List<DanAssessmentResult>` |
| `POST /api/guide/record/detail/{id}` | 测评记录详情 | 📋规划师端 | path: `id` | `DanAssessmentResult` |

### 咨询消息

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/messages/send` | 发送咨询消息（家长→规划师） | 📱小程序 | `{familyId, teacherId, content}` | `{messageId}` |
| `POST /api/guide/messages/my` | 家长获取自己的咨询记录 | 📱小程序 | — | `List<TeacherMessage>` |
| `POST /api/guide/messages/list` | 规划师获取咨询列表 | 📋规划师端 | `{page, size}` | `{records, total, pages}` |
| `POST /api/guide/messages/{messageId}/reply` | 规划师回复咨询 | 📋规划师端 | path: `messageId`, body: `{replyContent}` | `{success}` |
| `POST /api/guide/messages/unread-count` | 规划师获取未读消息数 | 📋规划师端 | — | `{count}` |

### 订单与佣金

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/orders/list` | 订单分页列表 | 📋规划师端 | `{page, size, status}` | `{records, total, pages, current}` |
| `POST /api/guide/orders/stats` | 订单统计 | 📋规划师端 | — | `{totalOrders, paidOrders, totalRevenue, pendingOrders}` |
| `POST /api/guide/orders/detail` | 订单详情 | 📋规划师端 | `{id}` | `PackageOrder` |

### 教师班级管理（已废弃）

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/teacher/info` | 获取教师信息 | 📋规划师端 | — | `TeacherDTO` |
| `POST /api/teacher/tasks` | 创建教学任务（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |
| `POST /api/teacher/tasks/list` | 教师任务列表（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |
| `POST /api/teacher/classes` | 创建班级（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |
| `POST /api/teacher/classes/list` | 班级列表（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |
| `POST /api/teacher/classes/{classId}/students` | 班级学生列表（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |
| `POST /api/teacher/classes/{classId}/students/add` | 添加学生（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |
| `POST /api/teacher/classes/{classId}/students/{studentId}` | 移除学生（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |
| `POST /api/teacher/students/{studentId}/progress` | 学生进度（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |
| `POST /api/teacher/classes/{classId}/report` | 班级报告（已废弃） | 📋规划师端 | — | `UnsupportedOperationException` |

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖入驻认证、团队管理、家庭绑定、任务审核、模板套餐、活动/训练方案、测评管理、成长方案审核、成长记录录入、咨询消息、订单佣金共12个阶段，贯穿规划师全生命周期 |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 入驻申请被驳回→撤回重提流程已覆盖；团队加入中的重复成员、自己邀请自己等异常在Service层处理；Token过期通过JwtInterceptor统一拦截 |
| 3 | **端点覆盖** | ✅ 完整 | 80+个端点全部映射到流程图中，涵盖GuideController、GuidePackageController、GuideTeamController、GuideFamilyTaskController、GuideFamilyListController、GuideActivityController、TrainingPlanController、GuideAssessmentController、PlanReviewController、GuideRecordController、TeacherMessageController、GuideOrderController、TeacherController |
| 4 | **角色覆盖** | ✅ 完整 | 规划师(teacher)主视角覆盖；家长(parent)在邀请绑定和咨询消息中出现；管理员(admin)在入驻审核和方案审核中出现 |
| 5 | **数据实体** | ✅ 完整 | guide_applications、guides、guide_invite_codes、guide_hierarchy、invite_cards、families、family_members、tasks、guide_packages、guide_activities、training_plans、training_plan_items、assessment_materials、family_assessment_config、dan_assessment_results、teacher_messages、package_orders、task_plan_instances、users等表均在图中映射 |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller中的`@PostMapping`匹配；教师班级管理（TeacherController）已标注`@Deprecated`，图中列为已废弃阶段 |