五维能量系统设计

日期: 2026-06-05（最后更新：2026-07-13） 状态: 已实施（核心） + 富维度子维度已落地 分支: cfclub 版本: v2.1

概述

本项目服务于身、心、智、行、富五个维度，服务内容包括活动、课程、商品、任务、咨询五大类。每个服务实例可影响多个维度，能量值按比例分配。能量系统为全新独立系统，与现有积分系统并行但解耦。

哲学基础： 五维之间的相生相克关系详见 2026-06-08-five-dimension-wuxing-philosophy.md。所有维度顺序、健康指数算法、内容推荐策略均以此为依据。

v2.1 更新（2026-07-13）： 富维度子维度拆分 + 身克富杠杆落地 + POST /api/energy/wealth-detail 富维度详情接口。详见 §6。

关键决策

决策项	结论
维度比例配置方式	按服务实例配置（每个具体任务/课程/商品创建时可指定维度比例）
能量值性质	可消耗值（类似积分，可增可减）
健康指数算法	已实施：各维度子分加权 + 五行相生增益 + 相克校准（v2.0），富维度子维度已落地（v2.1）
与积分系统关系	全新独立系统，不复用积分，但家长富-金钱/收入复用积分总量做参照
架构方案	方案B：维度定义表+流水表+余额表

1. 数据模型

1.1 energy_dimension — 维度定义表

列名	类型	说明
id	BIGINT AUTO_INCREMENT PK
code	VARCHAR(16) UNIQUE	body/mind/wisdom/action/wealth
name	VARCHAR(20)	身/心/智/行/富
icon	VARCHAR(16)	🌏/🔥/⚔️/🌿/💧
element	VARCHAR(10)	土/火/金/木/水
sort_order	INT	显示顺序
status	TINYINT DEFAULT 1	1启用/0禁用

种子数据（排序遵循相生链：智→富→行→心→身，详见五维五行哲学体系）：

code	name	icon	element	sort_order
wisdom	智	⚔️	金	1
wealth	富	💧	水	2
action	行	🌿	木	3
mind	心	🔥	火	4
body	身	🌏	土	5

1.2 energy_source_config — 服务-维度比例配置表

列名	类型	说明
id	BIGINT AUTO_INCREMENT PK
source_type	VARCHAR(32)	task/activity/course/product/consultation
source_id	BIGINT	对应业务表ID
source_name	VARCHAR(200)	冗余名称，方便展示
dimension_id	BIGINT	维度ID
ratio	DECIMAL(5,4)	该维度占比，如0.6000=60%
created_at	DATETIME DEFAULT CURRENT_TIMESTAMP

约束：同一 source_type+source_id 的所有 ratio 之和应 = 1.0。一个服务实例配多行记录。

示例：任务#42 → 行60%+心40% = 2行记录。

1.3 energy_log — 能量流水表

列名	类型	说明
id	BIGINT AUTO_INCREMENT PK
child_id	BIGINT	孩子ID
dimension_id	BIGINT	维度ID
amount	INT	变动量（正=获得，负=消耗）
balance_after	INT	变动后该维度余额
source_type	VARCHAR(32)	来源类型
source_id	BIGINT	来源ID
description	VARCHAR(500)	描述
created_at	DATETIME DEFAULT CURRENT_TIMESTAMP

索引：idx_child_dim (child_id, dimension_id)，idx_created (created_at)

1.4 energy_balance — 各维度当前余额表

列名	类型	说明
id	BIGINT AUTO_INCREMENT PK
child_id	BIGINT	孩子ID
dimension_id	BIGINT	维度ID
balance	INT DEFAULT 0	当前能量值
total_earned	INT DEFAULT 0	累计获得
total_spent	INT DEFAULT 0	累计消耗
updated_at	DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP

UNIQUE(child_id, dimension_id)

1.5 API 响应结构

GET /api/energy/overview?childId=123
{
  "code": 0,
  "data": {
    "dimensions": [
      {
        "code": "wisdom",
        "name": "智",
        "icon": "⚔️",
        "element": "金",
        "energy": 310,
        "healthIndex": 0
      },
      {
        "code": "wealth",
        "name": "富",
        "icon": "💧",
        "element": "水",
        "energy": 200,
        "healthIndex": 0
      },
      {
        "code": "action",
        "name": "行",
        "icon": "🌿",
        "element": "木",
        "energy": 350,
        "healthIndex": 0
      },
      {
        "code": "mind",
        "name": "心",
        "icon": "🔥",
        "element": "火",
        "energy": 280,
        "healthIndex": 0
      },
      {
        "code": "body",
        "name": "身",
        "icon": "🌏",
        "element": "土",
        "energy": 380,
        "healthIndex": 0
      }
    ],
    "totalEnergy": 1520,
    "totalHealthIndex": 0
  }
}

