# 用户使用流程图 — DAN 认知测评

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

## 流程图

```mermaid
flowchart TD
    %% ============ 颜色定义 ============
    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    classDef action fill:#fff3e0,stroke:#f57c00,stroke-width:1px
    classDef system fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
    classDef decision fill:#fce4ec,stroke:#d32f2f,stroke-width:1px
    classDef role fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
    classDef endpoint fill:#f5f5f5,stroke:#616111,stroke-width:1px
    classDef portMiniApp fill:#e3f2fd,stroke:#1565c0,stroke-width:1px,stroke-dasharray:3 2
    classDef portAdmin fill:#fce4ec,stroke:#c62828,stroke-width:1px,stroke-dasharray:3 2
    classDef portGuide fill:#fff8e1,stroke:#f57f17,stroke-width:1px,stroke-dasharray:3 2
    classDef portSystem fill:#f3e5f5,stroke:#6a1b9a,stroke-width:1px,stroke-dasharray:3 2

    subgraph 测评准备
        A1(("👤 家长")):::portMiniApp --> A2[📱 浏览测评材料<br/>/material/list]:::portMiniApp
        A2 --> A3[📱 获取当前启用材料<br/>/material/active]:::portMiniApp
        A3 --> A4{📱 家庭测评已启用?}:::portMiniApp
        A4 -->|否| A5[📱 启用家庭测评<br/>/family/enable]:::portMiniApp
        A4 -->|是| A6[📱 查看家庭配置<br/>/family/config]:::portMiniApp
        A5 --> A6
        A6 --> A7[📱 查看可用额度<br/>/quota/my-list]:::portMiniApp
        A7 --> A8[📱 额度详情<br/>/quota/detail]:::portMiniApp
    end

    subgraph 下单与支付
        A8 --> B1[📱 选择评估师/规划师<br/>/appointment/assessor-list]:::portMiniApp
        B1 --> B2[📱 创建测评订单<br/>/order/create]:::portMiniApp
        B2 --> B3[📱 支付订单<br/>/order/pay]:::portMiniApp
        B3 --> B4[📱 查看订单详情<br/>/order/detail]:::portMiniApp
        B4 --> B5{📱 支付成功?}:::portMiniApp
        B5 -->|否| B6[📱 取消订单<br/>/order/cancel]:::portMiniApp
        B5 -->|是| B7[⚙️ 订单状态: paid<br/>生成额度<br/>进入预约流程]:::portSystem
    end

    subgraph 预约管理
        B7 --> C1[📱 创建预约<br/>/appointment/create<br/>消耗额度 · 生成执行记录]:::portMiniApp
        C1 --> C2[📱 评估师列表<br/>/appointment/guide-list]:::portMiniApp
        C2 --> C3[📱 我的预约列表<br/>/appointment/my-list]:::portMiniApp
        C3 --> C4[📱 用户预约列表<br/>/appointment/user]:::portMiniApp
        C4 --> C5[📋 规划师预约列表<br/>/appointment/guide]:::portGuide
        C5 --> C6[📋 预约确认<br/>/appointment/confirm]:::portGuide
        C6 --> C7[线下/线上执行测评]
        C7 --> C8[📋 完成预约<br/>/appointment/complete]:::portGuide
    end

    subgraph 执行与确认
        C8 --> D1[📋 规划师完成任务<br/>/dan-execution/complete]:::portGuide
        D1 --> D2[📱 用户确认服务<br/>/dan-execution/confirm]:::portMiniApp
        D2 --> D3[📱 执行详情<br/>/dan-execution/detail]:::portMiniApp
        D3 --> D4[📱 用户评价<br/>/dan-execution/rate]:::portMiniApp
        D4 --> D5[📱 我的执行记录<br/>/dan-execution/my-list]:::portMiniApp
        D5 --> D6[📋 规划师待办<br/>/dan-execution/guide/my-tasks]:::portGuide
    end

    subgraph 结果录入
        D6 --> E1{结果来源}
        E1 -->|评估师录入| E2[📋 录入测评结果<br/>/result/record]:::portGuide
        E1 -->|家长上传PDF| E3[📱 上传报告<br/>/result/upload<br/>async AI解析]:::portMiniApp
        E1 -->|DAN PDF上传| E4[📱 上传预览<br/>/report/parse-preview<br/>Phase 1 AI解析]:::portMiniApp
        
        E2 --> E5[⚙️ 结构化分析<br/>/results/{id}/structured]:::portSystem
        E3 --> E6[⚙️ AI解析完成 → 草稿]:::portSystem
        E4 --> E7[⚙️ 预览解析结果]:::portSystem
        
        E7 --> E8[📱 确认入库<br/>/report/confirm<br/>Phase 2]:::portMiniApp
        E6 --> E9[📱 确认上传<br/>/result/{resultId}/confirm-upload]:::portMiniApp
        
        E5 --> E10[📱 获取成长建议<br/>/result/{resultId}/guidance]:::portMiniApp
        E10 --> E11[📋 保存成长建议<br/>/result/{resultId}/guidance/save]:::portGuide
        E8 --> E12[📱 孩子报告列表<br/>/report/child]:::portMiniApp
        E9 --> E12
    end

    subgraph 独立报告流程
        E12 --> F1[📱 上传独立PDF<br/>/dan-report/upload]:::portMiniApp
        F1 --> F2[📱 编辑草稿<br/>/{id}/edit]:::portMiniApp
        F2 --> F3[📱 确认入库<br/>/{id}/confirm]:::portMiniApp
        F3 --> F4[📱 完成分析<br/>/{id}/complete-analysis]:::portMiniApp
        F4 --> F5[📱 报告详情<br/>/{id}]:::portMiniApp
        F5 --> F6[📱 废弃草稿<br/>/{id}/discard]:::portMiniApp
        F6 --> F7[📱 报告列表<br/>/dan-report/list]:::portMiniApp
    end

    subgraph 结果查询与对比
        F7 --> G1[📱 最新测评结果<br/>/assessment/latest-result]:::portMiniApp
        G1 --> G2[📱 测评历史<br/>/assessment/history]:::portMiniApp
        G2 --> G3{📱 对比分析}:::portMiniApp
        G3 -->|孩子整体对比| G4[📱 首次vs最新<br/>/compare/by-child]:::portMiniApp
        G3 -->|单维度变化| G5[📱 维度对比<br/>/compare/by-child-dimension]:::portMiniApp
        G3 -->|家庭对比| G6[📱 家庭对比<br/>/compare/by-family]:::portMiniApp
        G3 -->|综合分析| G7[📱 综合分析<br/>/compare/narrative]:::portMiniApp
        G4 --> G8[📱 我的报告列表<br/>/assessment/my-results]:::portMiniApp
        G5 --> G8
        G6 --> G8
        G7 --> G8
        G8 --> G9[📋 下级规划师报告<br/>/assessment/child-results]:::portGuide
    end

    subgraph 家长端自评
        G9 --> H1[📱 创建自评<br/>/parent/assessment/create]:::portMiniApp
        H1 --> H2[📱 当前进度<br/>/parent/assessment/current]:::portMiniApp
        H2 --> H3[📱 提交自评<br/>/parent/assessment/complete/{recordId}]:::portMiniApp
        H3 --> H4[📱 自评记录<br/>/parent/assessment/records]:::portMiniApp
    end

    subgraph 规划师端评估管理
        H4 --> I1[📋 家庭测评列表<br/>/guide/assessment/families]:::portGuide
        I1 --> I2[📋 家庭详情<br/>/family/{familyId}]:::portGuide
        I2 --> I3[📋 启用/禁用<br/>/family/{familyId}/disable]:::portGuide
        I3 --> I4[📋 培训计划<br/>/guide/training-plans]:::portGuide
    end

    %% 角色标注
    RP1(("👤 家长")):::actor
    RT(("📋 规划师/评估师")):::role
    RS(("⚙️ AI解析引擎")):::system

    A1 -.- RP1
    B1 -.- RT
    C2 -.- RT
    D1 -.- RT
```

