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["🏠 家长端：成长档案页"]:::page
        P1 -->|"选择创建方式"| P1_choice{"手动录入 / 上传PDF / 购买测评"}:::page

        P1_choice -->|"手动录入"| P1a["🏠 家长端：录入表单"]:::page
        P1a -->|"孩子ID, 身高, 体重, 学校, 年级, 照片"| A1["🔗 POST /api/growth/record/create"]:::api
        A1 -->|"孩子ID, 身高, 体重, 学校, 年级"| S1["⚙️ GrowthRecordService.createRecord()"]:::service
        S1 -->|"写入一条成长档案记录"| D1["📦 growth_records 表"]:::data

        P1_choice -->|"上传PDF报告"| P1b["🏠 家长端：选择PDF文件"]:::page
        P1b -->|"PDF文件(多部件表单)"| A1a["🔗 POST /api/growth/record/upload-and-parse"]:::api
        A1a -->|"PDF文件"| S1a["⚙️ PDF解析引擎：OCR+结构化提取"]:::service
        S1a -->|"解析结果: 指标数据, 得分, 报告日期"| D1a["📦 ParsedReport（内存中）"]:::data
        D1a -->|"文件哈希值"| A1b["🔗 POST /api/growth/record/check-duplicate"]:::api
        A1b -->|"文件哈希值"| S1b["⚙️ 哈希去重校验"]:::service
        S1b -->|"重复"| D1b["📦 返回已有记录ID"]:::data
        S1b -->|"新记录"| A1c["🔗 POST /api/growth/record/create-from-upload"]:::api
        A1c -->|"解析后的报告数据"| S1c["⚙️ GrowthRecordService.createFromUpload()"]:::service
        S1c -->|"写入一条成长档案记录"| D1

        P1_choice -->|"创建档案+购买测评"| P1c["🏠 家长端：选择测评套餐"]:::page
        P1c -->|"孩子ID, 规划师ID, 套餐ID"| A1d["🔗 POST /api/growth/record/create-with-order"]:::api
        A1d -->|"孩子ID, 规划师ID, 套餐ID"| S1d["⚙️ GrowthRecordService + AssessmentOrderService"]:::service
        S1d -->|"写入档案记录 + 测评订单"| D1c["📦 growth_records + assessment_orders"]:::data
    end

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

        P2 -->|"外部同步"| P2b["🏠 家长端：选择外部系统"]:::page
        P2b -->|"孩子ID, 数据来源, 认证凭证"| A2a["🔗 POST /api/growth/external/sync"]:::api
        A2a -->|"孩子ID, 数据来源, 凭证"| S2a["⚙️ 外部数据同步引擎"]:::service
        S2a -->|"融合后的数据写入档案"| D1
    end

    %% ================================================================
    %% 阶段三：分析评估 — 查看测评结果
    %% ================================================================
    subgraph 阶段三[阶段三：分析评估]
        D1 -->|"家长ID"| P3["🏠 家长端：档案列表页"]:::page
        P3 -->|"选择档案"| P3a["🏠 家长端：档案详情页"]:::page
        P3a -->|"档案ID"| A3["🔗 GET /api/growth/record/{id}"]:::api
        A3 -->|"档案ID"| S3["⚙️ GrowthRecordService.getRecordDetail()"]:::service
        S3 -->|"档案完整数据 + 关联测评摘要"| D3["📦 GrowthRecord + DanAssessmentResult"]:::data

        D3 -->|"孩子ID, 分析结果"| P3b["📋 规划师端：测评分析页"]:::page
        P3b -->|"查看孩子测评报告"| A3a["🔗 GET /api/guide/assessment/child/{id}"]:::api
        A3a -->|"孩子ID"| S3a["⚙️ AssessmentService.getChildResults()"]:::service
        S3a -->|"维度得分, 结构化分析"| D3a["📦 DanAssessmentResult"]:::data
    end

    %% ================================================================
    %% 阶段四：制定成长计划
    %% ================================================================
    subgraph 阶段四[阶段四：制定成长计划]
        D3a -->|"测评分析结果: 维度得分, 弱项"| P4["📋 规划师端：制定成长计划页"]:::page
        P4 -->|"提交计划"| A4["🔗 POST /api/growth/plan/create"]:::api
        A4 -->|"孩子ID, 关联测评ID, 计划标题, 计划内容, 持续月数, 开始日期"| S4["⚙️ GrowthPlanService.createPlan()"]:::service
        S4 -->|"写入一条计划, 状态=活跃"| D4["📦 growth_plans 表"]:::data

        D4 -->|"孩子ID"| P4a["📋 规划师端：查看孩子计划列表"]:::page
        P4a -->|"查看列表"| A4a["🔗 GET /api/growth/plan/child/{childId}"]:::api
        A4a -->|"孩子ID"| S4a["⚙️ GrowthPlanService.getByChildId()"]:::service
        S4a -->|"该孩子的所有计划列表"| D4

        P4 -->|"更新计划"| P4b["📋 规划师端：编辑计划"]:::page
        P4b -->|"计划ID, 标题, 内容, 时长"| A4b["🔗 POST /api/growth/plan/update"]:::api
        A4b -->|"计划ID, 更新字段"| S4b["⚙️ GrowthPlanService.updatePlan()"]:::service
        S4b -->|"更新对应计划记录"| D4

        D4 -->|"孩子ID"| P4c["📱 家长端：查看计划"]:::page
    end

    %% ================================================================
    %% 阶段五：执行计划 + 记录成长
    %% ================================================================
    subgraph 阶段五[阶段五：执行计划与记录成长]
        D4 -->|"孩子ID, 活跃计划"| P5["📱 家长端：查看活跃计划"]:::page
        P5 -->|"按计划内容执行日常活动"| P5a["🏠 家长端：执行计划任务"]:::page
        P5a -->|"记录身高/体重/学业表现"| P5b["📱 家长/孩子端：创建生长记录"]:::page
        P5b -->|"孩子ID, 记录标题, 身高, 体重, 照片"| A5["🔗 POST /api/health/growth/create"]:::api
        A5 -->|"生长记录数据"| S5["⚙️ GrowthRecordService.createRecord()"]:::service
        S5 -->|"写入日常生长记录"| D5["📦 health_growth_records 表"]:::data

        P5a -->|"定期更新档案数据"| P5c["📱 家长端：更新成长档案"]:::page
        P5c -->|"孩子ID, 测评摘要, 成长建议"| A5a["🔗 POST /api/growth/record/create"]:::api
        A5a -->|"档案数据"| S5a["⚙️ GrowthRecordService.createRecord()"]:::service
        S5a -->|"写入新档案记录"| D1
    end

    %% ================================================================
    %% 阶段六：复盘与评估
    %% ================================================================
    subgraph 阶段六[阶段六：复盘与评估]
        D5 -->|"日常生长记录, 计划目标"| P6["📋 规划师端：查看执行记录"]:::page
        P6 -->|"计划ID, 复盘备注"| A6["🔗 POST /api/growth/plan/{id}/review"]:::api
        A6 -->|"计划ID, 复盘备注"| S6["⚙️ GrowthPlanService.reviewPlan()"]:::service
        S6 -->|"复盘次数+1, 更新状态"| D6["📦 growth_plans 表（复盘计数更新）"]:::data

        D6 -->|"复盘结论"| P6a["📋 规划师端：调整计划"]:::page
        P6a -->|"计划ID, 调整后的标题/内容/时长"| A6a["🔗 POST /api/growth/plan/update"]:::api
        A6a -->|"计划ID, 更新字段"| S6a["⚙️ GrowthPlanService.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
    }