cfc/docs/flows/energy-system-flow.md

用户使用流程图 — 五维能量系统

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

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

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 actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3
    classDef admin fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:5 3

    %% ============ 角色 ============
    USER(("👤 家长/孩子")):::actor
    ADMIN(("🖥 管理员")):::actor

    %% ================================================================
    %% 阶段一：能量沙盘与概览
    %% ================================================================
    subgraph 阶段一[阶段一：能量沙盘与概览]
        direction TB

        P1["🏠 能量沙盘页"]:::page
        P1 -->|"userId → 查家庭"| A1["🔗 POST /api/energy/sandbox"]:::api
        A1 -->|"userId"| S1["⚙️ EnergyService.calculateFamilyEnergy()"]:::service
        S1 -->|"收集所有家长+孩子, 计算五维分值"| D1["📦 users + family_members + tasks + points_logs + 多源数据"]:::data
        S1 -->|"持久化快照"| D1a["📦 five_dimension_scores 表（periodic快照）"]:::data
        A1 -->|"家庭聚合 + 成员明细"| D1b["📦 EnergySandboxDTO（整体分+成员列表）"]:::data

        P1 -->|"查看孩子概览"| P1a["🏠 五维概览页"]:::page
        P1a -->|"childId"| A2["🔗 POST /api/energy/overview"]:::api
        A2 -->|"childId"| S2["⚙️ EnergyService.getOverview()"]:::service
        S2 -->|"该孩子各维度能量摘要"| D1c["📦 计算结果（维度分值+排名等）"]:::data

        P1 -->|"家庭聚合"| P1b["🏠 家庭五维聚合"]:::page
        P1b -->|"familyId 或 userId"| A3["🔗 POST /api/energy/family-score-history"]:::api
        A3 -->|"familyId"| S3["⚙️ FiveDimensionScoreService.getLatestByFamilyMap()"]:::service
        S3 -->|"查询最近一次五维快照"| D1a

        P1 -->|"维度历史曲线"| P1c["🏠 五维分数历史"]:::page
        P1c -->|"memberId, memberType, dimensionCode"| A4["🔗 POST /api/energy/score-history"]:::api
        A4 -->|"memberId, memberType, dimensionCode, limit"| S4["⚙️ FiveDimensionScoreService.getHistoryByMember()"]:::service
        S4 -->|"按时间降序返回历史评分"| D1a
    end

    %% ================================================================
    %% 阶段二：能量流水与明细
    %% ================================================================
    subgraph 阶段二[阶段二：能量流水与明细]
        D1c -->|"childId"| P2["🏠 能量流水页"]:::page
        P2 -->|"筛选维度, 分页"| A5["🔗 POST /api/energy/logs"]:::api
        A5 -->|"childId, dimensionCode, page, size"| S5["⚙️ EnergyService.getLogs()"]:::service
        S5 -->|"分页查询流水"| D2["📦 energy_log 表（变动量+余额+来源）"]:::data

        P2 -->|"查看富维度"| P2a["🏠 富维度详情页"]:::page
        P2a -->|"memberId, memberType"| A6["🔗 POST /api/energy/wealth-detail"]:::api
        A6 -->|"memberId, memberType, userId"| S6["⚙️ EnergyService.calculateFamilyEnergy() 过滤"]:::service
        S6 -->|"从家庭沙盘中提取指定成员"| D1b
    end

    %% ================================================================
    %% 阶段三：能量操作（发放/扣除/配置）
    %% ================================================================
    subgraph 阶段三[阶段三：能量操作]
        D1a -->|"任务完成触发"| P3["⚙️ 系统：任务完成事件"]:::page
        P3 -->|"childId, taskId, amount, dimensionCode"| A7["🔗 POST /api/energy/grant"]:::api
        A7 -->|"childId, taskId, amount, dimensionCode"| S7["⚙️ EnergyService.grantEnergy()"]:::service
        S7 -->|"按energy_source_config比例分配至各维度"| D3a["📦 energy_source_config 表（比例配置）"]:::data
        S7 -->|"写入各维度流水+更新余额"| D3b["📦 energy_log + energy_balance 表"]:::data

        P3 -->|"心愿兑换触发"| P3a["⚙️ 系统：心愿兑换事件"]:::page
        P3a -->|"childId, wishId, amount"| A8["🔗 POST /api/energy/deduct-for-wish"]:::api
        A8 -->|"childId, wishId, amount"| S8["⚙️ EnergyService.deductForWish()"]:::service
        S8 -->|"从各维度按比例扣除能量"| D3b

        P3 -->|"配置来源比例"| P3b["🏠 配置来源比例页"]:::page
        P3b -->|"sourceType, sourceId, ratios[]"| A9["🔗 POST /api/energy/configure"]:::api
        A9 -->|"sourceType, sourceId, sourceName, ratios"| S9["⚙️ EnergyService.configureSourceRatios()"]:::service
        S9 -->|"写入/更新来源→维度比例"| D3a
    end

    %% ================================================================
    %% 阶段四：健康维度录入（7维）
    %% ================================================================
    subgraph 阶段四[阶段四：健康维度录入]
        P1a -->|"查看7维健康"| P4["🏠 健康维度概览页"]:::page
        P4 -->|"memberId"| A10["🔗 POST /api/dimension/overview"]:::api
        A10 -->|"memberId"| S10["⚙️ DimensionScoreService.getHealthDimension()"]:::service
        S10 -->|"七维健康指标+评分"| D4["📦 health_dimension_scores 表"]:::data

        P4 -->|"手动录入"| P4a["🏠 录入表单"]:::page
        P4a -->|"memberId, dimension, score, ..."| A11["🔗 POST /api/dimension/upload"]:::api
        A11 -->|"DimensionUploadVO"| S11["⚙️ DimensionScoreService.uploadScore()"]:::service
        S11 -->|"写入指定维度评分"| D4

        P4 -->|"问卷提交"| P4b["🏠 问卷页"]:::page
        P4b -->|"memberId, dimension, answers[]"| A12["🔗 POST /api/dimension/questionnaire"]:::api
        A12 -->|"HealthDimensionQuestionnaireVO"| S12["⚙️ DimensionScoreService.submitQuestionnaire()"]:::service
        S12 -->|"问卷答案→评分→写入"| D4

        P4 -->|"历史记录"| P4c["🏠 历史趋势页"]:::page
        P4c -->|"memberId, dimension, limit"| A13["🔗 POST /api/dimension/history"]:::api
        A13 -->|"memberId, dimension, limit"| S13["⚙️ DimensionScoreService.getDimensionHistory()"]:::service
        S13 -->|"该维度历史评分列表"| D4
    end

    %% ================================================================
    %% 阶段五：年度能量（星座生肖）
    %% ================================================================
    subgraph 阶段五[阶段五：年度能量预测]
        P1c -->|"查看年度能量"| P5["🏠 年度五维能量页"]:::page
        P5 -->|"birthYear, birthMonth, birthDay, zodiac(选)"| A14["🔗 POST /api/zodiac/energy"]:::api
        A14 -->|"出生年月日+生肖+目标年份"| S14["⚙️ ZodiacAnnualEnergyService.calculate()"]:::service
        S14 -->|"西方星座+中国生肖+行星星座=五维偏差"| D5["📦 内存计算（无持久化）"]:::data
        A14 -->|"body/mind/wisdom/action/wealth + 星座信息"| P5a["🏠 展示年度五维能量"]:::page
    end

    %% ================================================================
    %% 阶段六：维度权重配置（管理后台）
    %% ================================================================
    subgraph 阶段六[阶段六：维度权重配置]
        P6["🖥 管理后台：权重配置页"]:::admin
        P6 -->|"targetType, targetId, weights[]"| A15["🔗 POST /api/admin/dimension-weight/save"]:::api
        A15 -->|"目标类型+ID+维度权重列表"| S15["⚙️ DimensionWeightService.saveWeights()"]:::service
        S15 -->|"覆盖写入维度权重"| D6["📦 dimension_weights 表"]:::data

        P6 -->|"查看配置"| A16["🔗 POST /api/admin/dimension-weight/list"]:::api
        A16 -->|"targetType, targetId"| S16["⚙️ DimensionWeightService.getByTarget()"]:::service
        S16 -->|"该目标的所有维度权重"| D6
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    USER -.- P1
    USER -.- P2
    USER -.- P3b
    USER -.- P4
    USER -.- P5
    ADMIN -.- P6

