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

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 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

    %% ============ 角色 ============
    ROLE_PARENT(("👤 家长")):::actor
    ROLE_GUIDE(("📋 规划师/评估师")):::actor
    ROLE_AI(("⚙️ AI解析引擎")):::actor

    %% ================================================================
    %% 阶段一：测评准备
    %% ================================================================
    subgraph 阶段一[阶段一：测评准备]
        direction TB

        P1["🏠 家长端：测评申请页"]:::page
        P1 -->|"浏览测评材料"| A1["🔗 POST /api/dan-assessment/material/list"]:::api
        A1 -->|"—"| S1["⚙️ AssessmentService.getMaterialList()"]:::service
        S1 -->|"测评材料列表"| D1["📦 assessment_materials 表"]:::data

        P1 -->|"获取当前材料"| A2["🔗 POST /api/dan-assessment/material/active"]:::api
        A2 -->|"—"| S2["⚙️ AssessmentService.getActiveMaterial()"]:::service
        S2 -->|"当前启用材料"| D1

        P1 -->|"查询家庭测评状态"| A3["🔗 POST /api/dan-assessment/family/config"]:::api
        A3 -->|"familyId"| S3["⚙️ AssessmentService.getFamilyConfig()"]:::service
        S3 -->|"家庭测评配置(是否启用)"| D2["📦 family_assessment_config 表"]:::data

        D2 -->|"未启用"| P1a["🏠 启用家庭测评"]:::page
        P1a -->|"familyId, materialId"| A4["🔗 POST /api/dan-assessment/family/enable"]:::api
        A4 -->|"familyId, materialId, remindMonths"| S4["⚙️ AssessmentService.enableFamilyAssessment()"]:::service
        S4 -->|"写入启用配置"| D2

        P1 -->|"查看可用额度"| A5["🔗 POST /api/assessment/quota/my-list"]:::api
        A5 -->|"—"| S5["⚙️ AssessmentQuotaService.getMyQuotas()"]:::service
        S5 -->|"剩余次数, 有效期"| D3["📦 assessment_quotas 表"]:::data

        P1 -->|"额度详情"| A6["🔗 POST /api/assessment/quota/detail"]:::api
        A6 -->|"quotaId"| S6["⚙️ AssessmentQuotaService.getDetail()"]:::service
        S6 -->|"额度使用记录, 过期时间"| D3
    end

    %% ================================================================
    %% 阶段二：下单与支付
    %% ================================================================
    subgraph 阶段二[阶段二：下单与支付]
        D3 -->|"额度不足或需要新购"| P2["🏠 家长端：确认订单页"]:::page
        P2 -->|"选择评估师"| A7["🔗 POST /api/assessment/appointment/assessor-list"]:::api
        A7 -->|"—"| S7["⚙️ AssessmentAppointmentService.getAssessors()"]:::service
        S7 -->|"可选评估师列表"| D_USER["📦 users 表（按角色teacher）"]:::data

        P2 -->|"创建订单"| A8["🔗 POST /api/dan-assessment/order/create"]:::api
        A8 -->|"familyId, childId, guideId, packageId, totalPrice, discountAmount"| S8["⚙️ AssessmentOrderService.createOrder()"]:::service
        S8 -->|"写入订单, 状态=待支付"| D4["📦 assessment_orders 表"]:::data

        P2 -->|"支付订单"| A9["🔗 POST /api/dan-assessment/order/pay"]:::api
        A9 -->|"orderNo, payType"| S9["⚙️ AssessmentOrderService.payOrder()"]:::service
        S9 -->|"更新订单状态=已支付, 生成额度"| D4

        P2 -->|"查看订单详情"| A10["🔗 POST /api/dan-assessment/order/detail"]:::api
        A10 -->|"orderNo"| S10["⚙️ AssessmentOrderService.getByOrderNo()"]:::service
        S10 -->|"订单完整信息"| D4

        P2 -->|"取消订单"| A11["🔗 POST /api/dan-assessment/order/cancel"]:::api
        A11 -->|"orderNo"| S11["⚙️ AssessmentOrderService.cancelOrder()"]:::service
        S11 -->|"更新订单状态=已取消"| D4

        D4 -->|"支付成功"| A12["🔗 POST /api/dan-assessment/record/create"]:::api
        A12 -->|"familyId, childId, materialId"| S12["⚙️ AssessmentService.createRecord()"]:::service
        S12 -->|"创建测评记录, 进入预约流程"| D5["📦 assessment_records 表"]:::data
    end

    %% ================================================================
    %% 阶段三：预约管理
    %% ================================================================
    subgraph 阶段三[阶段三：预约管理]
        D5 -->|"测评记录"| P3["🏠 家长端：预约页"]:::page
        P3 -->|"创建预约"| A13["🔗 POST /api/assessment/appointment/create"]:::api
        A13 -->|"childId, quotaId, guideId/assessorId, appointmentDate, notes"| S13["⚙️ AssessmentAppointmentService.createAppointment()"]:::service
        S13 -->|"消耗额度, 创建预约+执行记录"| D6["📦 assessment_appointments + dan_assessment_executions 表"]:::data

        P3 -->|"我的预约列表"| A14["🔗 POST /api/assessment/appointment/my-list"]:::api
        A14 -->|"—"| S14["⚙️ AppointmentService.getByUserId()"]:::service
        S14 -->|"该用户所有预约"| D6

        D6 -->|"新预约, 状态=待确认"| P3a["📋 规划师端：预约管理页"]:::page
        P3a -->|"查看待确认预约"| A15["🔗 POST /api/assessment/appointment/guide-list"]:::api
        A15 -->|"userId(从token)"| S15["⚙️ AppointmentService.getByGuideId()"]:::service
        S15 -->|"规划师相关预约列表"| D6

        P3a -->|"确认预约"| A16["🔗 POST /api/assessment/appointment/confirm/{id}"]:::api
        A16 -->|"path: id (预约ID)"| S16["⚙️ AppointmentService.confirmAppointment()"]:::service
        S16 -->|"更新状态=已确认"| D6

        P3a -->|"完成预约(线下执行后)"| A17["🔗 POST /api/dan-assessment/appointment/complete"]:::api
        A17 -->|"id, teacherId"| S17["⚙️ AppointmentService.completeAppointment()"]:::service
        S17 -->|"更新状态=已完成"| D6
    end

    %% ================================================================
    %% 阶段四：执行与确认
    %% ================================================================
    subgraph 阶段四[阶段四：执行与确认]
        D6 -->|"执行记录, 状态=待执行"| P4["📋 规划师端：待办任务页"]:::page
        P4 -->|"查看待执行任务"| A18["🔗 POST /api/dan-execution/guide/my-tasks"]:::api
        A18 -->|"plannerId"| S18["⚙️ DanAssessmentExecutionService.getByPlannerId()"]:::service
        S18 -->|"规划师待执行任务列表"| D7["📦 dan_assessment_executions 表"]:::data

        P4 -->|"完成服务"| A19["🔗 POST /api/dan-execution/complete"]:::api
        A19 -->|"executionId, notes"| S19["⚙️ DanAssessmentExecutionService.completeExecution()"]:::service
        S19 -->|"更新状态=已执行"| D7

        D7 -->|"状态=已执行"| P4a["🏠 家长端：执行进度页"]:::page
        P4a -->|"用户确认服务"| A20["🔗 POST /api/dan-execution/confirm"]:::api
        A20 -->|"executionId"| S20["⚙️ DanAssessmentExecutionService.confirmExecution()"]:::service
        S20 -->|"更新状态=已确认, 更新结算"| D7

        P4a -->|"用户评价"| A21["🔗 POST /api/dan-execution/rate"]:::api
        A21 -->|"executionId, assessorRating, plannerRating, assessorComment, plannerComment"| S21["⚙️ DanAssessmentExecutionService.rateService()"]:::service
        S21 -->|"写入评价记录"| D8["📦 service_ratings 表"]:::data

        P4a -->|"查看执行详情"| A22["🔗 POST /api/dan-execution/detail"]:::api
        A22 -->|"executionId"| S22["⚙️ DanAssessmentExecutionService.getExecutionDetail()"]:::service
        S22 -->|"执行详情(含结算)"| D7

        P4a -->|"执行记录列表"| A23["🔗 POST /api/dan-execution/my-list"]:::api
        A23 -->|"familyId"| S23["⚙️ DanAssessmentExecutionService.getByFamilyId()"]:::service
        S23 -->|"该家庭所有执行记录"| D7
    end

    %% ================================================================
    %% 阶段五：结果录入
    %% ================================================================
    subgraph 阶段五[阶段五：结果录入]
        D7 -->|"待录入结果"| P5_choice{"录入方式"}:::page

        P5_choice -->|"规划师录入"| P5a["📋 规划师端：录入测评结果"]:::page
        P5a -->|"提交结果"| A24["🔗 POST /api/dan-assessment/result/record"]:::api
        A24 -->|"DanAssessmentResult(含维度得分, 分析报告)"| S24["⚙️ AssessmentService.recordResult()"]:::service
        S24 -->|"写入结果, 状态=completed"| D9["📦 dan_assessment_results 表"]:::data

        P5_choice -->|"家长上传PDF"| P5b["🏠 家长端：上传报告页"]:::page
        P5b -->|"上传PDF"| A25["🔗 POST /api/dan-assessment/result/upload"]:::api
        A25 -->|"file(Multipart), childId, notes"| S25["⚙️ FileStorageService.store() + ReportParseService.parseReport()"]:::service
        S25 -->|"存储文件, 异步AI解析, 状态=draft"| D9

        P5_choice -->|"DAN PDF上传"| P5c["🏠 家长端：DAN报告上传页"]:::page
        P5c -->|"Phase1上传+预览"| A26["🔗 POST /api/dan-report/upload"]:::api
        A26 -->|"file(Multipart), dimension, memberId"| S26["⚙️ DanReportUploadService.uploadAndParse()"]:::service
        S26 -->|"上传+AI解析, 返回草稿"| D10["📦 dan_report_uploads 表"]:::data

        D10 -->|"草稿ID"| P5d["🏠 编辑DAN报告草稿"]:::page
        P5d -->|"编辑草稿"| A27["🔗 POST /api/dan-report/{id}/edit"]:::api
        A27 -->|"path: id, DanReportEditDTO"| S27["⚙️ DanReportUploadService.editDraft()"]:::service
        S27 -->|"更新草稿内容"| D10

        P5d -->|"确认入库(Phase2)"| A28["🔗 POST /api/dan-report/{id}/confirm"]:::api
        A28 -->|"path: id, childName, assessmentDate"| S28["⚙️ DanReportUploadService.confirmUpload()"]:::service
        S28 -->|"状态=confirmed, 写入最终结果"| D9

        P5d -->|"废弃草稿"| A29["🔗 POST /api/dan-report/{id}/discard"]:::api
        A29 -->|"path: id"| S29["⚙️ DanReportUploadService.discardUpload()"]:::service
        S29 -->|"状态=discarded"| D10

        D9 -->|"结果ID"| P5e["📋 规划师端：结构化分析"]:::page
        P5e -->|"获取结构化分析"| A30["🔗 POST /api/dan-assessment/results/{id}/structured"]:::api
        A30 -->|"path: id"| S30["⚙️ 查询+组装结构化分析"]:::service
        S30 -->|"结构化数据(维度得分, 分析报告)"| D9

        P5e -->|"保存指导意见"| A31["🔗 POST /api/dan-assessment/result/{resultId}/guidance/save"]:::api
        A31 -->|"path: resultId, items: [GrowthGuidance]"| S31["⚙️ GrowthGuidanceService.saveGuidances()"]:::service
        S31 -->|"批量写入指导意见"| D11["📦 growth_guidances 表"]:::data

        P5e -->|"查看指导意见"| A32["🔗 POST /api/dan-assessment/result/{resultId}/guidance"]:::api
        A32 -->|"path: resultId"| S32["⚙️ GrowthGuidanceService.getByResultId()"]:::service
        S32 -->|"指导意见列表"| D11

        P5e -->|"确认上传(规划师确认家长上传)"| A33["🔗 POST /api/dan-assessment/result/{resultId}/confirm-upload"]:::api
        A33 -->|"path: resultId, overallScore"| S33["⚙️ 更新状态=completed, 自动生成方案"]:::service
        S33 -->|"状态=completed, 自动生成测评方案"| D9
    end

    %% ================================================================
    %% 阶段六：结果查询与对比
    %% ================================================================
    subgraph 阶段六[阶段六：结果查询与对比]
        D9 -->|"已完成的测评结果"| P6["🏠 家长端：测评报告页"]:::page
        P6 -->|"最新结果"| A34["🔗 POST /api/assessment/latest-result"]:::api
        A34 -->|"childId"| S34["⚙️ CognitiveService.getChildLatestResult()"]:::service
        S34 -->|"最新一条completed结果"| D9

        P6 -->|"历史记录"| A35["🔗 POST /api/assessment/history"]:::api
        A35 -->|"childId, size"| S35["⚙️ 查询历史completed结果列表"]:::service
        S35 -->|"测评历史(日期+综合得分)"| D9

        P6 -->|"选择对比方式"| P6c{"孩子整体 / 单维度 / 家庭 / 综合分析"}:::page

        P6c -->|"孩子首次vs最新"| A36["🔗 POST /api/assessment/compare/by-child"]:::api
        A36 -->|"childId"| S36["⚙️ AssessmentComparisonService.compareByChild()"]:::service
        S36 -->|"首次/最新结果对比数据"| D9

        P6c -->|"单维度变化"| A37["🔗 POST /api/assessment/compare/by-child-dimension"]:::api
        A37 -->|"childId, dimension"| S37["⚙️ AssessmentComparisonService.compareByDimension()"]:::service
        S37 -->|"指定维度历年得分对比"| D9

        P6c -->|"家庭对比"| A38["🔗 POST /api/assessment/compare/by-family"]:::api
        A38 -->|"familyId"| S38["⚙️ AssessmentComparisonService.compareByFamily()"]:::service
        S38 -->|"家庭内各成员结果对比"| D9

        P6c -->|"综合分析"| A39["🔗 POST /api/assessment/compare/narrative"]:::api
        A39 -->|"childId"| S39["⚙️ AssessmentComparisonService.narrativeAnalysis()"]:::service
        S39 -->|"综合文本分析报告"| D9

        P6 -->|"我的报告列表"| A40["🔗 POST /api/assessment/my-results"]:::api
        A40 -->|"userId"| S40["⚙️ AssessmentService.getAccessibleResults()"]:::service
        S40 -->|"可访问的测评报告列表"| D9

        P6c -->|"结果详情"| A41["🔗 POST /api/dan-assessment/result/{id}"]:::api
        A41 -->|"path: id"| S41["⚙️ AssessmentService.getByAppointmentId()"]:::service
        S41 -->|"单条测评结果完整数据"| D9
    end

    %% ================================================================
    %% 阶段七：家长端自评
    %% ================================================================
    subgraph 阶段七[阶段七：家长端自评]
        P6 -->|"创建自评"| P7["🏠 家长端：自评页"]:::page
        P7 -->|"创建自评任务"| A42["🔗 POST /api/parent/assessment/create"]:::api
        A42 -->|"userId(从token)"| S42["⚙️ AssessmentService.createRecord()"]:::service
        S42 -->|"创建自评记录, 状态=进行中"| D5

        P7 -->|"当前进度"| A43["🔗 POST /api/parent/assessment/current"]:::api
        A43 -->|"userId(从token)"| S43["⚙️ AssessmentService.getFamilyConfig() + getActiveMaterial()"]:::service
        S43 -->|"当前测评配置+材料信息"| D2

        P7 -->|"提交自评"| A44["🔗 POST /api/parent/assessment/complete/{recordId}"]:::api
        A44 -->|"path: recordId"| S44["⚙️ AssessmentService.completeRecord()"]:::service
        S44 -->|"状态=已完成"| D5

        P7 -->|"自评记录列表"| A45["🔗 POST /api/parent/assessment/records"]:::api
        A45 -->|"userId(从token)"| S45["⚙️ AssessmentService.getFamilyRecords()"]:::service
        S45 -->|"家庭所有测评记录"| D5
    end

    %% ================================================================
    %% 阶段八：规划师评估管理
    %% ================================================================
    subgraph 阶段八[阶段八：规划师评估管理]
        P3a -->|"管理家庭测评"| P8["📋 规划师端：家庭测评管理页"]:::page
        P8 -->|"家庭列表"| A46["🔗 POST /api/guide/assessment/families"]:::api
        A46 -->|"teacherId(从token)"| S46["⚙️ AssessmentService.getFamiliesByTeacher()"]:::service
        S46 -->|"该规划师管理的家庭测评配置"| D2

        P8 -->|"家庭详情"| A47["🔗 POST /api/guide/assessment/family/{familyId}"]:::api
        A47 -->|"path: familyId"| S47["⚙️ AssessmentService.getFamilyConfig()"]:::service
        S47 -->|"指定家庭测评配置详情"| D2

        P8 -->|"启用/禁用"| A48["🔗 POST /api/guide/assessment/family/{familyId}/disable"]:::api
        A48 -->|"path: familyId"| S48["⚙️ AssessmentService.disableFamilyAssessment()"]:::service
        S48 -->|"更新isEnabled=0"| D2

        P8 -->|"获取下级报告"| A49["🔗 POST /api/assessment/child-results"]:::api
        A49 -->|"userId"| S49["⚙️ AssessmentService.getAccessibleResults()"]:::service
        S49 -->|"下级规划师的测评报告"| D9

        P8 -->|"测评材料列表"| A50["🔗 POST /api/guide/assessment/materials"]:::api
        A50 -->|"—"| S50["⚙️ AssessmentService.getMaterialList()"]:::service
        S50 -->|"可用测评材料"| D1
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    ROLE_PARENT -.- P1
    ROLE_PARENT -.- P2
    ROLE_PARENT -.- P3
    ROLE_PARENT -.- P4a
    ROLE_PARENT -.- P5b
    ROLE_PARENT -.- P5c
    ROLE_PARENT -.- P6
    ROLE_PARENT -.- P7
    ROLE_GUIDE -.- P3a
    ROLE_GUIDE -.- P4
    ROLE_GUIDE -.- P5a
    ROLE_GUIDE -.- P5e
    ROLE_GUIDE -.- P8
    ROLE_AI -.- S26
    ROLE_AI -.- S25
