# 用户使用流程图 — 成长档案

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

## 核心概念

成长档案、成长计划、测评报告三者之间**不是一一对应关系**：

- **成长档案** (GrowthRecord)：孩子成长过程中的数据快照，可来自手动录入、PDF报告解析、外部系统同步
- **成长计划** (GrowthPlan)：由规划师基于测评分析制定的孩子成长方案，可引用某个测评报告的分析结果
- **测评报告** (DanAssessmentResult)：专业测评的结果数据，可被成长档案和成长计划引用

> 一个孩子可以有多个成长档案、多个成长计划、多份测评报告。它们通过 `assessmentId` 相互引用，但不存在强制的一对一链式关系。

```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
    C0(("👶 孩子")):::actor
    D0(("⚙️ 系统/第三方")):::actor

    %% ================================================================
    %% 阶段一：数据采集 — 创建成长档案
    %% ================================================================
    subgraph 阶段一[阶段一：数据采集]
        direction TB

        P1["🏠 家长端：成长档案页<br>选择创建方式"]:::page

        P1 -->|手动录入| P1a["🏠 家长端：录入表单<br>childId, height, weight,<br>school, grade, photo"]:::page
        P1a --> A1["🔗 POST /api/growth/record/create<br>body: {childId, height, weight,<br>school, grade, ...}"]:::api
        A1 --> S1["⚙️ GrowthRecordService<br>.createRecord()"]:::service
        S1 --> D1["📦 growth_records 表<br>写入一条记录"]:::data

        P1 -->|上传PDF报告| P1b["🏠 家长端：选择PDF文件<br>拍照/相册选择"]:::page
        P1b --> A1a["🔗 POST /api/growth/record/upload-and-parse<br>body: multipart file"]:::api
        A1a --> S1a["⚙️ PDF解析引擎<br>Stage1: OCR + 结构化提取"]:::service
        S1a --> D1a["📦 ParsedReport<br>{indicators, scores,<br>reportDate, ...}"]:::data
        D1a --> A1b["🔗 POST /api/growth/record/check-duplicate<br>body: {fileHash}"]:::api
        A1b --> S1b["⚙️ 哈希去重校验"]:::service
        S1b -->|重复| D1b["📦 返回现有记录ID"]:::data
        S1b -->|新记录| A1c["🔗 POST /api/growth/record/create-from-upload<br>body: {parsedReport}"]:::api
        A1c --> S1c["⚙️ GrowthRecordService<br>.createFromUpload()"]:::service
        S1c --> D1["📦 growth_records 表"]

        P1 -->|创建档案+购买测评| P1c["🏠 家长端：选择测评套餐<br>guideId, packageId"]:::page
        P1c --> A1d["🔗 POST /api/growth/record/create-with-order<br>body: {childId, guideId,<br>packageId, ...}"]:::api
        A1d --> S1d["⚙️ 创建档案 + 创建测评订单<br>GrowthRecordService<br>+ AssessmentOrderService"]:::service
        S1d --> D1c["📦 growth_records 表<br>+ assessment_orders 表"]:::data
    end

    %% ================================================================
    %% 阶段二：补充材料与外部同步
    %% ================================================================
    subgraph 阶段二[阶段二：补充材料与外部同步]
        D1 --> P2["🏠 家长端：档案详情页"]:::page
        P2 -->|补充材料| P2a["🏠 家长端：补充记录表单"]:::page
        P2a --> A2["🔗 POST /api/growth/record/supplement<br>body: {recordId, <br>supplementType, content}"]:::api
        A2 --> S2["⚙️ GrowthRecordService<br>.addSupplement()"]:::service
        S2 --> D2["📦 growth_record_supplements 表"]:::data

        P2 -->|外部同步| P2b["🏠 家长端：选择外部系统"]:::page
        P2b --> A2a["🔗 POST /api/growth/external/sync<br>body: {childId, source,<br>credentials}"]:::api
        A2a --> S2a["⚙️ 外部数据同步引擎<br>对接第三方API"]:::service
        S2a --> D2a["📦 融合后的数据写入<br>growth_records 表"]:::data
    end

    %% ================================================================
    %% 阶段三：分析评估 — 查看测评结果
    %% ================================================================
    subgraph 阶段三[阶段三：分析评估]
        D1 --> P3["🏠 家长端：档案列表页<br>GET /api/growth/record/list"]:::page
        P3 --> P3a["🏠 家长端：档案详情<br>GET /api/growth/record/{id}"]:::page
        P3a --> A3["🔗 GET /api/growth/record/{id}<br>返回: GrowthRecord +<br>关联的 assessmentSummary"]:::api
        A3 --> S3["⚙️ GrowthRecordService<br>.getRecordDetail()<br>关联查询测评结果"]:::service
        S3 --> D3["📦 GrowthRecord +<br>DanAssessmentResult<br>(通过 assessmentId 关联)"]:::data

        D3 --> P3b["📋 规划师端：测评分析页<br>查看孩子的测评报告"]:::page
        P3b --> A3a["🔗 GET /api/dan-assessment/my-results<br>或 /api/guide/assessment/child/{id}"]:::api
        A3a --> S3a["⚙️ AssessmentService<br>.getChildResults()"]:::service
        S3a --> D3a["📦 DanAssessmentResult<br>{dimensionScores,<br>structuredAnalysis, ...}"]:::data
    end

    %% ================================================================
    %% 阶段四：制定成长计划
    %% ================================================================
    subgraph 阶段四[阶段四：制定成长计划]
        D3a --> P4["📋 规划师端：制定成长计划页<br>基于测评分析结果"]:::page
        P4 --> A4["🔗 POST /api/growth/plan/create<br>body: {childId, assessmentId,<br>planTitle, planContent,<br>durationMonths, startDate}"]:::api
        A4 --> S4["⚙️ GrowthPlanService<br>.createPlan()<br>设置 status='active'"]:::service
        S4 --> D4["📦 growth_plans 表<br>一条计划记录"]:::data

        D4 --> P4a["📋 规划师端：查看孩子计划列表<br>GET /api/growth/plan/child/{childId}"]:::page
        P4a --> A4a["🔗 GET /api/growth/plan/child/{childId}<br>返回: GrowthPlan[]"]:::api
        A4a --> S4a["⚙️ GrowthPlanService<br>.getByChildId()"]:::service

        P4 -->|更新计划| P4b["📋 规划师端：编辑计划"]:::page
        P4b --> A4b["🔗 POST /api/growth/plan/update<br>body: {id, planTitle,<br>planContent, ...}"]:::api
        A4b --> S4b["⚙️ GrowthPlanService<br>.updatePlan()"]:::service
        S4b --> D4

        D4 --> P4c["📱 家长端：查看计划<br>GET /api/growth/plan/child/{childId}"]:::page
    end

    %% ================================================================
    %% 阶段五：执行计划 + 记录成长
    %% ================================================================
    subgraph 阶段五[阶段五：执行计划与记录成长]
        D4 --> P5["📱 家长端：查看活跃计划<br>GET /api/growth/plan/child/{childId}/active"]:::page
        P5 --> P5a["🏠 家长端：执行计划任务<br>按计划内容进行日常活动"]:::page
        P5a -->|执行中记录| P5b["📱 家长/孩子端：创建成长记录<br>记录身高/体重/学业/照片"]:::page
        P5b --> A5["🔗 POST /api/health/growth/create<br>body: {childId, recordTitle,<br>height, weight, ...}"]:::api
        A5 --> S5["⚙️ GrowthRecordService<br>.createRecord()<br>生长记录（非档案）"]:::service
        S5 --> D5["📦 health_growth_records 表<br>日常生长记录"]:::data

        P5a -->|定期更新档案| P5c["📱 家长端：更新成长档案<br>定期补充最新数据"]:::page
        P5c --> A5a["🔗 POST /api/growth/record/create<br>body: {childId, assessmentSummary,<br>growthSuggestions, ...}"]:::api
        A5a --> S5a["⚙️ GrowthRecordService<br>.createRecord()"]:::service
        S5a --> D1["📦 growth_records 表"]
    end

    %% ================================================================
    %% 阶段六：复盘与评估
    %% ================================================================
    subgraph 阶段六[阶段六：复盘与评估]
        D5 --> P6["📋 规划师端：查看执行记录<br>比较计划目标 vs 实际数据"]:::page
        P6 --> A6["🔗 POST /api/growth/plan/{id}/review<br>body: {reviewNotes}"]:::api
        A6 --> S6["⚙️ GrowthPlanService<br>.reviewPlan()<br>reviewCount++"]:::service
        S6 --> D6["📦 growth_plans 表<br>reviewCount 更新"]:::data

        D6 --> P6a["📋 规划师端：调整计划"]:::page
        P6a --> A6a["🔗 POST /api/growth/plan/update<br>基于复盘结果调整<br>计划内容/时长"]:::api
        A6a --> S6a["⚙️ GrowthPlanService<br>.updatePlan()"]:::service
        S6a --> D4

        D6 --> P6b["📱 家长端：查看复盘结果"]:::page
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    A0 -.- P1
    A0 -.- P2
    A0 -.- P3
    A0 -.- P4c
    A0 -.- P5
    A0 -.- P6b
    B0 -.- P3b
    B0 -.- P4
    B0 -.- P6
    C0 -.- P5a
    D0 -.- S1a
    D0 -.- S2a
```