端点明细

能量沙盘与概览

端点	说明	端口	请求数据	响应数据
POST /api/energy/sandbox	获取家庭能量沙盘	📱小程序	Header: Authorization	EnergySandboxDTO（家庭聚合分+成员明细）
POST /api/energy/overview	获取孩子五维概览	📱小程序	{childId}	Map（各维度分值+排名）
POST /api/energy/family-score-history	获取家庭五维聚合	📱小程序	{familyId} 或 {userId}	Map<String, Integer>（五维最新分）
POST /api/energy/score-history	获取五维分数历史	📱小程序	{memberId, memberType, dimensionCode, limit?}	List<FiveDimensionScore>
POST /api/energy/wealth-detail	获取富维度详情	📱小程序	{memberId, memberType}	MemberEnergyDTO（含收入/成就/人脉子分）

能量流水

端点	说明	端口	请求数据	响应数据
POST /api/energy/logs	查询能量流水（分页）	📱小程序	{childId, dimensionCode?, page, size}	Page<EnergyLog>
POST /api/energy/seed	生成种子数据	⚙️系统自动	—	—

能量操作

端点	说明	端口	请求数据	响应数据
POST /api/energy/grant	发放能量（任务完成）	⚙️系统自动	{childId, taskId, amount, dimensionCode?}	EnergyLog
POST /api/energy/deduct-for-wish	心愿兑换扣除能量	⚙️系统自动	{childId, wishId, amount}	{success}
POST /api/energy/configure	配置来源比例	📱小程序	{sourceType, sourceId, sourceName, ratios[]}	"配置成功"