```

## 端点明细

### 测评准备

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/dan-assessment/material/list` | 浏览测评材料 | 📱小程序 | — | `List<AssessmentMaterial>` |
| `POST /api/dan-assessment/material/active` | 获取当前启用材料 | 📱小程序 | — | `AssessmentMaterial` |
| `POST /api/dan-assessment/family/enable` | 启用家庭测评 | 📱小程序 | `{familyId, materialId, remindMonths}` | `{success}` |
| `POST /api/dan-assessment/family/disable` | 禁用家庭测评 | 📱小程序 | `{familyId}` | `{success}` |
| `POST /api/dan-assessment/family/config` | 获取家庭测评配置 | 📱小程序 | `familyId(Param)` | `FamilyAssessmentConfig` |
| `POST /api/dan-assessment/points-config` | 获取积分配置 | 📱小程序 | — | `AssessmentPointsConfig` |
| `POST /api/assessment/quota/my-list` | 我的可用额度列表 | 📱小程序 | — | `List<AssessmentQuotaVO>` |
| `POST /api/assessment/quota/detail` | 额度详情 | 📱小程序 | `{quotaId}` | `AssessmentQuotaVO` |

### 下单与支付

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/dan-assessment/order/create` | 创建测评订单 | 📱小程序 | `{familyId, userId, childId, guideId, packageId, guideName, packageName, totalPrice, discountAmount}` | `AssessmentOrder` |
| `POST /api/dan-assessment/order/pay` | 支付订单 | 📱小程序 | `{orderNo, payType}` | `{success}` |
| `POST /api/dan-assessment/order/detail` | 订单详情 | 📱小程序 | `orderNo(Param)` | `AssessmentOrder` |
| `POST /api/dan-assessment/order/family` | 家庭订单列表 | 📱小程序 | `familyId(Param)` | `List<AssessmentOrder>` |
| `POST /api/dan-assessment/order/cancel` | 取消订单 | 📱小程序 | `{orderNo}` | `{success}` |
| `POST /api/dan-assessment/record/create` | 创建测评记录 | 📱小程序 | `{familyId, childId, materialId}` | `AssessmentRecord` |
| `POST /api/dan-assessment/record/complete` | 完成测评记录 | 📱小程序 | `{recordId}` | `{success}` |

### 预约管理

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/dan-assessment/appointment/create` | 创建测评预约 | 📱小程序 | `{userId, childId, guideId, packageId, appointmentDate, appointmentTime, notes}` | `AssessmentAppointment` |
| `POST /api/dan-assessment/appointment/confirm` | 确认预约 | 📋规划师端 | `{id, teacherId}` | `{success}` |
| `POST /api/dan-assessment/appointment/complete` | 完成预约 | 📋规划师端 | `{id, teacherId}` | `{success}` |
| `POST /api/dan-assessment/appointment/cancel` | 取消预约 | 📱小程序 | `{id}` | `{success}` |
| `POST /api/dan-assessment/appointment/user` | 用户预约列表 | 📱小程序 | `{userId}` | `[AppointmentVO]` |
| `POST /api/dan-assessment/appointment/guide` | 规划师预约列表 | 📋规划师端 | `guideId(Param)` | `List<AssessmentAppointment>` |
| `POST /api/assessment/appointment/create` | 创建评估预约（含执行记录） | 📱小程序 | `{childId, quotaId, guideId/assessorId, appointmentDate, notes}` | `{appointmentId, executionId, quotaId}` |
| `POST /api/assessment/appointment/confirm/{id}` | 确认评估预约 | 📋规划师端 | path: `id` | `{success}` |
| `POST /api/assessment/appointment/cancel/{id}` | 取消评估预约 | 📱小程序 | path: `id` | `{success}` |
| `POST /api/assessment/appointment/my-list` | 我的预约列表 | 📱小程序 | — | `[AppointmentVO]` |
| `POST /api/assessment/appointment/guide-list` | 规划师预约列表 | 📋规划师端 | token: `role=teacher` | `[AppointmentVO]` |
| `POST /api/assessment/appointment/assessor-list` | 评估师列表 | 📱小程序 | — | `[AppointmentVO]` |

