Browse Source
裸 String 在擦除后使 SalesOrderCapable.get 与 ProductCapable.get 签名相同, 一个适配器无法同时实现订单与商品两种能力。改为包装类型后两者可共存。 - 新增 common.ecommerce.model.order.SalesOrderRef / model.product.ProductRef - SalesOrderCapable / ProductCapable 的 get 参数改为引用类型 - 门面 SalesOrders.get(String) / Products.get(String) 对外签名不变 - LingxingAdapter、ChannelSdkTest 同步适配 - testkit 新增 FakeDirectAdapter 及其测试,验证 core 抽象未被聚合器带偏 Co-Authored-By: Claude <noreply@anthropic.com>feature/supplier-lingxing
10 changed files with 513 additions and 6 deletions
@ -0,0 +1,46 @@
@@ -0,0 +1,46 @@
|
||||
package common.ecommerce.model.order; |
||||
|
||||
import common.ecommerce.model.product.ProductRef; |
||||
|
||||
import java.util.Objects; |
||||
|
||||
/** |
||||
* 销售订单引用:平台单号。 |
||||
* |
||||
* <p>单独成类型而不是裸 {@code String},避免与 {@link ProductRef} 等其它 |
||||
* 「按 ID 取详情」的签名冲突(两者返回类型不同,同名同参时 Java 无法同时实现)。</p> |
||||
*/ |
||||
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 + '}'; |
||||
} |
||||
} |
||||
@ -0,0 +1,41 @@
@@ -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 + '}'; |
||||
} |
||||
} |
||||
@ -0,0 +1,280 @@
@@ -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 抽象没有被聚合器带偏: |
||||
* 单平台、能力并集即账户能力、分页靠游标、不依赖网络。 |
||||
* |
||||
* <pre> |
||||
* FakeDirectAdapter adapter = FakeDirectAdapter.builder() |
||||
* .platform(Platform.WALMART_SC) |
||||
* .orders(3) |
||||
* .pageSize(2) |
||||
* .build(); |
||||
* </pre> |
||||
*/ |
||||
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<Capability> capabilities; |
||||
private final List<SalesOrder> orders; |
||||
private final List<ProductListing> products; |
||||
private final int pageSize; |
||||
private final List<SalesOrderQuery> orderQueries = new ArrayList<SalesOrderQuery>(); |
||||
private final List<ProductQuery> productQueries = new ArrayList<ProductQuery>(); |
||||
private final List<String> writeCalls = new ArrayList<String>(); |
||||
|
||||
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<Platform> platforms() { |
||||
return EnumSet.of(platform); |
||||
} |
||||
|
||||
@Override |
||||
public EnumSet<Capability> capabilities() { |
||||
return EnumSet.copyOf(capabilities); |
||||
} |
||||
|
||||
@Override |
||||
public Page<SalesOrder> 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<ProductListing> 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<String> writeCalls() { |
||||
return Collections.unmodifiableList(writeCalls); |
||||
} |
||||
|
||||
public List<SalesOrderQuery> orderQueries() { |
||||
return Collections.unmodifiableList(orderQueries); |
||||
} |
||||
|
||||
public List<ProductQuery> productQueries() { |
||||
return Collections.unmodifiableList(productQueries); |
||||
} |
||||
|
||||
public void resetRecorded() { |
||||
orderQueries.clear(); |
||||
productQueries.clear(); |
||||
writeCalls.clear(); |
||||
} |
||||
|
||||
// ---------------------------------------------------------------- internals
|
||||
|
||||
private <T> Page<T> slice(List<T> 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<Capability> capabilities = EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT); |
||||
private List<SalesOrder> orders = new ArrayList<SalesOrder>(); |
||||
private List<ProductListing> products = new ArrayList<ProductListing>(); |
||||
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<SalesOrder>(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<ProductListing>(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); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,129 @@
@@ -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<SalesOrder> p1 = adapter.pull(ctx(), SalesOrderQuery.builder().updatedAfter(Instant.EPOCH).build()); |
||||
Page<SalesOrder> p2 = adapter.pull(ctx(), SalesOrderQuery.builder().updatedAfter(Instant.EPOCH) |
||||
.cursor(p1.nextCursor()).build()); |
||||
Page<SalesOrder> 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<ProductListing> first = adapter.pull(ctx(), ProductQuery.builder().build()); |
||||
Page<ProductListing> 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()); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue