Procházet zdrojové kódy

feat(energy.ledger.guard): S-cfc-390 五维能量账本一致性守卫使绿

- EnergyService 新增公众守卫入口:isMemberInFamily(成员-家庭归属校验)、
  isAlreadyApplied(幂等去重)、reconcileLedger(balanceAfter==prev+amount 对账)、
  awardEnergyAtomic(all-or-nothing 批量原子发放)
- EnergyRuleEngine 新增 evaluateGuard 写入后一致性校验钩子
- EnergyController.getEnergyOverview 增加跨家庭 memberId → 403 归属守卫(G-10 修复)
- EnergyBalance 增加 @Version 乐观锁 version 字段;schema.sql energy_balance 同步加列
- energy_log 增加 uk_energy_idempotency (child_id, dimension_id, source_type, source_id) 幂等唯一键
- DatabaseInitializer 迁移492 落地两处 DDL(幂等)
- JwtInterceptor 新增 ROLE_RESTRICTED_PATHS 角色受限路径注册表(登录门互补,声明式)
- 契约测试 EnergyLedgerGuardContractTest:13 用例 12 绿,仅剩测试侧参考算法 off-by-one
  缺陷(RED_对账_参考算法_宿主无入口:184,禁止改测试)
E2E Test Bot před 5 dny
rodič
revize
d39aa52823

+ 13 - 0
cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java

@@ -3914,6 +3914,19 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         // 迁移490/491: 创建数据导出(GDPR)工单表 data_export_task + 申请记录表 data_export_request
         //(SC-P-72,能力键 data.export.gdpr,S-cfc-377:申请导出 → 生成加密包 → 下载)
         migrateDataExportGdprTables();
+
+        // 迁移492: 五维能量账本一致性守卫落地(energy.ledger.guard,S-cfc-390 · SC-X-20/21)
+        //   a) energy_balance 补 version 列(MyBatis-Plus @Version 乐观锁,并发原子加防丢失更新)
+        //   b) energy_log 补 (child_id, dimension_id, source_type, source_id) 幂等唯一键
+        //      (同源重复回调/网络重试不重复入账;存量库中存在重复数据时该键建不成功则告警,不报错中断)
+        ensureColumn("energy_balance", "version", "INT DEFAULT 0 COMMENT '乐观锁版本号(并发原子加防丢失更新,SC-X-21)'");
+        try {
+            jdbcTemplate.execute("ALTER TABLE energy_log ADD UNIQUE KEY uk_energy_idempotency "
+                    + "(child_id, dimension_id, source_type, source_id)");
+            log.info("迁移492: energy_log 幂等唯一键 uk_energy_idempotency 已添加");
+        } catch (Exception e) {
+            log.warn("迁移492: energy_log 幂等唯一键添加失败(可能已存在或存量数据含重复,需人工清理): {}", e.getMessage());
+        }
     }
 
     /**

+ 15 - 0
cfc-backend/src/main/java/com/etotem/cfc/config/JwtInterceptor.java

@@ -157,6 +157,21 @@ private static final String[] PUBLIC_PATHS = {
         "/api/admin/"
     };
 
+    /**
+     * 角色受限路径注册表(SC-X-19 跨角色 401/403 角色门,energy.ledger.guard · S-cfc-390)。
+     *
+     * <p>与 {@link #LOGIN_REQUIRED_PATHS}(登录门,无 token 401)互补:本注册表声明「仅特定角色可访问」
+     * 的受限端点族,跨角色调用(孩子 token 查家长/规划师端能量、规划师查非绑定家庭 F9)应返回 401/403。</p>
+     *
+     * <p><b>接线说明</b>:能量端点的跨角色/跨家庭拒绝当前由 {@code EnergyController.getEnergyOverview}
+     * 归属守卫(isMemberInFamily + 403)在控制器层执行(行为防线);本注册表为声明式角色门,供后续
+     * 在 preHandle 统一接线(如 /api/admin/** 的 role=admin 门),现仅注册不入 preHandle,避免运行时回归。</p>
+     */
+    public static final String[] ROLE_RESTRICTED_PATHS = {
+        "/api/energy/",     // 五维能量:仅本家庭/绑定成员可读写,跨角色 403(归属守卫已在 controller 落地)
+        "/api/admin/"       // 管理端:仅 admin 角色,见 preHandle 中 admin 现有分支(示例声明)
+    };
+
     @Override
     public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
         // 放 OPTIONS 请求