### 执行与确认

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/dan-execution/complete` | 规划师完成服务 | 📋规划师端 | `{executionId, notes}` | `{success}` |
| `POST /api/dan-execution/confirm` | 用户确认服务完成 | 📱小程序 | `{executionId}` | `{success}` |
| `POST /api/dan-execution/rate` | 用户评价服务 | 📱小程序 | `{executionId, assessorRating, plannerRating, ...}` | `ServiceRatingDTO` |
| `POST /api/dan-execution/detail` | 执行详情（含结算） | 📱📋 | `{executionId}` | `ExecutionDetailResponse` |
| `POST /api/dan-execution/my-list` | 用户执行记录 | 📱小程序 | `{familyId}` | `List<DanAssessmentExecution>` |
| `POST /api/dan-execution/guide/my-tasks` | 规划师待执行任务 | 📋规划师端 | `{plannerId}` | `List<DanAssessmentExecution>` |
| `POST /api/dan-execution/by-order` | 按订单查询执行 | 📱📋 | `{orderId}` | `DanAssessmentExecution` |

### 结果录入

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/dan-assessment/result/record` | 记录测评结果 | 📋规划师端 | `DanAssessmentResult(含维度得分, 分析报告)` | `DanAssessmentResult` |
| `POST /api/dan-assessment/result/upload` | 家长上传报告 | 📱小程序 | `file(Multipart), childId, notes` | `DanAssessmentResult(draft)` |
| `POST /api/dan-assessment/result/{id}` | 获取结果详情 | 📱📋 | path: `id` | `DanAssessmentResult` |
| `POST /api/dan-assessment/result/{resultId}/confirm-upload` | 规划师确认上传 | 📋规划师端 | path: `resultId`, `{overallScore}` | `DanAssessmentResult` |
| `POST /api/dan-assessment/result/{resultId}/guidance` | 获取指导意见 | 📱小程序 | path: `resultId` | `List<GrowthGuidance>` |
| `POST /api/dan-assessment/result/{resultId}/guidance/save` | 保存指导意见 | 📋规划师端 | path: `resultId`, `{items: [GrowthGuidance]}` | `List<GrowthGuidance>` |
| `POST /api/dan-assessment/results/{id}/structured` | 结构化分析 | ⚙️系统自动 | path: `id` | `{resultId, childName, assessmentDate, structuredAnalysis}` |
| `POST /api/dan-assessment/my-results` | 我的测评报告列表 | 📱📋 | `{userId}` | `List<DanAssessmentResult>` |
| `POST /api/dan-assessment/child-results` | 下级规划师报告 | 📋规划师端 | `{userId}` | `List<DanAssessmentResult>` |
| `POST /api/dan-assessment/record/family` | 家庭测评记录列表 | 📱小程序 | `familyId(Param)` | `List<AssessmentRecord>` |
| `POST /api/dan-assessment/record/current` | 当前测评 | 📱小程序 | `familyId(Param)` | `AssessmentRecord` |

