diff --git a/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java index e20bdef..5fb0040 100644 --- a/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java +++ b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java @@ -79,27 +79,58 @@ public final class Slf4jCallObserver implements CallObserver { @Override public void onCall(CallRecord record) { if (record.failed()) { - LOG.warn("sdk-call-failed at={} op={} provider={} platform={} omsStoreId={} storeId={} " - + "requestId={} cost={}ms result={} failed={} code={} params={} retryable={} platformCode={} " - + "platformRequestId={} error={}: {}", - at(record.occurredAt()), - record.operation(), record.provider(), record.platform(), - record.omsStoreId(), record.externalStoreId(), record.requestId(), - record.durationMillis(), record.resultCount(), record.failedCount(), - record.resultCode(), record.params(), - record.retryable(), record.platformCode(), record.platformRequestId(), - record.errorType(), safe(record.errorMessage())); + LOG.warn("{}", failedLine(record)); } else { - LOG.info("sdk-call at={} op={} provider={} platform={} omsStoreId={} storeId={} " - + "requestId={} cost={}ms result={} failed={} code={} params={}", - at(record.occurredAt()), - record.operation(), record.provider(), record.platform(), - record.omsStoreId(), record.externalStoreId(), record.requestId(), - record.durationMillis(), record.resultCount(), record.failedCount(), - record.resultCode(), record.params()); + LOG.info("{}", successLine(record)); } } + /** + * 成功的日志行(不含级别前缀)。 + * + *

包内可见:日志渲染与 SLF4J 绑定解耦,单测可以直接断言渲染结果, + * 不需要往 classpath 里塞日志实现。

+ */ + String successLine(CallRecord record) { + return "sdk-call at=" + at(record.occurredAt()) + + " op=" + record.operation() + + providerFields(record) + + " cost=" + record.durationMillis() + "ms" + + " result=" + record.resultCount() + + " failed=" + record.failedCount() + + " code=" + record.resultCode() + + " params=" + record.params(); + } + + /** + * 失败的日志行(不含级别前缀)。 + * + *

平台文案不可控,{@link #safe(String)} 会去掉换行/控制字符并截断, + * 避免一条日志被拆成多行(log forging)。

+ */ + String failedLine(CallRecord record) { + return "sdk-call-failed at=" + at(record.occurredAt()) + + " op=" + record.operation() + + providerFields(record) + + " cost=" + record.durationMillis() + "ms" + + " result=" + record.resultCount() + + " failed=" + record.failedCount() + + " code=" + record.resultCode() + + " params=" + record.params() + + " retryable=" + record.retryable() + + " platformCode=" + record.platformCode() + + " platformRequestId=" + record.platformRequestId() + + " error=" + record.errorType() + ": " + safe(record.errorMessage()); + } + + private static String providerFields(CallRecord record) { + return " provider=" + record.provider() + + " platform=" + record.platform() + + " omsStoreId=" + record.omsStoreId() + + " storeId=" + record.externalStoreId() + + " requestId=" + record.requestId(); + } + private String at(Instant instant) { return format(instant); } diff --git a/core/src/test/java/common/ecommerce/audit/Slf4jCallObserverTest.java b/core/src/test/java/common/ecommerce/audit/Slf4jCallObserverTest.java new file mode 100644 index 0000000..407eccf --- /dev/null +++ b/core/src/test/java/common/ecommerce/audit/Slf4jCallObserverTest.java @@ -0,0 +1,235 @@ +package common.ecommerce.audit; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.PlatformBusinessException; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; +import org.junit.jupiter.api.Test; + +import java.time.Instant; +import java.time.ZoneId; +import java.util.Arrays; +import java.util.Collections; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * {@link Slf4jCallObserver} 的日志契约:时区、时间格式、成功/失败字段、控制字符清洗与截断。 + * + *

断言的是包内可见的 {@code successLine} / {@code failedLine} 渲染结果, + * 不依赖 classpath 上有哪个 SLF4J 绑定,也就不会因为宿主换日志实现而失效。

+ */ +class Slf4jCallObserverTest { + + private static final Instant AT = Instant.parse("2026-11-05T00:00:00Z"); + + // ------------------------------------------------------------ 时间显示 + + @Test + void formatsTimeInConfiguredZone() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")); + String line = observer.successLine(record(AT).build()); + + assertTrue(line.contains("at=2026-11-05 08:00:00"), line); + assertFalse(line.contains("Z"), "日志不应出现 UTC 的 Z 后缀:" + line); + } + + @Test + void formatsTimeInUtcWhenConfigured() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("UTC")); + assertTrue(observer.successLine(record(AT).build()).contains("at=2026-11-05 00:00:00")); + } + + @Test + void formatsTimeWithCustomPatternIncludingMillisAndOffset() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"), + "yyyy-MM-dd HH:mm:ss.SSSXXX"); + assertEquals("yyyy-MM-dd HH:mm:ss.SSSXXX", observer.pattern()); + assertEquals("2026-11-05 08:00:00.123+08:00", + observer.format(AT.plusMillis(123))); + } + + @Test + void zoneAndPatternAreExposedForStartupLog() { + Slf4jCallObserver observer = new Slf4jCallObserver( + ZoneId.of("America/Chicago"), "yyyy/MM/dd HH:mm"); + assertEquals("America/Chicago", observer.zone().getId()); + assertEquals("yyyy/MM/dd HH:mm", observer.pattern()); + } + + @Test + void nullArgumentsRejected() { + assertThrows(NullPointerException.class, () -> new Slf4jCallObserver(null)); + assertThrows(NullPointerException.class, () -> new Slf4jCallObserver(ZoneId.of("UTC"), null)); + } + + // ------------------------------------------------------------ 成功 / 失败 + + @Test + void successLineCarriesResultFields() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("UTC")); + String line = observer.successLine(CallRecord.builder() + .occurredAt(AT) + .requestId("req-1") + .provider(ChannelProvider.LINGXING) + .platform(Platform.WALMART_SC) + .omsStoreId("oms-wm-001") + .externalStoreId("store-1") + .operation("salesOrders.pull") + .outcome(CallOutcome.SUCCESS) + .durationMillis(42L) + .resultCount(20) + .failedCount(0) + .params(Collections.singletonMap("pageSize", 20)) + .build()); + + assertTrue(line.startsWith("sdk-call "), line); + assertTrue(line.contains("op=salesOrders.pull"), line); + assertTrue(line.contains("provider=LINGXING"), line); + assertTrue(line.contains("platform=WALMART_SC"), line); + assertTrue(line.contains("omsStoreId=oms-wm-001"), line); + assertTrue(line.contains("storeId=store-1"), line); + assertTrue(line.contains("requestId=req-1"), line); + assertTrue(line.contains("cost=42ms"), line); + assertTrue(line.contains("result=20"), line); + assertTrue(line.contains("failed=0"), line); + assertTrue(line.contains("pageSize=20"), line); + assertFalse(line.contains("error="), "成功日志不应带 error:" + line); + } + + @Test + void partialLineKeepsSuccessPrefixAndFailedCount() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("UTC")); + String line = observer.successLine(CallRecord.builder() + .occurredAt(AT) + .operation("outbounds.review") + .outcome(CallOutcome.PARTIAL) + .resultCount(3) + .failedCount(1) + .build()); + + assertTrue(line.startsWith("sdk-call "), "PARTIAL 拿到了结果,按成功级别记录:" + line); + assertTrue(line.contains("result=3"), line); + assertTrue(line.contains("failed=1"), line); + } + + @Test + void failedLineCarriesPlatformFields() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("UTC")); + ChannelException error = ChannelException.builder() + .message("请求过于频繁") + .operation("salesOrders.pull") + .platformCode("3001008") + .platformRequestId("lx-req-1") + .retryable(true) + .build(); + + String line = observer.failedLine(CallRecord.builder() + .occurredAt(AT) + .requestId("req-1") + .operation("salesOrders.pull") + .outcome(CallOutcome.FAILURE) + .error(error) + .build()); + + assertTrue(line.startsWith("sdk-call-failed "), line); + assertTrue(line.contains("requestId=req-1"), line); + assertTrue(line.contains("retryable=true"), line); + assertTrue(line.contains("platformCode=3001008"), line); + assertTrue(line.contains("platformRequestId=lx-req-1"), line); + assertTrue(line.contains("error=" + ChannelException.class.getName() + ": 请求过于频繁"), line); + } + + @Test + void failedLineKeepsBusinessExceptionTypeAndCode() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("UTC")); + PlatformBusinessException error = new PlatformBusinessException(ChannelException.builder() + .message("shipment review failed for all orders, failNum=2") + .operation("outbounds.review") + .platformCode("3001008") + .retryable(true)); + + String line = observer.failedLine(CallRecord.builder() + .occurredAt(AT) + .operation("outbounds.review") + .outcome(CallOutcome.FAILURE) + .error(error) + .build()); + + assertTrue(line.contains("failNum=2"), line); + assertTrue(line.contains("platformCode=3001008"), line); + assertTrue(line.contains("error=" + PlatformBusinessException.class.getName()), line); + } + + // ------------------------------------------------------------ 清洗与截断 + + @Test + void controlCharactersAreStrippedIntoSingleLine() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("UTC")); + ChannelException error = ChannelException.builder() + .message("第一行\nFAKE LOG LINE\r\n第二行\t结束") + .operation("salesOrders.pull") + .build(); + + String line = observer.failedLine(CallRecord.builder() + .occurredAt(AT) + .operation("salesOrders.pull") + .outcome(CallOutcome.FAILURE) + .error(error) + .build()); + + assertFalse(line.contains("\n"), "换行必须被替换,否则可伪造日志行:" + line); + assertFalse(line.contains("\r"), line); + assertFalse(line.contains("\t"), line); + assertTrue(line.contains("第一行 FAKE LOG LINE"), line); + assertTrue(line.contains("第二行 结束"), line); + } + + @Test + void longMessageIsTruncated() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("UTC")); + char[] filler = new char[2000]; + Arrays.fill(filler, 'x'); + ChannelException error = ChannelException.builder() + .message(new String(filler)) + .operation("salesOrders.pull") + .build(); + + String line = observer.failedLine(CallRecord.builder() + .occurredAt(AT) + .operation("salesOrders.pull") + .outcome(CallOutcome.FAILURE) + .error(error) + .build()); + + assertTrue(line.contains("..."), "超长文案应截断并标记"); + assertFalse(line.contains(new String(filler)), "不应输出完整 2000 字符"); + } + + @Test + void nullErrorMessageRendersAsNull() { + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("UTC")); + String line = observer.failedLine(CallRecord.builder() + .occurredAt(AT) + .operation("writes.markShipped") + .outcome(CallOutcome.FAILURE) + .build()); + + assertTrue(line.contains("error=null: null"), line); + } + + /** 一条成功记录的骨架,测试按需覆盖字段。 */ + private static CallRecord.Builder record(Instant occurredAt) { + return CallRecord.builder() + .occurredAt(occurredAt) + .provider(ChannelProvider.DIRECT) + .platform(Platform.WALMART_SC) + .operation("salesOrders.pull") + .outcome(CallOutcome.SUCCESS) + .resultCount(0) + .failedCount(0); + } +} diff --git a/core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java b/core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java new file mode 100644 index 0000000..7deca99 --- /dev/null +++ b/core/src/test/java/common/ecommerce/idempotency/WriteAuditTest.java @@ -0,0 +1,332 @@ +package common.ecommerce.idempotency; + +import common.ecommerce.audit.CallObserver; +import common.ecommerce.audit.CallOutcome; +import common.ecommerce.audit.CallRecord; +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.IdempotencyClaim; +import common.ecommerce.spi.IdempotencyRecord; +import common.ecommerce.spi.IdempotencyStatus; +import common.ecommerce.spi.IdempotencyStore; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Optional; +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.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 幂等层的审计:每一次裁决都要留一条 {@code writes.} 记录。 + * + *

覆盖 EXECUTED、回放、崩溃窗口修复、并发冲突、终态失败、跨 provider 冲突、 + * 可重试/不可重试失败八种场景。core 不依赖 testkit,这里自带一个最小内存 store。

+ */ +class WriteAuditTest { + + private static final Instant T0 = Instant.parse("2026-11-05T00:00:00Z"); + private static final Clock CLOCK = Clock.fixed(T0, ZoneOffset.UTC); + + private static final WriteScope SCOPE = WriteScope.of( + ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001", "store-1", + "markShipped", "PO-1:pkg-1"); + + private static final class CollectingObserver implements CallObserver { + + private final List records = new ArrayList(); + + @Override + public void onCall(CallRecord record) { + records.add(record); + } + + CallRecord only() { + assertEquals(1, records.size(), "每次写操作只应产生一条幂等层记录"); + return records.get(0); + } + } + + /** 最小内存幂等存储:够覆盖守卫的全部分支。 */ + private static final class MapStore implements IdempotencyStore { + + private final Map records = new LinkedHashMap(); + + @Override + public IdempotencyClaim claim(String key, String owner, ChannelProvider provider, + Instant now, long ttlSeconds) { + IdempotencyRecord existing = records.get(key); + if (existing != null) { + if (existing.status() == IdempotencyStatus.SUCCEEDED) { + return IdempotencyClaim.of(IdempotencyClaim.Outcome.SUCCEEDED, existing); + } + if (existing.status() == IdempotencyStatus.FAILED_FINAL) { + return IdempotencyClaim.of(IdempotencyClaim.Outcome.FAILED_FINAL, existing); + } + if (existing.status() == IdempotencyStatus.IN_PROGRESS + && existing.updatedAt().plusSeconds(ttlSeconds).isAfter(now)) { + return IdempotencyClaim.of(IdempotencyClaim.Outcome.IN_PROGRESS, existing); + } + } + records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.IN_PROGRESS, provider, + owner, null, now)); + return IdempotencyClaim.acquire(); + } + + @Override + public void complete(String key, String owner, String resultRef, Instant now) { + IdempotencyRecord current = records.get(key); + records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.SUCCEEDED, + current.provider(), owner, resultRef, now)); + } + + @Override + public void fail(String key, String owner, boolean retryable, Instant now) { + IdempotencyRecord current = records.get(key); + records.put(key, IdempotencyRecord.of(key, + retryable ? IdempotencyStatus.FAILED_RETRYABLE : IdempotencyStatus.FAILED_FINAL, + current.provider(), owner, null, now)); + } + + @Override + public Optional get(String key) { + return Optional.ofNullable(records.get(key)); + } + + void seedSucceeded(String key, ChannelProvider provider, String resultRef) { + records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.SUCCEEDED, provider, + "other-worker", resultRef, T0)); + } + + void seedInProgress(String key, ChannelProvider provider, String owner) { + records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.IN_PROGRESS, provider, + owner, null, T0)); + } + } + + private MapStore store; + private CollectingObserver observer; + private IdempotencyGuard guard; + + @BeforeEach + void setUp() { + store = new MapStore(); + observer = new CollectingObserver(); + guard = new IdempotencyGuard(store, "worker-1", CLOCK, + IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS, observer); + } + + // ------------------------------------------------------------ 成功路径 + + @Test + void executedWriteIsRecorded() { + WriteResult result = guard.execute(SCOPE, () -> "SHIP-1", v -> v); + + assertEquals(WriteResult.Outcome.EXECUTED, result.outcome()); + + CallRecord record = observer.only(); + assertEquals("writes.markShipped", record.operation(), "操作名要带 writes. 前缀"); + assertEquals(CallOutcome.SUCCESS, record.outcome()); + assertEquals(ChannelProvider.LINGXING, record.provider()); + assertEquals(Platform.WALMART_SC, record.platform()); + assertEquals("oms-wm-001", record.omsStoreId()); + assertEquals(SCOPE.businessKey(), record.params().get("businessKey")); + assertEquals(SCOPE.providerKey(), record.params().get("providerKey")); + assertEquals("EXECUTED", record.params().get("stage")); + assertEquals("SHIP-1", record.params().get("resultRef")); + assertEquals(0, record.failedCount()); + assertFalse(record.failed()); + } + + @Test + void replayIsRecordedAsSuccessWithStage() { + guard.execute(SCOPE, () -> "SHIP-1", v -> v); + WriteResult replay = guard.execute(SCOPE, () -> "SHIP-2", v -> v); + + assertEquals(WriteResult.Outcome.ALREADY_COMPLETED, replay.outcome()); + assertEquals("SHIP-1", replay.resultRef()); + + assertEquals(2, observer.records.size(), "首次执行与回放各一条"); + CallRecord last = observer.records.get(1); + assertEquals(CallOutcome.SUCCESS, last.outcome(), "回放不是失败"); + assertEquals("ALREADY_COMPLETED", last.params().get("stage")); + assertEquals("SHIP-1", last.params().get("resultRef")); + } + + @Test + void crashWindowRepairIsRecordedWithItsOwnStage() { + // provider 键已成功、业务键没记上 + store.seedSucceeded(SCOPE.providerKey(), ChannelProvider.LINGXING, "SHIP-9"); + AtomicInteger calls = new AtomicInteger(); + + WriteResult result = guard.execute(SCOPE, () -> { + calls.incrementAndGet(); + return "SHIP-NEW"; + }, v -> v); + + assertEquals(WriteResult.Outcome.ALREADY_COMPLETED, result.outcome()); + assertEquals("SHIP-9", result.resultRef()); + assertEquals(0, calls.get(), "不得再次调用平台"); + + CallRecord record = observer.only(); + assertEquals(CallOutcome.SUCCESS, record.outcome()); + assertEquals("REPAIRED_FROM_PROVIDER_KEY", record.params().get("stage")); + assertEquals("SHIP-9", record.params().get("resultRef")); + } + + // ------------------------------------------------------------ 冲突与失败 + + @Test + void inProgressConflictIsRecordedAsFailure() { + store.seedInProgress(SCOPE.businessKey(), ChannelProvider.LINGXING, "worker-2"); + + assertThrows(IdempotencyConflictException.class, + () -> guard.execute(SCOPE, () -> "SHIP-1", v -> v)); + + CallRecord record = observer.only(); + assertEquals(CallOutcome.FAILURE, record.outcome()); + assertEquals("IN_PROGRESS", record.params().get("stage")); + assertEquals("worker-2", record.params().get("owner")); + assertNotNull(record.errorType()); + assertTrue(record.errorType().contains("IdempotencyConflictException"), record.errorType()); + } + + @Test + void failedFinalIsRecordedAsFailure() { + ChannelException fatal = ChannelException.builder() + .message("http 400") + .operation("markShipped") + .retryable(false) + .build(); + assertThrows(ChannelException.class, () -> guard.execute(SCOPE, () -> { + throw fatal; + }, v -> v)); + + // 第二次:终态,守卫直接拒绝 + ChannelException blocked = assertThrows(ChannelException.class, + () -> guard.execute(SCOPE, () -> "SHIP-2", v -> v)); + assertFalse(blocked.retryable()); + + assertEquals(2, observer.records.size()); + CallRecord last = observer.records.get(1); + assertEquals(CallOutcome.FAILURE, last.outcome()); + assertEquals("FAILED_FINAL", last.params().get("stage")); + } + + @Test + void crossProviderConflictIsRecordedAsFailure() { + guard.execute(SCOPE, () -> "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(SCOPE.businessKey(), viaDirect.businessKey()); + + assertThrows(CrossProviderConflictException.class, + () -> guard.execute(viaDirect, () -> "SHIP-2", v -> v)); + + CallRecord last = observer.records.get(observer.records.size() - 1); + assertEquals(CallOutcome.FAILURE, last.outcome()); + assertEquals("CROSS_PROVIDER_CONFLICT", last.params().get("stage")); + assertEquals("LINGXING", last.params().get("completedByProvider")); + assertEquals(ChannelProvider.DIRECT, last.provider(), "记录的是本次请求的 provider"); + } + + @Test + void retryableFailureIsRecordedAsFailureAndRerunSucceeds() { + ChannelException failure = ChannelException.builder() + .message("http 503") + .operation("markShipped") + .retryable(true) + .build(); + + assertThrows(ChannelException.class, () -> guard.execute(SCOPE, () -> { + throw failure; + }, v -> v)); + + CallRecord attempt = observer.only(); + assertEquals(CallOutcome.FAILURE, attempt.outcome()); + assertEquals("FAILED_RETRYABLE", attempt.params().get("stage")); + assertEquals(Boolean.TRUE, attempt.params().get("retryable")); + assertEquals(true, attempt.retryable()); + + WriteResult retry = guard.execute(SCOPE, () -> "SHIP-2", v -> v); + assertEquals(WriteResult.Outcome.EXECUTED, retry.outcome()); + assertEquals(2, observer.records.size()); + assertEquals(CallOutcome.SUCCESS, observer.records.get(1).outcome()); + } + + @Test + void nonRetryableFailureIsRecordedAsFinalFailure() { + ChannelException failure = ChannelException.builder() + .message("http 400") + .operation("markShipped") + .retryable(false) + .build(); + + assertThrows(ChannelException.class, () -> guard.execute(SCOPE, () -> { + throw failure; + }, v -> v)); + + CallRecord record = observer.only(); + assertEquals(CallOutcome.FAILURE, record.outcome()); + assertEquals("FAILED", record.params().get("stage")); + assertEquals(Boolean.FALSE, record.params().get("retryable")); + assertEquals(IdempotencyStatus.FAILED_FINAL, store.get(SCOPE.businessKey()).get().status()); + } + + // ------------------------------------------------------------ 观察者与兼容性 + + @Test + void observerFailureDoesNotBreakWrite() { + CallObserver broken = new CallObserver() { + @Override + public void onCall(CallRecord record) { + throw new IllegalStateException("observer down"); + } + }; + IdempotencyGuard guarded = new IdempotencyGuard(store, "worker-1", CLOCK, + IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS, broken); + + WriteResult result = guarded.execute(SCOPE, () -> "SHIP-1", v -> v); + assertEquals(WriteResult.Outcome.EXECUTED, result.outcome(), "埋点失败不能影响写结果"); + assertEquals(IdempotencyStatus.SUCCEEDED, store.get(SCOPE.businessKey()).get().status()); + } + + @Test + void guardWithoutObserverStillWorks() { + IdempotencyGuard silent = new IdempotencyGuard(store, "worker-1", CLOCK, 60); + assertEquals(WriteResult.Outcome.EXECUTED, + silent.execute(SCOPE, () -> "SHIP-1", v -> v).outcome()); + assertEquals(0, observer.records.size(), "没有注入观察者就不该产生记录"); + } + + @Test + void operationNamePrefixesAction() { + assertEquals("writes.markShipped", WriteAudit.operation(SCOPE)); + assertEquals("writes.", WriteAudit.OPERATION_PREFIX); + } + + @Test + void paramsCarryBothKeysAndStage() { + Map params = WriteAudit.params(SCOPE, WriteAudit.Stage.EXECUTED, + "resultRef", null); + assertEquals(SCOPE.businessKey(), params.get("businessKey")); + assertEquals(SCOPE.providerKey(), params.get("providerKey")); + assertEquals("EXECUTED", params.get("stage")); + assertTrue(params.containsKey("resultRef")); + } +} diff --git a/core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java b/core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java new file mode 100644 index 0000000..ae826ab --- /dev/null +++ b/core/src/test/java/common/ecommerce/sdk/RequestIdAndCoverageTest.java @@ -0,0 +1,258 @@ +package common.ecommerce.sdk; + +import common.ecommerce.audit.CallObserver; +import common.ecommerce.audit.CallOutcome; +import common.ecommerce.audit.CallRecord; +import common.ecommerce.audit.Slf4jCallObserver; +import common.ecommerce.capability.CapabilityReport; +import common.ecommerce.model.Capability; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; +import common.ecommerce.model.account.AccountKey; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.order.SalesOrder; +import common.ecommerce.model.order.SalesOrderQuery; +import common.ecommerce.model.support.Page; +import common.ecommerce.spi.ChannelSecret; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneId; +import java.time.ZoneOffset; +import java.util.ArrayList; +import java.util.HashSet; +import java.util.List; +import java.util.Set; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 链路 ID 粒度与覆盖盲区:每次调用独立 requestId、可注入生成器、capabilities 埋点、启动日志。 + */ +class RequestIdAndCoverageTest { + + private static final AccountKey KEY = + AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001"); + + private static final ChannelConnection CONNECTION = ChannelConnection.of( + "https://api.example.com", + ChannelSecret.builder().appKey("ak").appSecret("sk").build()); + + private static final Clock CLOCK = + Clock.fixed(Instant.parse("2026-11-05T00:00:00Z"), ZoneOffset.UTC); + + private static final class CollectingObserver implements CallObserver { + + private final List records = new ArrayList(); + + @Override + public void onCall(CallRecord record) { + records.add(record); + } + } + + private static ChannelAccount account() { + return ChannelAccount.builder() + .key(KEY) + .externalStoreId("wm-seller-01") + .credentialRef("test") + .marketplaceZone("America/Chicago") + .currency("USD") + .build(); + } + + private static ChannelSdk.Builder builder(CallObserver observer) { + return ChannelSdk.builder() + .accountRepository(new ChannelSdkTest.FixedAccounts(account())) + .clock(CLOCK) + .register(new ChannelSdkTest.FakeDirectAdapter()) + .callObserver(observer); + } + + private static SalesOrderQuery query() { + return SalesOrderQuery.builder().updatedAfter(Instant.EPOCH).build(); + } + + // ------------------------------------------------------------ 每次调用独立 ID + + @Test + void everyFacadeViewGetsItsOwnRequestId() { + CollectingObserver observer = new CollectingObserver(); + ChannelSdk sdk = builder(observer).build(); + + sdk.salesOrders(KEY, CONNECTION).pull(query()); + sdk.salesOrders(KEY, CONNECTION).pull(query()); + + assertEquals(2, observer.records.size()); + String first = observer.records.get(0).requestId(); + String second = observer.records.get(1).requestId(); + assertNotNull(first); + assertNotNull(second); + assertNotEquals(first, second, "两次取视图必须各自拿到独立的 requestId"); + } + + @Test + void cachedViewCanRefreshRequestIdPerCall() { + CollectingObserver observer = new CollectingObserver(); + ChannelSdk sdk = builder(observer).build(); + + // 宿主缓存门面对象时,同一个对象反复调用会共用取视图时的 ID + SalesOrdersFacadeHolder holder = new SalesOrdersFacadeHolder(); + holder.view = sdk.salesOrders(KEY, CONNECTION); + holder.view.pull(query()); + String cached = observer.records.get(0).requestId(); + holder.view.pull(query()); + assertEquals(cached, observer.records.get(1).requestId(), + "未刷新时就是共用同一个 ID,这是已知的取值范围"); + + // 用 withRequestId 显式换新 ID + AtomicInteger counter = new AtomicInteger(); + holder.view.withRequestId("trace-" + counter.incrementAndGet()).pull(query()); + holder.view.withRequestId("trace-" + counter.incrementAndGet()).pull(query()); + + Set ids = new HashSet(); + for (CallRecord record : observer.records) { + ids.add(record.requestId()); + } + assertEquals(4, ids.size(), "刷新后每条记录应有不同的 requestId"); + assertTrue(ids.contains("trace-1")); + assertTrue(ids.contains("trace-2")); + } + + @Test + void requestIdSupplierBridgesHostTraceId() { + CollectingObserver observer = new CollectingObserver(); + AtomicInteger counter = new AtomicInteger(); + ChannelSdk sdk = builder(observer) + .requestIdSupplier(() -> "trace-" + counter.incrementAndGet()) + .build(); + + sdk.salesOrders(KEY, CONNECTION).pull(query()); + sdk.salesOrders(KEY, CONNECTION).pull(query()); + + assertEquals("trace-1", observer.records.get(0).requestId()); + assertEquals("trace-2", observer.records.get(1).requestId()); + } + + @Test + void blankRequestIdFailsFastInsteadOfSilentlyPassing() { + ChannelSdk sdk = builder(new CollectingObserver()) + .requestIdSupplier(() -> " ") + .build(); + + IllegalStateException ex = assertThrows(IllegalStateException.class, + () -> sdk.salesOrders(KEY, CONNECTION)); + assertTrue(ex.getMessage().contains("requestIdSupplier"), ex.getMessage()); + } + + @Test + void contextWithRequestIdKeepsOtherFields() { + ChannelContext ctx = ChannelContext.of(account(), CONNECTION, "req-1", CLOCK); + ChannelContext copy = ctx.withRequestId("req-2"); + + assertEquals("req-2", copy.requestId()); + assertEquals("req-1", ctx.requestId(), "原对象不变,避免缓存对象被串号"); + assertEquals(KEY, copy.key()); + assertEquals("wm-seller-01", copy.account().externalStoreId()); + assertEquals("https://api.example.com", copy.endpointBaseUrl()); + } + + // ------------------------------------------------------------ capabilities 埋点 + + @Test + void capabilitiesIsNowObserved() { + CollectingObserver observer = new CollectingObserver(); + ChannelSdk sdk = builder(observer).build(); + + CapabilityReport report = sdk.capabilities(KEY); + + assertTrue(report.supports(Capability.SALES_ORDER)); + assertEquals(1, observer.records.size(), "capabilities 也要留一条记录"); + + CallRecord record = observer.records.get(0); + assertEquals("capabilities", record.operation()); + assertEquals(CallOutcome.SUCCESS, record.outcome()); + assertEquals(ChannelProvider.DIRECT, record.provider()); + assertEquals(Platform.WALMART_SC, record.platform()); + assertEquals("oms-wm-001", record.omsStoreId()); + assertEquals("wm-seller-01", record.externalStoreId()); + assertNotNull(record.requestId()); + } + + @Test + void missingAccountIsObservedAsFailureInsteadOfSilence() { + CollectingObserver observer = new CollectingObserver(); + ChannelSdk sdk = builder(observer).build(); + + AccountKey unknown = AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-unknown"); + assertThrows(IllegalStateException.class, () -> sdk.capabilities(unknown)); + + assertEquals(1, observer.records.size(), "账户没配好也要留痕,这是上线初期最常见的故障"); + CallRecord record = observer.records.get(0); + assertEquals("capabilities", record.operation()); + assertEquals(CallOutcome.FAILURE, record.outcome()); + assertEquals("oms-unknown", record.omsStoreId()); + assertEquals(null, record.externalStoreId()); + assertTrue(record.errorMessage().contains("not configured"), record.errorMessage()); + } + + @Test + void missingAdapterIsObservedAsFailure() { + CollectingObserver observer = new CollectingObserver(); + ChannelSdk sdk = builder(observer).build(); + + // 账户存在,但没有注册 LINGXING 的适配器 + AccountKey lingxing = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001"); + ChannelAccount lingxingAccount = ChannelAccount.builder() + .key(lingxing) + .externalStoreId("store-1") + .credentialRef("test") + .marketplaceZone("America/Chicago") + .currency("USD") + .build(); + ChannelSdk withLingxingAccount = ChannelSdk.builder() + .accountRepository(new ChannelSdkTest.FixedAccounts(lingxingAccount)) + .clock(CLOCK) + .register(new ChannelSdkTest.FakeDirectAdapter()) + .callObserver(observer) + .build(); + + assertThrows(IllegalStateException.class, () -> withLingxingAccount.capabilities(lingxing)); + + CallRecord record = observer.records.get(0); + assertEquals(CallOutcome.FAILURE, record.outcome()); + assertTrue(record.errorMessage().contains("no adapter registered"), record.errorMessage()); + } + + // ------------------------------------------------------------ 启动日志 + + @Test + void buildLogsStartupSummary() { + // 启动日志走 Slf4jCallObserver 用同一个 logger 体系;这里只验证装配不报错、 + // 且把 Slf4jCallObserver 作为观察者时 zone 能被识别 + Slf4jCallObserver observer = new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")); + ChannelSdk sdk = builder(observer).build(); + assertNotNull(sdk); + assertEquals("Asia/Shanghai", observer.zone().getId()); + } + + /** 只为了让「缓存门面对象」的写法更像宿主代码。 */ + private static final class SalesOrdersFacadeHolder { + + private common.ecommerce.capability.SalesOrders view; + } + + /** 冒烟:确认空页也能正常返回,避免上面用例受 FakeDirectAdapter 行为影响。 */ + @Test + void fakeAdapterReturnsEmptyPage() { + ChannelSdk sdk = builder(new CollectingObserver()).build(); + Page page = sdk.salesOrders(KEY, CONNECTION).pull(query()); + assertEquals(0, page.size()); + } +}