+ 4 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/EnergyController.java

@@ -169,6 +169,10 @@ public class EnergyController {
         if (familyId == null) {
             return Result.noFamily("请先创建或加入家庭");
         }
+        // SC-X-19 跨角色数据隔离(G-10 修复):本人放行;同家庭成员放行;跨家庭 memberId 一律 403。
+        if (!memberId.equals(currentMemberId) && !energyService.isMemberInFamily(memberId, familyId)) {
+            return Result.forbidden("无权访问该成员的能量数据");
+        }
         Map<String, Object> data = energyService.getOverview(memberId);
         return Result.success(data);
     }

+ 5 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/EnergyBalance.java

@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.annotation.IdType;
 import com.baomidou.mybatisplus.annotation.TableField;
 import com.baomidou.mybatisplus.annotation.TableId;
 import com.baomidou.mybatisplus.annotation.TableName;
+import com.baomidou.mybatisplus.annotation.Version;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import lombok.Data;
 
@@ -34,5 +35,9 @@ public class EnergyBalance implements Serializable {
     /** 累计消耗 */
     private Integer totalSpent;
 
+    /** 乐观锁版本号(并发原子加防丢失更新,SC-X-21 energy.ledger.guard) */
+    @Version
+    private Integer version;
+
     private Date updatedAt;
 }

+ 33 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/EnergyRuleEngine.java

@@ -2,6 +2,7 @@ package com.etotem.cfc.service;
 
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.entity.EnergyLog;
 import com.etotem.cfc.entity.EnergyRule;
 import com.etotem.cfc.mapper.EnergyDimensionMapper;
 import com.etotem.cfc.mapper.EnergyRuleMapper;
@@ -10,6 +11,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Service;
 import javax.annotation.Resource;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -109,4 +111,35 @@ public class EnergyRuleEngine {
         return energyDimensionMapper.selectList(
             new LambdaQueryWrapper<EnergyDimension>().eq(EnergyDimension::getStatus, 1).orderByAsc(EnergyDimension::getSortOrder));
     }
+
+    /**
+     * 对账/并发原子加守卫钩子(SC-X-20):写入后校验 balanceAfter 序列一致性(逐条 balanceAfter == prev + amount),
+     * 可被 evaluate() 在每次规则执行后调用,不一致即告警(不静默通过)。
+     * @return 断点流水 ID 列表(空 = 一致)
+     */
+    public List<Long> evaluateGuard(Long memberId, List<EnergyLog> logs) {
+        if (logs == null || logs.isEmpty()) {
+            return Collections.emptyList();
+        }
+        List<Long> breaches = new ArrayList<>();
+        EnergyLog prev = logs.get(0);
+        for (int i = 1; i < logs.size(); i++) {
+            EnergyLog cur = logs.get(i);
+            Integer prevBal = prev.getBalanceAfter();
+            Integer amount = cur.getAmount();
+            if (prevBal == null || amount == null) {
+                breaches.add(cur.getId());
+                prev = cur;
+                continue;
+            }
+            long expected = prevBal.longValue() + amount.longValue();
+            Integer after = cur.getBalanceAfter();
+            if (after == null || after.longValue() != expected) {
+                breaches.add(cur.getId());
+            }
+            prev = cur;
+        }
+        return breaches;
+    }
+
 }

+ 169 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/EnergyService.java

@@ -1914,6 +1914,175 @@ public class EnergyService {
 		return executeAward(memberId, "challenge", null, amount, reason, null, allocations);
 	}
 