### DAN报告上传（DanReportController）

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/dan-report/upload` | Phase1上传+AI解析 | 📱小程序 | `file(Multipart), dimension, memberId` | `{uploadId, parsedItems, ...}` |
| `POST /api/dan-report/{id}/edit` | 编辑草稿 | 📱小程序 | path: `id`, `DanReportEditDTO` | `DanReportUploadVO` |
| `POST /api/dan-report/{id}/confirm` | Phase2确认入库 | 📱小程序 | path: `id`, `{childName, assessmentDate}` | `DanReportUploadVO` |
| `POST /api/dan-report/{id}/discard` | 废弃草稿 | 📱小程序 | path: `id` | `{success}` |
| `POST /api/dan-report/{id}/complete-analysis` | 完成分析 | 📱小程序 | path: `id` | `{success}` |
| `POST /api/dan-report/{id}` | 报告详情 | 📱📋 | path: `id` | `DanReportUploadVO` |
| `POST /api/dan-report/list` | 报告列表 | 📱📋 | `{memberId, dimension}` | `List<DanReportUploadVO>` |

### 结果查询与对比

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/assessment/latest-result` | 孩子最新测评结果 | 📱小程序 | `{childId}` | `AssessmentResultDTO` |
| `POST /api/assessment/history` | 测评历史记录 | 📱小程序 | `{childId, size}` | `List<AssessmentHistoryItemDTO>` |
| `POST /api/assessment/my-results` | 我的报告列表 | 📱📋 | token: `userId` | `List<DanAssessmentResult>` |
| `POST /api/assessment/child-results` | 下级规划师报告 | 📋规划师端 | token: role检查 | `List<DanAssessmentResult>` |
| `POST /api/assessment/compare/by-child` | 孩子首次vs最新对比 | 📱小程序 | `{childId}` | `{first, latest, changes}` |
| `POST /api/assessment/compare/by-child-dimension` | 孩子单维度变化对比 | 📱小程序 | `{childId, dimension}` | `{dimension, trend, dataPoints}` |
| `POST /api/assessment/compare/by-family` | 家庭对比分析 | 📱小程序 | `{familyId}` | `{members: [{childId, scores}]}` |
| `POST /api/assessment/compare/narrative` | 综合分析报告 | 📱小程序 | `{childId}` | `{narrative, suggestions}` |

