Просмотр исходного кода

test(S-cfc-225): RED 契约级单测 energy.ledger.guard(SC-X-19/20/21 对账/并发原子/跨角色归属守卫)

Sisyphus Agent 3 дней назад
Родитель
Сommit
165cfc7478

+ 437 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyLedgerGuardContractTest.java

@@ -0,0 +1,437 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.config.JwtInterceptor;
+import com.etotem.cfc.controller.EnergyController;
+import com.etotem.cfc.entity.EnergyBalance;
+import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.entity.EnergyLog;
+import com.etotem.cfc.mapper.EnergyBalanceMapper;
+import com.etotem.cfc.mapper.EnergyBehaviorConfigMapper;
+import com.etotem.cfc.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.mapper.EnergyLogMapper;
+import com.etotem.cfc.mapper.EnergySourceConfigMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.WishMapper;
+import com.etotem.cfc.service.EnergyRuleEngine;
+import com.etotem.cfc.service.EnergyService;
+import com.etotem.cfc.service.FiveDimensionScoreService;
+import com.etotem.cfc.service.NotificationDispatchService;
+import com.etotem.cfc.service.UnlockGateService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Scanner;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:五维能量账本一致性守卫(能力键 {@code energy.ledger.guard},任务 S-cfc-225,TDD-RED 阶段)。
+ *
+ * <p><b>需求/设计溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-X-19(五维能量跨角色数据隔离)、
+ *       SC-X-20(五维能量流水溯源一致性对账)、SC-X-21(多来源并发同成员能量变动);
+ *       叙事 {@code tests/user-scenarios/07-five-dimension.md} ED-15/ED-16/ED-17;
+ *       用例 {@code tests/test-cases/cross-role-e2e.md} TC-X-19/TC-X-20/TC-X-21(含 -E 异常流/-P 权限流)。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.5(/api/energy:logs/score-history/overview/grant/configure);
+ *       G-10 已知缺口「energy/overview、energy/logs 未校验 memberId 归属(可跨家庭读)」;宿主
+ *       {@link EnergyController} / {@link EnergyRuleEngine} / {@link EnergyService} /
+ *       {@link JwtInterceptor}(role 检查,跨角色 401/403)。</li>
+ *   <li>职责边界:<b>本键 = 账本一致性守卫</b>(对账 + 并发原子 + 跨角色归属,SC-X-19/20/21);
+ *       查看口径由 {@code energy.ledger.view}(S-cfc,EnergyLedgerViewContractTest)、
+ *       每日上限由 {@code energy.dailyLimit.guard}(S-cfc-306,EnergyDailyLimitGuardContractTest)、
+ *       登录/家庭上下文隔离由 {@code energy.isolation}(EnergyIsolationContractTest 观察钉住)覆盖,
+ *       三者互补不重复:guard 新增「逐条 balanceAfter==prev+amount」「totalEarned-totalSpent==balance」
+ *       对账入口、乐观锁/幂等唯一键原子守卫、跨家庭 memberId 403 归属校验与 JwtInterceptor 角色门。</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为(TDD-RED 锚点,当前实现未落地 → 红)</b></p>
+ * <ul>
+ *   <li><b>SC-X-20 对账入口</b>:{@link EnergyService}/{@link EnergyRuleEngine} 应暴露 public 对账/守卫入口
+ *       (逐条 {@code balanceAfter == prev + amount} + {@code totalEarned - totalSpent == balance}),
+ *       任一条不一致即报警并定位断点(不静默通过)——当前二者均无此类方法(反射结构探测);</li>
+ *   <li><b>SC-X-21 并发原子加</b>:{@link EnergyBalance} 应含 {@code version} 字段(乐观锁,@Version),
+ *       schema.sql {@code energy_balance} 应有 {@code version} 列,杜绝 executeAward 读改写式并发丢失更新
+ *       ——当前实体与建表均无 version(反射 + schema.sql 探测);</li>
+ *   <li><b>SC-X-21 幂等不重复加</b>:{@code energy_log} 应有 {@code (child_id, dimension_id, source_type, source_id)}
+ *       幂等唯一键、{@link EnergyService} 应有去重/幂等守卫入口,重复回调/网络重试不重复入账
+ *       ——当前建表仅普通 INDEX idx_source(可重复),服务层无幂等入口(schema.sql + 反射探测);</li>
+ *   <li><b>SC-X-21 部分失败回滚</b>:{@link EnergyRuleEngine}/{@link EnergyService} 应暴露原子批次守卫入口
+ *       (all-or-nothing:失败回滚不残半笔)——当前无(反射结构探测);</li>
+ *   <li><b>SC-X-19 归属校验</b>:{@link EnergyService} 应提供成员-家庭归属校验入口
+ *       (isMemberInFamily/assertMemberInFamily),overview/logs 跨家庭 memberId 应 403——当前
+ *       getOverview 直接进入服务层返回 200(G-10 缺口,行为断言);</li>
+ *   <li><b>SC-X-19 角色门</b>:{@link JwtInterceptor} 应有角色受限路径注册表(如 ROLE_RESTRICTED_PATHS,
+ *       含 /api/energy/),跨角色(孩子 token 查家长/规划师端、规划师查非绑定 F9)401/403——
+ *       当前仅有 LOGIN_REQUIRED_PATHS(登录门),无角色门(反射结构探测)。</li>
+ * </ul>
+ *
+ * <p><b>RED 预期</b>:12 条契约缺口断言失败(红,失败原文含 {@code RED[energy.ledger.guard] …}),
+ * 1 条权限流标注(绿,说明性)。GREEN 阶段按 SC-X-19/20/21 落地上述守卫后自动转绿。</p>
+ *
+ * <p><b>测试范围</b>:纯 Mockito / 无 Spring 上下文 / 无 DB / 无外部服务;直接实例化
+ * {@link EnergyService}/{@link EnergyController} 并注入 mock(复用
+ * {@link EnergyContractTestBase#inject}/{@link EnergyContractTestBase#fiveDims}),
+ * 反射结构探测 + 行为断言 + schema.sql 文本探测。</p>
+ */
+class EnergyLedgerGuardContractTest extends EnergyContractTestBase {
+
+    private EnergyService service;
+    private EnergyController controller;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new EnergyService();
+        EnergyDimensionMapper dimensionMapper = mock(EnergyDimensionMapper.class);
+        EnergyBehaviorConfigMapper behaviorConfigMapper = mock(EnergyBehaviorConfigMapper.class);
+        EnergyLogMapper logMapper = mock(EnergyLogMapper.class);
+        EnergyBalanceMapper balanceMapper = mock(EnergyBalanceMapper.class);
+        FamilyMemberMapper familyMemberMapper = mock(FamilyMemberMapper.class);
+        EnergySourceConfigMapper sourceConfigMapper = mock(EnergySourceConfigMapper.class);
+
+        inject(service, "energyDimensionMapper", dimensionMapper);
+        inject(service, "energyBehaviorConfigMapper", behaviorConfigMapper);
+        inject(service, "energyLogMapper", logMapper);
+        inject(service, "energyBalanceMapper", balanceMapper);
+        inject(service, "energySourceConfigMapper", sourceConfigMapper);
+        inject(service, "wishMapper", mock(WishMapper.class));
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "notificationDispatchService", mock(NotificationDispatchService.class));
+
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(fiveDims()));
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+
+        controller = new EnergyController();
+        inject(controller, "energyService", service);
+        inject(controller, "fiveDimensionScoreService", mock(FiveDimensionScoreService.class));
+        inject(controller, "userMapper", mock(com.etotem.cfc.mapper.UserMapper.class));
+        inject(controller, "unlockGateService", mock(UnlockGateService.class));
+
+        initTable(EnergyDimension.class);
+        initTable(EnergyBalance.class);
+        initTable(EnergyLog.class);
+    }
+
+    // ==================== SC-X-20 流水溯源一致性对账(balanceAfter==prev+amount;totalEarned-totalSpent==balance) ====================
+
+    @Test
+    @DisplayName("RED:EnergyService 应暴露 public 对账入口(逐条 balanceAfter 序列 + totalEarned-totalSpent==balance)")
+    void RED_对账入口_EnergyService_public() {
+        boolean hasPublicReconcile = false;
+        for (Method m : EnergyService.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(reconcil|consisten|ledgercheck|verifybalance|assertbalance).*")
+                    && Modifier.isPublic(m.getModifiers())) {
+                hasPublicReconcile = true;
+                break;
+            }
+        }
+        assertTrue(hasPublicReconcile,
+                "RED[energy.ledger.guard]:EnergyService 应提供 public 对账入口(命名含 reconcile/consistency/"
+                        + "ledgerCheck/verifyBalance,逐条校验 balanceAfter==prev+amount 与 totalEarned-totalSpent==balance,"
+                        + "任一不一致报警并定位断点,SC-X-20)。当前无任何此类方法:对账只能靠人工查库,无法『不一致即报警』。");
+    }
+
+    @Test
+    @DisplayName("RED:EnergyRuleEngine 应提供对账守卫钩子(写入后校验 balanceAfter 序列)")
+    void RED_对账入口_EnergyRuleEngine() {
+        boolean hasGuard = false;
+        for (Method m : EnergyRuleEngine.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(reconcil|guard|consisten|ledger).*")) {
+                hasGuard = true;
+                break;
+            }
+        }
+        assertTrue(hasGuard,
+                "RED[energy.ledger.guard]:EnergyRuleEngine 应提供对账/守卫钩子方法(写入后校验 "
+                        + "balanceAfter==prev+amount,SC-X-20;并发原子加守卫,SC-X-21)。当前无任何 guard/对账方法,"
+                        + "evaluate() 直接委托 awardEnergy/deductEnergy,缺一致性防线。");
+    }
+
+    @Test
+    @DisplayName("RED:对账参考数学成立但宿主无入口——一致序列0断点/断点序列1断点(SC-X-20 TC-X-20-E)")
+    void RED_对账_参考算法_宿主无入口() {
+        // 参考算法(本测试内实现的契约数学):逐条 balanceAfter == prevBalanceAfter + amount
+        List<EnergyLog> consistent = new ArrayList<>();
+        consistent.add(energyLog(1L, 50L, 5L, 10, 10, "task", 100L));
+        consistent.add(energyLog(2L, 50L, 5L, 5, 15, "checkin", 200L));
+        consistent.add(energyLog(3L, 50L, 5L, -3, 12, "wish", 300L));
+        int breachesConsistent = referenceCountBreaches(consistent); // = 0
+
+        // 断点序列:第2条 balanceAfter=16,而 prev(10)+amount(5)=15 → 1 处断点
+        List<EnergyLog> broken = new ArrayList<>();
+        broken.add(energyLog(1L, 50L, 5L, 10, 10, "task", 100L));
+        broken.add(energyLog(2L, 50L, 5L, 5, 16, "checkin", 200L));
+        broken.add(energyLog(3L, 50L, 5L, -3, 12, "wish", 300L));
+        int breachesBroken = referenceCountBreaches(broken); // = 1
+
+        assertEquals(0, breachesConsistent, "参考算法前置:一致序列必须检出 0 处断点");
+        assertEquals(1, breachesBroken, "参考算法前置:断点序列必须检出 1 处断点,且能定位到具体流水");
+
+        // 契约:宿主 EnergyService 应暴露等价对账入口(TC-X-20-E:不一致报警并定位断点,不静默通过)
+        boolean hasPublicReconcile = false;
+        for (Method m : EnergyService.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(reconcil|ledgercheck|verifybalance|assertbalance).*")
+                    && Modifier.isPublic(m.getModifiers())) {
+                hasPublicReconcile = true;
+                break;
+            }
+        }
+        assertTrue(hasPublicReconcile,
+                "RED[energy.ledger.guard]:参考对账算法在一致序列检出 0 处断点、在断点序列检出 1 处断点"
+                        + "(第2条 balanceAfter=16 ≠ prev10+amount5),但 EnergyService 无 public 对账入口——"
+                        + "SC-X-20 的『不一致报警并定位断点』在实现中无法执行(TC-X-20-E 缺口)。");
+    }
+
+    // ==================== SC-X-21 并发原子加 / 幂等 / 部分失败回滚 ====================
+
+    @Test
+    @DisplayName("RED:EnergyBalance 应含 version 字段(乐观锁 @Version,并发原子加防丢失更新)")
+    void RED_原子加_EnergyBalance缺version() {
+        boolean hasVersion = false;
+        for (Field f : EnergyBalance.class.getDeclaredFields()) {
+            if ("version".equals(f.getName())) {
+                hasVersion = true;
+                break;
+            }
+        }
+        assertTrue(hasVersion,
+                "RED[energy.ledger.guard]:EnergyBalance 应含 version 字段(MyBatis-Plus @Version 乐观锁,"
+                        + "SC-X-21 并发原子加)。当前 executeAward/deductEnergy 为读改写(balance=balance+amount 后 "
+                        + "updateById),无版本控制,并发触发会丢失更新、破坏 balanceAfter 序列一致性(TC-X-21-E)。");
+    }
+
+    @Test
+    @DisplayName("RED:schema.sql energy_balance 应含 version 列(乐观锁落地)")
+    void RED_原子加_schema缺version列() {
+        String schema = readSchemaSql();
+        String balanceBlock = extractTableBlock(schema, "energy_balance");
+        assertTrue(balanceBlock.contains("version"),
+                "RED[energy.ledger.guard]:schema.sql energy_balance 建表应含 version 列(乐观锁,SC-X-21 并发原子加),"
+                        + "当前建表仅有 balance/total_earned/total_spent/updated_at,无 version。");
+    }
+
+    @Test
+    @DisplayName("RED:energy_log 应含幂等唯一键(同 member+dim+source 不重复入账)")
+    void RED_幂等_energy_log缺唯一键() {
+        String schema = readSchemaSql();
+        String logBlock = extractTableBlock(schema, "energy_log");
+        boolean hasUniqueKey = logBlock.contains("UNIQUE KEY")
+                || logBlock.matches("(?s).*\\bUNIQUE\\b.*\\bKEY\\b.*");
+        boolean hasIdempotencyUk = logBlock.toLowerCase().contains("uk_")
+                && logBlock.toLowerCase().contains("child_id")
+                && logBlock.toLowerCase().contains("source_type");
+        assertTrue(hasUniqueKey && hasIdempotencyUk,
+                "RED[energy.ledger.guard]:energy_log 应含幂等唯一键(child_id+dimension_id+source_type+source_id 唯一,"
+                        + "SC-X-21/ED-1 重复审批幂等)。当前建表仅非唯一 INDEX idx_source(同源重复回调可重复插流水,"
+                        + "重复审批/网络重试会重复加能量——TC-X-21-E 幂等缺口)。");
+    }
+
+    @Test
+    @DisplayName("RED:EnergyService 应提供幂等守卫入口(重复触发不重复加)")
+    void RED_幂等_EnergyService缺去重入口() {
+        boolean hasIdempotent = false;
+        for (Method m : EnergyService.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(idempot|dedup|duplicate|alreadyapplied).*")) {
+                hasIdempotent = true;
+                break;
+            }
+        }
+        assertTrue(hasIdempotent,
+                "RED[energy.ledger.guard]:EnergyService 应提供幂等/去重守卫入口(同 sourceType+sourceId 已入账则拒绝,"
+                        + "SC-X-21 重复请求幂等、ED-1 重复审批幂等)。当前 awardEnergy/grantEnergy 无去重入口,"
+                        + "重复回调会再次入账(TC-X-21-E 网络重试缺口)。");
+    }
+
+    @Test
+    @DisplayName("RED:EnergyRuleEngine 应提供并发原子加守卫入口(含日上限截断,SC-X-21)")
+    void RED_原子守卫_EnergyRuleEngine() {
+        boolean hasAtomic = false;
+        for (Method m : EnergyRuleEngine.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(atomic|allornothing|concurrent|guard).*")) {
+                hasAtomic = true;
+                break;
+            }
+        }
+        assertTrue(hasAtomic,
+                "RED[energy.ledger.guard]:EnergyRuleEngine 应提供并发原子加守卫入口(同成员同维度并发触发:逐笔原子加、"
+                        + "总额不超日上限、触顶最后到达被拒或截断,SC-X-21)。当前 evaluate() 直接循环委托 awardEnergy,"
+                        + "无原子守卫/触顶截断入口(TC-X-21-E 并发触顶缺口)。");
+    }
+
+    @Test
+    @DisplayName("RED:EnergyService 应提供批量原子守卫入口(部分失败回滚不残半笔)")
+    void RED_回滚_EnergyService缺原子批量() {
+        boolean hasAtomicBatch = false;
+        for (Method m : EnergyService.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(atomic|allornothing|batchaward|batchapply|rollbackguard).*")) {
+                hasAtomicBatch = true;
+                break;
+            }
+        }
+        assertTrue(hasAtomicBatch,
+                "RED[energy.ledger.guard]:EnergyService 应提供批量原子守卫入口(多维度一次发放 all-or-nothing:"
+                        + "部分失败回滚不残半笔流水,SC-X-21-E)。当前 executeAward 为 private 逐维循环,"
+                        + "缺显式原子批次守卫契约(TC-X-21-E 部分失败缺口)。");
+    }
+
+    // ==================== SC-X-19 跨角色数据隔离(memberId 归属校验 + JwtInterceptor 角色门) ====================
+
+    @Test
+    @DisplayName("RED:EnergyService 应提供成员-家庭归属校验入口(isMemberInFamily/assertMemberInFamily)")
+    void RED_归属守卫_EnergyService() {
+        boolean hasOwnership = false;
+        for (Method m : EnergyService.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(ismemberinfamily|assertmemberinfamily|memberbelongs|"
+                    + "belongstofamily|memberinfamily).*")) {
+                hasOwnership = true;
+                break;
+            }
+        }
+        assertTrue(hasOwnership,
+                "RED[energy.ledger.guard]:EnergyService 应提供成员-家庭归属校验入口(isMemberInFamily(memberId, familyId)"
+                        + "/assertMemberInFamily,SC-X-19 跨角色数据隔离:overview/logs/grant 的 memberId 必须属于"
+                        + "当前家庭,否则 403)。当前无任何归属校验方法——API_REFERENCE G-10 已知缺口"
+                        + "『energy/overview、energy/logs 未校验 memberId 归属(可跨家庭读)』(TC-X-19-P)。");
+    }
+
+    @Test
+    @DisplayName("RED:overview 跨家庭 memberId 应 403(当前返回 200,G-10 缺口)")
+    void RED_归属守卫_overview跨家庭403() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 999999L); // familyId=1 的登录者查询其他家庭成员
+        Result<Map<String, Object>> r = controller.getEnergyOverview(params, 1L, 50L);
+
+        assertEquals(403, r.getCode(),
+                "RED[energy.ledger.guard]:familyId=1 的登录者请求 memberId=999999(其他家庭)能量概览,"
+                        + "契约要求 403 越权拒绝(SC-X-19:各方仅访问本家庭/绑定成员能量;家长查他人 403)。"
+                        + "当前实现无归属校验直接返回 " + r.getCode() + "(API_REFERENCE G-10 缺口)。");
+    }
+
+    @Test
+    @DisplayName("RED:JwtInterceptor 应提供角色受限路径注册表(含 /api/energy/,跨角色 401/403)")
+    void RED_角色门_JwtInterceptor() throws Exception {
+        boolean hasRoleGuard = false;
+        for (Field f : JwtInterceptor.class.getDeclaredFields()) {
+            if (f.getName().matches("(?i).*(role).*(path|guard|require).*")) {
+                hasRoleGuard = true;
+                break;
+            }
+        }
+        if (!hasRoleGuard) {
+            for (Method m : JwtInterceptor.class.getDeclaredMethods()) {
+                if (m.getName().matches("(?i).*(requirerole|checkrole|enforcerole|roleguard).*")) {
+                    hasRoleGuard = true;
+                    break;
+                }
+            }
+        }
+        assertTrue(hasRoleGuard,
+                "RED[energy.ledger.guard]:JwtInterceptor 应提供角色受限路径注册表(如 ROLE_RESTRICTED_PATHS,"
+                        + "将 /api/energy/** 限定可访问角色),跨角色调用(孩子 token 查家长/规划师端能量、"
+                        + "规划师查非绑定家庭 F9)返回 401/403(SC-X-19)。当前仅有 LOGIN_REQUIRED_PATHS(登录门,"
+                        + "无 token 401),任何登录角色均可访问全部能量端点,无角色门(TC-X-19-E 权限缺口)。");
+    }
+
+    // ==================== 权限流(SC-X-19-P 等由本类归属/角色守卫 RED 用例覆盖) ====================
+
+    @Test
+    @DisplayName("权限流:SC-X-19-P 跨角色 401/403 由归属守卫与角色门 RED 用例覆盖(说明性)")
+    void 权限流_说明() {
+        // SC-X-19-P(横向越权查他人/非绑定家庭能量统一 403/401)的断言落在:
+        //   RED_归属守卫_overview跨家庭403(跨家庭 memberId → 403,行为断言)
+        //   RED_归属守卫_EnergyService / RED_角色门_JwtInterceptor(归属校验入口 + 角色门注册表,结构断言)
+        // TC-X-21-P(家长 A 触发 F9 成员并发能量变更 403)同属归属守卫覆盖范围。
+        // 登录门(无 token 401)与家庭上下文闸(5001)由 energy.isolation(EnergyIsolationContractTest)覆盖。
+        assertTrue(true, "权限流说明:SC-X-19-P/TC-X-21-P 由归属守卫类 RED 用例覆盖,本键无独立多余断言。");
+    }
+
+    // ==================== 辅助:参考对账算法 / schema 文本探测 / 反射 ====================
+
+    /**
+     * 契约参考算法(SC-X-20):按时间/ID 顺序逐条校验 {@code balanceAfter == prevBalanceAfter + amount},
+     * 返回断点日志 ID 列表(空 = 全一致)。GREEN 阶段 EnergyService 对账入口应产出等价结果。
+     */
+    private static List<Long> referenceCountBreachesDetail(List<EnergyLog> logs) {
+        List<Long> breaches = new ArrayList<>();
+        if (logs == null || logs.isEmpty()) {
+            return breaches;
+        }
+        List<EnergyLog> sorted = new ArrayList<>(logs);
+        sorted.sort((a, b) -> {
+            if (a.getCreatedAt() != null && b.getCreatedAt() != null) {
+                int c = a.getCreatedAt().compareTo(b.getCreatedAt());
+                if (c != 0) return c;
+            }
+            return Long.compare(a.getId() == null ? 0L : a.getId(), b.getId() == null ? 0L : b.getId());
+        });
+        int prevBalance = 0;
+        for (int i = 0; i < sorted.size(); i++) {
+            EnergyLog log = sorted.get(i);
+            if (i == 0) {
+                prevBalance = log.getBalanceAfter() == null ? 0 : log.getBalanceAfter() - (log.getAmount() == null ? 0 : log.getAmount());
+                continue;
+            }
+            int expected = prevBalance + (log.getAmount() == null ? 0 : log.getAmount());
+            if (log.getBalanceAfter() == null || log.getBalanceAfter() != expected) {
+                breaches.add(log.getId());
+            }
+            prevBalance = log.getBalanceAfter() == null ? expected : log.getBalanceAfter();
+        }
+        return breaches;
+    }
+
+    private static int referenceCountBreaches(List<EnergyLog> logs) {
+        return referenceCountBreachesDetail(logs).size();
+    }
+
+    /** 读取 schema.sql 全文(资源缺失返回空串,不抛错) */
+    private static String readSchemaSql() {
+        try (InputStream is = EnergyLedgerGuardContractTest.class.getClassLoader().getResourceAsStream("schema.sql")) {
+            if (is == null) {
+                return "";
+            }
+            try (Scanner scanner = new Scanner(is, StandardCharsets.UTF_8.name())) {
+                scanner.useDelimiter("\\A");
+                return scanner.hasNext() ? scanner.next() : "";
+            }
+        } catch (Exception e) {
+            return "";
+        }
+    }
+
+    /** 截取某表的 CREATE TABLE 块(起于表名出现处,止于下一个 -- 注释/表头前),用于按表断言列/键 */
+    private static String extractTableBlock(String schema, String tableName) {
+        if (schema == null || tableName == null) {
+            return "";
+        }
+        int idx = schema.indexOf("CREATE TABLE IF NOT EXISTS " + tableName + " (");
+        if (idx < 0) {
+            idx = schema.indexOf("CREATE TABLE " + tableName + " (");
+        }
+        if (idx < 0) {
+            return "";
+        }
+        int end = schema.indexOf(") ENGINE=InnoDB", idx);
+        if (end < 0) {
+            return schema.substring(idx);
+        }
+        return schema.substring(idx, end);
+    }
+}