cfc/docs/flows/growth-record-flow.md

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

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

分层说明: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

核心概念

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

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

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

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

数据实体关系

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
    }