### 家长端自评

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/parent/assessment/create` | 创建家长自评 | 📱小程序 | token: `userId` | `AssessmentRecord` |
| `POST /api/parent/assessment/current` | 当前自评进度 | 📱小程序 | token: `userId` | `{configId, title, content, ...}` |
| `POST /api/parent/assessment/complete/{recordId}` | 提交自评 | 📱小程序 | path: `recordId` | `{success}` |
| `POST /api/parent/assessment/records` | 自评记录 | 📱小程序 | token: `userId` | `List<AssessmentRecord>` |

### 规划师端评估管理

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/guide/assessment/families` | 家庭测评列表 | 📋规划师端 | token: `userId` | `[{familyId, isEnabled, materialTitle, ...}]` |
| `POST /api/guide/assessment/family/{familyId}` | 家庭测评详情 | 📋规划师端 | path: `familyId` | `FamilyAssessmentConfig+材料信息` |
| `POST /api/guide/assessment/family/{familyId}/disable` | 禁用家庭测评 | 📋规划师端 | path: `familyId` | `{success}` |
| `POST /api/guide/assessment/materials` | 可用测评材料 | 📋规划师端 | — | `List<AssessmentMaterial>` |
| `POST /api/guide/assessment/family/enable` | 为家庭启用测评 | 📋规划师端 | `{familyId, materialId, remindMonths}` | `{success}` |

