diff --git a/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java b/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java
new file mode 100644
index 0000000..cba4218
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java
@@ -0,0 +1,182 @@
+package common.ecommerce.idempotency;
+
+import common.ecommerce.error.ChannelException;
+import common.ecommerce.error.CrossProviderConflictException;
+import common.ecommerce.error.IdempotencyConflictException;
+import common.ecommerce.spi.IdempotencyClaim;
+import common.ecommerce.spi.IdempotencyRecord;
+import common.ecommerce.spi.IdempotencyStatus;
+import common.ecommerce.spi.IdempotencyStore;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.UUID;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+/**
+ * 写操作幂等守卫:业务键 + provider 请求键双锁。
+ *
+ *
+ * 1. 抢占业务键(不带 provider)——直连与聚合器共用,同一业务动作只成功一次
+ * 2. 抢占 provider 请求键(带 provider)——单 provider 内重试去重
+ * 3. 执行平台写操作
+ * 4. 先记 provider 键成功,再记业务键成功;中途崩溃时下次重试能靠 provider 键识别「已写过」
+ *
+ *
+ * 语义:
+ *
+ * - 业务键已 SUCCEEDED:返回 {@link WriteResult.Outcome#ALREADY_COMPLETED},不视为失败
+ * - 业务键已完成但由另一个 provider 完成:抛 {@link CrossProviderConflictException},不自动跨 provider 重试
+ * - 业务键 IN_PROGRESS:抛 {@link IdempotencyConflictException},拒绝并发重复
+ * - 业务键 FAILED_FINAL:抛终态异常,需人工介入
+ * - 可重试失败:两个键记为 FAILED_RETRYABLE,下次调用可重新抢占
+ *
+ *
+ * 守卫不碰平台协议,也不自行重试;重试由宿主调度决定。
+ */
+public final class IdempotencyGuard {
+
+ public static final long DEFAULT_CLAIM_TTL_SECONDS = 300L;
+
+ private final IdempotencyStore store;
+ private final String owner;
+ private final Clock clock;
+ private final long claimTtlSeconds;
+
+ public IdempotencyGuard(IdempotencyStore store, Clock clock) {
+ this(store, UUID.randomUUID().toString(), clock, DEFAULT_CLAIM_TTL_SECONDS);
+ }
+
+ public IdempotencyGuard(IdempotencyStore store, String owner, Clock clock, long claimTtlSeconds) {
+ this.store = Objects.requireNonNull(store, "store");
+ this.owner = Objects.requireNonNull(owner, "owner");
+ this.clock = Objects.requireNonNull(clock, "clock");
+ if (claimTtlSeconds <= 0) {
+ throw new IllegalArgumentException("claimTtlSeconds must be positive");
+ }
+ this.claimTtlSeconds = claimTtlSeconds;
+ }
+
+ /**
+ * 执行一次写操作。
+ *
+ * @param scope 标识维度
+ * @param action 平台写操作;抛 {@link ChannelException} 时按其 {@code retryable()} 决定是否可重试
+ * @param resultRef 从执行结果中提取结果引用(订单号 / 包裹号等),可为 null
+ */
+ public WriteResult execute(WriteScope scope, Supplier action, Function super T, String> resultRef) {
+ Objects.requireNonNull(scope, "scope");
+ Objects.requireNonNull(action, "action");
+ Objects.requireNonNull(resultRef, "resultRef");
+
+ final String businessKey = scope.businessKey();
+ final String providerKey = scope.providerKey();
+ final Instant now = Instant.now(clock);
+
+ // 1) 业务键:跨 provider 的最终裁决
+ IdempotencyClaim business = store.claim(businessKey, owner, scope.provider(), now, claimTtlSeconds);
+ if (!business.acquired()) {
+ return handleNotAcquired(scope, business, businessKey, providerKey);
+ }
+
+ // 2) provider 键:识别「平台已写、业务键没来得及记成功」的崩溃窗口
+ IdempotencyClaim provider = store.claim(providerKey, owner, scope.provider(), now, claimTtlSeconds);
+ if (!provider.acquired()) {
+ if (provider.outcome() == IdempotencyClaim.Outcome.SUCCEEDED) {
+ store.complete(businessKey, owner, provider.record().resultRef(), Instant.now(clock));
+ return replay(scope, provider.record(), businessKey, providerKey);
+ }
+ store.fail(businessKey, owner, provider.outcome() != IdempotencyClaim.Outcome.FAILED_FINAL,
+ Instant.now(clock));
+ return handleNotAcquired(scope, provider, businessKey, providerKey);
+ }
+
+ // 3) 执行
+ T value;
+ try {
+ value = action.get();
+ } catch (RuntimeException e) {
+ boolean retryable = isRetryable(e);
+ store.fail(providerKey, owner, retryable, Instant.now(clock));
+ store.fail(businessKey, owner, retryable, Instant.now(clock));
+ throw e;
+ }
+
+ // 4) 先记 provider 键,再记业务键
+ String ref = resultRef.apply(value);
+ store.complete(providerKey, owner, ref, Instant.now(clock));
+ store.complete(businessKey, owner, ref, Instant.now(clock));
+ return WriteResult.executed(value, ref, businessKey, providerKey);
+ }
+
+ // ---------------------------------------------------------------- internals
+
+ private WriteResult handleNotAcquired(WriteScope scope, IdempotencyClaim claim,
+ String businessKey, String providerKey) {
+ IdempotencyRecord record = claim.record();
+ switch (claim.outcome()) {
+ case SUCCEEDED:
+ return replay(scope, record, businessKey, providerKey);
+ case IN_PROGRESS:
+ throw new IdempotencyConflictException(ChannelException.builder()
+ .message("write already in progress: " + providerKey)
+ .operation(scope.action())
+ .provider(scope.provider().name())
+ .omsStoreId(scope.omsStoreId())
+ .platform(scope.platform()), businessKey);
+ case FAILED_FINAL:
+ throw ChannelException.builder()
+ .message("previous attempt failed permanently, manual intervention required: " + businessKey)
+ .operation(scope.action())
+ .provider(scope.provider().name())
+ .omsStoreId(scope.omsStoreId())
+ .platform(scope.platform())
+ .retryable(false)
+ .build();
+ default:
+ throw new IllegalStateException("unexpected claim outcome " + claim.outcome() + " for " + businessKey);
+ }
+ }
+
+ private WriteResult replay(WriteScope scope, IdempotencyRecord record,
+ String businessKey, String providerKey) {
+ if (record.provider() != null && record.provider() != scope.provider()) {
+ throw new CrossProviderConflictException(ChannelException.builder()
+ .message("business action already completed by " + record.provider()
+ + ", requested via " + scope.provider() + ": " + businessKey)
+ .operation(scope.action())
+ .provider(scope.provider().name())
+ .omsStoreId(scope.omsStoreId())
+ .platform(scope.platform())
+ .retryable(false), record.provider().name());
+ }
+ return WriteResult.alreadyCompleted(record.resultRef(), businessKey, providerKey);
+ }
+
+ /**
+ * 只有显式标记可重试的 {@link ChannelException} 才允许重跑。
+ *
+ * 超时等「结果未知」的异常由适配器先回查再抛:确认未写入抛可重试异常,
+ * 确认已写入应当返回成功,而不是抛异常。
+ */
+ private static boolean isRetryable(RuntimeException e) {
+ return e instanceof ChannelException && ((ChannelException) e).retryable();
+ }
+
+ public String owner() {
+ return owner;
+ }
+
+ /** 只读查询,供运维排查。 */
+ public Optional status(WriteScope scope) {
+ return store.get(scope.businessKey());
+ }
+
+ /** 该状态是否可安全重跑。 */
+ public static boolean isRetryableStatus(IdempotencyStatus status) {
+ return status == IdempotencyStatus.FAILED_RETRYABLE;
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/idempotency/WriteResult.java b/core/src/main/java/common/ecommerce/idempotency/WriteResult.java
new file mode 100644
index 0000000..d0accd8
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/idempotency/WriteResult.java
@@ -0,0 +1,71 @@
+package common.ecommerce.idempotency;
+
+/**
+ * 写操作执行结果。
+ *
+ * 重复调用不视为失败:{@link Outcome#ALREADY_COMPLETED} 表示该业务动作此前已成功,
+ * 本次没有再次调用平台。
+ */
+public final class WriteResult {
+
+ public enum Outcome {
+ /** 本次真正执行了平台写操作。 */
+ EXECUTED,
+ /** 此前已成功,本次直接回放,未调用平台。 */
+ ALREADY_COMPLETED
+ }
+
+ private final Outcome outcome;
+ private final T value;
+ private final String resultRef;
+ private final String businessKey;
+ private final String providerKey;
+
+ private WriteResult(Outcome outcome, T value, String resultRef, String businessKey, String providerKey) {
+ this.outcome = outcome;
+ this.value = value;
+ this.resultRef = resultRef;
+ this.businessKey = businessKey;
+ this.providerKey = providerKey;
+ }
+
+ public static WriteResult executed(T value, String resultRef, String businessKey, String providerKey) {
+ return new WriteResult(Outcome.EXECUTED, value, resultRef, businessKey, providerKey);
+ }
+
+ /** 回放:没有本次调用的返回值,只有上次记录的结果引用。 */
+ public static WriteResult alreadyCompleted(String resultRef, String businessKey, String providerKey) {
+ return new WriteResult(Outcome.ALREADY_COMPLETED, null, resultRef, businessKey, providerKey);
+ }
+
+ public Outcome outcome() {
+ return outcome;
+ }
+
+ /** 本次执行结果;ALREADY_COMPLETED 时为 null。 */
+ public T value() {
+ return value;
+ }
+
+ /** 结果引用(订单号 / 包裹号等);可能为 null。 */
+ public String resultRef() {
+ return resultRef;
+ }
+
+ public String businessKey() {
+ return businessKey;
+ }
+
+ public String providerKey() {
+ return providerKey;
+ }
+
+ public boolean alreadyCompleted() {
+ return outcome == Outcome.ALREADY_COMPLETED;
+ }
+
+ @Override
+ public String toString() {
+ return "WriteResult{" + outcome + (resultRef == null ? "" : " -> " + resultRef) + '}';
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/idempotency/WriteScope.java b/core/src/main/java/common/ecommerce/idempotency/WriteScope.java
new file mode 100644
index 0000000..2257647
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/idempotency/WriteScope.java
@@ -0,0 +1,92 @@
+package common.ecommerce.idempotency;
+
+import common.ecommerce.model.support.CanonicalKeys;
+import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.model.Platform;
+
+import java.util.Objects;
+
+/**
+ * 一次写操作的标识维度,由业务键与 provider 请求键共同组成。
+ *
+ *
+ * - 业务键:{@code platform + omsStoreId + businessRef + action},不带 provider,
+ * 直连与聚合器共用,保证同一业务动作只成功一次
+ * - provider 请求键:{@code provider + platform + externalStoreId + operation + providerRef},
+ * 只防单 provider 内的重复请求/重试
+ *
+ */
+public final class WriteScope {
+
+ private final ChannelProvider provider;
+ private final Platform platform;
+ private final String omsStoreId;
+ private final String externalStoreId;
+ private final String action;
+ private final String businessRef;
+
+ private WriteScope(ChannelProvider provider, Platform platform, String omsStoreId, String externalStoreId,
+ String action, String businessRef) {
+ this.provider = Objects.requireNonNull(provider, "provider");
+ this.platform = Objects.requireNonNull(platform, "platform");
+ this.omsStoreId = requireText(omsStoreId, "omsStoreId");
+ this.externalStoreId = requireText(externalStoreId, "externalStoreId");
+ this.action = requireText(action, "action");
+ this.businessRef = requireText(businessRef, "businessRef");
+ }
+
+ /**
+ * @param businessRef 业务自然键,如 {@code PO-1:pkg-1} 或 {@code RET-1:ITEM-1:REFUND-1};
+ * 不得使用金额
+ */
+ public static WriteScope of(ChannelProvider provider, Platform platform, String omsStoreId,
+ String externalStoreId, String action, String businessRef) {
+ return new WriteScope(provider, platform, omsStoreId, externalStoreId, action, businessRef);
+ }
+
+ public ChannelProvider provider() {
+ return provider;
+ }
+
+ public Platform platform() {
+ return platform;
+ }
+
+ public String omsStoreId() {
+ return omsStoreId;
+ }
+
+ public String externalStoreId() {
+ return externalStoreId;
+ }
+
+ public String action() {
+ return action;
+ }
+
+ public String businessRef() {
+ return businessRef;
+ }
+
+ /** 跨 provider 的业务幂等键。 */
+ public String businessKey() {
+ return CanonicalKeys.businessIdempotencyKey(platform, omsStoreId, businessRef, action);
+ }
+
+ /** 单 provider 内的请求幂等键。 */
+ public String providerKey() {
+ return CanonicalKeys.providerRequestKey(provider, platform, externalStoreId, action, businessRef);
+ }
+
+ @Override
+ public String toString() {
+ return provider + ":" + platform + ":" + omsStoreId + ":" + action + ":" + businessRef;
+ }
+
+ private static String requireText(String value, String name) {
+ if (value == null || value.trim().isEmpty()) {
+ throw new IllegalArgumentException(name + " must not be blank");
+ }
+ return value.trim();
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
index 154ade2..c96a6dc 100644
--- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
+++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
@@ -1,13 +1,16 @@
package common.ecommerce.sdk;
+import common.ecommerce.model.Platform;
import common.ecommerce.capability.AdapterCapabilityReport;
import common.ecommerce.capability.CapabilityReport;
import common.ecommerce.capability.PlatformAdapter;
import common.ecommerce.capability.Products;
import common.ecommerce.capability.SalesOrders;
+import common.ecommerce.idempotency.IdempotencyGuard;
import common.ecommerce.model.account.AccountKey;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.spi.ChannelAccountRepository;
+import common.ecommerce.spi.IdempotencyStore;
import java.time.Clock;
import java.util.ArrayList;
@@ -34,11 +37,15 @@ public final class ChannelSdk implements ProviderResolver {
private final Map adapters;
private final ChannelAccountRepository accountRepository;
private final Clock clock;
+ private final IdempotencyGuard idempotencyGuard;
private ChannelSdk(Builder b) {
this.adapters = Collections.unmodifiableMap(new LinkedHashMap(b.adapters));
this.accountRepository = b.accountRepository;
this.clock = b.clock;
+ this.idempotencyGuard = b.idempotencyStore == null ? null
+ : new IdempotencyGuard(b.idempotencyStore, b.idempotencyOwner, b.clock,
+ IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS);
}
public static Builder builder() {
@@ -65,6 +72,19 @@ public final class ChannelSdk implements ProviderResolver {
return new Products(resolve(key), account, newContext(account));
}
+ /**
+ * 写操作幂等守卫(业务键 + provider 请求键双锁)。
+ *
+ * 写操作必须经守卫执行;未注入 {@code IdempotencyStore} 时直接失败,
+ * 不提供「无幂等」的降级路径。
+ */
+ public IdempotencyGuard writes() {
+ if (idempotencyGuard == null) {
+ throw new IllegalStateException("ChannelSdk requires an idempotencyStore for write operations");
+ }
+ return idempotencyGuard;
+ }
+
/** 按 AccountKey 解析适配器;不自动选路、不自动兜底。 */
@Override
public PlatformAdapter resolve(AccountKey key) {
@@ -99,6 +119,8 @@ public final class ChannelSdk implements ProviderResolver {
private final Map adapters = new LinkedHashMap();
private final List factories = new ArrayList();
private ChannelAccountRepository accountRepository;
+ private IdempotencyStore idempotencyStore;
+ private String idempotencyOwner = UUID.randomUUID().toString();
private Clock clock = Clock.systemUTC();
/** 注入账户仓库;宿主实现。 */
@@ -113,6 +135,18 @@ public final class ChannelSdk implements ProviderResolver {
return this;
}
+ /** 注入幂等存储;不注入时调用 {@link ChannelSdk#writes()} 会失败。 */
+ public Builder idempotencyStore(IdempotencyStore idempotencyStore) {
+ this.idempotencyStore = idempotencyStore;
+ return this;
+ }
+
+ /** 抢占方标识,多实例部署时应能区分;缺省随机 UUID。 */
+ public Builder idempotencyOwner(String owner) {
+ this.idempotencyOwner = Objects.requireNonNull(owner, "owner");
+ return this;
+ }
+
/** 注册适配器工厂;工厂覆盖的平台会在 build 时创建并注册。 */
public Builder register(AdapterFactory factory) {
this.factories.add(Objects.requireNonNull(factory, "factory"));
@@ -131,7 +165,7 @@ public final class ChannelSdk implements ProviderResolver {
/** 直接注册适配器实例,主要用于测试替身。 */
public Builder register(PlatformAdapter adapter) {
Objects.requireNonNull(adapter, "adapter");
- for (common.ecommerce.model.Platform p : adapter.platforms()) {
+ for (Platform p : adapter.platforms()) {
put(adapter.provider().name() + '|' + p.name(), adapter);
}
return this;
diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java b/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java
new file mode 100644
index 0000000..8a10d5c
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java
@@ -0,0 +1,57 @@
+package common.ecommerce.spi;
+
+/**
+ * 抢占幂等键的结果。
+ *
+ * 宿主实现 {@link IdempotencyStore#claim} 时按以下规则返回:
+ *
+ * - 无记录,或记录为 FAILED_RETRYABLE,或 IN_PROGRESS 已超过 TTL:{@link Outcome#ACQUIRED},并写入 IN_PROGRESS
+ * - 记录为 IN_PROGRESS 且未过期:{@link Outcome#IN_PROGRESS},拒绝并发执行
+ * - 记录为 SUCCEEDED:{@link Outcome#SUCCEEDED},回放结果
+ * - 记录为 FAILED_FINAL:{@link Outcome#FAILED_FINAL},需人工介入
+ *
+ */
+public final class IdempotencyClaim {
+
+ public enum Outcome {
+ ACQUIRED,
+ IN_PROGRESS,
+ SUCCEEDED,
+ FAILED_FINAL
+ }
+
+ private final Outcome outcome;
+ private final IdempotencyRecord record;
+
+ private IdempotencyClaim(Outcome outcome, IdempotencyRecord record) {
+ this.outcome = outcome;
+ this.record = record;
+ }
+
+ /** 抢占成功;record 为 null(没有历史记录)。 */
+ public static IdempotencyClaim acquire() {
+ return new IdempotencyClaim(Outcome.ACQUIRED, null);
+ }
+
+ public static IdempotencyClaim of(Outcome outcome, IdempotencyRecord record) {
+ return new IdempotencyClaim(outcome, record);
+ }
+
+ public Outcome outcome() {
+ return outcome;
+ }
+
+ /** 已有记录;ACQUIRED 时为 null。 */
+ public IdempotencyRecord record() {
+ return record;
+ }
+
+ public boolean acquired() {
+ return outcome == Outcome.ACQUIRED;
+ }
+
+ @Override
+ public String toString() {
+ return "IdempotencyClaim{" + outcome + (record == null ? "" : " " + record) + '}';
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java b/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java
new file mode 100644
index 0000000..c9b010d
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java
@@ -0,0 +1,69 @@
+package common.ecommerce.spi;
+
+import common.ecommerce.model.ChannelProvider;
+
+import java.time.Instant;
+import java.util.Objects;
+
+/**
+ * 幂等键的当前记录。
+ *
+ * {@code provider} 记录该动作最终由哪条接入通道完成,用于识别跨 provider
+ * 重复执行;{@code owner} 是抢占该键的实例标识,用于判断并发。
+ */
+public final class IdempotencyRecord {
+
+ private final String key;
+ private final IdempotencyStatus status;
+ private final ChannelProvider provider;
+ private final String owner;
+ private final String resultRef;
+ private final Instant updatedAt;
+
+ private IdempotencyRecord(String key, IdempotencyStatus status, ChannelProvider provider,
+ String owner, String resultRef, Instant updatedAt) {
+ this.key = Objects.requireNonNull(key, "key");
+ this.status = Objects.requireNonNull(status, "status");
+ this.provider = provider;
+ this.owner = owner;
+ this.resultRef = resultRef;
+ this.updatedAt = Objects.requireNonNull(updatedAt, "updatedAt");
+ }
+
+ public static IdempotencyRecord of(String key, IdempotencyStatus status, ChannelProvider provider,
+ String owner, String resultRef, Instant updatedAt) {
+ return new IdempotencyRecord(key, status, provider, owner, resultRef, updatedAt);
+ }
+
+ public String key() {
+ return key;
+ }
+
+ public IdempotencyStatus status() {
+ return status;
+ }
+
+ /** 完成该动作的 provider;IN_PROGRESS 时为抢占方。 */
+ public ChannelProvider provider() {
+ return provider;
+ }
+
+ public String owner() {
+ return owner;
+ }
+
+ /** 结果引用(订单号 / 包裹号等),不保存完整业务结果。 */
+ public String resultRef() {
+ return resultRef;
+ }
+
+ public Instant updatedAt() {
+ return updatedAt;
+ }
+
+ @Override
+ public String toString() {
+ return "IdempotencyRecord{" + key + " " + status + " by " + provider + '/' + owner
+ + (resultRef == null ? "" : " -> " + resultRef) + '}';
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyStatus.java b/core/src/main/java/common/ecommerce/spi/IdempotencyStatus.java
new file mode 100644
index 0000000..4cec7a3
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/spi/IdempotencyStatus.java
@@ -0,0 +1,18 @@
+package common.ecommerce.spi;
+
+/**
+ * 幂等键状态。
+ *
+ * 写操作按「抢占 → 执行 → 记录结果」流转,只有 SUCCEEDED 可以回放结果。
+ */
+public enum IdempotencyStatus {
+
+ /** 已抢占,执行中;并发重复请求被拒绝。 */
+ IN_PROGRESS,
+ /** 已成功;重复请求直接回放结果。 */
+ SUCCEEDED,
+ /** 可重试失败;允许再次抢占重跑。 */
+ FAILED_RETRYABLE,
+ /** 终态失败;需人工介入,不再自动重试。 */
+ FAILED_FINAL
+}
diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java b/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java
new file mode 100644
index 0000000..8bed7cf
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java
@@ -0,0 +1,34 @@
+package common.ecommerce.spi;
+
+import common.ecommerce.model.ChannelProvider;
+
+import java.time.Instant;
+import java.util.Optional;
+
+/**
+ * 幂等存储 SPI。宿主实现(典型 MySQL / Redis),SDK 只调用。
+ *
+ * 实现必须保证 {@link #claim} 的原子性(唯一索引或 Redis SETNX):并发抢占同一键时
+ * 只有一个调用能得到 {@link IdempotencyClaim.Outcome#ACQUIRED}。
+ */
+public interface IdempotencyStore {
+
+ /**
+ * 抢占幂等键。
+ *
+ * @param key 幂等键(业务键或 provider 请求键)
+ * @param owner 抢占方实例标识
+ * @param provider 接入通道,写入记录用于识别跨 provider 重复
+ * @param now 当前时间(UTC)
+ * @param ttlSeconds 抢占后无结果的最长保留时间,过期视为可重新抢占
+ */
+ IdempotencyClaim claim(String key, String owner, ChannelProvider provider, Instant now, long ttlSeconds);
+
+ /** 执行成功,记录结果引用。只有当前 owner 可以写入。 */
+ void complete(String key, String owner, String resultRef, Instant now);
+
+ /** 执行失败;{@code retryable=false} 记为终态,不再自动重试。 */
+ void fail(String key, String owner, boolean retryable, Instant now);
+
+ Optional get(String key);
+}
diff --git a/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java b/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java
index 1f0a2de..45f5acf 100644
--- a/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java
+++ b/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java
@@ -3,6 +3,7 @@ package common.ecommerce.sdk;
import common.ecommerce.capability.CapabilityReport;
import common.ecommerce.capability.PlatformAdapter;
import common.ecommerce.error.ChannelException;
+import common.ecommerce.idempotency.WriteResult;
import common.ecommerce.model.account.AccountKey;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
@@ -10,7 +11,6 @@ import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.support.Page;
import common.ecommerce.model.Platform;
import common.ecommerce.model.order.SalesOrder;
-import common.ecommerce.model.order.SalesOrderRef;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.sdk.ChannelContext;
import common.ecommerce.spi.ChannelAccountRepository;
@@ -63,7 +63,7 @@ class ChannelSdkTest {
}
@Override
- public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) {
+ public SalesOrder get(ChannelContext ctx, common.ecommerce.model.order.SalesOrderRef ref) {
return null;
}
}
@@ -181,4 +181,69 @@ class ChannelSdkTest {
.register(new FakeDirectAdapter());
assertThrows(IllegalStateException.class, () -> builder.register(new FakeDirectAdapter()));
}
+
+ @Test
+ void writesRequireIdempotencyStore() {
+ ChannelSdk sdk = sdkWith(new FakeDirectAdapter());
+ IllegalStateException ex = assertThrows(IllegalStateException.class, sdk::writes);
+ assertTrue(ex.getMessage().contains("idempotencyStore"), ex.getMessage());
+ }
+
+ @Test
+ void writesUseInjectedStore() {
+ // core 不能依赖 testkit,这里用最小本地替身验证门面装配
+ common.ecommerce.spi.IdempotencyStore store =
+ new common.ecommerce.spi.IdempotencyStore() {
+ private final java.util.Map records =
+ new java.util.LinkedHashMap();
+
+ @Override
+ public common.ecommerce.spi.IdempotencyClaim claim(String key, String owner,
+ ChannelProvider provider, java.time.Instant now, long ttlSeconds) {
+ common.ecommerce.spi.IdempotencyRecord existing = records.get(key);
+ if (existing != null && existing.status() == common.ecommerce.spi.IdempotencyStatus.SUCCEEDED) {
+ return common.ecommerce.spi.IdempotencyClaim.of(
+ common.ecommerce.spi.IdempotencyClaim.Outcome.SUCCEEDED, existing);
+ }
+ records.put(key, common.ecommerce.spi.IdempotencyRecord.of(key,
+ common.ecommerce.spi.IdempotencyStatus.IN_PROGRESS, provider, owner, null, now));
+ return common.ecommerce.spi.IdempotencyClaim.acquire();
+ }
+
+ @Override
+ public void complete(String key, String owner, String resultRef, java.time.Instant now) {
+ common.ecommerce.spi.IdempotencyRecord current = records.get(key);
+ records.put(key, common.ecommerce.spi.IdempotencyRecord.of(key,
+ common.ecommerce.spi.IdempotencyStatus.SUCCEEDED, current.provider(),
+ owner, resultRef, now));
+ }
+
+ @Override
+ public void fail(String key, String owner, boolean retryable, java.time.Instant now) {
+ common.ecommerce.spi.IdempotencyRecord current = records.get(key);
+ records.put(key, common.ecommerce.spi.IdempotencyRecord.of(key,
+ common.ecommerce.spi.IdempotencyStatus.FAILED_RETRYABLE,
+ current.provider(), owner, null, now));
+ }
+
+ @Override
+ public java.util.Optional get(String key) {
+ return java.util.Optional.ofNullable(records.get(key));
+ }
+ };
+
+ ChannelSdk sdk = ChannelSdk.builder()
+ .accountRepository(new FixedAccounts(walmartAccount()))
+ .idempotencyStore(store)
+ .register(new FakeDirectAdapter())
+ .build();
+
+ common.ecommerce.idempotency.WriteScope scope = common.ecommerce.idempotency.WriteScope.of(
+ ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001", "wm-seller-01",
+ "markShipped", "PO-1:pkg-1");
+ assertEquals(WriteResult.Outcome.EXECUTED,
+ sdk.writes().execute(scope, () -> "SHIP-1", v -> v).outcome());
+ assertEquals(WriteResult.Outcome.ALREADY_COMPLETED,
+ sdk.writes().execute(scope, () -> "SHIP-2", v -> v).outcome());
+ }
}
diff --git a/testkit/pom.xml b/testkit/pom.xml
index 96566c8..7c62040 100644
--- a/testkit/pom.xml
+++ b/testkit/pom.xml
@@ -29,6 +29,7 @@
org.junit.jupiter
junit-jupiter
+ test
diff --git a/testkit/src/main/java/common/ecommerce/testkit/InMemoryIdempotencyStore.java b/testkit/src/main/java/common/ecommerce/testkit/InMemoryIdempotencyStore.java
new file mode 100644
index 0000000..0737f24
--- /dev/null
+++ b/testkit/src/main/java/common/ecommerce/testkit/InMemoryIdempotencyStore.java
@@ -0,0 +1,116 @@
+package common.ecommerce.testkit;
+
+import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.spi.IdempotencyClaim;
+import common.ecommerce.spi.IdempotencyRecord;
+import common.ecommerce.spi.IdempotencyStatus;
+import common.ecommerce.spi.IdempotencyStore;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * 内存版幂等存储,语义与宿主实现一致:
+ *
+ *
+ * - 无记录 / FAILED_RETRYABLE / IN_PROGRESS 超过 TTL → 抢占成功
+ * - IN_PROGRESS 未过期 → 拒绝并发
+ * - SUCCEEDED → 回放;FAILED_FINAL → 终态
+ *
+ *
+ * 并发相关的行为只能在单 JVM 内验证;真实抢占原子性由宿主唯一索引 / Redis 保证。
+ */
+public final class InMemoryIdempotencyStore implements IdempotencyStore {
+
+ private final Map records = new HashMap();
+ private int claimAcquired;
+ private int claimRejected;
+
+ @Override
+ public synchronized IdempotencyClaim claim(String key, String owner, ChannelProvider provider,
+ Instant now, long ttlSeconds) {
+ IdempotencyRecord existing = records.get(key);
+ if (existing == null || isReclaimable(existing, now, ttlSeconds)) {
+ records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.IN_PROGRESS, provider, owner, null, now));
+ claimAcquired++;
+ return IdempotencyClaim.acquire();
+ }
+ claimRejected++;
+ switch (existing.status()) {
+ case SUCCEEDED:
+ return IdempotencyClaim.of(IdempotencyClaim.Outcome.SUCCEEDED, existing);
+ case FAILED_FINAL:
+ return IdempotencyClaim.of(IdempotencyClaim.Outcome.FAILED_FINAL, existing);
+ default:
+ return IdempotencyClaim.of(IdempotencyClaim.Outcome.IN_PROGRESS, existing);
+ }
+ }
+
+ @Override
+ public synchronized void complete(String key, String owner, String resultRef, Instant now) {
+ IdempotencyRecord current = requireOwned(key, owner);
+ records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.SUCCEEDED,
+ current.provider(), owner, resultRef, now));
+ }
+
+ @Override
+ public synchronized void fail(String key, String owner, boolean retryable, Instant now) {
+ IdempotencyRecord current = requireOwned(key, owner);
+ records.put(key, IdempotencyRecord.of(key,
+ retryable ? IdempotencyStatus.FAILED_RETRYABLE : IdempotencyStatus.FAILED_FINAL,
+ current.provider(), owner, current.resultRef(), now));
+ }
+
+ @Override
+ public synchronized Optional get(String key) {
+ return Optional.ofNullable(records.get(key));
+ }
+
+ /** 测试辅助:直接写入一条已完成记录,模拟「另一个 provider 早就做过」。 */
+ public synchronized InMemoryIdempotencyStore seedSucceeded(String key, ChannelProvider provider,
+ String resultRef, Instant at) {
+ records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.SUCCEEDED, provider, "seed", resultRef, at));
+ return this;
+ }
+
+ /** 测试辅助:直接写入 IN_PROGRESS 记录,模拟并发执行中。 */
+ public synchronized InMemoryIdempotencyStore seedInProgress(String key, ChannelProvider provider,
+ String owner, Instant at) {
+ records.put(key, IdempotencyRecord.of(key, IdempotencyStatus.IN_PROGRESS, provider, owner, null, at));
+ return this;
+ }
+
+ public synchronized int claimAcquiredCount() {
+ return claimAcquired;
+ }
+
+ public synchronized int claimRejectedCount() {
+ return claimRejected;
+ }
+
+ public synchronized int size() {
+ return records.size();
+ }
+
+ private IdempotencyRecord requireOwned(String key, String owner) {
+ IdempotencyRecord current = records.get(key);
+ if (current == null) {
+ throw new IllegalStateException("no idempotency record for " + key);
+ }
+ if (!current.owner().equals(owner) || current.status() != IdempotencyStatus.IN_PROGRESS) {
+ throw new IllegalStateException("record not owned by " + owner + " in progress: " + current);
+ }
+ return current;
+ }
+
+ private static boolean isReclaimable(IdempotencyRecord record, Instant now, long ttlSeconds) {
+ if (record.status() == IdempotencyStatus.FAILED_RETRYABLE) {
+ return true;
+ }
+ return record.status() == IdempotencyStatus.IN_PROGRESS
+ && !now.isBefore(record.updatedAt().plus(Duration.ofSeconds(ttlSeconds)));
+ }
+}
diff --git a/testkit/src/main/java/common/ecommerce/testkit/MutableClock.java b/testkit/src/main/java/common/ecommerce/testkit/MutableClock.java
new file mode 100644
index 0000000..fdec95c
--- /dev/null
+++ b/testkit/src/main/java/common/ecommerce/testkit/MutableClock.java
@@ -0,0 +1,49 @@
+package common.ecommerce.testkit;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZoneOffset;
+
+/**
+ * 可推进的时钟。用来验证 TTL、提前续期、水位线等与时间有关的边界。
+ */
+public final class MutableClock extends Clock {
+
+ private Instant now;
+ private final ZoneId zone;
+
+ public MutableClock(Instant now, ZoneId zone) {
+ this.now = now;
+ this.zone = zone;
+ }
+
+ public static MutableClock atUtc(String iso) {
+ return new MutableClock(Instant.parse(iso), ZoneOffset.UTC);
+ }
+
+ public MutableClock advance(Duration duration) {
+ now = now.plus(duration);
+ return this;
+ }
+
+ public void set(Instant instant) {
+ this.now = instant;
+ }
+
+ @Override
+ public ZoneId getZone() {
+ return zone;
+ }
+
+ @Override
+ public Clock withZone(ZoneId zone) {
+ return new MutableClock(now, zone);
+ }
+
+ @Override
+ public Instant instant() {
+ return now;
+ }
+}
diff --git a/testkit/src/test/java/common/ecommerce/idempotency/IdempotencyGuardTest.java b/testkit/src/test/java/common/ecommerce/idempotency/IdempotencyGuardTest.java
new file mode 100644
index 0000000..699a450
--- /dev/null
+++ b/testkit/src/test/java/common/ecommerce/idempotency/IdempotencyGuardTest.java
@@ -0,0 +1,212 @@
+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));
+ }
+}