healthIndex 和 totalHealthIndex 算法待定，先返回0。

2. 后端服务架构

2.1 新增文件清单

文件	位置	职责
EnergyDimension	entity/	维度定义实体
EnergySourceConfig	entity/	服务-维度比例配置实体
EnergyLog	entity/	能量流水实体
EnergyBalance	entity/	维度余额实体
EnergyDimensionMapper	mapper/	维度CRUD
EnergySourceConfigMapper	mapper/	比例配置CRUD
EnergyLogMapper	mapper/	流水查询
EnergyBalanceMapper	mapper/	余额查询/更新
EnergyService	service/	核心业务：发放/扣除能量、查余额、算指数
EnergyController	controller/energy/	API入口：概览、流水、配置

2.2 EnergyService 核心方法

/**
 * 发放能量 — 指定source_type+source_id，自动查比例配置，按比例分配到各维度
 * @return 各维度实际发放量 Map<dimensionCode, amount>
 */
Map<String, Integer> awardEnergy(Long childId, String sourceType, Long sourceId, Integer totalAmount, String description)

/**
 * 扣除能量 — 指定维度，检查余额，余额不足返回-1
 * @return 扣除后余额，-1表示余额不足
 */
int deductEnergy(Long childId, Long dimensionId, Integer amount, String reason)

/**
 * 查询概览 — 返回5维度能量值+健康指数+总能量+总指数
 */
Map<String, Object> getOverview(Long childId)

/**
 * 查询流水 — 按维度筛选，分页
 */
Page<EnergyLog> getLogs(Long childId, String dimensionCode, Integer page, Integer size)

/**
 * 配置比例 — 为某服务实例设置维度比例
 * ratios: [{dimensionCode:"action", ratio:0.6}, {dimensionCode:"mind", ratio:0.4}]
 */
void configureSourceRatios(String sourceType, Long sourceId, String sourceName, List<Map<String, Object>> ratios)

2.3 与现有系统的集成点

业务场景	调用位置	调用方式
完成任务	TaskService.completeTask()	energyService.awardEnergy(childId, "task", taskId, energyAmount, "完成任务: "+title)
购买商品	商品订单支付成功回调	energyService.awardEnergy(childId, "product", productId, energyAmount, "购买商品: "+name)
参加活动	活动报名/签到	energyService.awardEnergy(childId, "activity", activityId, energyAmount, "参加活动: "+title)
课程学习	课程完成/打卡	energyService.awardEnergy(childId, "course", courseId, energyAmount, "完成课程: "+title)
咨询完成	咨询结束后	energyService.awardEnergy(childId, "consultation", consultId, energyAmount, "完成咨询")

能量发放额度由各业务方自行决定，EnergyService只负责按比例分配。

2.4 awardEnergy 核心流程

1. 根据 sourceType+sourceId 查 energy_source_config 获取比例列表
2. 若无配置，查 Product.domain 作为 fallback（单维度100%）
3. 若仍无配置，默认分配到"行"维度100%
4. 按 ratio * totalAmount 计算各维度发放量（整数，余数加到最大比例维度）
5. 对每个维度：
   a. 查 energy_balance 获取当前余额
   b. 计算新余额
   c. 更新 energy_balance
   d. 写入 energy_log
6. 返回各维度实际发放量

3. 前端可视化设计

3.1 五角星布局（五行顺序：木→火→土→金→水，从最左侧顺时针排列）

            心·火 (顶)
          ↗        ↖
   行·木 (左)        (右) 身·土
          ↖        ↗
   富·水 (左下)    (右下) 智·金

3.2 三层视觉结构

外层 — 维度角（五角形顶点） 每个角显示：

图标 + 名称（如 🔥心·火）
能量值：绝对数字，如 320
点击可跳转该维度详情页

中层 — 健康指数扇区（角底边→中心的三角形区域） 每个维度的三角形区域外围显示该维度的健康指数：

数字显示，如 78
背景色按指数高低渐变（绿→黄→红）
指数算法待定，先显示0占位

内层 — 中心圆 中央圆形区域显示：

总体能量值：五维度能量值之和，如 1520
总体健康指数：综合指数，如 75
算法待定，先显示0占位

3.3 wuxing-sandbox.vue Props 接口

props: {
  mode: String,        // 'preview' | 'parent' | 'child'
  dimensions: {        // API返回的维度数据
    type: Array,
    default: () => []
  },
  totalEnergy: {
    type: Number,
    default: 0
  },
  totalHealthIndex: {
    type: Number,
    default: 0
  }
}

dimensions 数组元素结构：

{ "code": "body", "name": "身", "icon": "🌏", "element": "土", "energy": 320, "healthIndex": 0 }

3.4 新增页面

页面	路径	说明
维度详情页	pages/energy/detail.vue	某维度能量值、流水记录、提升建议

在 pages.json 中注册（非TabBar页），从沙盘点位点击 navigateTo 进入。

3.5 API 调用

// utils/api.js 新增
getEnergyOverview(childId)      // POST /api/energy/overview
getEnergyLogs(childId, dimensionCode, page, size)  // POST /api/energy/logs

3.6 现有引用更新

页面	当前用法	更新为
parent-index.vue	`<wuxing-sandbox mode="parent" badgeText="综合成长力 0%" />`	传入从API获取的 dimensions/totalEnergy/totalHealthIndex
child-index.vue	`<wuxing-sandbox mode="child" badgeText="综合 0%" />`	同上
discover/index.vue	`<wuxing-sandbox mode="preview" badgeText="登录查看完整报告" />`	保持预览模式，用空数据

4. 数据库迁移与兼容性

4.1 DatabaseInitializer 迁移步骤

创建4张新表（IF NOT EXISTS）
插入5条维度种子数据
为现有Product种子数据插入默认 energy_source_config（1:1单维度映射，与当前Product.domain一致）
为任务模板插入默认比例配置（任务默认→行100%）

4.2 现有系统兼容

项目	处理方式
积分系统（PointsService）	完全不动，能量系统独立运行
TaskService.completeTask()	新增一行 energyService.awardEnergy(...) 调用，积分和能量并行发放
Product.domain 字段	保留不删除，作为无 energy_source_config 时的 fallback
wuxing-sandbox.vue	组件接口从硬编码改为接收 props 数据
前端3处引用	parent-index/child-index/discover 传入实际数据

4.3 无比例配置时的 Fallback 链

1. 查 energy_source_config → 有 → 使用配置比例
2. 无 → source_type 为 "product" 时查 Product.domain → 有 → 单维度100%
3. 无 → 默认分配到"行"维度100%

6. 富维度算法（v2.1）

日期: 2026-07-12 实施，2026-07-13 文档化 实施提交: 3a302b3 — feat: 电商体系升级 — 五维能量富维度详情 关联计划: 2026-07-12-wealth-dimension-redesign.md

6.1 背景

成人和孩子的"富"原为单一值（成人=积分总量/500，孩子=积分获取效率），无差异化"富"定义，也无身克富的系统体现。v2.1 将"富"拆为 3 个子维度，并在 calcParentEnergy/calcChildEnergy 末尾调用 applyBodyWealthRestraint 施加身克富杠杆。

6.2 孩子子维度（`calcChildWealth`）

子维度	符号	数据源	权重
学业成绩	`wealthEducation`	DanAssessmentResult 最近3次综合分均值 + 进步趋势修正（最近一次 vs 前面平均的 10% delta）	30%
社交筹码	`wealthSocial`	活动参与次数（活动系统）— 第一阶段返回 0	20%
规则博弈（积分效率）	`wealthPoints`	一年内已 earned 积分 / 一年内可获取总积分 × 100	50%

评分公式：wealth = edu*0.3 + social*0.2 + points*0.5

实现位置：EnergyService.calcChildWealthEducation/Social/Points（540-614 行）。

6.3 成人子维度（`calcParentWealth`）

子维度	符号	数据源	权重
金钱/收入	`wealthIncome`	`User.totalPoints / 500 × 100`，clamp[0,100]	50%
社会成就	`wealthAchievement`	`User.achievements` 扩展字段 JSON — 第一阶段返回 0	30%
资源网络	`wealthNetwork`	推荐团队人数 — 第一阶段返回 0	20%

评分公式：wealth = income*0.5 + achievement*0.3 + network*0.2

实现位置：EnergyService.calcParentWealthIncome/Achievement/Network（253-280 行）。

6.4 身克富杠杆（`applyBodyWealthRestraint`）

在 calcParentEnergy/calcChildEnergy 中，wealthScore 计算完成后、综合分 overallScore 之前调用：

applyBodyWealthRestraint(bodyScore, dto.getWealthScore(), dto);

条件	状态 (`bodyWealthStatus`)	行为	用户文案 (`bodyWealthMessage`)
身 < 40	`penalty`	wealth *= (0.5 + 0.5 × 身/100)，即最低打对折	"健康正在稀释财富能量，建议优先关注身体健康"
身 < 50 且富 > 身+20	`overdraw`	不下调 wealthScore，仅透支预警	"财富能量超出身体承受范围，注意劳逸结合"
否则	`normal`	不调整；身≥70 给正向文案	身≥70："身体底盘稳固，财富能量充沛" / 其他：空串

实现位置：EnergyService.applyBodyWealthRestraint（622-645 行）。

算法哲学依据： 见五维五行哲学体系 §2 相克关系。身克富 = "健康是创富的底盘，身体不好财富没有意义"。v2.0 将"克"从惩罚层面升级为信号/平衡层面：penalty 是校准触发，overdraw 是引导触发，normal 是正向标记。

6.5 DTO 扩展

MemberEnergyDTO v2.1 新增字段：

// 富的子维度（parent）
private Integer wealthIncome;       // 金钱/收入
private Integer wealthAchievement;  // 社会成就
private Integer wealthNetwork;      // 资源网络

// 富的子维度（child）
private Integer wealthEducation;    // 学业成绩
private Integer wealthSocial;       // 社交筹码
private Integer wealthPoints;       // 规则博弈（积分效率）

// 身克富标记
private String bodyWealthStatus;    // normal / overdraw / penalty
private String bodyWealthMessage;   // 用户可见的消息

注：wealthScore（综合富分）已在 v1 定义，v2.1 由 calcChildWealth/calcParentWealth 赋值，并可被 applyBodyWealthRestraint 在 penalty 状态下下调。

6.6 富维度详情接口

POST /api/energy/wealth-detail
Body: { "memberId": <Long>, "memberType": "child"|"parent" }
Header: Authorization: Bearer <jwt>

逻辑（EnergyController.getWealthDetail，221-250 行）：

取当前 JWT 用户，校验已加入家庭
调用 energyService.calculateFamilyEnergy(familyId) 算家庭整个 sandbox
按 memberId + memberType 过滤出该成员的 MemberEnergyDTO
返回含全部子维度字段 + 身克富标记

前端调用： utils/api.js 新增 getWealthDetail(memberId, memberType)，pages/wealth/index.vue 用其替代原 getEnergyOverview 单独加载富维度数据。

6.7 不做的事

不新建 schema 表、不改 schema.sql、不改 DatabaseInitializer（富子维度无需存储，全部由现有数据源即时计算）
不改 EnergySandboxDTO（家庭聚合值不受影响，子维度只在单成员 DTO 上承载）
不改任何 Mapper

7. 待定事项

事项	说明	影响
能量过期/衰减	是否需要能量值过期机制	暂不实现，energy_log.created_at 可支撑后续时间窗口计算
Web管理端	管理端维度比例配置页面	后端API已就绪，管理端UI后续迭代
能量兑换/消耗	扣除能量的具体业务场景	deductEnergy 方法已预留，具体场景待定
成人富-成就/网络数据源	第一阶段回 0，待 `User.achievements` 字段和推荐团队体系落地	子维度结构已定，仅需补充数据源
孩子富-社交筹码数据源	第一阶段回 0，待活动参与系统完善	同上

附录：文档演变

版本	日期	变更内容
v1.0	2026-06-05	初稿，能量系统架构方案B（维度定义表+流水表+余额表），健康指数先返回0占位
v2.1	2026-07-13	富维度子维度拆分（孩子3+成人3）+ 身克富三态杠杆算法 + `POST /api/energy/wealth-detail` 接口 + DTO 扩展文档化

2026-06-05-five-dimension-energy-design.md 17 KB Patstāvīgā saite Vēsture Neapstrādāts