## 端点明细

### 测评准备
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/dan-assessment/material/list` | 浏览测评材料 | 📱小程序 |
| `/api/dan-assessment/material/active` | 获取当前启用材料 | 📱小程序 |
| `/api/dan-assessment/family/enable` | 启用家庭测评 | 📱小程序 |
| `/api/dan-assessment/family/disable` | 禁用家庭测评 | 📱小程序 |
| `/api/dan-assessment/family/config` | 获取家庭测评配置 | 📱小程序 |
| `/api/dan-assessment/points-config` | 获取积分配置 | 📱小程序 |
| `/api/assessment/quota/my-list` | 我的可用额度列表 | 📱小程序 |
| `/api/assessment/quota/detail` | 额度详情 | 📱小程序 |

### 下单与支付
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/dan-assessment/order/create` | 创建测评订单 | 📱小程序 |
| `/api/dan-assessment/order/pay` | 支付订单 | 📱小程序 |
| `/api/dan-assessment/order/detail` | 订单详情 | 📱小程序 |
| `/api/dan-assessment/order/family` | 家庭订单列表 | 📱小程序 |
| `/api/dan-assessment/order/cancel` | 取消订单 | 📱小程序 |

### 预约管理
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/dan-assessment/appointment/create` | 创建预约 | 📱小程序 |
| `/api/dan-assessment/appointment/confirm` | 确认预约 | 📋规划师端 |
| `/api/dan-assessment/appointment/complete` | 完成预约 | 📋规划师端 |
| `/api/dan-assessment/appointment/cancel` | 取消预约 | 📱小程序 |
| `/api/dan-assessment/appointment/user` | 用户预约列表 | 📱小程序 |
| `/api/dan-assessment/appointment/guide` | 规划师预约列表 | 📋规划师端 |
| `/api/assessment/appointment/create` | 创建评估预约（含执行记录） | 📱小程序 |
| `/api/assessment/appointment/confirm/{id}` | 确认评估预约 | 📋规划师端 |
| `/api/assessment/appointment/cancel/{id}` | 取消评估预约 | 📱小程序 |
| `/api/assessment/appointment/guide-list` | 评估师可选列表 | 📱小程序 |
| `/api/assessment/appointment/my-list` | 我的预约列表 | 📱小程序 |
| `/api/assessment/appointment/assessor-list` | 评估师列表 | 📱小程序 |
| `/api/assessment/appointment/user` | 用户端预约列表 | 📱小程序 |

### 执行与确认
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/dan-execution/complete` | 规划师完成服务 | 📋规划师端 |
| `/api/dan-execution/confirm` | 用户确认服务完成 | 📱小程序 |
| `/api/dan-execution/rate` | 用户评价服务 | 📱小程序 |
| `/api/dan-execution/detail` | 执行详情（含结算） | 📱小程序/📋规划师端 |
| `/api/dan-execution/my-list` | 用户执行记录 | 📱小程序 |
| `/api/dan-execution/guide/my-tasks` | 规划师待执行任务 | 📋规划师端 |
| `/api/dan-execution/by-order` | 按订单查询执行 | 📱小程序/📋规划师端 |