健康维度

端点	说明	端口	请求数据	响应数据
POST /api/dimension/overview	获取健康维度概览	📱小程序	{memberId}	HealthDimensionVO（7维健康指标）
POST /api/dimension/upload	手动录入维度评分	📱小程序	{memberId, dimension, score, ...}	null
POST /api/dimension/questionnaire	问卷提交维度评分	📱小程序	{memberId, dimension, answers[]}	null
POST /api/dimension/history	获取维度历史记录	📱小程序	{memberId, dimension, limit?}	List<DimensionItem>

年度能量

端点	说明	端口	请求数据	响应数据
POST /api/zodiac/energy	获取年度五维能量	📱小程序	{birthYear, birthMonth, birthDay, zodiac?, year?}	{westernSign, zodiacCode, dimensions: {body,mind,...}}

维度权重配置（管理后台）

端点	说明	端口	请求数据	响应数据
POST /api/admin/dimension-weight/save	保存维度权重	🖥管理后台	{targetType, targetId, weights: [{dimension, weight, enabled}]}	null
POST /api/admin/dimension-weight/list	查询维度权重	🖥管理后台	{targetType, targetId}	List<DimensionWeight>

数据实体关系

erDiagram
    EnergyDimension {
        Long id PK
        string code "body/mind/wisdom/action/wealth"
        string name "身/心/智/行/富"
        string element "土/火/金/木/水"
        int sortOrder
        int status "1启用/0禁用"
    }

    EnergySourceConfig {
        Long id PK
        string sourceType "task/activity/course/product"
        Long sourceId "业务表ID"
        string sourceName
        Long dimensionId FK "维度ID"
        int ratio "占比如6000=60%"
    }

    EnergyLog {
        Long id PK
        Long childId FK "孩子ID"
        Long dimensionId FK "维度ID"
        int amount "正=获得,负=消耗"
        int balanceAfter "变动后余额"
        string sourceType "task/product/..."
        Long sourceId "来源ID"
        date expiresAt "过期时间"
    }

    FiveDimensionScore {
        Long id PK
        Long memberId "成员ID"
        string memberType "user/member"
        Long familyId
        string dimensionCode "body/mind/wisdom/action/wealth"
        int score "0-100"
        string sourceType "periodic/task/assessment/manual"
        string detailJson "细分项快照"
    }

    DimensionWeight {
        Long id PK
        string targetType "activity/product/article"
        Long targetId
        string dimension "body/mind/wisdom/action/wealth"
        int weight "百分比"
        bool enabled
    }

    EnergyDimension ||--o{ EnergySourceConfig : "维度被引用"
    EnergyDimension ||--o{ EnergyLog : "维度流水"
    EnergyDimension ||--o{ FiveDimensionScore : "维度历史"
    EnergyDimension ||--o{ DimensionWeight : "维度权重"

完整性分析

#	维度	评估	说明
1	流程完整性	✅ 完整	覆盖能量系统六大功能域：沙盘概览(查)、流水明细(查)、发放扣除(写)、维度录入(健康7维)、年度预测(星座生肖)、权重配置(管理后台)
2	异常路径	✅ 完整	家庭无成员时返回空DTO；健康报告查询异常时降级为任务完成率计算；维度评分持久化失败仅记warn不中断主流程
3	端点覆盖	✅ 完整	16个端点全部映射到流程图，与EnergyController、HealthDimensionController、ZodiacEnergyController、DimensionWeightController中的@PostMapping一致
4	角色覆盖	✅ 完整	家长/孩子(查看能量沙盘+维度录入)、系统自动(发放/扣除)、管理员(维度权重配置)各有独立入口
5	数据实体	✅ 完整	energy_dimension(维度定义)、energy_source_config(比例配置)、energy_log(流水)、energy_balance(余额)、five_dimension_scores(历史快照)、dimension_weights(权重) 全部在图中映射
6	一致性	✅ 与代码一致	能量计算引擎集成多数据源：tasks/points_logs/game_records/dan_assessment_results/article_reading_records/health_reports，通过calculateFamilyEnergy统一聚合