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

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

```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 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>` |

## 数据实体关系

```mermaid
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`统一聚合 |