### 结果录入
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/dan-assessment/result/record` | 记录测评结果 | 📋规划师端 |
| `/api/dan-assessment/result/upload` | 家长上传报告 | 📱小程序 |
| `/api/dan-assessment/result/{id}` | 获取结果详情 | 📱小程序/📋规划师端 |
| `/api/dan-assessment/result/{resultId}/confirm-upload` | 确认上传 | 📱小程序 |
| `/api/dan-assessment/result/{resultId}/guidance` | 获取成长建议 | 📱小程序 |
| `/api/dan-assessment/result/{resultId}/guidance/save` | 保存成长建议 | 📋规划师端 |
| `/api/dan-assessment/results/{id}/structured` | 结构化分析 | ⚙️系统自动 |
| `/api/dan-assessment/record/create` | 创建测评记录 | 📱小程序 |
| `/api/dan-assessment/record/complete` | 完成测评记录 | 📋规划师端 |
| `/api/dan-assessment/record/family` | 家庭测评记录列表 | 📱小程序 |
| `/api/dan-assessment/record/current` | 当前测评 | 📱小程序 |

### 报告上传（DanAssessmentController）
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/dan-assessment/report/parse-preview` | DAN PDF上传预览（Phase 1 AI解析） | 📱小程序 |
| `/api/dan-assessment/report/confirm` | 确认入库（Phase 2） | 📱小程序 |
| `/api/dan-assessment/report/child` | 孩子DAN报告列表 | 📱小程序 |

### 独立报告流程（DanReportController）
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/dan-report/upload` | 上传独立PDF | 📱小程序 |
| `/api/dan-report/{id}/edit` | 编辑草稿 | 📱小程序 |
| `/api/dan-report/{id}/confirm` | 确认入库 | 📱小程序 |
| `/api/dan-report/{id}/discard` | 废弃草稿 | 📱小程序 |
| `/api/dan-report/{id}/complete-analysis` | 完成分析 | 📱小程序 |
| `/api/dan-report/{id}` | 报告详情 | 📱小程序/📋规划师端 |
| `/api/dan-report/list` | 报告列表 | 📱小程序/📋规划师端 |

### 结果查询与对比
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/assessment/latest-result` | 孩子最新测评结果 | 📱小程序 |
| `/api/assessment/history` | 测评历史记录 | 📱小程序 |
| `/api/assessment/my-results` | 我的报告列表 | 📱小程序/📋规划师端 |
| `/api/assessment/child-results` | 下级规划师报告 | 📋规划师端 |
| `/api/assessment/compare/by-child` | 孩子首次vs最新对比 | 📱小程序 |
| `/api/assessment/compare/by-child-dimension` | 孩子单维度变化对比 | 📱小程序 |
| `/api/assessment/compare/by-family` | 家庭对比分析 | 📱小程序 |
| `/api/assessment/compare/narrative` | 综合分析报告 | 📱小程序 |

### 家长端自评
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/parent/assessment/create` | 创建家长自评 | 📱小程序 |
| `/api/parent/assessment/current` | 当前自评进度 | 📱小程序 |
| `/api/parent/assessment/complete/{recordId}` | 提交自评 | 📱小程序 |
| `/api/parent/assessment/records` | 自评记录 | 📱小程序 |

### 规划师端评估管理
| 端点 | 说明 | 端口 |
|------|------|------|
| `/api/guide/assessment/families` | 家庭测评列表 | 📋规划师端 |
| `/api/guide/assessment/family/{familyId}` | 家庭测评详情 | 📋规划师端 |
| `/api/guide/assessment/family/{familyId}/disable` | 禁用家庭测评 | 📋规划师端 |