diff --git a/core/src/main/java/common/ecommerce/capability/ProductCapable.java b/core/src/main/java/common/ecommerce/capability/ProductCapable.java index 98a6bef..0ebde8c 100644 --- a/core/src/main/java/common/ecommerce/capability/ProductCapable.java +++ b/core/src/main/java/common/ecommerce/capability/ProductCapable.java @@ -4,6 +4,7 @@ import common.ecommerce.model.Capability; import common.ecommerce.model.support.Page; import common.ecommerce.model.product.ProductListing; import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.product.ProductRef; import common.ecommerce.model.product.ProductSyncStrategy; import common.ecommerce.sdk.ChannelContext; @@ -17,7 +18,7 @@ public interface ProductCapable extends PlatformAdapter { Page pull(ChannelContext ctx, ProductQuery query); - ProductListing get(ChannelContext ctx, String platformSku); + ProductListing get(ChannelContext ctx, ProductRef ref); default Capability requiredCapability() { return Capability.PRODUCT; diff --git a/core/src/main/java/common/ecommerce/capability/Products.java b/core/src/main/java/common/ecommerce/capability/Products.java index e18691a..19a16fb 100644 --- a/core/src/main/java/common/ecommerce/capability/Products.java +++ b/core/src/main/java/common/ecommerce/capability/Products.java @@ -6,6 +6,7 @@ import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.model.support.Page; import common.ecommerce.model.product.ProductListing; import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.product.ProductRef; import common.ecommerce.sdk.ChannelContext; /** 门面持有的商品视图。 */ @@ -28,7 +29,7 @@ public final class Products { public ProductListing get(String platformSku) { requireProductCapable(); - return ((ProductCapable) adapter).get(ctx, platformSku); + return ((ProductCapable) adapter).get(ctx, ProductRef.of(platformSku)); } private void requireProductCapable() { diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java b/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java index 7761c41..0a9dede 100644 --- a/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java +++ b/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java @@ -3,12 +3,17 @@ package common.ecommerce.capability; import common.ecommerce.error.ChannelException; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.model.order.SalesOrderQuery; +import common.ecommerce.model.order.SalesOrderRef; import common.ecommerce.model.support.Page; import common.ecommerce.model.Capability; import common.ecommerce.sdk.ChannelContext; /** * 3P 销售订单能力:消费者订单。 + * + *

详情参数用 {@link SalesOrderRef} 而不是裸 String:同一适配器可同时实现 + * {@link ProductCapable},两者都是 {@code get(ChannelContext, X)},裸 String 会因 + * 擦除后签名相同而无法同时实现。

*/ public interface SalesOrderCapable extends PlatformAdapter { @@ -16,7 +21,7 @@ public interface SalesOrderCapable extends PlatformAdapter { Page pull(ChannelContext ctx, SalesOrderQuery query); /** 单订单详情。 */ - SalesOrder get(ChannelContext ctx, String channelOrderId); + SalesOrder get(ChannelContext ctx, SalesOrderRef ref); /** * 默认实现:未声明该能力即拒绝,避免适配器漏实现导致静默返回空。 diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrders.java b/core/src/main/java/common/ecommerce/capability/SalesOrders.java index b21ff47..bc7e560 100644 --- a/core/src/main/java/common/ecommerce/capability/SalesOrders.java +++ b/core/src/main/java/common/ecommerce/capability/SalesOrders.java @@ -5,6 +5,7 @@ import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.error.ChannelException; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.model.order.SalesOrderQuery; +import common.ecommerce.model.order.SalesOrderRef; import common.ecommerce.model.support.Page; import common.ecommerce.sdk.ChannelContext; @@ -30,7 +31,7 @@ public final class SalesOrders { public SalesOrder get(String channelOrderId) { requireSalesOrderCapable(); - return ((SalesOrderCapable) adapter).get(ctx, channelOrderId); + return ((SalesOrderCapable) adapter).get(ctx, SalesOrderRef.of(channelOrderId)); } private void requireSalesOrderCapable() { diff --git a/core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java b/core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java new file mode 100644 index 0000000..26f7f9e --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java @@ -0,0 +1,46 @@ +package common.ecommerce.model.order; + +import common.ecommerce.model.product.ProductRef; + +import java.util.Objects; + +/** + * 销售订单引用:平台单号。 + * + *

单独成类型而不是裸 {@code String},避免与 {@link ProductRef} 等其它 + * 「按 ID 取详情」的签名冲突(两者返回类型不同,同名同参时 Java 无法同时实现)。

+ */ +public final class SalesOrderRef { + + private final String channelOrderId; + + private SalesOrderRef(String channelOrderId) { + if (channelOrderId == null || channelOrderId.trim().isEmpty()) { + throw new IllegalArgumentException("channelOrderId must not be blank"); + } + this.channelOrderId = channelOrderId.trim(); + } + + public static SalesOrderRef of(String channelOrderId) { + return new SalesOrderRef(channelOrderId); + } + + public String channelOrderId() { + return channelOrderId; + } + + @Override + public boolean equals(Object o) { + return o instanceof SalesOrderRef && channelOrderId.equals(((SalesOrderRef) o).channelOrderId); + } + + @Override + public int hashCode() { + return Objects.hash(channelOrderId); + } + + @Override + public String toString() { + return "SalesOrderRef{" + channelOrderId + '}'; + } +} diff --git a/core/src/main/java/common/ecommerce/model/product/ProductRef.java b/core/src/main/java/common/ecommerce/model/product/ProductRef.java new file mode 100644 index 0000000..9e49ded --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/product/ProductRef.java @@ -0,0 +1,41 @@ +package common.ecommerce.model.product; + +import java.util.Objects; + +/** + * 商品引用:平台 SKU。 + */ +public final class ProductRef { + + private final String platformSku; + + private ProductRef(String platformSku) { + if (platformSku == null || platformSku.trim().isEmpty()) { + throw new IllegalArgumentException("platformSku must not be blank"); + } + this.platformSku = platformSku.trim(); + } + + public static ProductRef of(String platformSku) { + return new ProductRef(platformSku); + } + + public String platformSku() { + return platformSku; + } + + @Override + public boolean equals(Object o) { + return o instanceof ProductRef && platformSku.equals(((ProductRef) o).platformSku); + } + + @Override + public int hashCode() { + return Objects.hash(platformSku); + } + + @Override + public String toString() { + return "ProductRef{" + platformSku + '}'; + } +} diff --git a/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java b/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java index 4d77026..1f0a2de 100644 --- a/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java +++ b/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java @@ -10,6 +10,7 @@ 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; @@ -62,7 +63,7 @@ class ChannelSdkTest { } @Override - public SalesOrder get(ChannelContext ctx, String channelOrderId) { + public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { return null; } } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java index d8c15e8..9c35b2d 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java @@ -17,6 +17,7 @@ import common.ecommerce.model.support.Page; import common.ecommerce.model.Platform; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.model.order.SalesOrderQuery; +import common.ecommerce.model.order.SalesOrderRef; import common.ecommerce.sdk.ChannelContext; import common.ecommerce.spi.AccessToken; import common.ecommerce.spi.ChannelSecret; @@ -169,7 +170,8 @@ public final class LingxingAdapter implements SalesOrderCapable, AggregatorCapab /** 单订单详情接口待核对(领星以列表接口为主),先显式拒绝而不是返回 null。 */ @Override - public SalesOrder get(ChannelContext ctx, String channelOrderId) { + public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { + String channelOrderId = ref.channelOrderId(); throw ChannelException.builder() .message("lingxing order detail is not implemented yet") .operation("salesOrders.get") diff --git a/testkit/src/main/java/common/ecommerce/testkit/FakeDirectAdapter.java b/testkit/src/main/java/common/ecommerce/testkit/FakeDirectAdapter.java new file mode 100644 index 0000000..b1b36d7 --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/FakeDirectAdapter.java @@ -0,0 +1,280 @@ +package common.ecommerce.testkit; + +import common.ecommerce.capability.ProductCapable; +import common.ecommerce.capability.SalesOrderCapable; +import common.ecommerce.error.ChannelException; +import common.ecommerce.model.account.AccountKey; +import common.ecommerce.model.Capability; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.support.Money; +import common.ecommerce.model.order.OrderLine; +import common.ecommerce.model.support.Page; +import common.ecommerce.model.Platform; +import common.ecommerce.model.support.PlatformTime; +import common.ecommerce.model.product.ProductListing; +import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.product.ProductRef; +import common.ecommerce.model.product.ProductSyncStrategy; +import common.ecommerce.model.order.SalesOrder; +import common.ecommerce.model.order.SalesOrderQuery; +import common.ecommerce.model.order.SalesOrderRef; +import common.ecommerce.sdk.ChannelContext; + +import java.time.Instant; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.EnumSet; +import java.util.List; +import java.util.Set; + +/** + * 假直连适配器。用来验证 core 抽象没有被聚合器带偏: + * 单平台、能力并集即账户能力、分页靠游标、不依赖网络。 + * + *
+ * FakeDirectAdapter adapter = FakeDirectAdapter.builder()
+ *         .platform(Platform.WALMART_SC)
+ *         .orders(3)
+ *         .pageSize(2)
+ *         .build();
+ * 
+ */ +public final class FakeDirectAdapter implements SalesOrderCapable, ProductCapable { + + /** 游标格式:{@code item:序号},仅用于测试分页。 */ + private static final String CURSOR_PREFIX = "item:"; + + private final String adapterId; + private final Platform platform; + private final EnumSet capabilities; + private final List orders; + private final List products; + private final int pageSize; + private final List orderQueries = new ArrayList(); + private final List productQueries = new ArrayList(); + private final List writeCalls = new ArrayList(); + + private FakeDirectAdapter(Builder b) { + this.adapterId = b.adapterId; + this.platform = b.platform; + this.capabilities = b.capabilities; + this.orders = b.orders; + this.products = b.products; + this.pageSize = b.pageSize; + } + + public static Builder builder() { + return new Builder(); + } + + /** 直连测试账户;聚合器账户只是 provider / platformCode 不同,能力检查逻辑共用。 */ + public static ChannelAccount account(Platform platform, String omsStoreId) { + return ChannelAccount.builder() + .key(AccountKey.of(ChannelProvider.DIRECT, platform, omsStoreId)) + .externalStoreId("fake-seller-01") + .credentialRef("kms://test/fake-direct") + .marketplaceZone("America/Los_Angeles") + .currency("USD") + .build(); + } + + @Override + public String adapterId() { + return adapterId; + } + + @Override + public ChannelProvider provider() { + return ChannelProvider.DIRECT; + } + + @Override + public Set platforms() { + return EnumSet.of(platform); + } + + @Override + public EnumSet capabilities() { + return EnumSet.copyOf(capabilities); + } + + @Override + public Page pull(ChannelContext ctx, SalesOrderQuery query) { + requireCapability(Capability.SALES_ORDER); + orderQueries.add(query); + return slice(orders, query.cursor()); + } + + @Override + public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { + requireCapability(Capability.SALES_ORDER); + for (SalesOrder o : orders) { + if (o.channelOrderId().equals(ref.channelOrderId())) { + return o; + } + } + return null; + } + + @Override + public ProductSyncStrategy syncStrategy() { + return ProductSyncStrategy.FULL_PULL_DIFF; + } + + @Override + public Page pull(ChannelContext ctx, ProductQuery query) { + requireCapability(Capability.PRODUCT); + productQueries.add(query); + return slice(products, query.cursor()); + } + + @Override + public ProductListing get(ChannelContext ctx, ProductRef ref) { + requireCapability(Capability.PRODUCT); + for (ProductListing p : products) { + if (p.platformSku().equals(ref.platformSku())) { + return p; + } + } + return null; + } + + /** 模拟一次写操作,如标发;带 IdempotencyGuard 的测试用它确认平台只被真正调用一次。 */ + public String markShipped(String packageId, String trackingNumber) { + writeCalls.add(packageId + ':' + trackingNumber); + return "SHIP-" + writeCalls.size(); + } + + public int writeCallCount() { + return writeCalls.size(); + } + + public List writeCalls() { + return Collections.unmodifiableList(writeCalls); + } + + public List orderQueries() { + return Collections.unmodifiableList(orderQueries); + } + + public List productQueries() { + return Collections.unmodifiableList(productQueries); + } + + public void resetRecorded() { + orderQueries.clear(); + productQueries.clear(); + writeCalls.clear(); + } + + // ---------------------------------------------------------------- internals + + private Page slice(List all, String cursor) { + int from = cursorIndex(cursor); + int to = Math.min(from + pageSize, all.size()); + String next = to < all.size() ? CURSOR_PREFIX + to : null; + return Page.of(all.subList(from, to), next); + } + + private void requireCapability(Capability capability) { + if (!capabilities.contains(capability)) { + throw new ChannelException.UnsupportedCapabilityException(capability); + } + } + + private static int cursorIndex(String cursor) { + if (cursor == null || cursor.isEmpty()) { + return 0; + } + if (!cursor.startsWith(CURSOR_PREFIX)) { + throw new IllegalArgumentException("bad cursor: " + cursor); + } + return Integer.parseInt(cursor.substring(CURSOR_PREFIX.length())); + } + + private static SalesOrder sampleOrder(Platform platform, String channelOrderId) { + return SalesOrder.builder() + .omsStoreId("oms-test-001") + .channelOrderId(channelOrderId) + .status("Created") + .buyerName("Fake Buyer") + .shipToCountryCode("US") + .lines(Collections.singletonList(OrderLine.builder() + .lineId(channelOrderId + "-1") + .platformSku("SKU-1") + .quantity(1) + .unitPrice(Money.of("9.99", "USD")) + .build())) + .totalAmount(Money.of("9.99", "USD")) + .occurredAt(PlatformTime.of(Instant.parse("2026-10-26T00:00:00Z"), "America/Los_Angeles")) + .sourceProvider(ChannelProvider.DIRECT) + .sourceAccountId("fake-seller-01") + .build(); + } + + // ---------------------------------------------------------------- builder + + public static final class Builder { + + private String adapterId = "fake-direct"; + private Platform platform = Platform.WALMART_SC; + private EnumSet capabilities = EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT); + private List orders = new ArrayList(); + private List products = new ArrayList(); + private int pageSize = 100; + + public Builder adapterId(String adapterId) { + this.adapterId = adapterId; + return this; + } + + public Builder platform(Platform platform) { + this.platform = platform; + return this; + } + + /** 能力并集必须与实现的接口一致;默认订单 + 商品。 */ + public Builder capabilities(Capability... capabilities) { + this.capabilities = capabilities.length == 0 + ? EnumSet.noneOf(Capability.class) : EnumSet.copyOf(Arrays.asList(capabilities)); + return this; + } + + /** 生成 count 条顺序订单,单号形如 {@code FAKE-1..count}。 */ + public Builder orders(int count) { + this.orders = new ArrayList(count); + for (int i = 1; i <= count; i++) { + this.orders.add(sampleOrder(platform, "FAKE-" + i)); + } + return this; + } + + public Builder products(int count) { + this.products = new ArrayList(count); + for (int i = 1; i <= count; i++) { + this.products.add(ProductListing.builder() + .omsStoreId("oms-test-001") + .platformSku("SKU-" + i) + .title("Fake product " + i) + .status("ACTIVE") + .sourceProvider(ChannelProvider.DIRECT) + .build()); + } + return this; + } + + public Builder pageSize(int pageSize) { + if (pageSize <= 0) { + throw new IllegalArgumentException("pageSize must be positive"); + } + this.pageSize = pageSize; + return this; + } + + public FakeDirectAdapter build() { + return new FakeDirectAdapter(this); + } + } +} diff --git a/testkit/src/test/java/common/ecommerce/testkit/FakeDirectAdapterTest.java b/testkit/src/test/java/common/ecommerce/testkit/FakeDirectAdapterTest.java new file mode 100644 index 0000000..6ae7080 --- /dev/null +++ b/testkit/src/test/java/common/ecommerce/testkit/FakeDirectAdapterTest.java @@ -0,0 +1,129 @@ +package common.ecommerce.testkit; + +import common.ecommerce.capability.AdapterCapabilityReport; +import common.ecommerce.capability.CapabilityReport; +import common.ecommerce.error.ChannelException; +import common.ecommerce.model.Capability; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.support.Page; +import common.ecommerce.model.Platform; +import common.ecommerce.model.product.ProductListing; +import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.product.ProductRef; +import common.ecommerce.model.order.SalesOrder; +import common.ecommerce.model.order.SalesOrderQuery; +import common.ecommerce.sdk.ChannelContext; +import common.ecommerce.sync.SyncEngine; +import common.ecommerce.sync.SyncResult; +import common.ecommerce.sync.SyncSpec; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Duration; +import java.time.Instant; +import java.time.ZoneOffset; + +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.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 直连假适配器验证 core 抽象:能力报告、游标翻页、SyncEngine 多页推进水位线。 + */ +class FakeDirectAdapterTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-10-29T00:00:00Z"), ZoneOffset.UTC); + + private static ChannelContext ctx() { + ChannelAccount account = FakeDirectAdapter.account(Platform.WALMART_SC, "oms-test-001"); + return ChannelContext.of(account, "req-1", CLOCK); + } + + @Test + void directCapabilitiesEqualDeclaredSet() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(1).build(); + ChannelAccount account = FakeDirectAdapter.account(Platform.WALMART_SC, "oms-test-001"); + + CapabilityReport report = new AdapterCapabilityReport(adapter, account); + assertTrue(report.supports(Capability.SALES_ORDER)); + assertTrue(report.supports(Capability.PRODUCT)); + assertFalse(report.supports(Capability.REFUND)); + assertEquals(adapter.capabilities(), report.supported()); + } + + @Test + void cursorPagingWalksAllOrders() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(5).pageSize(2).build(); + + Page p1 = adapter.pull(ctx(), SalesOrderQuery.builder().updatedAfter(Instant.EPOCH).build()); + Page p2 = adapter.pull(ctx(), SalesOrderQuery.builder().updatedAfter(Instant.EPOCH) + .cursor(p1.nextCursor()).build()); + Page p3 = adapter.pull(ctx(), SalesOrderQuery.builder().updatedAfter(Instant.EPOCH) + .cursor(p2.nextCursor()).build()); + + assertEquals(2, p1.size()); + assertEquals("FAKE-1", p1.items().get(0).channelOrderId()); + assertEquals(2, p2.size()); + assertEquals(1, p3.size()); + assertNull(p3.nextCursor()); + } + + @Test + void syncEnginePagesThroughAndAdvancesOnce() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(5).pageSize(2).build(); + InMemoryCursorStore cursors = new InMemoryCursorStore(); + InMemorySink sink = new InMemorySink(); + String stream = SyncSpec.STREAM_SALES_ORDERS; + cursors.seed(ChannelProvider.DIRECT, "oms-test-001", stream, Instant.parse("2026-10-28T00:00:00Z")); + + SyncSpec spec = SyncSpec.of(ChannelProvider.DIRECT, "oms-test-001", stream, Duration.ofMinutes(15)); + Instant to = Instant.parse("2026-10-29T00:00:00Z"); + SyncResult result = new SyncEngine(cursors, sink).syncSalesOrders(spec, to, + (from, cursor) -> adapter.pull(ctx(), SalesOrderQuery.builder() + .updatedAfter(from).updatedBefore(to).cursor(cursor).build())); + + assertEquals(3, result.pages()); + assertEquals(5, result.items()); + assertTrue(result.watermarkAdvanced()); + assertEquals(to, cursors.watermark(ChannelProvider.DIRECT, "oms-test-001", stream)); + assertEquals(3, sink.salesOrderUpsertCalls()); + assertEquals(5, sink.salesOrders().size()); + // 起点回退了重叠窗口 + assertEquals(Instant.parse("2026-10-27T23:45:00Z"), adapter.orderQueries().get(0).updatedAfter()); + } + + @Test + void productPagingUsesProductContract() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().products(3).pageSize(2).build(); + + Page first = adapter.pull(ctx(), ProductQuery.builder().build()); + Page second = adapter.pull(ctx(), ProductQuery.builder() + .cursor(first.nextCursor()).build()); + + assertEquals(2, first.size()); + assertEquals("SKU-1", first.items().get(0).platformSku()); + assertEquals(1, second.size()); + assertNotNull(adapter.get(ctx(), ProductRef.of("SKU-2"))); + } + + @Test + void undeclaredCapabilityThrows() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().capabilities(Capability.SALES_ORDER).build(); + + assertThrows(ChannelException.UnsupportedCapabilityException.class, + () -> adapter.pull(ctx(), ProductQuery.builder().build())); + } + + @Test + void writeCallsRecordedForIdempotencyTests() { + FakeDirectAdapter adapter = FakeDirectAdapter.builder().build(); + assertEquals("SHIP-1", adapter.markShipped("pkg-1", "1Z-1")); + assertEquals(1, adapter.writeCallCount()); + adapter.resetRecorded(); + assertEquals(0, adapter.writeCallCount()); + } +}