package common.ecommerce.idempotency; import common.ecommerce.error.ChannelException; import common.ecommerce.error.CrossProviderConflictException; import common.ecommerce.error.IdempotencyConflictException; import common.ecommerce.model.ChannelProvider; import common.ecommerce.model.Platform; import common.ecommerce.spi.IdempotencyStatus; import common.ecommerce.testkit.InMemoryIdempotencyStore; import common.ecommerce.testkit.MutableClock; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.Test; import java.time.Duration; import java.time.Instant; import java.util.concurrent.atomic.AtomicInteger; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; /** * 双锁幂等守卫的行为:回放、跨 provider 冲突、并发拒绝、可重试失败、TTL 重抢。 */ class IdempotencyGuardTest { private static final Instant T0 = Instant.parse("2026-10-29T00:00:00Z"); private static final WriteScope MARK_SHIPPED = WriteScope.of( ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001", "1108413237731", "markShipped", "PO-1:pkg-1"); private InMemoryIdempotencyStore store; private MutableClock clock; private IdempotencyGuard guard; @BeforeEach void setUp() { store = new InMemoryIdempotencyStore(); clock = new MutableClock(T0, java.time.ZoneOffset.UTC); guard = new IdempotencyGuard(store, "worker-1", clock, 60); } @Test void firstCallExecutesSecondCallReplays() { AtomicInteger calls = new AtomicInteger(); WriteResult first = guard.execute(MARK_SHIPPED, () -> { calls.incrementAndGet(); return "SHIP-1"; }, v -> v); WriteResult second = guard.execute(MARK_SHIPPED, () -> { calls.incrementAndGet(); return "SHIP-2"; }, v -> v); assertEquals(WriteResult.Outcome.EXECUTED, first.outcome()); assertEquals("SHIP-1", first.resultRef()); assertEquals(WriteResult.Outcome.ALREADY_COMPLETED, second.outcome()); assertEquals("SHIP-1", second.resultRef()); assertNull(second.value()); assertEquals(1, calls.get(), "platform write must happen only once"); } @Test void doubleKeysPersistedWithProviderAndRef() { guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v); assertEquals(IdempotencyStatus.SUCCEEDED, store.get(MARK_SHIPPED.businessKey()).get().status()); assertEquals(IdempotencyStatus.SUCCEEDED, store.get(MARK_SHIPPED.providerKey()).get().status()); assertEquals(ChannelProvider.LINGXING, store.get(MARK_SHIPPED.businessKey()).get().provider()); assertTrue(MARK_SHIPPED.providerKey().startsWith("LINGXING:WALMART_SC:1108413237731:markShipped:")); assertTrue(MARK_SHIPPED.businessKey().startsWith("WALMART_SC:oms-wm-001:PO-1:pkg-1:")); } @Test void sameBusinessActionViaOtherProviderIsConflict() { guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v); WriteScope viaDirect = WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", "wm-seller-01", "markShipped", "PO-1:pkg-1"); assertEquals(MARK_SHIPPED.businessKey(), viaDirect.businessKey()); CrossProviderConflictException ex = assertThrows(CrossProviderConflictException.class, () -> guard.execute(viaDirect, () -> "SHIP-2", v -> v)); assertEquals("LINGXING", ex.completedByProvider()); assertFalse(ex.retryable()); } @Test void concurrentAttemptRejectedWhileInProgress() { store.seedInProgress(MARK_SHIPPED.businessKey(), ChannelProvider.LINGXING, "worker-2", T0); IdempotencyConflictException ex = assertThrows(IdempotencyConflictException.class, () -> guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v)); assertEquals(MARK_SHIPPED.businessKey(), ex.idempotencyKey()); } @Test void retryableFailureAllowsRerun() { ChannelException failure = ChannelException.builder() .message("http 503") .operation("markShipped") .retryable(true) .build(); assertThrows(ChannelException.class, () -> guard.execute(MARK_SHIPPED, () -> { throw failure; }, v -> v)); assertEquals(IdempotencyStatus.FAILED_RETRYABLE, store.get(MARK_SHIPPED.businessKey()).get().status()); assertEquals(IdempotencyStatus.FAILED_RETRYABLE, store.get(MARK_SHIPPED.providerKey()).get().status()); WriteResult retry = guard.execute(MARK_SHIPPED, () -> "SHIP-2", v -> v); assertEquals(WriteResult.Outcome.EXECUTED, retry.outcome()); assertEquals("SHIP-2", retry.resultRef()); } @Test void nonRetryableFailureBlocksAutomaticRetry() { ChannelException failure = ChannelException.builder() .message("http 400") .operation("markShipped") .retryable(false) .build(); assertThrows(ChannelException.class, () -> guard.execute(MARK_SHIPPED, () -> { throw failure; }, v -> v)); assertEquals(IdempotencyStatus.FAILED_FINAL, store.get(MARK_SHIPPED.businessKey()).get().status()); ChannelException ex = assertThrows(ChannelException.class, () -> guard.execute(MARK_SHIPPED, () -> "SHIP-2", v -> v)); assertTrue(ex.getMessage().contains("manual intervention"), ex.getMessage()); assertFalse(ex.retryable()); } @Test void staleInProgressCanBeReclaimedAfterTtl() { store.seedInProgress(MARK_SHIPPED.businessKey(), ChannelProvider.LINGXING, "dead-worker", T0); clock.advance(Duration.ofSeconds(61)); WriteResult result = guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v); assertEquals(WriteResult.Outcome.EXECUTED, result.outcome()); assertEquals(IdempotencyStatus.SUCCEEDED, store.get(MARK_SHIPPED.businessKey()).get().status()); assertEquals("SHIP-1", store.get(MARK_SHIPPED.businessKey()).get().resultRef()); } @Test void providerKeyRecoversCrashWindowWithoutRewriting() { // 模拟:平台已写入、provider 键已记成功,但业务键没来得及写 store.seedSucceeded(MARK_SHIPPED.providerKey(), ChannelProvider.LINGXING, "SHIP-1", T0); AtomicInteger calls = new AtomicInteger(); WriteResult result = guard.execute(MARK_SHIPPED, () -> { calls.incrementAndGet(); return "SHIP-2"; }, v -> v); assertEquals(WriteResult.Outcome.ALREADY_COMPLETED, result.outcome()); assertEquals("SHIP-1", result.resultRef()); assertEquals(0, calls.get(), "must not call platform again"); assertEquals(IdempotencyStatus.SUCCEEDED, store.get(MARK_SHIPPED.businessKey()).get().status()); } @Test void refundKeyMustNotUseAmount() { // 同一退款请求重复提交,金额格式变化不应产生新的业务动作 WriteScope a = WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", "wm-seller-01", "refund", "RET-1:ITEM-1:RFD-1"); WriteScope b = WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", "wm-seller-01", "refund", "RET-1:ITEM-1:RFD-1"); assertEquals(a.businessKey(), b.businessKey()); } @Test void guardOnlyWritesPlatformOnceAcrossRetry() { // 适配器层记录:平台写操作只应发生一次 common.ecommerce.testkit.FakeDirectAdapter adapter = common.ecommerce.testkit.FakeDirectAdapter.builder().build(); guard.execute(MARK_SHIPPED, () -> adapter.markShipped("pkg-1", "1Z-1"), v -> v); guard.execute(MARK_SHIPPED, () -> adapter.markShipped("pkg-1", "1Z-1"), v -> v); assertEquals(1, adapter.writeCallCount()); } @Test void blankScopePartsRejected() { assertThrows(IllegalArgumentException.class, () -> WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", "wm-seller-01", "markShipped", " ")); } @Test void statusLookupForOps() { assertFalse(guard.status(MARK_SHIPPED).isPresent()); guard.execute(MARK_SHIPPED, () -> "SHIP-1", v -> v); assertTrue(guard.status(MARK_SHIPPED).isPresent()); assertTrue(IdempotencyGuard.isRetryableStatus(IdempotencyStatus.FAILED_RETRYABLE)); } }