## 完整性分析

| # | 维度 | 评估 | 说明 |
|---|------|------|------|
| 1 | **流程完整性** | ✅ 完整 | 覆盖测评准备、下单支付、预约管理、执行确认、结果录入（3种方式）、结果查询对比、家长自评、规划师管理8个阶段，测评全生命周期闭环 |
| 2 | **异常路径** | ⚠️ 部分覆盖 | 订单取消、预约取消、草稿废弃均已覆盖；额度不足时引导重新购买已覆盖；支付失败后重新支付未在图中展开（逻辑在Service层） |
| 3 | **端点覆盖** | ✅ 完整 | 50个端点全部映射到流程图中，覆盖DanAssessmentController、AssessmentAppointmentController、DanAssessmentExecutionController、AssessmentReportController、AssessmentResultController、AssessmentComparisonController、DanReportController、ParentAssessmentController、GuideAssessmentController、AssessmentQuotaController |
| 4 | **角色覆盖** | ✅ 完整 | 家长(申请/支付/确认/评价/查看)、规划师/评估师(确认预约/执行/录入结果/管理)、AI引擎(自动解析)三种角色均覆盖；管理员不在本图范围 |
| 5 | **数据实体** | ✅ 完整 | assessment_materials、family_assessment_config、assessment_orders、assessment_quotas、assessment_records、assessment_appointments、dan_assessment_executions、dan_assessment_results、dan_report_uploads、growth_guidances、service_ratings均在图中映射 |
| 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller中的`@PostMapping`匹配；DAN报告上传有Phase1→Phase2两阶段流程（DanReportController独立化后与DanAssessmentController兼容并存） |