# 用户使用流程图 — 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/>page: apply<br/>/material/list]:::portMiniApp
        A2 --> A3[📱 获取当前启用材料<br/>page: apply<br/>/material/active]:::portMiniApp
        A3 --> A4{📱 家庭测评已启用?}:::portMiniApp
        A4 -->|否| A5[📱 启用家庭测评<br/>page: apply<br/>/family/enable]:::portMiniApp
        A4 -->|是| A6[📱 查看家庭配置<br/>page: apply<br/>/family/config]:::portMiniApp
        A5 --> A6
        A6 --> A7[📱 查看可用额度<br/>page: quota<br/>/quota/my-list]:::portMiniApp
        A7 --> A8[📱 额度详情<br/>page: quota<br/>/quota/detail]:::portMiniApp
    end

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

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

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

    subgraph 结果录入
        D6 --> E1{结果来源}
        E1 -->|评估师录入| E2[📋 录入测评结果<br/>page: teacher/service-tasks<br/>/result/record]:::portGuide
        E1 -->|家长上传PDF| E3[📱 上传报告<br/>page: upload-report<br/>/result/upload<br/>async AI解析]:::portMiniApp
        E1 -->|DAN PDF上传| E4[📱 上传预览<br/>page: dan-assessment/report-upload<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/>page: dan-assessment/report-upload<br/>/report/confirm<br/>Phase 2]:::portMiniApp
        E6 --> E9[📱 确认上传<br/>page: upload-report<br/>/result/:resultId/confirm-upload]:::portMiniApp
        
        E5 --> E10[📱 获取成长建议<br/>page: results<br/>/result/:resultId/guidance]:::portMiniApp
        E10 --> E11[📋 保存成长建议<br/>/result/:resultId/guidance/save]:::portGuide
        E8 --> E12[📱 孩子报告列表<br/>page: results<br/>/report/child]:::portMiniApp
        E9 --> E12
    end

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

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

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

    subgraph 规划师端评估管理
        H4 --> I1[📋 家庭测评列表<br/>page: teacher/assessment<br/>/guide/assessment/families]:::portGuide
        I1 --> I2[📋 家庭详情<br/>page: teacher/assessment<br/>/family/:familyId]:::portGuide
        I2 --> I3[📋 启用/禁用<br/>page: teacher/assessment<br/>/family/:familyId/disable]:::portGuide
        I3 --> I4[📋 培训计划<br/>page: teacher/assessment<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` | 禁用家庭测评 | 📋规划师端 |

---

## 前端页面映射与 UI 交互说明

前端基于 uni-app (Vue 2, Options API) 微信小程序，页面路径均在 `pages/assessment/`、`pages/dan-assessment/`、`pages/growth/`、`pages/teacher/` 子包中。

| 流程阶段 | 前端页面 | 页面路径 | 交互说明 |
|---------|---------|---------|---------|
| **测评准备** | 申请测评 | `pages/assessment/apply.vue` | 用户进入页面后可浏览测评材料说明、选择成长规划师（可选，由系统安排或指定规划师）、选择测评类型、选择预约日期时间。底部「申请测评」按钮触发下单流程。页面上方有额度概览入口。 |
| | 我的额度 | `pages/assessment/quota.vue` | 展示已购买的测评任务模板及可用次数。每个额度卡片显示产品名称、使用进度条（已用/总数）、剩余次数、有效期。剩余次数 >0 且未过期时显示「预约测评」按钮。 |
| **下单与支付** | 确认订单 | `pages/assessment/order.vue` | 展示订单详情：任务模板名称、成长规划师、预约日期时间。费用信息包含测评费用、优惠金额、实付金额。微信支付/支付宝两种支付方式，底部按钮显示实付金额。 |
| **预约管理** | 执行进度 | `pages/assessment/execution.vue` | 用户端查看预约/执行记录。列表展示每条执行记录的状态和操作入口。状态包括：待确认、已确认、已完成。可在此页面确认服务完成。 |
| | 预约管理（规划师端） | `pages/teacher/appointments.vue` | 规划师端管理预约列表，顶部状态筛选（全部/待确认/已确认/已完成）。每个预约卡片展示孩子ID、预约日期时间、备注。操作按钮：待确认→「确认预约」，已确认→「录入结果」，待确认→「取消」。 |
| | 待办服务任务（规划师端） | `pages/teacher/service-tasks.vue` | 规划师端待办服务任务列表，展示任务ID、订单号、创建时间、评估师状态、规划师状态。点击进入任务详情，可完成任务执行或录入结果。 |
| **执行与确认** | 执行进度 | `pages/assessment/execution.vue` | 用户端执行详情页：展示评估师和规划师完成状态。双方均完成时显示「确认服务」按钮。用户确认后显示「评价」入口。`canConfirm` 计算属性判断：评估师完成 && （规划师不存在或已完成）&& 用户未确认。 |
| | 服务评价 | `pages/assessment/rating.vue` | 评价表单页：分别对评估师和规划师进行 1-5 星评分，每颗星有评价文本提示。可选输入文字评论，最长 500 字。支持仅评价其中一方。 |
| **结果录入** | 上传报告 | `pages/assessment/upload-report.vue` | 选择孩子 → 选择文件（PDF/JPG/PNG）→ 添加备注 → 提交。调用 `uploadAssessmentReport` API 上传，支持 async AI 解析。解析完成后在结果列表显示「确认上传」按钮。 |
| | DAN报告上传 | `pages/dan-assessment/report-upload.vue` | DAN 专用 PDF 上传页，两步流程：Phase 1 上传并预览 AI 解析结果 → Phase 2 确认入库。支持编辑草稿、废弃草稿、完成分析操作。完整的草稿生命周期管理。 |
| **结果查询** | 测评报告 | `pages/assessment/results.vue` | 双 Tab 视图：「我的报告」和「下级报告」（规划师视角）。报告卡片展示孩子姓名、测评日期、综合得分、分析报告预览。点击进入详情页，可查看各维度得分和成长建议。 |
| | 测评报告详情 | `pages/growth/assessment-result.vue` | 报告详情页：展示各维度得分（注意力/专注力/记忆力/逻辑思维）、综合得分、分析报告文本、成长建议。底部显示测评日期和测评ID。 |
| **规划师端** | 预约管理 | `pages/teacher/appointments.vue` | 同上「预约管理（规划师端）」 |
| | 待办服务任务 | `pages/teacher/service-tasks.vue` | 同上「待办服务任务（规划师端）」 |

### 核心交互模式

1. **家长端 → 规划师端流转**：家长提交申请 → 系统生成订单/预约 → 规划师在预约管理中确认 → 线下执行 → 规划师完成任务 → 家长确认并评价
2. **结果录入双通道**：规划师直接录入（结构化数据）或家长上传 PDF（AI 解析 → 草稿 → 家长确认入库）
3. **角色感知**：家长端页面 `pages/assessment/*` 仅家长角色可访问；规划师端 `pages/teacher/*` 仅 `role=teacher` 可访问
4. **数据驱动**：页面通过 `onLoad(options)` 接收参数（如 `executionId`、`resultId`），调用 `/api/*` 接口获取渲染数据