## 端点明细

### 成长档案

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/growth/record/create` | 创建成长档案 | 📱小程序 | `{childId, height, weight, school, grade, assessmentSummary, ...}` | `GrowthRecord` |
| `POST /api/growth/record/create-with-order` | 创建档案并购买测评 | 📱小程序 | `{childId, guideId, packageId, ...}` | `GrowthRecord + AssessmentOrder` |
| `POST /api/growth/record/upload-and-parse` | 上传并解析PDF | 📱小程序 | `multipart file` | `ParsedReport` |
| `POST /api/growth/record/create-from-upload` | 从解析结果创建档案 | 📱小程序 | `{parsedReport}` | `GrowthRecord` |
| `POST /api/growth/record/check-duplicate` | 检查重复记录 | ⚙️系统 | `{fileHash}` | `{isDuplicate, existingId}` |
| `GET /api/growth/record/list` | 获取家长档案列表 | 📱小程序 | `{page, size}` | `Page<GrowthRecord>` |
| `GET /api/growth/record/child/{childId}` | 获取指定孩子档案 | 📱小程序 | path: `childId` | `List<GrowthRecord>` |
| `GET /api/growth/record/child-records` | 获取孩子的成长档案 | 📱小程序 | `{childId}` | `List<GrowthRecord>` |
| `GET /api/growth/record/{id}` | 获取档案详情 | 📱小程序 | path: `id` | `GrowthRecord + 关联数据` |
| `DELETE /api/growth/record/{id}/delete` | 删除成长档案 | 📱小程序 | path: `id` | `boolean` |
| `POST /api/growth/record/supplement` | 创建补充记录 | 📱小程序 | `{recordId, supplementType, content}` | `Supplement` |
| `GET /api/growth/record/{id}/supplements` | 获取补充记录 | 📱小程序 | path: `id` | `List<Supplement>` |
| `POST /api/growth/external/sync` | 外部系统同步 | 📱小程序 | `{childId, source, credentials}` | `GrowthRecord` |

### 生长记录（日常追踪）

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `GET /api/health/growth/list` | 获取生长记录列表 | 📱小程序 | `{childId, page, size}` | `Page<HealthGrowthRecord>` |
| `GET /api/health/growth/detail` | 获取生长记录详情 | 📱小程序 | `{id}` | `HealthGrowthRecord` |
| `POST /api/health/growth/create` | 创建生长记录 | 📱小程序 | `{childId, recordTitle, height, weight, ...}` | `HealthGrowthRecord` |
| `POST /api/health/growth/update` | 更新生长记录 | 📱小程序 | `{id, ...}` | `boolean` |
| `DELETE /api/health/growth/delete` | 删除生长记录 | 📱小程序 | `{id}` | `boolean` |

### 成长计划

| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
|------|------|------|---------|---------|
| `POST /api/growth/plan/create` | 创建成长计划 | 📋规划师端 | `{childId, assessmentId, planTitle, planContent, durationMonths, startDate}` | `GrowthPlan` |
| `POST /api/growth/plan/update` | 更新成长计划 | 📋规划师端 | `{id, planTitle, planContent, durationMonths, ...}` | `boolean` |
| `GET /api/growth/plan/child/{childId}` | 查看孩子计划列表 | 📱📋 | path: `childId` | `List<GrowthPlan>` |
| `GET /api/growth/plan/child/{childId}/active` | 获取当前活跃计划 | 📱📋 | path: `childId` | `GrowthPlan` |
| `GET /api/growth/plan/{id}` | 查看计划详情 | 📱📋 | path: `id` | `GrowthPlan` |
| `POST /api/growth/plan/{id}/review` | 复盘成长计划 | 📋规划师端 | path: `id`, body: `{reviewNotes}` | `boolean` |

## 数据实体关系

```mermaid
erDiagram
    GrowthRecord ||--o{ DanAssessmentResult : "assessmentId 引用"
    GrowthPlan ||--o{ DanAssessmentResult : "assessmentId 引用"
    GrowthRecord ||--o{ Supplement : "一条记录多个补充"
    Child ||--o{ GrowthRecord : "一个孩子多个档案"
    Child ||--o{ GrowthPlan : "一个孩子多个计划"
    Child ||--o{ DanAssessmentResult : "一个孩子多份报告"

    GrowthRecord {
        Long id PK
        Long childId FK
        Long assessmentId FK "nullable"
        string recordTitle
        string height
        string weight
        string school
        int grade
        string assessmentSummary
        int overallScore
        string growthSuggestions
    }

    GrowthPlan {
        Long id PK
        Long childId FK
        Long teacherId FK
        Long assessmentId FK "nullable"
        string planTitle
        string planContent
        int durationMonths
        string status "active/inactive"
        date startDate
        date endDate
        int reviewCount
    }

    DanAssessmentResult {
        Long id PK
        Long childId FK
        string dimensionScores
        string structuredAnalysis
        string source
    }
```