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

fix(energy): executeAward 当日幂等守卫防止 uk_energy_idempotency 重复入账 500

根因:迁移492新增的 uk_energy_idempotency(child_id,dimension_id,source_type,source_id,stat_date)
使同日同源重复入账(如 streak 每日打卡 source_id=0 第二次发放)撞唯一键,
DuplicateKeyException 在 @Transactional awardEnergy 内层边界污染共享事务,
外层 commit 抛 UnexpectedRollbackException → completeTask 500。

修复:executeAward 逐维度发放前加当日作用域幂等检查(member+dim+sourceType+sourceId+created_at∈今日
已入账则跳过该维度:balance 不自增、不插流水),与 uk 键语义精确一致;跳过在 balance 自增之前,
账本保持一致。新增 EnergySameDayIdempotencyContractTest 契约测试(TDD RED→GREEN)。
Xiaogang Liao 6 часов назад
Родитель
Сommit
a6ca13d52e

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

@@ -1743,6 +1743,15 @@ public class EnergyService {
         for (Map.Entry<Long, Integer> entry : allocations.entrySet()) {
             if (entry.getValue() <= 0) continue;
 
+            // SC-X-21 当日幂等守卫(与 uk_energy_idempotency 键语义精确一致:
+            // member+dim+sourceType+sourceId+stat_date(=DATE(created_at)) 已入账 → 跳过该维度,
+            // balance 不自增、不插流水。必须在 balance 自增之前检查,否则账本不一致)
+            if (isSameDayApplied(memberId, entry.getKey(), sourceType, sourceId)) {
+                log.info("能量当日已入账,幂等跳过发放: memberId={}, dimensionId={}, sourceType={}, sourceId={}",
+                        memberId, entry.getKey(), sourceType, sourceId);
+                continue;
+            }
+
             EnergyBalance balance = getOrCreateBalance(memberId, entry.getKey());
             balance.setBalance(balance.getBalance() + entry.getValue());
             balance.setTotalEarned(balance.getTotalEarned() + entry.getValue());
@@ -1977,6 +1986,37 @@ public class EnergyService {
         }
     }
 
+    /**
+     * 当日作用域幂等守卫(SC-X-21 / uk_energy_idempotency 语义对齐)。
+     *
+     * <p>同 member + dimension + sourceType + sourceId <b>且 stat_date∈今日</b> 已入账则返回 true
+     * (应跳过重复发放),与唯一键 {@code uk_energy_idempotency} (child_id, dimension_id, source_type,
+     * source_id, stat_date) 语义精确一致(stat_date = DATE(created_at))。
+     *
+     * <p>区别于无日期维度的 {@link #isAlreadyApplied}(用于 ED-1 重复审批):本守卫含日期窗口,
+     * streak 每日打卡(source_id=0)跨日可正常再发、仅同日重复回调被拦;服务端当日窗口
+     * 00:00:00.000–23:59:59.999,次日起自动归零。</p>
+     */
+    private boolean isSameDayApplied(Long memberId, Long dimensionId, String sourceType, Long sourceId) {
+        if (memberId == null || dimensionId == null || sourceType == null || sourceId == null) {
+            return false;
+        }
+        try {
+            Date todayStart = getTodayStart();
+            Date todayEnd = getTodayEnd();
+            Long count = energyLogMapper.selectCount(new LambdaQueryWrapper<EnergyLog>()
+                    .eq(EnergyLog::getMemberId, memberId)
+                    .eq(EnergyLog::getDimensionId, dimensionId)
+                    .eq(EnergyLog::getSourceType, sourceType)
+                    .eq(EnergyLog::getSourceId, sourceId)
+                    .between(EnergyLog::getCreatedAt, todayStart, todayEnd));
+            return count != null && count > 0;
+        } catch (Exception e) {
+            log.warn("能量当日幂等检查异常 memberId={}: {}", memberId, e.getMessage());
+            return false;
+        }
+    }
+
     /**
      * 账本一致性对账入口(SC-X-20)。
      *

+ 118 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergySameDayIdempotencyContractTest.java

@@ -0,0 +1,118 @@
+package com.etotem.cfc.unit;
+
+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.EnergyService;
+import com.etotem.cfc.service.NotificationDispatchService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 能力键 {@code energy.idempotency.today}(bug 修复契约测试:uk_energy_idempotency 当日二次入账 500)。
+ *
+ * <p><b>bug 现场(2026-11-18 生产)</b>:StreakService.checkAndAwardMilestone 每日打卡能量
+ * {@code awardEnergy(memberId,"streak",0L,5,...)} 无当日守卫,同日第二次任务完成会再次向 energy_log
+ * 插入 (memberId, dim, "streak", 0, 今日) 行 → 撞迁移492唯一键 uk_energy_idempotency →
+ * DuplicateKeyException 污染内层 @Transactional 事务 → 外层 commit 抛 UnexpectedRollbackException → 500。</p>
+ *
+ * <p><b>契约行为(GREEN 目标)</b>:executeAward 逐维度发放前做<b>当日作用域</b>幂等检查
+ * (member+dim+sourceType+sourceId+created_at∈今日 已入账 → 跳过该维度:balance 不自增、不插流水),
+ * 与 uk 键语义精确一致;但检查含日期维度,次日同源发放不受阻断(streak source_id=0 跨日合法)。</p>
+ *
+ * <p><b>测试范围</b>:纯 Mockito(复用 {@link EnergyContractTestBase}),无 Spring 上下文/无 DB;
+ * 直接 new EnergyService() 注入 mock 依赖,走 awardEnergy → executeAward 完整链路。</p>
+ */
+class EnergySameDayIdempotencyContractTest extends EnergyContractTestBase {
+
+    private static final Long MEMBER_ID = 21L;
+
+    private EnergyService service;
+    private EnergyBalanceMapper balanceMapper;
+    private EnergyLogMapper logMapper;
+    private EnergyBalance balance;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new EnergyService();
+        EnergyDimensionMapper dimensionMapper = mock(EnergyDimensionMapper.class);
+        EnergyBehaviorConfigMapper behaviorConfigMapper = mock(EnergyBehaviorConfigMapper.class);
+        logMapper = mock(EnergyLogMapper.class);
+        balanceMapper = mock(EnergyBalanceMapper.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", mock(FamilyMemberMapper.class));
+        inject(service, "notificationDispatchService", mock(NotificationDispatchService.class));
+
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(fiveDims()));
+        when(behaviorConfigMapper.selectOne(any())).thenReturn(null);
+        when(sourceConfigMapper.selectList(any())).thenReturn(Collections.emptyList());
+        when(logMapper.selectList(any())).thenReturn(Collections.emptyList());
+
+        balance = new EnergyBalance();
+        balance.setMemberId(MEMBER_ID);
+        balance.setDimensionId(3L);
+        balance.setBalance(0);
+        balance.setTotalEarned(0);
+        balance.setTotalSpent(0);
+        when(balanceMapper.selectOne(any())).thenReturn(balance);
+
+        initTable(EnergyDimension.class);
+        initTable(EnergyBalance.class);
+        initTable(EnergyLog.class);
+    }
+
+    @Test
+    @DisplayName("同日同源重复入账只发一次:第二次 awardEnergy(streak,0) 不加余额、不插流水、不抛异常")
+    void 当日重复发放_只入账一次() {
+        // selectCount 语义:第1次调用(首发)无当日流水 → 0;第2次调用(同日重放)已有当日流水 → 1
+        when(logMapper.selectCount(any())).thenReturn(0L, 1L);
+
+        Map<String, Integer> first = service.awardEnergy(MEMBER_ID, "streak", 0L, 5, "连续打卡", null);
+        Map<String, Integer> second = service.awardEnergy(MEMBER_ID, "streak", 0L, 5, "连续打卡", null);
+
+        assertEquals(1, first.size(), "首发应正常发放");
+        assertEquals(0, second.size(), "同日重放应被幂等跳过:返回空结果");
+        assertEquals(5, balance.getBalance(), "同日重复发放余额只加一次(5),不得自增至10");
+        verify(balanceMapper, times(1)).updateById(any());
+        verify(logMapper, times(1)).insert(any());
+    }
+
+    @Test
+    @DisplayName("首发正常入账:无当日流水时照常加余额+插流水")
+    void 首发_正常入账() {
+        when(logMapper.selectCount(any())).thenReturn(0L);
+
+        Map<String, Integer> result = service.awardEnergy(MEMBER_ID, "streak", 0L, 5, "连续打卡", null);
+
+        assertEquals(1, result.size());
+        assertEquals(5, balance.getBalance());
+        verify(balanceMapper, times(1)).updateById(any());
+        verify(logMapper, times(1)).insert(any());
+    }
+}