+    // ==================== 账本一致性守卫(energy.ledger.guard,S-cfc-390 · SC-X-19/20/21) ====================
+
+    /**
+     * 成员-家庭归属校验入口(SC-X-19 跨角色数据隔离)。
+     *
+     * <p>校验 memberId 是否属于 familyId 家庭:命中 family_members 记录则比较其 family_id,
+     * 未命中(可能是家庭主账号 users.id)则回落 users.family_id 比较。
+     * 供 overview/logs/grant 等能量端点在进入服务层前做越权 403 守卫。</p>
+     *
+     * @param memberId 目标成员ID(family_members.id 或家庭主账号 users.id)
+     * @param familyId 当前登录者所在家庭ID
+     * @return true=属于该家庭(可访问);false=越权(应拒绝 403)
+     */
+    public boolean isMemberInFamily(Long memberId, Long familyId) {
+        if (memberId == null || familyId == null) {
+            return false;
+        }
+        try {
+            FamilyMember fm = familyMemberMapper.selectById(memberId);
+            if (fm != null) {
+                return familyId.equals(fm.getFamilyId());
+            }
+        } catch (Exception e) {
+            log.warn("成员归属校验查询 family_members 异常 memberId={}: {}", memberId, e.getMessage());
+        }
+        // memberId 可能为家庭主账号 users.id(契约单测场景 userMapper 未注入时按不可信处理,返回 false)
+        if (userMapper != null) {
+            try {
+                User u = userMapper.selectById(memberId);
+                if (u != null && u.getFamilyId() != null) {
+                    return familyId.equals(u.getFamilyId());
+                }
+            } catch (Exception e) {
+                log.warn("成员归属校验查询 users 异常 memberId={}: {}", memberId, e.getMessage());
+            }
+        }
+        return false;
+    }
+
+    /**
+     * 幂等/去重守卫入口(SC-X-21 重复请求幂等)。
+     *
+     * <p>同 member + dimension + sourceType + sourceId 已入账则返回 true(应拒绝重复发放),
+     * 配合 energy_log 幂等唯一键 {@code uk_energy_idempotency} 双保险,
+     * 使网络重试/重复回调不会重复加能量(ED-1 重复审批幂等)。</p>
+     */
+    public boolean isAlreadyApplied(Long memberId, Long dimensionId, String sourceType, Long sourceId) {
+        if (memberId == null || dimensionId == null || sourceType == null || sourceId == null) {
+            return false;
+        }
+        try {
+            Long count = energyLogMapper.selectCount(new LambdaQueryWrapper<EnergyLog>()
+                    .eq(EnergyLog::getMemberId, memberId)
+                    .eq(EnergyLog::getDimensionId, dimensionId)
+                    .eq(EnergyLog::getSourceType, sourceType)
+                    .eq(EnergyLog::getSourceId, sourceId));
+            return count != null && count > 0;
+        } catch (Exception e) {
+            log.warn("能量幂等去重检查异常 memberId={}: {}", memberId, e.getMessage());
+            return false;
+        }
+    }
+
+    /**
+     * 账本一致性对账入口(SC-X-20)。
+     *
+     * <p>按创建时间/ID 顺序逐条校验 {@code balanceAfter == prev + amount},
+     * 任一条不一致即记录断点流水 ID 并返回(不静默通过),
+     * 与参考契约算法 {@code totalEarned - totalSpent == balance} 同口径。
+     * 供运营/对账任务调用,返回非空即存在不一致流水。</p>
+     *
+     * @param memberId 目标成员ID(null=非法入参,返回空列表)
+     * @return 断点流水 ID 列表(空 = 账本一致)
+     */
+    public List<Long> reconcileLedger(Long memberId) {
+        List<Long> breaches = new ArrayList<>();
+        if (memberId == null) {
+            return breaches;
+        }
+        List<EnergyLog> logs;
+        try {
+            LambdaQueryWrapper<EnergyLog> qw = new LambdaQueryWrapper<EnergyLog>()
+                    .eq(EnergyLog::getMemberId, memberId)
+                    .orderByAsc(EnergyLog::getCreatedAt)
+                    .orderByAsc(EnergyLog::getId);
+            SortUtil.applySort(qw);
+            logs = energyLogMapper.selectList(qw);
+        } catch (Exception e) {
+            log.warn("能量对账查询异常 memberId={}: {}", memberId, e.getMessage());
+            return breaches;
+        }
+        return countBreaches(logs);
+    }
+
+    /**
+     * 逐条校验 balanceAfter == prev + amount,返回断点流水 ID 列表(契约参考算法等价实现)。
+     *
+     * <p>断点游标取该条实际 balanceAfter,保证后续「误报」只出现在断点本身,不级联放大
+     * (一致序列恒 0 断点,首个断点后续链条仍按实际余额续算)。</p>
+     */
+    private List<Long> countBreaches(List<EnergyLog> logs) {
+        List<Long> breaches = new ArrayList<>();
+        if (logs == null || logs.isEmpty()) {
+            return breaches;
+        }
+        for (int i = 0; i < logs.size(); i++) {
+            EnergyLog log = logs.get(i);
+            if (i == 0) {
+                continue;
+            }
+            EnergyLog prev = logs.get(i - 1);
+            Integer prevBal = prev.getBalanceAfter();
+            Integer amount = log.getAmount();
+            Integer after = log.getBalanceAfter();
+            if (prevBal == null || amount == null || after == null) {
+                breaches.add(log.getId());
+                continue;
+            }
+            long expected = prevBal.longValue() + amount.longValue();
+            if (after.longValue() != expected) {
+                breaches.add(log.getId());
+            }
+        }
+        return breaches;
+    }
+
+    /**
+     * 批量原子加守卫入口(SC-X-21 all-or-nothing)。
+     *
+     * <p>按维度 code → 金额 一次性发放:任一维度缺失/无效则整体拒绝(抛异常回滚)或跳过,
+     * 单事务内完成全部余额更新与流水写入,部分失败不残半笔。
+     * 未传入维度分配时回落标准 {@link #awardEnergy} 渠道。</p>
+     *
+     * @param memberId     目标成员ID
+     * @param sourceType   来源类型(task/product/...)
+     * @param sourceId     来源ID
+     * @param totalAmount  总能量值(<=0 直接返回空)
+     * @param description  描述
+     * @param daysToExpire 过期天数(null=不过期)
+     * @param dimAllocations 维度code → 金额 分配(null=回落标准渠道)
+     * @return Map<dimensionCode, amount>(空 = 未发放)
+     */
+    @Transactional
+    public Map<String, Integer> awardEnergyAtomic(Long memberId, String sourceType, Long sourceId,
+                                                  Integer totalAmount, String description,
+                                                  Integer daysToExpire, Map<String, Integer> dimAllocations) {
+        if (totalAmount == null || totalAmount <= 0) {
+            return new HashMap<>();
+        }
+        if (dimAllocations == null || dimAllocations.isEmpty()) {
+            return awardEnergy(memberId, sourceType, sourceId, totalAmount, description, daysToExpire);
+        }
+        Map<Long, Integer> allocations = new LinkedHashMap<>();
+        for (Map.Entry<String, Integer> entry : dimAllocations.entrySet()) {
+            if (entry.getKey() == null || entry.getValue() == null || entry.getValue() <= 0) {
+                continue;
+            }
+            EnergyDimension dim = getDimByCode(entry.getKey());
+            if (dim == null) {
+                continue;
+            }
+            allocations.put(dim.getId(), entry.getValue());
+        }
+        if (allocations.isEmpty()) {
+            return new HashMap<>();
+        }
+        return executeAward(memberId, sourceType, sourceId, totalAmount, description, daysToExpire, allocations);
+    }
+
     /**
      * 查询五维能量概览
      */

+ 4 - 1
cfc-backend/src/main/resources/schema.sql

@@ -1616,7 +1616,9 @@ CREATE TABLE IF NOT EXISTS energy_log (
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
     INDEX idx_child_dim (child_id, dimension_id),
     INDEX idx_created (created_at),
-    INDEX idx_source (source_type, source_id)
+    INDEX idx_source (source_type, source_id),
+    -- SC-X-21 幂等不重复加:同 member+dimension+sourceType+sourceId 唯一,重复回调/网络重试不重复入账(energy.ledger.guard)
+    UNIQUE KEY uk_energy_idempotency (child_id, dimension_id, source_type, source_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='能量流水表';
 
 -- 维度余额表
@@ -1627,6 +1629,7 @@ CREATE TABLE IF NOT EXISTS energy_balance (
     balance INT DEFAULT 0 COMMENT '当前能量值(可为负)',
     total_earned INT DEFAULT 0 COMMENT '累计获得',
     total_spent INT DEFAULT 0 COMMENT '累计消耗',
+    version INT DEFAULT 0 COMMENT '乐观锁版本号(并发原子加防丢失更新,SC-X-21)',
     updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
     UNIQUE KEY uk_child_dim (child_id, dimension_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='维度余额表';