docs: 数据移到连线标注 + 中文命名

docs/flows/growth-record-flow.md

@@ -36,115 +36,117 @@ flowchart TD
     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
+        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 --> 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
+        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 --> 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
+        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["📋 规划师端：制定成长计划页<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
+        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 --> 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 表"]
+        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["📋 规划师端：查看执行记录<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
+        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 --> A6a["🔗 POST /api/growth/plan/update<br>基于复盘结果调整<br>计划内容/时长"]:::api
-        A6a --> S6a["⚙️ GrowthPlanService<br>.updatePlan()"]:::service
-        S6a --> D4
+        D6 -->|"复盘结论"| P6a["📋 规划师端：调整计划"]:::page
+        P6a -->|"计划ID, 调整后的标题/内容/时长"| A6a["🔗 POST /api/growth/plan/update"]:::api
+        A6a -->|"计划ID, 更新字段"| S6a["⚙️ GrowthPlanService.updatePlan()"]:::service
+        S6a -->|"更新计划记录"| D4
 
-        D6 --> P6b["📱 家长端：查看复盘结果"]:::page
+        D6 -->|"复盘结果"| P6b["📱 家长端：查看复盘结果"]:::page
     end
 
     %% ================================================================