Browse Source

refactor: 包名去掉 apelet 前缀并按职责拆分 model 子包

- 包路径 apelet.common.ecommerce → common.ecommerce(四个模块的 main/test 全量迁移)
- model 拆为 account / order / product / support 四个子包,枚举留在根包
- 同步更新 README 包结构与导入路径

行为无变化,仅重命名与目录调整。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 3 weeks ago
parent
commit
ff9ec456c2
  1. 152
      README.md
  2. 60
      core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java
  3. 54
      core/src/main/java/common/ecommerce/capability/AggregatorCapable.java
  4. 19
      core/src/main/java/common/ecommerce/capability/CapabilityReport.java
  5. 36
      core/src/main/java/common/ecommerce/capability/PlatformAdapter.java
  6. 25
      core/src/main/java/common/ecommerce/capability/ProductCapable.java
  7. 39
      core/src/main/java/common/ecommerce/capability/Products.java
  8. 29
      core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java
  9. 41
      core/src/main/java/common/ecommerce/capability/SalesOrders.java
  10. 17
      core/src/main/java/common/ecommerce/error/AuthException.java
  11. 154
      core/src/main/java/common/ecommerce/error/ChannelException.java
  12. 22
      core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java
  13. 18
      core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java
  14. 13
      core/src/main/java/common/ecommerce/error/PlatformBusinessException.java
  15. 20
      core/src/main/java/common/ecommerce/error/RateLimitException.java
  16. 13
      core/src/main/java/common/ecommerce/error/TransientException.java
  17. 17
      core/src/main/java/common/ecommerce/error/ValidationException.java
  18. 45
      core/src/main/java/common/ecommerce/model/Capability.java
  19. 23
      core/src/main/java/common/ecommerce/model/ChannelProvider.java
  20. 12
      core/src/main/java/common/ecommerce/model/FulfillmentMode.java
  21. 42
      core/src/main/java/common/ecommerce/model/Platform.java
  22. 69
      core/src/main/java/common/ecommerce/model/account/AccountKey.java
  23. 170
      core/src/main/java/common/ecommerce/model/account/ChannelAccount.java
  24. 99
      core/src/main/java/common/ecommerce/model/order/OrderLine.java
  25. 155
      core/src/main/java/common/ecommerce/model/order/SalesOrder.java
  26. 82
      core/src/main/java/common/ecommerce/model/order/SalesOrderQuery.java
  27. 115
      core/src/main/java/common/ecommerce/model/product/ProductListing.java
  28. 74
      core/src/main/java/common/ecommerce/model/product/ProductQuery.java
  29. 12
      core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java
  30. 115
      core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java
  31. 104
      core/src/main/java/common/ecommerce/model/support/Money.java
  32. 52
      core/src/main/java/common/ecommerce/model/support/Page.java
  33. 85
      core/src/main/java/common/ecommerce/model/support/PlatformTime.java
  34. 47
      core/src/main/java/common/ecommerce/sdk/AdapterFactory.java
  35. 48
      core/src/main/java/common/ecommerce/sdk/ChannelContext.java
  36. 169
      core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
  37. 14
      core/src/main/java/common/ecommerce/sdk/ProviderResolver.java
  38. 84
      core/src/main/java/common/ecommerce/spi/AccessToken.java
  39. 16
      core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java
  40. 91
      core/src/main/java/common/ecommerce/spi/ChannelSecret.java
  41. 24
      core/src/main/java/common/ecommerce/spi/LockProvider.java
  42. 14
      core/src/main/java/common/ecommerce/spi/SecretProvider.java
  43. 18
      core/src/main/java/common/ecommerce/spi/Sink.java
  44. 18
      core/src/main/java/common/ecommerce/spi/SyncCursorStore.java
  45. 15
      core/src/main/java/common/ecommerce/spi/TokenStore.java
  46. 77
      core/src/main/java/common/ecommerce/sync/SyncEngine.java
  47. 43
      core/src/main/java/common/ecommerce/sync/SyncResult.java
  48. 59
      core/src/main/java/common/ecommerce/sync/SyncSpec.java
  49. 80
      core/src/test/java/common/ecommerce/model/support/CanonicalKeysTest.java
  50. 183
      core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java
  51. 110
      http/src/main/java/common/ecommerce/http/HttpRequest.java
  52. 69
      http/src/main/java/common/ecommerce/http/HttpResponse.java
  53. 9
      http/src/main/java/common/ecommerce/http/HttpTransport.java
  54. 86
      http/src/main/java/common/ecommerce/http/JacksonJsonCodec.java
  55. 17
      http/src/main/java/common/ecommerce/http/JsonCodec.java
  56. 70
      http/src/main/java/common/ecommerce/http/OkHttpTransport.java
  57. 56
      http/src/main/java/common/ecommerce/http/Responses.java
  58. 10
      http/src/main/java/common/ecommerce/http/Signer.java
  59. 85
      http/src/main/java/common/ecommerce/http/TokenManager.java
  60. 43
      http/src/test/java/common/ecommerce/http/ResponsesTest.java
  61. 262
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java
  62. 58
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapterFactory.java
  63. 61
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java
  64. 112
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java
  65. 58
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingSigner.java
  66. 67
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingTokenClient.java
  67. 196
      lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderDto.java
  68. 88
      lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderItemDto.java
  69. 191
      lingxing/src/test/java/common/ecommerce/lingxing/LingxingAdapterTest.java
  70. 73
      lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java
  71. 54
      lingxing/src/test/java/common/ecommerce/lingxing/LingxingSignerTest.java
  72. 85
      testkit/src/main/java/common/ecommerce/testkit/FakeTransport.java
  73. 36
      testkit/src/main/java/common/ecommerce/testkit/Fixtures.java
  74. 59
      testkit/src/main/java/common/ecommerce/testkit/InMemoryAccounts.java
  75. 37
      testkit/src/main/java/common/ecommerce/testkit/InMemoryCursorStore.java
  76. 52
      testkit/src/main/java/common/ecommerce/testkit/InMemoryLockProvider.java
  77. 47
      testkit/src/main/java/common/ecommerce/testkit/InMemorySink.java
  78. 36
      testkit/src/main/java/common/ecommerce/testkit/InMemoryTokenStore.java
  79. 25
      testkit/src/main/java/common/ecommerce/testkit/Responses.java
  80. 32
      testkit/src/main/java/common/ecommerce/testkit/TestData.java

152
README.md

@ -31,45 +31,64 @@ mvn clean test @@ -31,45 +31,64 @@ mvn clean test
要求 JDK 1.8、Maven 3.6+。
> 第一次接触这个库,先读 [`GUIDE.md`](GUIDE.md):分层心智模型、三条流水线逐段讲、
> 接入一个新平台的 8 个步骤与 5 层测试。本文档是速查,GUIDE 是教程。
---
## 一、包职责
```
apelet.common.ecommerce
├── model 领域模型与标识计算(core)
common.ecommerce
├── model 领域模型(core)
│ ├── account AccountKey / ChannelAccount
│ ├── order SalesOrder / OrderLine / Query / Ref
│ ├── product ProductListing / Query / Ref / SyncStrategy
│ └── support Money / PlatformTime / Page / CanonicalKeys
├── capability 能力接口,适配器实现这些(core)
├── error 统一异常体系(core)
├── sdk 门面、上下文、适配器工厂接口(core)
├── sync 增量同步引擎与水位线计算(core)
├── idempotency 写操作双锁幂等守卫(core)
├── spi 宿主必须实现的扩展点(core)
├── http HTTP 传输、JSON、签名、令牌(http)
├── testkit 测试替身与夹具(testkit)
└── lingxing 领星适配器(lingxing)
```
包名统一前缀 `apelet.common.ecommerce.`,下表省略前缀。
包名统一前缀 `common.ecommerce.`,下表省略前缀。
### `model` —— 领域模型
所有对象**不可变**,用 Builder 构造,无 setter。Java 8 不引入 record/sealed。
| 类 | 职责 |
子包分工:
| 子包 | 内容 |
|:---|:---|
| `Platform` | 业务平台枚举。**不含 provider**,直连与聚合器映射到同一值 |
| `ChannelProvider` | 接入通道:DIRECT / LINGXING / TEAPPLIX / CUSTOM |
| `Capability` | 能力枚举,适配器声明、门面校验 |
| `FulfillmentMode` | A/C/D 三种履约模式(B 平台仓只读,不在枚举内) |
| `ProductSyncStrategy` | 增量 / 全量 diff / 报告 |
| `AccountKey` | `provider + platform + omsStoreId`,所有调用的隔离维度 |
| `ChannelAccount` | 渠道账户配置。只存 `credentialRef`,**不存密钥** |
| `CanonicalKeys` | 三级标识与指纹计算,见下方「标识体系」 |
| `PlatformTime` | 三轴时间:UTC 真值 + 市场当地 + 北京时间 |
| `Money` | `BigDecimal + Currency`,跨币种运算直接拒绝 |
| `SalesOrder` / `OrderLine` | 3P 销售订单 |
| `ProductListing` | 商品 / Listing |
| `SalesOrderQuery` / `ProductQuery` | 查询条件(时间窗 + 分页游标) |
| `Page<T>` | 分页载体,`nextCursor == null` 表示结束 |
| `model`(本包) | **枚举**:`Platform` / `ChannelProvider` / `Capability` / `FulfillmentMode` |
| `model.account` | `AccountKey` / `ChannelAccount` |
| `model.order` | `SalesOrder` / `OrderLine` / `SalesOrderQuery` / `SalesOrderRef` |
| `model.product` | `ProductListing` / `ProductQuery` / `ProductRef` / `ProductSyncStrategy` |
| `model.support` | `Money` / `PlatformTime` / `Page` / `CanonicalKeys` |
| 类 | 包袱 | 职责 |
|:---|:---|:---|
| `Platform` | 枚举 | 业务平台。**不含 provider**,直连与聚合器映射到同一值 |
| `ChannelProvider` | 枚举 | 接入通道:DIRECT / LINGXING / TEAPPLIX / CUSTOM |
| `Capability` | 枚举 | 能力枚举,适配器声明、门面校验 |
| `FulfillmentMode` | 枚举 | A/C/D 三种履约模式(B 平台仓只读,不在枚举内) |
| `ProductSyncStrategy` | 枚举 | 增量 / 全量 diff / 报告(放在 `model.product`) |
| `AccountKey` | 标识 | `provider + platform + omsStoreId`,所有调用的隔离维度 |
| `ChannelAccount` | 配置 | 渠道账户配置。只存 `credentialRef`,**不存密钥** |
| `CanonicalKeys` | 工具 | 三级标识与指纹计算,见下方「标识体系」 |
| `PlatformTime` | 值对象 | 三轴时间:UTC 真值 + 市场当地 + 北京时间 |
| `Money` | 值对象 | `BigDecimal + Currency`,跨币种运算直接拒绝 |
| `SalesOrder` / `OrderLine` | 实体 | 3P 销售订单 |
| `ProductListing` | 实体 | 商品 / Listing |
| `SalesOrderQuery` / `ProductQuery` | 查询 | 查询条件(时间窗 + 分页游标) |
| `SalesOrderRef` / `ProductRef` | 引用 | 详情入参。**不能用裸 String**,否则订单+商品接口签名冲突 |
| `Page<T>` | 载体 | 分页载体,`nextCursor == null` 表示结束 |
### `capability` —— 能力接口
@ -79,8 +98,8 @@ apelet.common.ecommerce @@ -79,8 +98,8 @@ apelet.common.ecommerce
|:---|:---|
| `PlatformAdapter` | 基座:`adapterId()` / `provider()` / `platforms()` / `capabilities()` / `supports(account, cap)` |
| `AggregatorCapable` | 聚合器扩展:`listSubChannels(account)`,按子平台细化能力 |
| `SalesOrderCapable` | `pull(ctx, query)` / `get(ctx, orderId)` |
| `ProductCapable` | `syncStrategy()` / `pull(ctx, query)` / `get(ctx, sku)` |
| `SalesOrderCapable` | `pull(ctx, query)` / `get(ctx, SalesOrderRef)` |
| `ProductCapable` | `syncStrategy()` / `pull(ctx, query)` / `get(ctx, ProductRef)` |
| `CapabilityReport` | 能力报告:`supports()` / `supported()` / `unsupported()` |
| `SalesOrders` / `Products` | 门面持有的视图,调用前做能力检查 |
@ -101,6 +120,8 @@ apelet.common.ecommerce @@ -101,6 +120,8 @@ apelet.common.ecommerce
**注意** `UnsupportedCapabilityException` 是 `ChannelException` 的静态内部类,用 `ChannelException.UnsupportedCapabilityException` 引用。
**详情参数是包装类型**:`SalesOrderCapable.get` 收 `SalesOrderRef`、`ProductCapable.get` 收 `ProductRef`,不是裸 `String`。同一适配器同时实现两种能力时,裸 `String` 会擦除成相同签名而无法同时实现。
**同名类** `Responses` 有两个:`http.Responses`(状态码 → 异常)与 `testkit.Responses`(快捷构造响应)。测试里注意 import 哪个。
### `sdk` —— 门面与上下文
@ -110,7 +131,15 @@ apelet.common.ecommerce @@ -110,7 +131,15 @@ apelet.common.ecommerce
| `ChannelContext` | 单次调用上下文:`account` + `requestId` + `clock`。**由 SDK 创建,适配器不得自造** |
| `AdapterFactory` | 适配器工厂:`adapterId()` / `provider()` / `platforms()` / `create(AdapterConfig)` |
| `ProviderResolver` | 按 `AccountKey` 解析适配器,不自动选路 |
| `ChannelSdk` | 统一门面:`capabilities()` / `salesOrders()` / `products()`;`build()` 校验必需项 |
| `ChannelSdk` | 统一门面:`capabilities()` / `salesOrders()` / `products()` / `writes()`;`build()` 校验必需项 |
### `idempotency` —— 写操作幂等
| 类 | 职责 |
|:---|:---|
| `WriteScope` | 一次写操作的维度:`provider + platform + omsStoreId + externalStoreId + action + businessRef` |
| `WriteResult` | 执行结果:`EXECUTED` / `ALREADY_COMPLETED`(回放,不算失败) |
| `IdempotencyGuard` | 双锁守卫:业务键(跨 provider)+ provider 请求键(单 provider 内重试) |
### `sync` —— 增量同步
@ -132,6 +161,8 @@ apelet.common.ecommerce @@ -132,6 +161,8 @@ apelet.common.ecommerce
| `TokenStore` | access/refresh token 读写 | MySQL / Redis(加密) |
| `AccessToken` | 令牌载体,`needsRefresh(now, earlySec)` 判断提前续期 |
| `SyncCursorStore` | 水位线读写 | MySQL |
| `IdempotencyStore` | 幂等键抢占与结果记录;`claim` 必须原子 | MySQL / Redis |
| `IdempotencyClaim` / `IdempotencyRecord` / `IdempotencyStatus` | 抢占结果、记录、四态(IN_PROGRESS / SUCCEEDED / FAILED_RETRYABLE / FAILED_FINAL) | — |
| `Sink` | 领域对象落库(当前 `upsertSalesOrders` / `upsertProducts`) | MyBatis |
| `LockProvider` | token 刷新防击穿、账户级互斥 | Redisson / DB |
@ -151,8 +182,10 @@ apelet.common.ecommerce @@ -151,8 +182,10 @@ apelet.common.ecommerce
| 类 | 职责 |
|:---|:---|
| `FakeTransport` | 按 URL 子串 + 方法路由,直接返回录制响应,记录全部请求 |
| `FakeDirectAdapter` | 直连假适配器:游标分页、能力并集即账户能力、记录写调用 |
| `InMemoryAccounts` | 内存版账户仓库 + 密钥提供者 |
| `InMemoryTokenStore` / `InMemoryCursorStore` / `InMemorySink` / `InMemoryLockProvider` | 全套内存 SPI |
| `InMemoryTokenStore` / `InMemoryCursorStore` / `InMemorySink` / `InMemoryLockProvider` / `InMemoryIdempotencyStore` | 全套内存 SPI |
| `MutableClock` | 可推进时钟,验证 TTL / 续期 / 水位线边界 |
| `Fixtures` | 夹具加载,约定 `fixtures/{platform}/{operation}/{case}.json` |
| `Responses` / `TestData` | 响应与同步测试的快捷构造 |
@ -194,13 +227,15 @@ CanonicalKeys.businessIdempotencyKey(Platform.WALMART_SC, "oms-wm-001", "PO-1:pk @@ -194,13 +227,15 @@ CanonicalKeys.businessIdempotencyKey(Platform.WALMART_SC, "oms-wm-001", "PO-1:pk
CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC, "wm-seller-01", "shipping", "PO-1:pkg-1");
```
两把锁不要手写串联,用 `IdempotencyGuard` 执行(见 3.5)。
---
## 三、调用方式
### 状态说明
`ChannelSdk` 门面已可用:`capabilities()` / `salesOrders()` / `products()` 已挂接,
`ChannelSdk` 门面已可用:`capabilities()` / `salesOrders()` / `products()` / `writes()` 已挂接,
`build()` 做必需项校验(缺 `accountRepository`、缺适配器都会抛异常)。
目前仅接入了订单与商品两种能力,其余能力随适配器逐个补齐。
@ -289,6 +324,7 @@ result.watermarkAdvanced(); // true == 水位线已推进到 to @@ -289,6 +324,7 @@ result.watermarkAdvanced(); // true == 水位线已推进到 to
ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(accountRepo) // 必需
.clock(Clock.systemUTC()) // 可选,默认 UTC
.idempotencyStore(idempotencyStore) // 写操作用;不注入则 writes() 失败
.register(new LingxingAdapterFactory(secretProvider, tokenStore, lockProvider, Clock.systemUTC()))
.build(); // 缺必需项立刻抛异常
@ -330,6 +366,42 @@ adapter.supports(ebayAccount, Capability.BILLING); // false @@ -330,6 +366,42 @@ adapter.supports(ebayAccount, Capability.BILLING); // false
缺失能力时抛 `ChannelException.UnsupportedCapabilityException`,由调用方走 3PL / 人工兜底,**SDK 不会自动换 provider**。
### 3.5 写操作幂等(双锁)
所有写操作(标发、发货确认、退款、退货审批……)都经 `IdempotencyGuard` 执行。
业务键不带 provider,与 provider 请求键一起抢占;重复调用返回已完成结果,不算失败。
```java
WriteScope scope = WriteScope.of(
ChannelProvider.LINGXING, // 本次用哪条接入通道
Platform.WALMART_SC,
"oms-wm-001", // 业务店铺维度
"1108413237731", // 平台/领星店铺 ID,用于 provider 请求键
"markShipped",
"PO-1:pkg-1"); // 业务自然键;退款用 returnId:itemId:refundRequestId,禁止用金额
WriteResult<ShipResult> result = sdk.writes().execute(scope,
() -> adapter.markShipped(ctx, command), // 真正调用平台
ShipResult::shipmentId); // 结果引用,回放时返回
result.outcome(); // EXECUTED / ALREADY_COMPLETED
```
行为:
| 情形 | 结果 |
|:---|:---|
| 首次调用 | 抢两把锁 → 执行 → 两把锁都记 SUCCEEDED |
| 重复调用(同 provider) | `ALREADY_COMPLETED`,不调用平台 |
| 重复调用(另一 provider) | `CrossProviderConflictException`,人工确认 |
| 并发调用 | `IdempotencyConflictException`,拒绝重复执行 |
| 抛 `retryable=true` 的异常 | 两把锁记 `FAILED_RETRYABLE`,可重跑 |
| 抛 `retryable=false` 的异常 | 记 `FAILED_FINAL`,需人工介入 |
| 平台已写、业务键未记成功(崩溃) | provider 键命中,回放结果,不重复写 |
`IdempotencyStore.claim` 必须原子(唯一索引 / Redis SETNX),否则并发语义不成立。
`IdempotencyGuard` 不做退避重试,重试节奏由宿主调度决定。
---
## 四、扩展方式
@ -356,7 +428,7 @@ public final class AmazonScAdapter implements SalesOrderCapable, FulfillmentCapa @@ -356,7 +428,7 @@ public final class AmazonScAdapter implements SalesOrderCapable, FulfillmentCapa
}
@Override public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) { ... }
@Override public SalesOrder get(ChannelContext ctx, String orderId) { ... }
@Override public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { ... }
}
```
@ -408,7 +480,7 @@ public final class MyAggregatorAdapter implements SalesOrderCapable, AggregatorC @@ -408,7 +480,7 @@ public final class MyAggregatorAdapter implements SalesOrderCapable, AggregatorC
4. 领域模型加实体(`Refund` / `ReturnOrder` …);
5. `Sink` 加对应 `upsert`,testkit 加 `InMemory` 实现。
**不会改动的**:`PlatformAdapter`、`ChannelContext`、`AccountKey`、`CanonicalKeys`、`SyncEngine`。
**不会改动的**:`PlatformAdapter`、`ChannelContext`、`AccountKey`、`CanonicalKeys`、`SyncEngine`、`IdempotencyGuard`。
### 4.4 新增一个 SPI
@ -485,6 +557,20 @@ assertEquals("PO-123456789", page.items().get(0).channelOrderId()); @@ -485,6 +557,20 @@ assertEquals("PO-123456789", page.items().get(0).channelOrderId());
完整示例见 `lingxing/src/test/java/.../LingxingAdapterTest.java`。
直连抽象与幂等守卫不用真平台也能测:
```java
// core 抽象没被聚合器带偏:单平台、能力并集、游标翻页
FakeDirectAdapter adapter = FakeDirectAdapter.builder().orders(5).pageSize(2).build();
// 双锁幂等:第二次调用回放,平台只真正写一次
MutableClock clock = MutableClock.atUtc("2026-10-29T00:00:00Z");
IdempotencyGuard guard = new IdempotencyGuard(new InMemoryIdempotencyStore(), clock);
guard.execute(scope, () -> adapter.markShipped("pkg-1", "1Z-1"), v -> v);
guard.execute(scope, () -> adapter.markShipped("pkg-1", "1Z-1"), v -> v);
assertEquals(1, adapter.writeCallCount());
```
### 执行
```bash
@ -501,11 +587,20 @@ mvn -pl lingxing -Dtest=LingxingAdapterTest test @@ -501,11 +587,20 @@ mvn -pl lingxing -Dtest=LingxingAdapterTest test
| 项 | 说明 |
|:---|:---|
| `FakeDirectAdapter` 进 testkit | 当前以 `ChannelSdkTest` 内部类形式存在,验证后抽到 testkit |
| `IdempotencyStore` + 双锁 | 写操作幂等尚未装配 |
| `RawPayloadStore` | 原始报文留痕 |
| `RawPayloadStore` | 原始报文留痕(脱敏) |
| `RefundLedger` | 已退款金额汇总与超退校验,与 `IdempotencyGuard` 配合 |
| `DuplicateOrderGuard` | 跨 provider 重复订单告警 |
| `SalesOrder` 补 `platform` 字段 | `Sink` 落库时无法得知订单来自哪个平台,只能靠 `omsStoreId` 反查 |
| 适配器层重试 | 401/429/5xx 目前只分类不重试,退避由宿主包一层 |
| 写操作门面视图 | 只有 `sdk.writes()`,写之前需手动 `resolve` + 转型 + 查能力,缺 `sdk.fulfillment(key)` 这类视图 |
| 其余由文档 `Spec 0` 定义的能力 | 履约、面单、账单、售后、Webhook、异步报表 |
**待处理(已确认,延后执行)**
| 项 | 说明 | 影响面 |
|:---|:---|:---|
| Maven `groupId` 仍是 `apelet` | Java 包名已去掉前缀(`apelet.common.ecommerce` → `common.ecommerce`),但 `pom.xml` 的 `groupId` 未改。需确认新坐标后再统一处理:根 `pom.xml` 的 `groupId` 与三处 `dependencyManagement`,四个子模块的 `<parent>` 与依赖坐标,`GUIDE.md` 第三章的三处示例 | 会影响宿主 OMS 引入依赖的 Maven 坐标 |
**待核对(需官方文档 + 真实沙箱,联调时集中修改)**
| 位置 | 内容 |
@ -517,4 +612,5 @@ mvn -pl lingxing -Dtest=LingxingAdapterTest test @@ -517,4 +612,5 @@ mvn -pl lingxing -Dtest=LingxingAdapterTest test
## 设计文档
- [`GUIDE.md`](GUIDE.md):开发指南 —— 心智模型、基接口逐个讲、接入新平台 8 步、5 层测试
- OMS 侧 `cross-border-fulfillment-sdk-design.md`(Spec 0 总体设计)

60
core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java

@ -0,0 +1,60 @@ @@ -0,0 +1,60 @@
package common.ecommerce.capability;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
import java.util.EnumSet;
/**
* 由适配器与账户推导出的能力报告。
*
* <p>逐项询问 {@link PlatformAdapter#supports(ChannelAccount, Capability)},
* 因此聚合器能按子平台给出精确结果,而直连适配器等价于 {@code capabilities()}。</p>
*/
public final class AdapterCapabilityReport implements CapabilityReport {
private final PlatformAdapter adapter;
private final ChannelAccount account;
private final EnumSet<Capability> supported;
public AdapterCapabilityReport(PlatformAdapter adapter, ChannelAccount account) {
this.adapter = adapter;
this.account = account;
this.supported = EnumSet.noneOf(Capability.class);
for (Capability c : Capability.values()) {
if (adapter.supports(account, c)) {
supported.add(c);
}
}
}
@Override
public boolean supports(Capability capability) {
return supported.contains(capability);
}
@Override
public EnumSet<Capability> supported() {
return EnumSet.copyOf(supported);
}
@Override
public EnumSet<Capability> unsupported() {
EnumSet<Capability> all = EnumSet.allOf(Capability.class);
all.removeAll(supported);
return all;
}
public PlatformAdapter adapter() {
return adapter;
}
public ChannelAccount account() {
return account;
}
@Override
public String toString() {
return "Capabilities[" + adapter.adapterId() + "/" + account.omsStoreId() + "] supported=" + supported;
}
}

54
core/src/main/java/common/ecommerce/capability/AggregatorCapable.java

@ -0,0 +1,54 @@ @@ -0,0 +1,54 @@
package common.ecommerce.capability;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.Platform;
import java.util.List;
/**
* 聚合器扩展:列出子渠道(如领星店铺/平台码)。
*
* <p>子渠道由 {@code ChannelAccount.platformCode} + {@code externalStoreId} 配置,
* 不新增平台模块。</p>
*/
public interface AggregatorCapable extends PlatformAdapter {
List<SubChannel> listSubChannels(ChannelAccount account);
/** 聚合器通过子平台的 platform_code 细化能力。 */
@Override
boolean supports(ChannelAccount account, Capability capability);
/** 子渠道。 */
final class SubChannel {
private final int platformCode;
private final String externalStoreId;
private final Platform platform;
private final String name;
public SubChannel(int platformCode, String externalStoreId, Platform platform, String name) {
this.platformCode = platformCode;
this.externalStoreId = externalStoreId;
this.platform = platform;
this.name = name;
}
public int platformCode() {
return platformCode;
}
public String externalStoreId() {
return externalStoreId;
}
public Platform platform() {
return platform;
}
public String name() {
return name;
}
}
}

19
core/src/main/java/common/ecommerce/capability/CapabilityReport.java

@ -0,0 +1,19 @@ @@ -0,0 +1,19 @@
package common.ecommerce.capability;
import common.ecommerce.model.Capability;
import java.util.EnumSet;
/**
* 能力报告:只读,不触发真实 API。
*
* <p>调用方据此决定是否换账户、走直连或人工,SDK 不做推荐与兜底。</p>
*/
public interface CapabilityReport {
boolean supports(Capability capability);
EnumSet<Capability> supported();
EnumSet<Capability> unsupported();
}

36
core/src/main/java/common/ecommerce/capability/PlatformAdapter.java

@ -0,0 +1,36 @@ @@ -0,0 +1,36 @@
package common.ecommerce.capability;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
import java.util.EnumSet;
import java.util.Set;
/**
* 平台适配器基座。直连适配器与聚合器都实现它。
*/
public interface PlatformAdapter {
/** 适配器标识,如 amazon-sc / lingxing。 */
String adapterId();
ChannelProvider provider();
/** 该适配器覆盖的平台。 */
Set<Platform> platforms();
/** 适配器能力并集。 */
EnumSet<Capability> capabilities();
/**
* 按账户细化能力。
*
* <p>直连适配器默认使用 {@link #capabilities()};聚合器按账户的子平台覆盖,
* 例如领星对 Walmart 支持标发、对 eBay 只支持订单。</p>
*/
default boolean supports(ChannelAccount account, Capability capability) {
return capabilities().contains(capability);
}
}

25
core/src/main/java/common/ecommerce/capability/ProductCapable.java

@ -0,0 +1,25 @@ @@ -0,0 +1,25 @@
package common.ecommerce.capability;
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.ProductSyncStrategy;
import common.ecommerce.sdk.ChannelContext;
/**
* 商品 / Listing 能力。
*/
public interface ProductCapable extends PlatformAdapter {
/** 适配器声明自己支持哪一种同步策略。 */
ProductSyncStrategy syncStrategy();
Page<ProductListing> pull(ChannelContext ctx, ProductQuery query);
ProductListing get(ChannelContext ctx, String platformSku);
default Capability requiredCapability() {
return Capability.PRODUCT;
}
}

39
core/src/main/java/common/ecommerce/capability/Products.java

@ -0,0 +1,39 @@ @@ -0,0 +1,39 @@
package common.ecommerce.capability;
import common.ecommerce.error.ChannelException;
import common.ecommerce.model.Capability;
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.sdk.ChannelContext;
/** 门面持有的商品视图。 */
public final class Products {
private final PlatformAdapter adapter;
private final ChannelAccount account;
private final ChannelContext ctx;
public Products(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
this.adapter = adapter;
this.account = account;
this.ctx = ctx;
}
public Page<ProductListing> pull(ProductQuery query) {
requireProductCapable();
return ((ProductCapable) adapter).pull(ctx, query);
}
public ProductListing get(String platformSku) {
requireProductCapable();
return ((ProductCapable) adapter).get(ctx, platformSku);
}
private void requireProductCapable() {
if (!adapter.supports(account, Capability.PRODUCT) || !(adapter instanceof ProductCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.PRODUCT);
}
}
}

29
core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java

@ -0,0 +1,29 @@ @@ -0,0 +1,29 @@
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.support.Page;
import common.ecommerce.model.Capability;
import common.ecommerce.sdk.ChannelContext;
/**
* 3P 销售订单能力:消费者订单。
*/
public interface SalesOrderCapable extends PlatformAdapter {
/** 分页拉取。时间窗与游标由适配器解释。 */
Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query);
/** 单订单详情。 */
SalesOrder get(ChannelContext ctx, String channelOrderId);
/**
* 默认实现:未声明该能力即拒绝,避免适配器漏实现导致静默返回空。
*/
default void requireCapability() {
if (!capabilities().contains(Capability.SALES_ORDER)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER);
}
}
}

41
core/src/main/java/common/ecommerce/capability/SalesOrders.java

@ -0,0 +1,41 @@ @@ -0,0 +1,41 @@
package common.ecommerce.capability;
import common.ecommerce.model.Capability;
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.support.Page;
import common.ecommerce.sdk.ChannelContext;
/**
* 门面持有的销售订单视图。调用前做能力检查,缺失时显式拒绝。
*/
public final class SalesOrders {
private final PlatformAdapter adapter;
private final ChannelAccount account;
private final ChannelContext ctx;
public SalesOrders(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
this.adapter = adapter;
this.account = account;
this.ctx = ctx;
}
public Page<SalesOrder> pull(SalesOrderQuery query) {
requireSalesOrderCapable();
return ((SalesOrderCapable) adapter).pull(ctx, query);
}
public SalesOrder get(String channelOrderId) {
requireSalesOrderCapable();
return ((SalesOrderCapable) adapter).get(ctx, channelOrderId);
}
private void requireSalesOrderCapable() {
if (!adapter.supports(account, Capability.SALES_ORDER) || !(adapter instanceof SalesOrderCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER);
}
}
}

17
core/src/main/java/common/ecommerce/error/AuthException.java

@ -0,0 +1,17 @@ @@ -0,0 +1,17 @@
package common.ecommerce.error;
/**
* 认证失败:401/403、token 失效。刷新后重试一次;仍失败则告警并停用账户。
*/
public class AuthException extends ChannelException {
private static final long serialVersionUID = 1L;
public AuthException(Builder b) {
super(b, null);
}
public AuthException(Builder b, Throwable cause) {
super(b, cause);
}
}

154
core/src/main/java/common/ecommerce/error/ChannelException.java

@ -0,0 +1,154 @@ @@ -0,0 +1,154 @@
package common.ecommerce.error;
import common.ecommerce.model.Capability;
import common.ecommerce.model.Platform;
/**
* 统一异常基类。适配器把平台错误映射到这里;{@code rawResponse} 必须已脱敏。
*/
public class ChannelException extends RuntimeException {
private static final long serialVersionUID = 1L;
private final Platform platform;
private final String provider;
private final String omsStoreId;
private final String operation;
private final String requestId;
private final String platformCode;
private final boolean retryable;
private final String rawResponse;
public ChannelException(Builder b, Throwable cause) {
super(b.message != null ? b.message : b.operation, cause);
this.platform = b.platform;
this.provider = b.provider;
this.omsStoreId = b.omsStoreId;
this.operation = b.operation;
this.requestId = b.requestId;
this.platformCode = b.platformCode;
this.retryable = b.retryable;
this.rawResponse = b.rawResponse;
}
public static Builder builder() {
return new Builder();
}
public Platform platform() {
return platform;
}
public String provider() {
return provider;
}
public String omsStoreId() {
return omsStoreId;
}
public String operation() {
return operation;
}
public String requestId() {
return requestId;
}
public String platformCode() {
return platformCode;
}
public boolean retryable() {
return retryable;
}
public String rawResponse() {
return rawResponse;
}
public static class Builder {
protected String message;
protected Platform platform;
protected String provider;
protected String omsStoreId;
protected String operation;
protected String requestId;
protected String platformCode;
protected boolean retryable;
protected String rawResponse;
public Builder message(String message) {
this.message = message;
return this;
}
public Builder platform(Platform platform) {
this.platform = platform;
return this;
}
public Builder provider(String provider) {
this.provider = provider;
return this;
}
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
public Builder operation(String operation) {
this.operation = operation;
return this;
}
public Builder requestId(String requestId) {
this.requestId = requestId;
return this;
}
public Builder platformCode(String platformCode) {
this.platformCode = platformCode;
return this;
}
public Builder retryable(boolean retryable) {
this.retryable = retryable;
return this;
}
public Builder rawResponse(String rawResponse) {
this.rawResponse = rawResponse;
return this;
}
public ChannelException build() {
return new ChannelException(this, null);
}
public ChannelException build(Throwable cause) {
return new ChannelException(this, cause);
}
}
/** 平台不支持该能力;调用方走 3PL 或人工兜底。 */
public static class UnsupportedCapabilityException extends ChannelException {
private static final long serialVersionUID = 1L;
private final Capability capability;
public UnsupportedCapabilityException(Capability capability) {
super(ChannelException.builder()
.message("capability [" + capability + "] is not supported by this adapter")
.operation("capabilities"), null);
this.capability = capability;
}
public Capability capability() {
return capability;
}
}
}

22
core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java

@ -0,0 +1,22 @@ @@ -0,0 +1,22 @@
package common.ecommerce.error;
/**
* 跨 provider 冲突:同一业务动作已由另一个 provider 完成。
*
* <p>不自动跨 provider 重试,必须人工确认。</p>
*/
public class CrossProviderConflictException extends ChannelException {
private static final long serialVersionUID = 1L;
private final String completedByProvider;
public CrossProviderConflictException(Builder b, String completedByProvider) {
super(b, null);
this.completedByProvider = completedByProvider;
}
public String completedByProvider() {
return completedByProvider;
}
}

18
core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java

@ -0,0 +1,18 @@ @@ -0,0 +1,18 @@
package common.ecommerce.error;
/** 写操作幂等冲突:重复写。返回已完成结果,不视为失败。 */
public class IdempotencyConflictException extends ChannelException {
private static final long serialVersionUID = 1L;
private final String idempotencyKey;
public IdempotencyConflictException(Builder b, String idempotencyKey) {
super(b, null);
this.idempotencyKey = idempotencyKey;
}
public String idempotencyKey() {
return idempotencyKey;
}
}

13
core/src/main/java/common/ecommerce/error/PlatformBusinessException.java

@ -0,0 +1,13 @@ @@ -0,0 +1,13 @@
package common.ecommerce.error;
/**
* 平台业务错误码。是否重试视错误码而定,保留 code/message/raw。
*/
public class PlatformBusinessException extends ChannelException {
private static final long serialVersionUID = 1L;
public PlatformBusinessException(Builder b) {
super(b, null);
}
}

20
core/src/main/java/common/ecommerce/error/RateLimitException.java

@ -0,0 +1,20 @@ @@ -0,0 +1,20 @@
package common.ecommerce.error;
/**
* 限流:429。遵守 Retry-After 并退避。
*/
public class RateLimitException extends ChannelException {
private static final long serialVersionUID = 1L;
private final long retryAfterMillis;
public RateLimitException(Builder b, long retryAfterMillis) {
super(b, null);
this.retryAfterMillis = retryAfterMillis;
}
public long retryAfterMillis() {
return retryAfterMillis;
}
}

13
core/src/main/java/common/ecommerce/error/TransientException.java

@ -0,0 +1,13 @@ @@ -0,0 +1,13 @@
package common.ecommerce.error;
/**
* 瞬时错误:5xx / 网络 / 超时。退避加抖动后重试,超过上限进入补偿队列。
*/
public class TransientException extends ChannelException {
private static final long serialVersionUID = 1L;
public TransientException(Builder b, Throwable cause) {
super(b, cause);
}
}

17
core/src/main/java/common/ecommerce/error/ValidationException.java

@ -0,0 +1,17 @@ @@ -0,0 +1,17 @@
package common.ecommerce.error;
/**
* 参数或映射错误:4xx。不重试,保留原始报文由人工修正映射。
*/
public class ValidationException extends ChannelException {
private static final long serialVersionUID = 1L;
public ValidationException(Builder b) {
super(b, null);
}
public ValidationException(Builder b, Throwable cause) {
super(b, cause);
}
}

45
core/src/main/java/common/ecommerce/model/Capability.java

@ -0,0 +1,45 @@ @@ -0,0 +1,45 @@
package common.ecommerce.model;
/**
* 能力枚举。
*
* <p>适配器实现哪些能力接口,就声明哪些能力;门面据此在调用前做能力检查,
* 缺失时抛 UnsupportedCapabilityException,而不是静默失败。</p>
*/
public enum Capability {
/** 商品 / Listing */
PRODUCT,
/** 3P 销售订单 */
SALES_ORDER,
/** 1P 采购订单 */
PURCHASE_ORDER,
/** 3P 标发 */
MARK_SHIPPED,
/** 1P DF/DSV 发货确认 */
VENDOR_SHIPMENT,
/** 1P Retail ASN(856) */
ASN,
/** 1P 发票 */
INVOICE,
/** 平台面单 */
LABEL,
/** 作废面单 */
LABEL_VOID,
/** 账单 / 结算 */
BILLING,
/** 退货单 */
RETURNS,
/** 退款 */
REFUND,
/** 退货运单 */
RETURN_LABEL,
/** 1P 扣款 / 红字 */
DEDUCTION,
/** 事件接入 */
WEBHOOK,
/** 异步报表 */
ASYNC_REPORT,
/** EDI 报文 */
EDI
}

23
core/src/main/java/common/ecommerce/model/ChannelProvider.java

@ -0,0 +1,23 @@ @@ -0,0 +1,23 @@
package common.ecommerce.model;
/**
* 接入 provider 枚举。
*
* <p>provider 是接入通道,不是业务渠道。同一个平台店铺可以同时存在
* {@link #DIRECT} 与 {@link #LINGXING} 两条接入通道,由调用方显式选择;
* SDK 不做推荐、不自动选路、不自动兜底。</p>
*/
public enum ChannelProvider {
/** 平台直连 */
DIRECT,
/** 领星聚合 */
LINGXING,
/** Teapplix 订单源 */
TEAPPLIX,
/** 其他聚合器或自建通道 */
CUSTOM;
/** 直连账户的 platformCode 哨兵值,避免 {@code (provider, externalStoreId, platformCode)} 唯一索引因 NULL 失效。 */
public static final int NO_PLATFORM_CODE = 0;
}

12
core/src/main/java/common/ecommerce/model/FulfillmentMode.java

@ -0,0 +1,12 @@ @@ -0,0 +1,12 @@
package common.ecommerce.model;
/** 履约模式,对应四种业务模式中的 A / C / D;B(FBA/WFS 平台仓发货)只读,不在枚举内。 */
public enum FulfillmentMode {
/** A:3P 卖家自发货 */
THIRD_PARTY_SHIP,
/** C:1P 代发(VC DF / 沃尔玛 DSV) */
VENDOR_DF_SHIP,
/** D:1P Retail 供应商供货 */
VENDOR_RETAIL_ASN
}

42
core/src/main/java/common/ecommerce/model/Platform.java

@ -0,0 +1,42 @@ @@ -0,0 +1,42 @@
package common.ecommerce.model;
/**
* 业务平台枚举。
*
* <p>不含 provider:直连与领星等聚合器都映射到同一个平台值,
* 保证业务主键(canonicalKey)在 provider 切换时不变。</p>
*/
public enum Platform {
/** 亚马逊卖家平台(3P) */
AMAZON_SC,
/** 亚马逊供应商平台(1P) */
AMAZON_VC,
/** 沃尔玛 3P */
WALMART_SC,
/** 沃尔玛 1P */
WALMART_1P,
/** TikTok Shop */
TIKTOK,
/** Temu */
TEMU,
/** eBay(首期经领星接入) */
EBAY,
/** SHEIN(首期经领星接入) */
SHEIN,
/** Mirakl 市场 */
MIRAKL,
/** Target(领星平台码待确认) */
TARGET,
/** BestBuy(Mirakl/自定义,待确认) */
BESTBUY,
/** AEPH(平台码待确认) */
AEPH,
/** 自定义平台 */
CUSTOM;
/** 是否属于 1P(平台向供应商采购)语义。 */
public boolean isFirstParty() {
return this == AMAZON_VC || this == WALMART_1P;
}
}

69
core/src/main/java/common/ecommerce/model/account/AccountKey.java

@ -0,0 +1,69 @@ @@ -0,0 +1,69 @@
package common.ecommerce.model.account;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
import common.ecommerce.model.support.CanonicalKeys;
import java.util.Objects;
/**
* 渠道账户标识:{@code provider + platform + omsStoreId}。
*
* <p>这是所有门面调用的隔离维度。同一 omsStoreId 可以同时绑定直连与聚合器账户,
* 业务实体不会因此重复——provider 不进入业务主键,见 {@link CanonicalKeys}。</p>
*/
public final class AccountKey {
private final ChannelProvider provider;
private final Platform platform;
private final String omsStoreId;
private AccountKey(ChannelProvider provider, Platform platform, String omsStoreId) {
this.provider = Objects.requireNonNull(provider, "provider");
this.platform = Objects.requireNonNull(platform, "platform");
if (omsStoreId == null || omsStoreId.trim().isEmpty()) {
throw new IllegalArgumentException("omsStoreId must not be blank");
}
this.omsStoreId = omsStoreId.trim();
}
public static AccountKey of(ChannelProvider provider, Platform platform, String omsStoreId) {
return new AccountKey(provider, platform, omsStoreId);
}
public ChannelProvider provider() {
return provider;
}
public Platform platform() {
return platform;
}
public String omsStoreId() {
return omsStoreId;
}
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (!(o instanceof AccountKey)) {
return false;
}
AccountKey that = (AccountKey) o;
return provider == that.provider
&& platform == that.platform
&& omsStoreId.equals(that.omsStoreId);
}
@Override
public int hashCode() {
return Objects.hash(provider, platform, omsStoreId);
}
@Override
public String toString() {
return provider + ":" + platform + ":" + omsStoreId;
}
}

170
core/src/main/java/common/ecommerce/model/account/ChannelAccount.java

@ -0,0 +1,170 @@ @@ -0,0 +1,170 @@
package common.ecommerce.model.account;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Objects;
/**
* 渠道账户。一个 omsStoreId 可绑定多个 provider 账户。
*
* <p>凭证不落配置:本对象只保存 {@code credentialRef},真实密钥由宿主
* {@code SecretProvider} 按引用取出。</p>
*/
public final class ChannelAccount {
private final AccountKey key;
private final String externalStoreId;
private final Integer platformCode;
private final String region;
private final List<String> marketplaceIds;
private final String credentialRef;
private final String marketplaceZone;
private final String currency;
private final String shipNode;
private final boolean sandbox;
private ChannelAccount(Builder b) {
this.key = Objects.requireNonNull(b.key, "key");
this.externalStoreId = Objects.requireNonNull(b.externalStoreId, "externalStoreId");
this.platformCode = b.platformCode;
this.region = b.region;
this.marketplaceIds = Collections.unmodifiableList(new ArrayList<String>(b.marketplaceIds));
this.credentialRef = Objects.requireNonNull(b.credentialRef, "credentialRef");
this.marketplaceZone = Objects.requireNonNull(b.marketplaceZone, "marketplaceZone");
this.currency = Objects.requireNonNull(b.currency, "currency");
this.shipNode = b.shipNode;
this.sandbox = b.sandbox;
}
public static Builder builder() {
return new Builder();
}
public AccountKey key() {
return key;
}
public String omsStoreId() {
return key.omsStoreId();
}
public Platform platform() {
return key.platform();
}
public ChannelProvider provider() {
return key.provider();
}
/** 平台店铺 ID / 领星 store_id */
public String externalStoreId() {
return externalStoreId;
}
/** 领星 platform_code;直连账户为 null,落库时用 {@link ChannelProvider#NO_PLATFORM_CODE} */
public Integer platformCode() {
return platformCode;
}
public String region() {
return region;
}
public List<String> marketplaceIds() {
return marketplaceIds;
}
/** SecretProvider 的引用,不是密钥本身 */
public String credentialRef() {
return credentialRef;
}
/** IANA 时区 ID,如 America/Los_Angeles */
public String marketplaceZone() {
return marketplaceZone;
}
public String currency() {
return currency;
}
public String shipNode() {
return shipNode;
}
public boolean sandbox() {
return sandbox;
}
public static final class Builder {
private AccountKey key;
private String externalStoreId;
private Integer platformCode;
private String region;
private List<String> marketplaceIds = Collections.emptyList();
private String credentialRef;
private String marketplaceZone;
private String currency;
private String shipNode;
private boolean sandbox;
public Builder key(AccountKey key) {
this.key = key;
return this;
}
public Builder externalStoreId(String externalStoreId) {
this.externalStoreId = externalStoreId;
return this;
}
public Builder platformCode(Integer platformCode) {
this.platformCode = platformCode;
return this;
}
public Builder region(String region) {
this.region = region;
return this;
}
public Builder marketplaceIds(List<String> marketplaceIds) {
this.marketplaceIds = marketplaceIds == null ? Collections.<String>emptyList() : marketplaceIds;
return this;
}
public Builder credentialRef(String credentialRef) {
this.credentialRef = credentialRef;
return this;
}
public Builder marketplaceZone(String marketplaceZone) {
this.marketplaceZone = marketplaceZone;
return this;
}
public Builder currency(String currency) {
this.currency = currency;
return this;
}
public Builder shipNode(String shipNode) {
this.shipNode = shipNode;
return this;
}
public Builder sandbox(boolean sandbox) {
this.sandbox = sandbox;
return this;
}
public ChannelAccount build() {
return new ChannelAccount(this);
}
}
}

99
core/src/main/java/common/ecommerce/model/order/OrderLine.java

@ -0,0 +1,99 @@ @@ -0,0 +1,99 @@
package common.ecommerce.model.order;
import common.ecommerce.model.support.Money;
import java.util.Objects;
/**
* 订单明细行。
*/
public final class OrderLine {
private final String lineId;
private final String platformSku;
private final int quantity;
private final Money unitPrice;
private final Money tax;
private final Money discount;
private OrderLine(Builder b) {
this.lineId = b.lineId;
this.platformSku = Objects.requireNonNull(b.platformSku, "platformSku");
this.quantity = b.quantity;
this.unitPrice = b.unitPrice;
this.tax = b.tax;
this.discount = b.discount;
}
public static Builder builder() {
return new Builder();
}
public String lineId() {
return lineId;
}
public String platformSku() {
return platformSku;
}
public int quantity() {
return quantity;
}
public Money unitPrice() {
return unitPrice;
}
public Money tax() {
return tax;
}
public Money discount() {
return discount;
}
public static final class Builder {
private String lineId;
private String platformSku;
private int quantity;
private Money unitPrice;
private Money tax;
private Money discount;
public Builder lineId(String lineId) {
this.lineId = lineId;
return this;
}
public Builder platformSku(String platformSku) {
this.platformSku = platformSku;
return this;
}
public Builder quantity(int quantity) {
this.quantity = quantity;
return this;
}
public Builder unitPrice(Money unitPrice) {
this.unitPrice = unitPrice;
return this;
}
public Builder tax(Money tax) {
this.tax = tax;
return this;
}
public Builder discount(Money discount) {
this.discount = discount;
return this;
}
public OrderLine build() {
return new OrderLine(this);
}
}
}

155
core/src/main/java/common/ecommerce/model/order/SalesOrder.java

@ -0,0 +1,155 @@ @@ -0,0 +1,155 @@
package common.ecommerce.model.order;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.support.Money;
import common.ecommerce.model.support.PlatformTime;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Objects;
/**
* 3P 销售订单。
*
* <p>统一带 {@code omsStoreId + sourceProvider + sourceAccountId},
* 用于跨 provider 去重与追溯。</p>
*/
public final class SalesOrder {
private final String omsStoreId;
private final String channelOrderId;
private final String status;
private final String buyerName;
private final String shipToCountryCode;
private final List<OrderLine> lines;
private final Money totalAmount;
private final PlatformTime occurredAt;
private final ChannelProvider sourceProvider;
private final String sourceAccountId;
private SalesOrder(Builder b) {
this.omsStoreId = Objects.requireNonNull(b.omsStoreId, "omsStoreId");
this.channelOrderId = Objects.requireNonNull(b.channelOrderId, "channelOrderId");
this.status = b.status;
this.buyerName = b.buyerName;
this.shipToCountryCode = b.shipToCountryCode;
this.lines = Collections.unmodifiableList(new ArrayList<OrderLine>(b.lines));
this.totalAmount = b.totalAmount;
this.occurredAt = Objects.requireNonNull(b.occurredAt, "occurredAt");
this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider");
this.sourceAccountId = b.sourceAccountId;
}
public static Builder builder() {
return new Builder();
}
public String omsStoreId() {
return omsStoreId;
}
public String channelOrderId() {
return channelOrderId;
}
public String status() {
return status;
}
public String buyerName() {
return buyerName;
}
public String shipToCountryCode() {
return shipToCountryCode;
}
public List<OrderLine> lines() {
return lines;
}
public Money totalAmount() {
return totalAmount;
}
public PlatformTime occurredAt() {
return occurredAt;
}
public ChannelProvider sourceProvider() {
return sourceProvider;
}
public String sourceAccountId() {
return sourceAccountId;
}
public static final class Builder {
private String omsStoreId;
private String channelOrderId;
private String status;
private String buyerName;
private String shipToCountryCode;
private List<OrderLine> lines = Collections.emptyList();
private Money totalAmount;
private PlatformTime occurredAt;
private ChannelProvider sourceProvider;
private String sourceAccountId;
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
public Builder channelOrderId(String channelOrderId) {
this.channelOrderId = channelOrderId;
return this;
}
public Builder status(String status) {
this.status = status;
return this;
}
public Builder buyerName(String buyerName) {
this.buyerName = buyerName;
return this;
}
public Builder shipToCountryCode(String shipToCountryCode) {
this.shipToCountryCode = shipToCountryCode;
return this;
}
public Builder lines(List<OrderLine> lines) {
this.lines = lines == null ? Collections.<OrderLine>emptyList() : lines;
return this;
}
public Builder totalAmount(Money totalAmount) {
this.totalAmount = totalAmount;
return this;
}
public Builder occurredAt(PlatformTime occurredAt) {
this.occurredAt = occurredAt;
return this;
}
public Builder sourceProvider(ChannelProvider sourceProvider) {
this.sourceProvider = sourceProvider;
return this;
}
public Builder sourceAccountId(String sourceAccountId) {
this.sourceAccountId = sourceAccountId;
return this;
}
public SalesOrder build() {
return new SalesOrder(this);
}
}
}

82
core/src/main/java/common/ecommerce/model/order/SalesOrderQuery.java

@ -0,0 +1,82 @@ @@ -0,0 +1,82 @@
package common.ecommerce.model.order;
import java.time.Instant;
import java.util.Objects;
/**
* 销售订单查询条件(单次查询,不推进水位线)。
*/
public final class SalesOrderQuery {
private final Instant updatedAfter;
private final Instant updatedBefore;
private final int pageSize;
private final String cursor;
private SalesOrderQuery(Builder b) {
this.updatedAfter = Objects.requireNonNull(b.updatedAfter, "updatedAfter");
this.updatedBefore = b.updatedBefore;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
public static Builder builder() {
return new Builder();
}
public Instant updatedAfter() {
return updatedAfter;
}
public Instant updatedBefore() {
return updatedBefore;
}
public int pageSize() {
return pageSize;
}
public String cursor() {
return cursor;
}
public Builder toBuilder() {
return builder()
.updatedAfter(updatedAfter)
.updatedBefore(updatedBefore)
.pageSize(pageSize)
.cursor(cursor);
}
public static final class Builder {
private Instant updatedAfter;
private Instant updatedBefore;
private int pageSize = 100;
private String cursor;
public Builder updatedAfter(Instant updatedAfter) {
this.updatedAfter = updatedAfter;
return this;
}
public Builder updatedBefore(Instant updatedBefore) {
this.updatedBefore = updatedBefore;
return this;
}
public Builder pageSize(int pageSize) {
this.pageSize = pageSize;
return this;
}
public Builder cursor(String cursor) {
this.cursor = cursor;
return this;
}
public SalesOrderQuery build() {
return new SalesOrderQuery(this);
}
}
}

115
core/src/main/java/common/ecommerce/model/product/ProductListing.java

@ -0,0 +1,115 @@ @@ -0,0 +1,115 @@
package common.ecommerce.model.product;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.support.PlatformTime;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Objects;
/**
* 统一商品 / Listing。
*/
public final class ProductListing {
private final String omsStoreId;
private final String platformSku;
private final String title;
private final List<String> imageUrls;
private final String status;
private final PlatformTime updatedAt;
private final ChannelProvider sourceProvider;
private ProductListing(Builder b) {
this.omsStoreId = Objects.requireNonNull(b.omsStoreId, "omsStoreId");
this.platformSku = Objects.requireNonNull(b.platformSku, "platformSku");
this.title = b.title;
this.imageUrls = Collections.unmodifiableList(new ArrayList<String>(b.imageUrls));
this.status = b.status;
this.updatedAt = b.updatedAt;
this.sourceProvider = b.sourceProvider;
}
public static Builder builder() {
return new Builder();
}
public String omsStoreId() {
return omsStoreId;
}
public String platformSku() {
return platformSku;
}
public String title() {
return title;
}
public List<String> imageUrls() {
return imageUrls;
}
public String status() {
return status;
}
public PlatformTime updatedAt() {
return updatedAt;
}
public ChannelProvider sourceProvider() {
return sourceProvider;
}
public static final class Builder {
private String omsStoreId;
private String platformSku;
private String title;
private List<String> imageUrls = Collections.emptyList();
private String status;
private PlatformTime updatedAt;
private ChannelProvider sourceProvider;
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
public Builder platformSku(String platformSku) {
this.platformSku = platformSku;
return this;
}
public Builder title(String title) {
this.title = title;
return this;
}
public Builder imageUrls(List<String> imageUrls) {
this.imageUrls = imageUrls == null ? Collections.<String>emptyList() : imageUrls;
return this;
}
public Builder status(String status) {
this.status = status;
return this;
}
public Builder updatedAt(PlatformTime updatedAt) {
this.updatedAt = updatedAt;
return this;
}
public Builder sourceProvider(ChannelProvider sourceProvider) {
this.sourceProvider = sourceProvider;
return this;
}
public ProductListing build() {
return new ProductListing(this);
}
}
}

74
core/src/main/java/common/ecommerce/model/product/ProductQuery.java

@ -0,0 +1,74 @@ @@ -0,0 +1,74 @@
package common.ecommerce.model.product;
import java.time.Instant;
import java.util.Objects;
/**
* 商品查询条件。
*/
public final class ProductQuery {
private final Instant updatedAfter;
private final Instant updatedBefore;
private final int pageSize;
private final String cursor;
private ProductQuery(Builder b) {
this.updatedAfter = b.updatedAfter;
this.updatedBefore = b.updatedBefore;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
public static Builder builder() {
return new Builder();
}
public Instant updatedAfter() {
return updatedAfter;
}
public Instant updatedBefore() {
return updatedBefore;
}
public int pageSize() {
return pageSize;
}
public String cursor() {
return cursor;
}
public static final class Builder {
private Instant updatedAfter;
private Instant updatedBefore;
private int pageSize = 100;
private String cursor;
public Builder updatedAfter(Instant updatedAfter) {
this.updatedAfter = updatedAfter;
return this;
}
public Builder updatedBefore(Instant updatedBefore) {
this.updatedBefore = updatedBefore;
return this;
}
public Builder pageSize(int pageSize) {
this.pageSize = pageSize;
return this;
}
public Builder cursor(String cursor) {
this.cursor = cursor;
return this;
}
public ProductQuery build() {
return new ProductQuery(this);
}
}
}

12
core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java

@ -0,0 +1,12 @@ @@ -0,0 +1,12 @@
package common.ecommerce.model.product;
/** 商品同步策略,适配器声明自己支持哪一种。 */
public enum ProductSyncStrategy {
/** 时间窗增量 */
INCREMENTAL_TIME_WINDOW,
/** 全量拉取 + 差异比对 */
FULL_PULL_DIFF,
/** 报告 / 文件 */
REPORT
}

115
core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java

@ -0,0 +1,115 @@ @@ -0,0 +1,115 @@
package common.ecommerce.model.support;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
/**
* 三级标识计算。
*
* <ul>
* <li><b>omsStoreId</b>:业务归属,直连与聚合器都映射到同一个店铺</li>
* <li><b>canonicalKey</b>:platform + omsStoreId + 平台实体 ID,用于 upsert、去重、状态流转</li>
* <li><b>sourceKey</b>:provider + platform + externalStoreId + 平台实体 ID,用于原始报文、水位线、审计</li>
* </ul>
*
* <p>provider 不得进入 canonicalKey,否则直连与聚合器切换会把同一实体变成两条。</p>
*/
public final class CanonicalKeys {
private CanonicalKeys() {
}
public static String canonical(Platform platform, String omsStoreId, String platformEntityId) {
return platform.name() + ':' + require(omsStoreId, "omsStoreId") + ':' + require(platformEntityId, "platformEntityId");
}
public static String source(ChannelProvider provider, Platform platform, String externalStoreId, String platformEntityId) {
return provider.name() + ':' + platform.name() + ':' + require(externalStoreId, "externalStoreId")
+ ':' + require(platformEntityId, "platformEntityId");
}
/** 销售订单 canonicalKey:platform + omsStoreId + channelOrderId */
public static String salesOrder(Platform platform, String omsStoreId, String channelOrderId) {
return canonical(platform, omsStoreId, channelOrderId);
}
/** 商品 canonicalKey:platform + omsStoreId + platformSku */
public static String product(Platform platform, String omsStoreId, String platformSku) {
return canonical(platform, omsStoreId, platformSku);
}
/**
* 结算单指纹:hash(periodStart, periodEnd, currency, paymentId/statementNo)。
*
* <p>刻意不含金额,避免不同 provider 的舍入差异造成重复账单;金额差异由 SourceConflict 记录。</p>
*/
public static String statementFingerprint(String periodStart, String periodEnd, String currency, String statementNo) {
return sha256Hex("STMT|" + periodStart + '|' + periodEnd + '|' + currency + '|' + statementNo);
}
/** 账单行指纹:hash(platformTxnId, orderRef, type, amount, currency, postedAt) */
public static String txnFingerprint(String platformTxnId, String orderRef, String type,
String amount, String currency, String postedAt) {
return sha256Hex("TXN|" + platformTxnId + '|' + orderRef + '|' + type + '|' + amount + '|' + currency + '|' + postedAt);
}
/** 事件指纹:hash(eventType, platformOrderId, returnId/refundId, occurredAt, status) */
public static String eventFingerprint(String eventType, String platformOrderId, String returnOrRefundId,
String occurredAt, String status) {
return sha256Hex("EVT|" + eventType + '|' + platformOrderId + '|' + returnOrRefundId + '|' + occurredAt + '|' + status);
}
/** 1P 扣款指纹:hash(poNumber, invoiceNumber, type, amount, currency, period, reason) */
public static String deductionFingerprint(String poNumber, String invoiceNumber, String type,
String amount, String currency, String period, String reason) {
return sha256Hex("DED|" + poNumber + '|' + invoiceNumber + '|' + type + '|'
+ amount + '|' + currency + '|' + period + '|' + reason);
}
/**
* 写操作业务幂等键:platform + omsStoreId + businessRef + action。
*
* <p>不带 provider,直连与聚合器共用,保证同一业务动作只成功一次。</p>
*/
public static String businessIdempotencyKey(Platform platform, String omsStoreId, String businessRef, String action) {
return platform.name() + ':' + require(omsStoreId, "omsStoreId") + ':' + require(businessRef, "businessRef")
+ ':' + require(action, "action");
}
/**
* provider 请求幂等键:provider + platform + externalStoreId + operation + providerRef。
*
* <p>带 provider,用于单 provider 内的重复请求/重试去重。</p>
*/
public static String providerRequestKey(ChannelProvider provider, Platform platform, String externalStoreId,
String operation, String providerRef) {
return provider.name() + ':' + platform.name() + ':' + require(externalStoreId, "externalStoreId")
+ ':' + require(operation, "operation") + ':' + require(providerRef, "providerRef");
}
static String sha256Hex(String raw) {
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] digest = md.digest(raw.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder(digest.length * 2);
for (byte b : digest) {
sb.append(Character.forDigit((b >> 4) & 0xF, 16));
sb.append(Character.forDigit(b & 0xF, 16));
}
return sb.toString();
} catch (NoSuchAlgorithmException e) {
throw new IllegalStateException("SHA-256 not available", e);
}
}
private static String require(String value, String name) {
if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return value.trim();
}
}

104
core/src/main/java/common/ecommerce/model/support/Money.java

@ -0,0 +1,104 @@ @@ -0,0 +1,104 @@
package common.ecommerce.model.support;
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.Currency;
import java.util.Objects;
/**
* 金额:{@link BigDecimal} + {@link Currency}。
*
* <p>禁止使用 double。保留平台原始精度与币种,不做隐式舍入。</p>
*/
public final class Money {
private final BigDecimal amount;
private final Currency currency;
private Money(BigDecimal amount, Currency currency) {
this.amount = Objects.requireNonNull(amount, "amount");
this.currency = Objects.requireNonNull(currency, "currency");
}
public static Money of(BigDecimal amount, String currencyCode) {
return new Money(amount, Currency.getInstance(currencyCode));
}
public static Money of(String amount, String currencyCode) {
return of(new BigDecimal(amount), currencyCode);
}
public static Money zero(String currencyCode) {
return of(BigDecimal.ZERO, currencyCode);
}
public BigDecimal amount() {
return amount;
}
public Currency currency() {
return currency;
}
public String currencyCode() {
return currency.getCurrencyCode();
}
public Money add(Money other) {
requireSameCurrency(other);
return new Money(amount.add(other.amount), currency);
}
public Money subtract(Money other) {
requireSameCurrency(other);
return new Money(amount.subtract(other.amount), currency);
}
public Money multiply(BigDecimal factor) {
return new Money(amount.multiply(factor), currency);
}
/** 按币种最小单位舍入,仅用于展示或平台要求的定长格式,不用于内部累计。 */
public Money round() {
return new Money(amount.setScale(currency.getDefaultFractionDigits(), RoundingMode.HALF_UP), currency);
}
public boolean isNegative() {
return amount.signum() < 0;
}
public int compareTo(Money other) {
requireSameCurrency(other);
return amount.compareTo(other.amount);
}
private void requireSameCurrency(Money other) {
Objects.requireNonNull(other, "other");
if (!currency.equals(other.currency)) {
throw new IllegalArgumentException(
"currency mismatch: " + currency.getCurrencyCode() + " vs " + other.currency.getCurrencyCode());
}
}
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (!(o instanceof Money)) {
return false;
}
Money that = (Money) o;
return amount.compareTo(that.amount) == 0 && currency.equals(that.currency);
}
@Override
public int hashCode() {
return Objects.hash(amount.stripTrailingZeros(), currency);
}
@Override
public String toString() {
return amount.toPlainString() + " " + currency.getCurrencyCode();
}
}

52
core/src/main/java/common/ecommerce/model/support/Page.java

@ -0,0 +1,52 @@ @@ -0,0 +1,52 @@
package common.ecommerce.model.support;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 分页结果的通用载体。
*
* @param <T> 条目类型
*/
public final class Page<T> {
private final List<T> items;
private final String nextCursor;
private final boolean hasMore;
private Page(List<T> items, String nextCursor, boolean hasMore) {
this.items = Collections.unmodifiableList(new ArrayList<T>(items));
this.nextCursor = nextCursor;
this.hasMore = hasMore;
}
public static <T> Page<T> of(List<T> items, String nextCursor) {
return new Page<T>(items, nextCursor, nextCursor != null && !nextCursor.isEmpty());
}
public static <T> Page<T> last(List<T> items) {
return new Page<T>(items, null, false);
}
public static <T> Page<T> empty() {
return new Page<T>(Collections.<T>emptyList(), null, false);
}
public List<T> items() {
return items;
}
/** 下一页游标;null 表示结束。 */
public String nextCursor() {
return nextCursor;
}
public boolean hasMore() {
return hasMore;
}
public int size() {
return items.size();
}
}

85
core/src/main/java/common/ecommerce/model/support/PlatformTime.java

@ -0,0 +1,85 @@ @@ -0,0 +1,85 @@
package common.ecommerce.model.support;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.util.Objects;
/**
* 三轴时间:UTC 是唯一真值,市场当地时间与北京时间是派生/物化视图。
*
* <p>夏令时一律通过 {@link ZoneId} 解析,禁止使用固定偏移量。</p>
*/
public final class PlatformTime {
/** 北京时间固定时区。 */
public static final ZoneId BEIJING_ZONE = ZoneId.of("Asia/Shanghai");
private final Instant utc;
private final ZoneId marketplaceZone;
private PlatformTime(Instant utc, ZoneId marketplaceZone) {
this.utc = Objects.requireNonNull(utc, "utc");
this.marketplaceZone = Objects.requireNonNull(marketplaceZone, "marketplaceZone");
}
public static PlatformTime of(Instant utc, ZoneId marketplaceZone) {
return new PlatformTime(utc, marketplaceZone);
}
public static PlatformTime of(Instant utc, String marketplaceZone) {
return of(utc, ZoneId.of(marketplaceZone));
}
/** 以当前 UTC 时刻构造。 */
public static PlatformTime now(Clock clock, ZoneId marketplaceZone) {
return of(Instant.now(clock), marketplaceZone);
}
/** 存储与计算基准。 */
public Instant utc() {
return utc;
}
public ZoneId marketplaceZone() {
return marketplaceZone;
}
/** 平台/买家当地展示时间。 */
public ZonedDateTime marketplaceLocal() {
return utc.atZone(marketplaceZone);
}
/** 运营/财务/客服展示时间。 */
public ZonedDateTime beijing() {
return utc.atZone(BEIJING_ZONE);
}
/** 在市场当地时区上做偏移,返回新的三轴时间。 */
public PlatformTime plus(java.time.Duration duration) {
return new PlatformTime(utc.plus(duration), marketplaceZone);
}
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (!(o instanceof PlatformTime)) {
return false;
}
PlatformTime that = (PlatformTime) o;
return utc.equals(that.utc) && marketplaceZone.equals(that.marketplaceZone);
}
@Override
public int hashCode() {
return Objects.hash(utc, marketplaceZone);
}
@Override
public String toString() {
return utc + " (" + marketplaceZone + ")";
}
}

47
core/src/main/java/common/ecommerce/sdk/AdapterFactory.java

@ -0,0 +1,47 @@ @@ -0,0 +1,47 @@
package common.ecommerce.sdk;
import common.ecommerce.capability.PlatformAdapter;
import common.ecommerce.model.account.AccountKey;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
import java.util.EnumSet;
/**
* 适配器工厂。直连与聚合器统一注册,SDK 按 AccountKey 的 provider 解析。
*/
public interface AdapterFactory {
String adapterId();
ChannelProvider provider();
EnumSet<Platform> platforms();
PlatformAdapter create(AdapterConfig config);
/** 适配器实例化所需的最小配置;凭证与账户信息在调用时经 ChannelContext 传入。 */
final class AdapterConfig {
private final String endpointBaseUrl;
private final boolean sandbox;
public AdapterConfig(String endpointBaseUrl, boolean sandbox) {
this.endpointBaseUrl = endpointBaseUrl;
this.sandbox = sandbox;
}
public String endpointBaseUrl() {
return endpointBaseUrl;
}
public boolean sandbox() {
return sandbox;
}
}
/** 兜底:由平台推导默认 adapterId,便于日志定位。 */
static String defaultAdapterId(AccountKey key) {
return key.platform().name().toLowerCase() + "-" + key.provider().name().toLowerCase();
}
}

48
core/src/main/java/common/ecommerce/sdk/ChannelContext.java

@ -0,0 +1,48 @@ @@ -0,0 +1,48 @@
package common.ecommerce.sdk;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.Platform;
import java.time.Clock;
/**
* 单次调用的上下文。由 SDK 统一创建并注入适配器,适配器不得自行构造。
*/
public final class ChannelContext {
private final ChannelAccount account;
private final String requestId;
private final Clock clock;
private ChannelContext(ChannelAccount account, String requestId, Clock clock) {
this.account = account;
this.requestId = requestId;
this.clock = clock;
}
public static ChannelContext of(ChannelAccount account, String requestId, Clock clock) {
return new ChannelContext(account, requestId, clock);
}
public ChannelAccount account() {
return account;
}
public String omsStoreId() {
return account.omsStoreId();
}
public Platform platform() {
return account.platform();
}
/** 链路 ID,用于日志与原始报文关联。 */
public String requestId() {
return requestId;
}
/** UTC 时钟;测试可注入固定时间。 */
public Clock clock() {
return clock;
}
}

169
core/src/main/java/common/ecommerce/sdk/ChannelSdk.java

@ -0,0 +1,169 @@ @@ -0,0 +1,169 @@
package common.ecommerce.sdk;
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.model.account.AccountKey;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.spi.ChannelAccountRepository;
import java.time.Clock;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.UUID;
/**
* 渠道 SDK 统一门面。
*
* <p>业务层只依赖本类,不直接感知平台协议。所有外部副作用经 SPI 注入,
* SDK 自身不访问数据库 / Redis / MQ,也不持有线程或定时器。</p>
*
* <p>provider 由调用方在 {@link AccountKey} 中显式指定,SDK 不推荐、
* 不自动选路、不自动兜底;能力缺失时抛
* {@code ChannelException.UnsupportedCapabilityException}。</p>
*/
public final class ChannelSdk implements ProviderResolver {
private final Map<String, PlatformAdapter> adapters;
private final ChannelAccountRepository accountRepository;
private final Clock clock;
private ChannelSdk(Builder b) {
this.adapters = Collections.unmodifiableMap(new LinkedHashMap<String, PlatformAdapter>(b.adapters));
this.accountRepository = b.accountRepository;
this.clock = b.clock;
}
public static Builder builder() {
return new Builder();
}
// ------------------------------------------------------------------ 门面方法
/** 能力矩阵,只读,不触发任何真实 API。 */
public CapabilityReport capabilities(AccountKey key) {
ChannelAccount account = requireAccount(key);
return new AdapterCapabilityReport(resolve(key), account);
}
/** 3P 销售订单视图。 */
public SalesOrders salesOrders(AccountKey key) {
ChannelAccount account = requireAccount(key);
return new SalesOrders(resolve(key), account, newContext(account));
}
/** 商品 / Listing 视图。 */
public Products products(AccountKey key) {
ChannelAccount account = requireAccount(key);
return new Products(resolve(key), account, newContext(account));
}
/** 按 AccountKey 解析适配器;不自动选路、不自动兜底。 */
@Override
public PlatformAdapter resolve(AccountKey key) {
PlatformAdapter adapter = adapters.get(registryKey(key));
if (adapter == null) {
throw new IllegalStateException("no adapter registered for " + key
+ "; registered: " + adapters.keySet());
}
return adapter;
}
// ------------------------------------------------------------------ internals
private ChannelAccount requireAccount(AccountKey key) {
return accountRepository.findByKey(key.provider().name(), key.platform().name(), key.omsStoreId())
.orElseThrow(() -> new IllegalStateException("channel account not configured: " + key));
}
private ChannelContext newContext(ChannelAccount account) {
return ChannelContext.of(account, UUID.randomUUID().toString(), clock);
}
/** 注册维度:provider + platform。同一组合下只能有一个适配器。 */
private static String registryKey(AccountKey key) {
return key.provider().name() + '|' + key.platform().name();
}
// ------------------------------------------------------------------ builder
public static final class Builder {
private final Map<String, PlatformAdapter> adapters = new LinkedHashMap<String, PlatformAdapter>();
private final List<AdapterFactory> factories = new ArrayList<AdapterFactory>();
private ChannelAccountRepository accountRepository;
private Clock clock = Clock.systemUTC();
/** 注入账户仓库;宿主实现。 */
public Builder accountRepository(ChannelAccountRepository accountRepository) {
this.accountRepository = accountRepository;
return this;
}
/** 注入时钟;测试可给固定时间。 */
public Builder clock(Clock clock) {
this.clock = clock;
return this;
}
/** 注册适配器工厂;工厂覆盖的平台会在 build 时创建并注册。 */
public Builder register(AdapterFactory factory) {
this.factories.add(Objects.requireNonNull(factory, "factory"));
return this;
}
public Builder registerAll(Collection<? extends AdapterFactory> factories) {
if (factories != null) {
for (AdapterFactory f : factories) {
register(f);
}
}
return this;
}
/** 直接注册适配器实例,主要用于测试替身。 */
public Builder register(PlatformAdapter adapter) {
Objects.requireNonNull(adapter, "adapter");
for (common.ecommerce.model.Platform p : adapter.platforms()) {
put(adapter.provider().name() + '|' + p.name(), adapter);
}
return this;
}
/**
* 构建门面。
*
* <p>缺必需配置时立刻失败,而不是返回一个不可用的空对象。</p>
*/
public ChannelSdk build() {
if (accountRepository == null) {
throw new IllegalStateException("ChannelSdk requires an accountRepository");
}
if (clock == null) {
throw new IllegalStateException("ChannelSdk requires a clock");
}
if (adapters.isEmpty() && factories.isEmpty()) {
throw new IllegalStateException("ChannelSdk requires at least one adapter or adapter factory");
}
for (AdapterFactory factory : factories) {
register(factory.create(new AdapterFactory.AdapterConfig(null, false)));
}
return new ChannelSdk(this);
}
private void put(String key, PlatformAdapter adapter) {
PlatformAdapter previous = adapters.put(key, adapter);
if (previous != null && previous != adapter) {
throw new IllegalStateException("duplicate adapter for " + key
+ ": " + previous.adapterId() + " / " + adapter.adapterId());
}
}
}
}

14
core/src/main/java/common/ecommerce/sdk/ProviderResolver.java

@ -0,0 +1,14 @@ @@ -0,0 +1,14 @@
package common.ecommerce.sdk;
import common.ecommerce.capability.PlatformAdapter;
import common.ecommerce.model.account.AccountKey;
/**
* 按 AccountKey 解析适配器。
*
* <p>不自动选路、不自动兜底:provider 由调用方在 AccountKey 中显式指定。</p>
*/
public interface ProviderResolver {
PlatformAdapter resolve(AccountKey key);
}

84
core/src/main/java/common/ecommerce/spi/AccessToken.java

@ -0,0 +1,84 @@ @@ -0,0 +1,84 @@
package common.ecommerce.spi;
import java.time.Instant;
import java.util.Objects;
/**
* 访问令牌。
*/
public final class AccessToken {
private final String value;
private final String refreshToken;
private final Instant expiresAt;
private final String tokenType;
private AccessToken(Builder b) {
this.value = Objects.requireNonNull(b.value, "value");
this.refreshToken = b.refreshToken;
this.expiresAt = Objects.requireNonNull(b.expiresAt, "expiresAt");
this.tokenType = b.tokenType == null ? "Bearer" : b.tokenType;
}
public static Builder builder() {
return new Builder();
}
public String value() {
return value;
}
public String refreshToken() {
return refreshToken;
}
public Instant expiresAt() {
return expiresAt;
}
public String tokenType() {
return tokenType;
}
/** 是否已过期或将在 {@code earlyRefreshSeconds} 内过期。 */
public boolean needsRefresh(Instant now, long earlyRefreshSeconds) {
return !now.plusSeconds(earlyRefreshSeconds).isBefore(expiresAt);
}
/** 日志用指纹,不打印令牌本体。 */
public String fingerprint() {
return "token#" + Integer.toHexString(value.hashCode());
}
public static final class Builder {
private String value;
private String refreshToken;
private Instant expiresAt;
private String tokenType;
public Builder value(String value) {
this.value = value;
return this;
}
public Builder refreshToken(String refreshToken) {
this.refreshToken = refreshToken;
return this;
}
public Builder expiresAt(Instant expiresAt) {
this.expiresAt = expiresAt;
return this;
}
public Builder tokenType(String tokenType) {
this.tokenType = tokenType;
return this;
}
public AccessToken build() {
return new AccessToken(this);
}
}
}

16
core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java

@ -0,0 +1,16 @@ @@ -0,0 +1,16 @@
package common.ecommerce.spi;
import common.ecommerce.model.account.ChannelAccount;
import java.util.Optional;
/**
* 渠道账户读取 SPI。由宿主实现(典型 MySQL)。
*/
public interface ChannelAccountRepository {
Optional<ChannelAccount> findByKey(String provider, String platform, String omsStoreId);
/** 同一 omsStoreId 下所有 provider 账户。 */
java.util.List<ChannelAccount> findByOmsStoreId(String omsStoreId);
}

91
core/src/main/java/common/ecommerce/spi/ChannelSecret.java

@ -0,0 +1,91 @@ @@ -0,0 +1,91 @@
package common.ecommerce.spi;
import java.util.Objects;
/**
* 凭证内容。按 provider 需要取用,未使用的字段为 null。
*/
public final class ChannelSecret {
private final String appKey;
private final String appSecret;
private final String clientId;
private final String clientSecret;
private final String refreshToken;
private ChannelSecret(Builder b) {
this.appKey = b.appKey;
this.appSecret = b.appSecret;
this.clientId = b.clientId;
this.clientSecret = b.clientSecret;
this.refreshToken = b.refreshToken;
}
public static Builder builder() {
return new Builder();
}
public String appKey() {
return appKey;
}
public String appSecret() {
return appSecret;
}
public String clientId() {
return clientId;
}
public String clientSecret() {
return clientSecret;
}
public String refreshToken() {
return refreshToken;
}
/** 用于日志的安全指纹,不泄露内容。 */
public String fingerprint() {
String seed = String.valueOf(Objects.hash(appKey, clientId));
return "secret#" + Integer.toHexString(seed.hashCode());
}
public static final class Builder {
private String appKey;
private String appSecret;
private String clientId;
private String clientSecret;
private String refreshToken;
public Builder appKey(String appKey) {
this.appKey = appKey;
return this;
}
public Builder appSecret(String appSecret) {
this.appSecret = appSecret;
return this;
}
public Builder clientId(String clientId) {
this.clientId = clientId;
return this;
}
public Builder clientSecret(String clientSecret) {
this.clientSecret = clientSecret;
return this;
}
public Builder refreshToken(String refreshToken) {
this.refreshToken = refreshToken;
return this;
}
public ChannelSecret build() {
return new ChannelSecret(this);
}
}
}

24
core/src/main/java/common/ecommerce/spi/LockProvider.java

@ -0,0 +1,24 @@ @@ -0,0 +1,24 @@
package common.ecommerce.spi;
import java.util.Optional;
/**
* 锁 SPI。用于 token 刷新防击穿、账户级同步互斥。
*/
public interface LockProvider {
/**
* 尝试获取锁,不阻塞。
*
* @param key 锁键
* @param ttlSeconds 锁自动过期时间
* @return 锁句柄;未获取到返回 empty
*/
Optional<Lock> tryLock(String key, long ttlSeconds);
interface Lock extends AutoCloseable {
@Override
void close();
}
}

14
core/src/main/java/common/ecommerce/spi/SecretProvider.java

@ -0,0 +1,14 @@ @@ -0,0 +1,14 @@
package common.ecommerce.spi;
/**
* 凭证读取 SPI。{@code credentialRef} 由 {@code ChannelAccount} 提供。
*
* <p>真实密钥只在内存中出现,禁止落配置、禁止写日志。</p>
*/
public interface SecretProvider {
/**
* @param credentialRef 形如 {@code kms://oms/lingxing/store-001}
*/
ChannelSecret get(String credentialRef);
}

18
core/src/main/java/common/ecommerce/spi/Sink.java

@ -0,0 +1,18 @@ @@ -0,0 +1,18 @@
package common.ecommerce.spi;
import common.ecommerce.model.support.Page;
import common.ecommerce.model.product.ProductListing;
import common.ecommerce.model.order.SalesOrder;
/**
* 领域对象落库 SPI。SDK 只调用,不碰数据库。
*
* <p>实现方必须按 canonicalKey 做 upsert:同一实体从直连与聚合器同步时
* 不得产生两条记录。</p>
*/
public interface Sink {
void upsertSalesOrders(Page<SalesOrder> page);
void upsertProducts(Page<ProductListing> page);
}

18
core/src/main/java/common/ecommerce/spi/SyncCursorStore.java

@ -0,0 +1,18 @@ @@ -0,0 +1,18 @@
package common.ecommerce.spi;
import common.ecommerce.model.ChannelProvider;
import java.time.Instant;
/**
* 增量水位线 SPI。
*
* <p>按 {@code provider + account + stream} 分开维护;只在整个批次成功后推进。</p>
*/
public interface SyncCursorStore {
/** 返回 null 表示还没有水位线,需要首次全量建底。 */
Instant get(ChannelProvider provider, String accountKey, String stream);
void advance(ChannelProvider provider, String accountKey, String stream, Instant watermark);
}

15
core/src/main/java/common/ecommerce/spi/TokenStore.java

@ -0,0 +1,15 @@ @@ -0,0 +1,15 @@
package common.ecommerce.spi;
import java.util.Optional;
/**
* 访问令牌读取/写入 SPI。宿主负责加密存储。
*/
public interface TokenStore {
Optional<AccessToken> get(String tokenKey);
void save(String tokenKey, AccessToken token);
void remove(String tokenKey);
}

77
core/src/main/java/common/ecommerce/sync/SyncEngine.java

@ -0,0 +1,77 @@ @@ -0,0 +1,77 @@
package common.ecommerce.sync;
import common.ecommerce.model.support.Page;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.spi.Sink;
import common.ecommerce.spi.SyncCursorStore;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.time.Instant;
import java.util.function.BiFunction;
/**
* 增量同步引擎。
*
* <pre>
* from = lastWatermark - overlapWindow
* to = now
* loop 拉一页 → 经 Sink upsert → cursor = page.nextCursor
* 直到 cursor == null
* 全部成功才推进水位线,失败不推进
* </pre>
*
* <p>引擎不持有线程或定时器,由宿主调度触发。</p>
*/
public final class SyncEngine {
private static final Logger LOG = LoggerFactory.getLogger(SyncEngine.class);
private final SyncCursorStore cursorStore;
private final Sink sink;
public SyncEngine(SyncCursorStore cursorStore, Sink sink) {
this.cursorStore = cursorStore;
this.sink = sink;
}
/**
* 同步销售订单。
*
* @param spec 同步维度(provider + account + stream + overlap)
* @param to 本次增量终点
* @param fetch 拉一页的函数:(from, cursor) → page
*/
public SyncResult syncSalesOrders(SyncSpec spec, Instant to,
BiFunction<Instant, String, Page<SalesOrder>> fetch) {
Instant watermark = cursorStore.get(spec.provider(), spec.accountKey(), spec.stream());
Instant from = spec.from(watermark);
if (from == null) {
throw new IllegalStateException("no watermark for " + spec.accountKey()
+ "/" + spec.stream() + ", run full bootstrap first");
}
int pages = 0;
int items = 0;
String cursor = null;
// 首页需要 from,后续页沿用同一 from(时间窗固定,靠游标翻页)
while (true) {
Page<SalesOrder> page = fetch.apply(from, cursor);
if (page == null || page.size() == 0) {
break;
}
sink.upsertSalesOrders(page);
pages++;
items += page.size();
cursor = page.nextCursor();
if (cursor == null) {
break;
}
}
cursorStore.advance(spec.provider(), spec.accountKey(), spec.stream(), to);
LOG.debug("sync {} pages={} items={} from={} to={}", spec.stream(), pages, items, from, to);
return SyncResult.of(pages, items, true);
}
}

43
core/src/main/java/common/ecommerce/sync/SyncResult.java

@ -0,0 +1,43 @@ @@ -0,0 +1,43 @@
package common.ecommerce.sync;
/**
* 单次同步结果。
*/
public final class SyncResult {
private final int pages;
private final int items;
private final boolean watermarkAdvanced;
private SyncResult(int pages, int items, boolean watermarkAdvanced) {
this.pages = pages;
this.items = items;
this.watermarkAdvanced = watermarkAdvanced;
}
public static SyncResult of(int pages, int items, boolean watermarkAdvanced) {
return new SyncResult(pages, items, watermarkAdvanced);
}
public static SyncResult empty() {
return new SyncResult(0, 0, false);
}
public int pages() {
return pages;
}
public int items() {
return items;
}
/** 只有全部页成功才为 true。 */
public boolean watermarkAdvanced() {
return watermarkAdvanced;
}
@Override
public String toString() {
return "SyncResult{pages=" + pages + ", items=" + items + ", watermarkAdvanced=" + watermarkAdvanced + '}';
}
}

59
core/src/main/java/common/ecommerce/sync/SyncSpec.java

@ -0,0 +1,59 @@ @@ -0,0 +1,59 @@
package common.ecommerce.sync;
import common.ecommerce.model.ChannelProvider;
import java.time.Duration;
import java.time.Instant;
/**
* 同步流的执行配置。
*/
public final class SyncSpec {
/** 订单流标识,用于水位线维度。 */
public static final String STREAM_SALES_ORDERS = "salesOrders";
/** 商品流标识。 */
public static final String STREAM_PRODUCTS = "products";
private final ChannelProvider provider;
private final String accountKey;
private final String stream;
private final Duration overlap;
private SyncSpec(ChannelProvider provider, String accountKey, String stream, Duration overlap) {
this.provider = provider;
this.accountKey = accountKey;
this.stream = stream;
this.overlap = overlap;
}
public static SyncSpec of(ChannelProvider provider, String accountKey, String stream, Duration overlap) {
return new SyncSpec(provider, accountKey, stream, overlap);
}
public ChannelProvider provider() {
return provider;
}
public String accountKey() {
return accountKey;
}
public String stream() {
return stream;
}
/** 上次水位线回退的重叠窗口,防边界丢单。 */
public Duration overlap() {
return overlap;
}
/**
* 计算增量起点。
*
* <p>没有水位线时返回 null,由调用方走首次全量。</p>
*/
public Instant from(Instant watermark) {
return watermark == null ? null : watermark.minus(overlap);
}
}

80
core/src/test/java/common/ecommerce/model/support/CanonicalKeysTest.java

@ -0,0 +1,80 @@ @@ -0,0 +1,80 @@
package common.ecommerce.model.support;
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 static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
class CanonicalKeysTest {
@Test
void canonicalKeyMustNotContainProvider() {
// 直连和领星拉到同一订单,canonicalKey 必须相同
String direct = CanonicalKeys.salesOrder(Platform.WALMART_SC, "oms-wm-001", "PO-123");
String lingxing = CanonicalKeys.salesOrder(Platform.WALMART_SC, "oms-wm-001", "PO-123");
assertEquals(direct, lingxing);
assertEquals("WALMART_SC:oms-wm-001:PO-123", direct);
}
@Test
void sourceKeyIncludesProvider() {
String direct = CanonicalKeys.source(ChannelProvider.DIRECT, Platform.WALMART_SC, "wm-seller-01", "PO-123");
String lingxing = CanonicalKeys.source(ChannelProvider.LINGXING, Platform.WALMART_SC, "1108", "PO-123");
assertNotEquals(direct, lingxing);
}
@Test
void statementFingerprintIgnoresAmount() {
String a = CanonicalKeys.statementFingerprint("2026-09-01", "2026-09-30", "USD", "STMT-1");
String b = CanonicalKeys.statementFingerprint("2026-09-01", "2026-09-30", "USD", "STMT-1");
assertEquals(a, b);
assertNotEquals(a, CanonicalKeys.statementFingerprint("2026-09-01", "2026-09-30", "USD", "STMT-2"));
}
@Test
void businessKeyDiffersFromProviderKey() {
String business = CanonicalKeys.businessIdempotencyKey(Platform.WALMART_SC, "oms-wm-001", "PO-1:pkg-1", "shipping");
String providerKey = CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC,
"wm-seller-01", "shipping", "PO-1:pkg-1");
assertNotEquals(business, providerKey);
}
@Test
void blankIdRejected() {
assertThrows(IllegalArgumentException.class,
() -> CanonicalKeys.canonical(Platform.TEMU, " ", "order-1"));
}
@Test
void platformTimeKeepsThreeAxes() {
Instant utc = Instant.parse("2026-10-29T02:00:00Z");
PlatformTime t = PlatformTime.of(utc, ZoneId.of("America/Los_Angeles"));
assertEquals(utc, t.utc());
assertEquals(19, t.marketplaceLocal().getHour()); // 前一天 19:00 PDT
assertEquals(10, t.beijing().getHour());
}
@Test
void dstHandledByZoneId() {
// 2026-03-08 美国太平洋时区进入夏令时
PlatformTime before = PlatformTime.of(Instant.parse("2026-03-08T09:59:00Z"), "America/Los_Angeles");
PlatformTime after = PlatformTime.of(Instant.parse("2026-03-08T10:00:00Z"), "America/Los_Angeles");
assertEquals(1, before.marketplaceLocal().getHour()); // PST UTC-8
assertEquals(3, after.marketplaceLocal().getHour()); // PDT UTC-7
}
@Test
void moneyRejectsCurrencyMix() {
Money usd = Money.of("10.00", "USD");
Money cny = Money.of("10.00", "CNY");
assertThrows(IllegalArgumentException.class, () -> usd.add(cny));
assertEquals("15.00", usd.add(Money.of("5.00", "USD")).amount().toPlainString());
}
}

183
core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java

@ -0,0 +1,183 @@ @@ -0,0 +1,183 @@
package common.ecommerce.sdk;
import common.ecommerce.capability.CapabilityReport;
import common.ecommerce.capability.PlatformAdapter;
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.Page;
import common.ecommerce.model.Platform;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.sdk.ChannelContext;
import common.ecommerce.spi.ChannelAccountRepository;
import org.junit.jupiter.api.Test;
import java.util.Collections;
import java.util.EnumSet;
import java.util.Optional;
import java.util.Set;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertSame;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 门面骨架测试:校验 build 的必需项、路由解析、能力检查。
*/
class ChannelSdkTest {
private static final AccountKey WM = AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001");
/** 假直连适配器:单平台,只有订单能力。 */
static final class FakeDirectAdapter implements common.ecommerce.capability.SalesOrderCapable {
@Override
public String adapterId() {
return "fake-walmart-sc";
}
@Override
public ChannelProvider provider() {
return ChannelProvider.DIRECT;
}
@Override
public Set<Platform> platforms() {
return EnumSet.of(Platform.WALMART_SC);
}
@Override
public EnumSet<Capability> capabilities() {
return EnumSet.of(Capability.SALES_ORDER);
}
@Override
public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) {
return Page.empty();
}
@Override
public SalesOrder get(ChannelContext ctx, String channelOrderId) {
return null;
}
}
static final class FixedAccounts implements ChannelAccountRepository {
private final ChannelAccount account;
FixedAccounts(ChannelAccount account) {
this.account = account;
}
@Override
public Optional<ChannelAccount> findByKey(String provider, String platform, String omsStoreId) {
return account.provider().name().equals(provider)
&& account.platform().name().equals(platform)
&& account.omsStoreId().equals(omsStoreId)
? Optional.of(account) : Optional.<ChannelAccount>empty();
}
@Override
public java.util.List<ChannelAccount> findByOmsStoreId(String omsStoreId) {
return Collections.singletonList(account);
}
}
private static ChannelAccount walmartAccount() {
return ChannelAccount.builder()
.key(WM)
.externalStoreId("wm-seller-01")
.credentialRef("kms://test/wm")
.marketplaceZone("America/Chicago")
.currency("USD")
.build();
}
private static ChannelSdk sdkWith(PlatformAdapter adapter) {
return ChannelSdk.builder()
.accountRepository(new FixedAccounts(walmartAccount()))
.register(adapter)
.build();
}
@Test
void buildRequiresAccountRepository() {
IllegalStateException ex = assertThrows(IllegalStateException.class,
() -> ChannelSdk.builder().register(new FakeDirectAdapter()).build());
assertTrue(ex.getMessage().contains("accountRepository"), ex.getMessage());
}
@Test
void buildRequiresAtLeastOneAdapter() {
IllegalStateException ex = assertThrows(IllegalStateException.class,
() -> ChannelSdk.builder()
.accountRepository(new FixedAccounts(walmartAccount()))
.build());
assertTrue(ex.getMessage().contains("adapter"), ex.getMessage());
}
@Test
void resolveReturnsRegisteredAdapter() {
FakeDirectAdapter adapter = new FakeDirectAdapter();
ChannelSdk sdk = sdkWith(adapter);
assertSame(adapter, sdk.resolve(WM));
}
@Test
void resolveFailsForUnregisteredProvider() {
ChannelSdk sdk = sdkWith(new FakeDirectAdapter());
AccountKey lingxing = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001");
IllegalStateException ex = assertThrows(IllegalStateException.class, () -> sdk.resolve(lingxing));
assertTrue(ex.getMessage().contains("no adapter registered"), ex.getMessage());
}
@Test
void capabilitiesReflectAdapter() {
ChannelSdk sdk = sdkWith(new FakeDirectAdapter());
CapabilityReport caps = sdk.capabilities(WM);
assertTrue(caps.supports(Capability.SALES_ORDER));
assertEquals(false, caps.supports(Capability.REFUND));
assertTrue(caps.unsupported().contains(Capability.REFUND));
}
@Test
void facadeDelegatesToAdapter() {
ChannelSdk sdk = sdkWith(new FakeDirectAdapter());
Page<SalesOrder> page = sdk.salesOrders(WM).pull(SalesOrderQuery.builder()
.updatedAfter(java.time.Instant.parse("2026-10-25T00:00:00Z"))
.build());
assertNotNull(page);
assertEquals(0, page.size());
}
@Test
void missingCapabilityThrowsUnsupported() {
ChannelSdk sdk = sdkWith(new FakeDirectAdapter());
assertThrows(ChannelException.UnsupportedCapabilityException.class,
() -> sdk.products(WM).pull(common.ecommerce.model.product.ProductQuery.builder().build()));
}
@Test
void unknownAccountFailsFast() {
ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(new FixedAccounts(walmartAccount()))
.register(new FakeDirectAdapter())
.build();
AccountKey other = AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-unknown");
assertThrows(IllegalStateException.class, () -> sdk.capabilities(other));
}
@Test
void duplicateAdapterRegistrationRejected() {
ChannelSdk.Builder builder = ChannelSdk.builder()
.accountRepository(new FixedAccounts(walmartAccount()))
.register(new FakeDirectAdapter());
assertThrows(IllegalStateException.class, () -> builder.register(new FakeDirectAdapter()));
}
}

110
http/src/main/java/common/ecommerce/http/HttpRequest.java

@ -0,0 +1,110 @@ @@ -0,0 +1,110 @@
package common.ecommerce.http;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Objects;
/**
* 统一请求对象。保留原始 header/body 供留痕。
*/
public final class HttpRequest {
private final String method;
private final String url;
private final Map<String, String> headers;
private final String body;
private final String operation;
private HttpRequest(Builder b) {
this.method = Objects.requireNonNull(b.method, "method");
this.url = Objects.requireNonNull(b.url, "url");
this.headers = Collections.unmodifiableMap(new LinkedHashMap<String, String>(b.headers));
this.body = b.body;
this.operation = b.operation;
}
public static Builder builder() {
return new Builder();
}
public static HttpRequest get(String url) {
return builder().method("GET").url(url).build();
}
public static HttpRequest post(String url, String body) {
return builder().method("POST").url(url).body(body).build();
}
public String method() {
return method;
}
public String url() {
return url;
}
public Map<String, String> headers() {
return headers;
}
public String body() {
return body;
}
/** 操作名,如 salesOrders.pull / token.refresh。 */
public String operation() {
return operation;
}
public Builder toBuilder() {
return builder().method(method).url(url).headers(headers).body(body).operation(operation);
}
public static final class Builder {
private String method;
private String url;
private Map<String, String> headers = new LinkedHashMap<String, String>();
private String body;
private String operation;
public Builder method(String method) {
this.method = method;
return this;
}
public Builder url(String url) {
this.url = url;
return this;
}
public Builder header(String name, String value) {
if (value != null) {
this.headers.put(name, value);
}
return this;
}
public Builder headers(Map<String, String> headers) {
if (headers != null) {
this.headers.putAll(headers);
}
return this;
}
public Builder body(String body) {
this.body = body;
return this;
}
public Builder operation(String operation) {
this.operation = operation;
return this;
}
public HttpRequest build() {
return new HttpRequest(this);
}
}
}

69
http/src/main/java/common/ecommerce/http/HttpResponse.java

@ -0,0 +1,69 @@ @@ -0,0 +1,69 @@
package common.ecommerce.http;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* 统一响应对象。保留原始 header/body 供留痕与错误映射。
*/
public final class HttpResponse {
private final int statusCode;
private final Map<String, String> headers;
private final String body;
private final long latencyMillis;
private HttpResponse(int statusCode, Map<String, String> headers, String body, long latencyMillis) {
this.statusCode = statusCode;
this.headers = Collections.unmodifiableMap(new LinkedHashMap<String, String>(headers));
this.body = body;
this.latencyMillis = latencyMillis;
}
public static HttpResponse of(int statusCode, Map<String, String> headers, String body, long latencyMillis) {
return new HttpResponse(statusCode, headers == null ? Collections.<String, String>emptyMap() : headers,
body, latencyMillis);
}
public int statusCode() {
return statusCode;
}
public Map<String, String> headers() {
return headers;
}
public String body() {
return body;
}
public long latencyMillis() {
return latencyMillis;
}
public boolean isSuccess() {
return statusCode >= 200 && statusCode < 300;
}
public boolean isAuthFailure() {
return statusCode == 401 || statusCode == 403;
}
public boolean isRateLimited() {
return statusCode == 429;
}
public boolean isServerError() {
return statusCode >= 500;
}
public String header(String name) {
for (Map.Entry<String, String> e : headers.entrySet()) {
if (e.getKey().equalsIgnoreCase(name)) {
return e.getValue();
}
}
return null;
}
}

9
http/src/main/java/common/ecommerce/http/HttpTransport.java

@ -0,0 +1,9 @@ @@ -0,0 +1,9 @@
package common.ecommerce.http;
/**
* HTTP 传输接口。默认实现 OkHttp,可替换为 Apache HttpClient 或测试用 Fake。
*/
public interface HttpTransport {
HttpResponse execute(HttpRequest request);
}

86
http/src/main/java/common/ecommerce/http/JacksonJsonCodec.java

@ -0,0 +1,86 @@ @@ -0,0 +1,86 @@
package common.ecommerce.http;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import java.util.ArrayList;
import java.util.List;
/**
* Jackson 实现。
*/
public final class JacksonJsonCodec implements JsonCodec {
private final ObjectMapper mapper;
public JacksonJsonCodec() {
this.mapper = new ObjectMapper()
.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
}
public ObjectMapper mapper() {
return mapper;
}
@Override
public String toJson(Object value) {
try {
return mapper.writeValueAsString(value);
} catch (Exception e) {
throw new IllegalArgumentException("serialize failed", e);
}
}
@Override
public <T> T fromJson(String json, Class<T> type) {
try {
return mapper.readValue(json, type);
} catch (Exception e) {
throw new IllegalArgumentException("deserialize failed for " + type.getSimpleName(), e);
}
}
@Override
public String stringAt(String json, String pointer) {
JsonNode node = nodeAt(json, pointer);
return node == null || node.isNull() ? null : node.asText();
}
/** 按点路径取节点,如 {@code data.list}。数组下标用数字段。 */
public JsonNode nodeAt(String json, String pointer) {
if (json == null || pointer == null || pointer.isEmpty()) {
return null;
}
try {
JsonNode cur = mapper.readTree(json);
for (String seg : pointer.split("\\.")) {
if (cur == null || cur.isNull()) {
return null;
}
if (cur.isArray() && seg.matches("\\d+")) {
cur = cur.get(Integer.parseInt(seg));
} else {
cur = cur.get(seg);
}
}
return cur;
} catch (Exception e) {
return null;
}
}
/** 把点路径下的数组节点反序列化为列表。 */
public <T> List<T> listAt(String json, String pointer, Class<T> type) {
JsonNode node = nodeAt(json, pointer);
if (node == null || !node.isArray()) {
return new ArrayList<T>();
}
List<T> out = new ArrayList<T>(node.size());
for (JsonNode item : (ArrayNode) node) {
out.add(mapper.convertValue(item, type));
}
return out;
}
}

17
http/src/main/java/common/ecommerce/http/JsonCodec.java

@ -0,0 +1,17 @@ @@ -0,0 +1,17 @@
package common.ecommerce.http;
/**
* 够用的最小 JSON 读写抽象,避免 core 层绑死 Jackson。
*/
public interface JsonCodec {
String toJson(Object value);
<T> T fromJson(String json, Class<T> type);
/**
* 按点路径取字段值,用于解析平台响应里的 data.list 这类结构。
* 找不到返回 null。
*/
String stringAt(String json, String pointer);
}

70
http/src/main/java/common/ecommerce/http/OkHttpTransport.java

@ -0,0 +1,70 @@ @@ -0,0 +1,70 @@
package common.ecommerce.http;
import common.ecommerce.error.TransientException;
import java.util.concurrent.TimeUnit;
/**
* OkHttp 实现。连接池、超时、统一 User-Agent。
*/
public final class OkHttpTransport implements HttpTransport {
private final okhttp3.OkHttpClient client;
private final String userAgent;
public OkHttpTransport(String userAgent) {
this(userAgent, 5_000, 30_000);
}
public OkHttpTransport(String userAgent, long connectTimeoutMillis, long readTimeoutMillis) {
this.userAgent = userAgent;
this.client = new okhttp3.OkHttpClient.Builder()
.connectTimeout(connectTimeoutMillis, TimeUnit.MILLISECONDS)
.readTimeout(readTimeoutMillis, TimeUnit.MILLISECONDS)
.writeTimeout(readTimeoutMillis, TimeUnit.MILLISECONDS)
.build();
}
@Override
public HttpResponse execute(HttpRequest request) {
long start = System.nanoTime();
okhttp3.Request.Builder rb = new okhttp3.Request.Builder()
.url(request.url())
.header("User-Agent", userAgent);
for (java.util.Map.Entry<String, String> e : request.headers().entrySet()) {
rb.header(e.getKey(), e.getValue());
}
String method = request.method().toUpperCase();
okhttp3.RequestBody body = null;
if (request.body() != null) {
body = okhttp3.RequestBody.create(request.body(),
okhttp3.MediaType.parse("application/json; charset=utf-8"));
}
if ("POST".equals(method)) {
rb.post(body == null ? okhttp3.RequestBody.create(new byte[0], null) : body);
} else if ("PUT".equals(method)) {
rb.put(body == null ? okhttp3.RequestBody.create(new byte[0], null) : body);
} else if ("DELETE".equals(method)) {
rb.delete();
} else {
rb.get();
}
try (okhttp3.Response resp = client.newCall(rb.build()).execute()) {
long latency = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start);
String respBody = resp.body() == null ? null : resp.body().string();
java.util.Map<String, String> headers = new java.util.LinkedHashMap<String, String>();
for (String name : resp.headers().names()) {
headers.put(name, resp.header(name));
}
return HttpResponse.of(resp.code(), headers, respBody, latency);
} catch (java.io.IOException e) {
throw TransientException.class.cast(new TransientException(
common.ecommerce.error.ChannelException.builder()
.message("http transport failed: " + e.getMessage())
.operation(request.operation())
.retryable(true), e));
}
}
}

56
http/src/main/java/common/ecommerce/http/Responses.java

@ -0,0 +1,56 @@ @@ -0,0 +1,56 @@
package common.ecommerce.http;
import common.ecommerce.error.AuthException;
import common.ecommerce.error.ChannelException;
import common.ecommerce.error.RateLimitException;
import common.ecommerce.error.TransientException;
/**
* 响应判定与重试分类。
*
* <ul>
* <li>2xx:成功</li>
* <li>401/403:{@link AuthException},刷新后重试一次</li>
* <li>429:{@link RateLimitException},遵守 Retry-After</li>
* <li>5xx / 网络:{@link TransientException},退避加抖动</li>
* <li>其他 4xx:业务错误,不在此层重试</li>
* </ul>
*/
public final class Responses {
private Responses() {
}
public static void throwIfNotSuccess(HttpResponse response, String operation) {
if (response.isSuccess()) {
return;
}
ChannelException.Builder b = ChannelException.builder()
.message("http " + response.statusCode() + " on " + operation)
.operation(operation)
.platformCode(String.valueOf(response.statusCode()))
.rawResponse(response.body());
if (response.isAuthFailure()) {
throw new AuthException(b);
}
if (response.isRateLimited()) {
throw new RateLimitException(b, parseRetryAfterMillis(response.header("Retry-After")));
}
if (response.isServerError()) {
throw new TransientException(b.retryable(true), null);
}
throw new common.ecommerce.error.ValidationException(b);
}
static long parseRetryAfterMillis(String raw) {
if (raw == null || raw.trim().isEmpty()) {
return 1_000L;
}
try {
return Math.max(0L, Long.parseLong(raw.trim()) * 1000L);
} catch (NumberFormatException e) {
return 1_000L;
}
}
}

10
http/src/main/java/common/ecommerce/http/Signer.java

@ -0,0 +1,10 @@ @@ -0,0 +1,10 @@
package common.ecommerce.http;
/**
* 签名器。按平台实现,差异收敛在适配器内。
*/
public interface Signer {
/** 在请求上补齐签名相关的 header / query。 */
HttpRequest sign(HttpRequest request, common.ecommerce.spi.ChannelSecret secret);
}

85
http/src/main/java/common/ecommerce/http/TokenManager.java

@ -0,0 +1,85 @@ @@ -0,0 +1,85 @@
package common.ecommerce.http;
import common.ecommerce.spi.AccessToken;
import common.ecommerce.spi.ChannelSecret;
import common.ecommerce.spi.LockProvider;
import common.ecommerce.spi.TokenStore;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.time.Clock;
import java.time.Instant;
import java.util.Optional;
/**
* 令牌管理模板。
*
* <ul>
* <li>按账户隔离缓存</li>
* <li>提前 {@code earlyRefreshSeconds} 续期</li>
* <li>刷新用 {@link LockProvider} 防击穿</li>
* <li>刷新失败不返回旧 token(除显式宽限窗口)</li>
* <li>日志只打印指纹</li>
* </ul>
*/
public abstract class TokenManager {
private static final Logger LOG = LoggerFactory.getLogger(TokenManager.class);
protected final TokenStore tokenStore;
protected final LockProvider lockProvider;
protected final Clock clock;
private final long earlyRefreshSeconds;
protected TokenManager(TokenStore tokenStore, LockProvider lockProvider, Clock clock, long earlyRefreshSeconds) {
this.tokenStore = tokenStore;
this.lockProvider = lockProvider;
this.clock = clock;
this.earlyRefreshSeconds = earlyRefreshSeconds;
}
/** 拿到可用的 access token;必要时刷新。 */
public AccessToken getOrRefresh(String tokenKey, ChannelSecret secret) {
Instant now = Instant.now(clock);
Optional<AccessToken> cached = tokenStore.get(tokenKey);
if (cached.isPresent() && !cached.get().needsRefresh(now, earlyRefreshSeconds)) {
return cached.get();
}
Optional<LockProvider.Lock> lock = lockProvider.tryLock("token-refresh:" + tokenKey, 30);
if (!lock.isPresent()) {
// 别的线程在刷新:再读一次,读不到就短等待后重读
Optional<AccessToken> again = tokenStore.get(tokenKey);
if (again.isPresent() && !again.get().needsRefresh(now, earlyRefreshSeconds)) {
return again.get();
}
throw new common.ecommerce.error.AuthException(
common.ecommerce.error.ChannelException.builder()
.message("token refresh in progress for " + tokenKey)
.operation("token.refresh"));
}
try {
Optional<AccessToken> again = tokenStore.get(tokenKey);
Instant nowInLock = Instant.now(clock);
if (again.isPresent() && !again.get().needsRefresh(nowInLock, earlyRefreshSeconds)) {
return again.get();
}
AccessToken refreshed = refresh(secret, cached.orElse(null));
tokenStore.save(tokenKey, refreshed);
LOG.info("token refreshed for {} [{}]", tokenKey, refreshed.fingerprint());
return refreshed;
} finally {
lock.get().close();
}
}
/** 401 后作废并强制重取一次。 */
public AccessToken forceRefresh(String tokenKey, ChannelSecret secret) {
tokenStore.remove(tokenKey);
return getOrRefresh(tokenKey, secret);
}
/** 由平台实现:向平台换取新令牌。 */
protected abstract AccessToken refresh(ChannelSecret secret, AccessToken previous);
}

43
http/src/test/java/common/ecommerce/http/ResponsesTest.java

@ -0,0 +1,43 @@ @@ -0,0 +1,43 @@
package common.ecommerce.http;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
class ResponsesTest {
@Test
void successPasses() {
Responses.throwIfNotSuccess(HttpResponse.of(200, null, "{}", 1), "op");
}
@Test
void authMapsToAuthException() {
assertThrows(common.ecommerce.error.AuthException.class,
() -> Responses.throwIfNotSuccess(HttpResponse.of(401, null, "{}", 1), "op"));
}
@Test
void rateLimitCarriesRetryAfter() {
common.ecommerce.error.RateLimitException ex = assertThrows(
common.ecommerce.error.RateLimitException.class,
() -> Responses.throwIfNotSuccess(
HttpResponse.of(429, java.util.Collections.singletonMap("Retry-After", "3"), "", 1), "op"));
assertEquals(3000L, ex.retryAfterMillis());
}
@Test
void serverErrorIsRetryable() {
common.ecommerce.error.TransientException ex = assertThrows(
common.ecommerce.error.TransientException.class,
() -> Responses.throwIfNotSuccess(HttpResponse.of(503, null, "", 1), "op"));
assertEquals(true, ex.retryable());
}
@Test
void badRequestIsValidation() {
assertThrows(common.ecommerce.error.ValidationException.class,
() -> Responses.throwIfNotSuccess(HttpResponse.of(400, null, "", 1), "op"));
}
}

262
lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java

@ -0,0 +1,262 @@ @@ -0,0 +1,262 @@
package common.ecommerce.lingxing;
import common.ecommerce.capability.AggregatorCapable;
import common.ecommerce.capability.SalesOrderCapable;
import common.ecommerce.error.ChannelException;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.Responses;
import common.ecommerce.http.TokenManager;
import common.ecommerce.lingxing.dto.LingxingOrderDto;
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.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.sdk.ChannelContext;
import common.ecommerce.spi.AccessToken;
import common.ecommerce.spi.ChannelSecret;
import common.ecommerce.spi.LockProvider;
import common.ecommerce.spi.SecretProvider;
import common.ecommerce.spi.TokenStore;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneId;
import java.util.ArrayList;
import java.util.Collections;
import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
/**
* 领星聚合适配器。
*
* <p>一个适配器服务多个子平台,子平台由 {@code ChannelAccount.platformCode} 决定,
* 能力按子平台细化({@link #supports})。首期只实现订单列表拉取。</p>
*
* <p>领星字段名与签名细节标注为「待核对」的地方集中在 {@code dto} 与
* {@link LingxingSigner},联调时只改这两处。</p>
*/
public final class LingxingAdapter implements SalesOrderCapable, AggregatorCapable {
/** 领星订单列表令牌桶:10 req/s(文档 9.3 按接口配置)。 */
private static final int ORDERS_PER_SECOND = 10;
private final String baseUrl;
private final HttpTransport transport;
private final JacksonJsonCodec json;
private final SecretProvider secretProvider;
private final Clock clock;
private final LingxingOrderMapper mapper;
private final TokenManager tokenManager;
private final SimpleRateLimiter rateLimiter;
public LingxingAdapter(String baseUrl, HttpTransport transport, JacksonJsonCodec json,
SecretProvider secretProvider, TokenStore tokenStore, LockProvider lockProvider,
Clock clock) {
this.baseUrl = baseUrl;
this.transport = transport;
this.json = json;
this.secretProvider = secretProvider;
this.clock = clock;
this.mapper = new LingxingOrderMapper(json);
final LingxingTokenClient tokenClient = new LingxingTokenClient(transport, json, baseUrl);
// 领星 access_token 约 2h,提前 10 分钟续期
this.tokenManager = new TokenManager(tokenStore, lockProvider, clock, 600) {
@Override
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) {
return tokenClient.fetch(secret.appKey(), secret.appSecret());
}
};
this.rateLimiter = new SimpleRateLimiter(ORDERS_PER_SECOND);
}
@Override
public String adapterId() {
return LingxingConstants.ADAPTER_ID;
}
@Override
public ChannelProvider provider() {
return ChannelProvider.LINGXING;
}
@Override
public Set<Platform> platforms() {
return EnumSet.of(Platform.AMAZON_SC, Platform.AMAZON_VC, Platform.WALMART_SC, Platform.TIKTOK,
Platform.TEMU, Platform.EBAY, Platform.SHEIN, Platform.MIRAKL, Platform.CUSTOM);
}
@Override
public EnumSet<Capability> capabilities() {
return EnumSet.of(Capability.SALES_ORDER);
}
/**
* 聚合器按子平台细化能力。
*
* <p>eBay / SHEIN / Mirakl / 自定义平台在领星侧只有订单,未见账单与售后接口,
* 因此只声明 SALES_ORDER,缺口由能力报告显式暴露,不假装支持。</p>
*/
@Override
public boolean supports(ChannelAccount account, Capability capability) {
if (!capabilities().contains(capability)) {
return false;
}
Platform p = LingxingConstants.toPlatform(account.platformCode());
if (p == Platform.EBAY || p == Platform.SHEIN || p == Platform.MIRAKL || p == Platform.CUSTOM) {
return capability == Capability.SALES_ORDER;
}
return true;
}
@Override
public List<SubChannel> listSubChannels(ChannelAccount account) {
// 首期一个账户对应一个子渠道;店铺列表接口待接入
SubChannel ch = new SubChannel(
account.platformCode() == null ? 0 : account.platformCode(),
account.externalStoreId(),
LingxingConstants.toPlatform(account.platformCode()),
account.externalStoreId());
return Collections.singletonList(ch);
}
@Override
public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) {
requireCapability();
ChannelAccount account = ctx.account();
ZoneId zone = ZoneId.of(account.marketplaceZone());
Instant from = query.updatedAfter();
Instant to = query.updatedBefore() != null ? query.updatedBefore() : Instant.now(clock);
// 领星时间窗 ≤31 天:超出时截断到最近 31 天,由 SyncEngine 分段推进
if (Duration.between(from, to).toDays() > LingxingConstants.MAX_QUERY_DAYS) {
from = to.minus(Duration.ofDays(LingxingConstants.MAX_QUERY_DAYS));
}
int length = Math.min(query.pageSize() <= 0 ? 100 : query.pageSize(), LingxingConstants.MAX_PAGE_SIZE);
int offset = query.cursor() == null ? 0 : Integer.parseInt(query.cursor());
rateLimiter.acquire();
String body = buildOrderListBody(account, from, to, offset, length);
HttpRequest req = signedPost(ctx, LingxingConstants.PATH_ORDER_LIST, body, "salesOrders.pull");
HttpResponse resp = transport.execute(req);
Responses.throwIfNotSuccess(resp, "salesOrders.pull");
List<LingxingOrderDto> dtos = mapper.parseList(resp.body());
int total = mapper.parseTotal(resp.body());
List<SalesOrder> orders = new ArrayList<SalesOrder>(dtos.size());
for (LingxingOrderDto dto : dtos) {
orders.add(mapper.toSalesOrder(dto, account.omsStoreId(), zone));
}
int nextOffset = offset + dtos.size();
String nextCursor = (dtos.isEmpty() || nextOffset >= total) ? null : String.valueOf(nextOffset);
return Page.of(orders, nextCursor);
}
/** 单订单详情接口待核对(领星以列表接口为主),先显式拒绝而不是返回 null。 */
@Override
public SalesOrder get(ChannelContext ctx, String channelOrderId) {
throw ChannelException.builder()
.message("lingxing order detail is not implemented yet")
.operation("salesOrders.get")
.provider(provider().name())
.omsStoreId(ctx.omsStoreId())
.requestId(ctx.requestId())
.platformCode(channelOrderId)
.build();
}
// ---------------------------------------------------------------- internals
private String buildOrderListBody(ChannelAccount account, Instant from, Instant to, int offset, int length) {
Map<String, Object> body = new LinkedHashMap<String, Object>();
body.put("offset", offset);
body.put("length", length);
if (account.platformCode() != null) {
body.put("platform_code", account.platformCode());
}
if (account.externalStoreId() != null) {
body.put("store_id", account.externalStoreId());
}
// 领星查询时间为 epoch 秒
body.put("update_time_start", from.getEpochSecond());
body.put("update_time_end", to.getEpochSecond());
return json.toJson(body);
}
private HttpRequest signedPost(ChannelContext ctx, String path, String body, String operation) {
ChannelAccount account = ctx.account();
ChannelSecret secret = secretProvider.get(account.credentialRef());
AccessToken token = tokenManager.getOrRefresh(tokenKey(account), secret);
Map<String, String> common = new LinkedHashMap<String, String>();
common.put("app_key", secret.appKey());
common.put("timestamp", String.valueOf(Instant.now(clock).getEpochSecond()));
String sign = LingxingSigner.sign(common, secret);
String url = baseUrl + path
+ "?app_key=" + urlEncode(common.get("app_key"))
+ "&timestamp=" + common.get("timestamp")
+ "&sign=" + sign;
return HttpRequest.builder()
.method("POST")
.url(url)
.header("Content-Type", "application/json")
.header("Authorization", token.tokenType() + " " + token.value())
.header("X-Request-Id", ctx.requestId())
.body(body)
.operation(operation)
.build();
}
private static String tokenKey(ChannelAccount account) {
return "lingxing:" + account.externalStoreId();
}
private static String urlEncode(String v) {
try {
return URLEncoder.encode(v == null ? "" : v, "UTF-8");
} catch (UnsupportedEncodingException e) {
throw new IllegalStateException(e);
}
}
/** 简单令牌桶;首期按接口串行即可,后续替换为通用 RateLimiter。 */
static final class SimpleRateLimiter {
private final long intervalNanos;
private long nextAllowed;
SimpleRateLimiter(int permitsPerSecond) {
this.intervalNanos = 1_000_000_000L / permitsPerSecond;
}
synchronized void acquire() {
long now = System.nanoTime();
if (now < nextAllowed) {
long waitNanos = nextAllowed - now;
try {
Thread.sleep(waitNanos / 1_000_000L, (int) (waitNanos % 1_000_000L));
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
nextAllowed = System.nanoTime() + intervalNanos;
}
}
}

58
lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapterFactory.java

@ -0,0 +1,58 @@ @@ -0,0 +1,58 @@
package common.ecommerce.lingxing;
import common.ecommerce.capability.PlatformAdapter;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
import common.ecommerce.sdk.AdapterFactory;
import common.ecommerce.spi.LockProvider;
import common.ecommerce.spi.SecretProvider;
import common.ecommerce.spi.TokenStore;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.time.Clock;
import java.util.EnumSet;
/**
* 领星适配器工厂。直连适配器使用同一套注册机制。
*/
public final class LingxingAdapterFactory implements AdapterFactory {
private final SecretProvider secretProvider;
private final TokenStore tokenStore;
private final LockProvider lockProvider;
private final Clock clock;
public LingxingAdapterFactory(SecretProvider secretProvider, TokenStore tokenStore,
LockProvider lockProvider, Clock clock) {
this.secretProvider = secretProvider;
this.tokenStore = tokenStore;
this.lockProvider = lockProvider;
this.clock = clock;
}
@Override
public String adapterId() {
return LingxingConstants.ADAPTER_ID;
}
@Override
public ChannelProvider provider() {
return ChannelProvider.LINGXING;
}
@Override
public EnumSet<Platform> platforms() {
return EnumSet.of(Platform.AMAZON_SC, Platform.AMAZON_VC, Platform.WALMART_SC, Platform.TIKTOK,
Platform.TEMU, Platform.EBAY, Platform.SHEIN, Platform.MIRAKL, Platform.CUSTOM);
}
@Override
public PlatformAdapter create(AdapterConfig config) {
String baseUrl = config.endpointBaseUrl() == null
? LingxingConstants.DEFAULT_BASE_URL : config.endpointBaseUrl();
return new LingxingAdapter(baseUrl,
new common.ecommerce.http.OkHttpTransport("common-ecommerce/1.0.0 (lingxing)"),
new common.ecommerce.http.JacksonJsonCodec(),
secretProvider, tokenStore, lockProvider, clock);
}
}

61
lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java

@ -0,0 +1,61 @@ @@ -0,0 +1,61 @@
package common.ecommerce.lingxing;
import common.ecommerce.model.Platform;
/** 领星常量与 platform_code 映射。 */
public final class LingxingConstants {
/** 生产环境基址。 */
public static final String DEFAULT_BASE_URL = "https://openapi.lingxing.com";
public static final String ADAPTER_ID = "lingxing";
/** 获取令牌。 */
public static final String PATH_ACCESS_TOKEN = "/api/auth-server/oauth/access-token";
/** 多平台订单列表(各平台自发货)。 */
public static final String PATH_ORDER_LIST = "/pb/mp/order/v2/list";
/** 店铺列表。 */
public static final String PATH_SELLER_LIST = "/pb/mp/shop/v2/getSellerList";
/** 订单查询时间跨度上限:31 天。 */
public static final int MAX_QUERY_DAYS = 31;
/** 分页 length 上限。 */
public static final int MAX_PAGE_SIZE = 500;
private LingxingConstants() {
}
/**
* 领星 platform_code → 统一 Platform。
*
* <p>10034 同时对应 Mirakl / BestBuy;Target、AEPH 未独立枚举,
* 按文档需要到领星后台确认,此处先映射到 CUSTOM,待核对。</p>
*/
public static Platform toPlatform(Integer platformCode) {
if (platformCode == null) {
return null;
}
switch (platformCode) {
case 10001:
return Platform.AMAZON_SC;
case 10035:
return Platform.AMAZON_VC;
case 10008:
return Platform.WALMART_SC;
case 10011:
return Platform.TIKTOK;
case 10022:
case 10024:
return Platform.TEMU;
case 10003:
return Platform.EBAY;
case 10021:
case 10027:
case 10028:
return Platform.SHEIN;
case 10034:
return Platform.MIRAKL;
default:
return Platform.CUSTOM;
}
}
}

112
lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java

@ -0,0 +1,112 @@ @@ -0,0 +1,112 @@
package common.ecommerce.lingxing;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.lingxing.dto.LingxingOrderDto;
import common.ecommerce.lingxing.dto.LingxingOrderItemDto;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.support.Money;
import common.ecommerce.model.order.OrderLine;
import common.ecommerce.model.Platform;
import common.ecommerce.model.support.PlatformTime;
import common.ecommerce.model.order.SalesOrder;
import java.time.Instant;
import java.time.ZoneId;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.List;
/**
* 领星订单 → 统一模型。
*
* <p>领星订单是唯一的映射入口,平台差异全部收敛在这里。</p>
*/
public final class LingxingOrderMapper {
private final JacksonJsonCodec json;
public LingxingOrderMapper(JacksonJsonCodec json) {
this.json = json;
}
public SalesOrder toSalesOrder(LingxingOrderDto dto, String omsStoreId, ZoneId marketplaceZone) {
Platform platform = LingxingConstants.toPlatform(dto.getPlatformCode());
String channelOrderId = resolveChannelOrderId(dto);
String currency = dto.getCurrencyCode() == null ? "USD" : dto.getCurrencyCode();
List<OrderLine> lines = new ArrayList<OrderLine>();
for (LingxingOrderItemDto item : safe(dto.getItemList())) {
lines.add(OrderLine.builder()
.lineId(item.getOrderItemId())
// 领星 MSKU 与平台 SKU 不总一致;优先 platform_sku,缺失时回落 sku
.platformSku(item.getPlatformSku() != null ? item.getPlatformSku() : item.getSku())
.quantity(item.getQuantity() == null ? 0 : item.getQuantity())
.unitPrice(moneyOrNull(item.getItemPrice(), currency))
.tax(moneyOrNull(item.getTax(), currency))
.discount(moneyOrNull(item.getDiscount(), currency))
.build());
}
Instant occur = dto.getPurchaseTime() != null
? Instant.ofEpochSecond(dto.getPurchaseTime())
: Instant.EPOCH;
return SalesOrder.builder()
.omsStoreId(omsStoreId)
.channelOrderId(channelOrderId)
.status(dto.getOrderStatus())
.buyerName(dto.getBuyerName())
.shipToCountryCode(dto.getCountryCode())
.lines(lines)
.totalAmount(moneyOrNull(dto.getOrderTotal(), currency))
.occurredAt(PlatformTime.of(occur, marketplaceZone))
.sourceProvider(ChannelProvider.LINGXING)
.sourceAccountId(dto.getStoreId())
.build();
}
/**
* channelOrderId 是 canonicalKey 的一部分,必须稳定。
*
* <p>优先平台单号;缺失时退回领星 order_id(此时跨 provider 无法去重,
* 会由 DuplicateOrderGuard 记录差异)。</p>
*/
static String resolveChannelOrderId(LingxingOrderDto dto) {
if (dto.getPlatformOrderNo() != null && !dto.getPlatformOrderNo().trim().isEmpty()) {
return dto.getPlatformOrderNo().trim();
}
List<String> names = dto.getPlatformOrderNames();
if (names != null && !names.isEmpty()) {
List<String> sorted = new ArrayList<String>(names);
Collections.sort(sorted, new Comparator<String>() {
@Override
public int compare(String a, String b) {
return a.compareTo(b);
}
});
return sorted.get(0);
}
return dto.getOrderId();
}
public List<LingxingOrderDto> parseList(String body) {
return json.listAt(body, "data.list", LingxingOrderDto.class);
}
public int parseTotal(String body) {
String total = json.stringAt(body, "data.total");
return total == null ? 0 : Integer.parseInt(total);
}
private static <T> List<T> safe(List<T> in) {
return in == null ? Collections.<T>emptyList() : in;
}
private static Money moneyOrNull(String value, String currency) {
if (value == null || value.trim().isEmpty()) {
return null;
}
return Money.of(value.trim(), currency);
}
}

58
lingxing/src/main/java/common/ecommerce/lingxing/LingxingSigner.java

@ -0,0 +1,58 @@ @@ -0,0 +1,58 @@
package common.ecommerce.lingxing;
import common.ecommerce.spi.ChannelSecret;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Map;
/**
* 领星签名:公共参数按 ASCII 升序拼接 {@code key+value},前后拼 appSecret,MD5 小写。
*
* <p>待核对:官方文档对 sign 的大小写与大写规则未在需求文档中固化,
* 实现集中在 {@link #sign(Map, String)} 一处,便于联调时调整。</p>
*/
public final class LingxingSigner {
private LingxingSigner() {
}
/**
* @param params 参与签名的参数(不含 sign),值不得为 null
* @param appSecret 应用密钥
*/
public static String sign(Map<String, String> params, String appSecret) {
List<String> keys = new ArrayList<String>(params.keySet());
Collections.sort(keys);
StringBuilder sb = new StringBuilder(appSecret);
for (String k : keys) {
sb.append(k).append(params.get(k));
}
sb.append(appSecret);
return md5Hex(sb.toString());
}
/** 便捷:从凭证取 appSecret。 */
public static String sign(Map<String, String> params, ChannelSecret secret) {
return sign(params, secret.appSecret());
}
static String md5Hex(String raw) {
try {
MessageDigest md = MessageDigest.getInstance("MD5");
byte[] digest = md.digest(raw.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder(digest.length * 2);
for (byte b : digest) {
sb.append(Character.forDigit((b >> 4) & 0xF, 16));
sb.append(Character.forDigit(b & 0xF, 16));
}
return sb.toString();
} catch (NoSuchAlgorithmException e) {
throw new IllegalStateException("MD5 not available", e);
}
}
}

67
lingxing/src/main/java/common/ecommerce/lingxing/LingxingTokenClient.java

@ -0,0 +1,67 @@ @@ -0,0 +1,67 @@
package common.ecommerce.lingxing;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JsonCodec;
import common.ecommerce.http.Responses;
import common.ecommerce.spi.AccessToken;
import java.time.Instant;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* 领星令牌获取:{@code POST /api/auth-server/oauth/access-token}。
*
* <p>请求体字段名以官方文档为准(appId/appSecret),这里集中在一处便于联调调整。</p>
*/
public final class LingxingTokenClient {
private final HttpTransport transport;
private final JsonCodec json;
private final String baseUrl;
public LingxingTokenClient(HttpTransport transport, JsonCodec json, String baseUrl) {
this.transport = transport;
this.json = json;
this.baseUrl = baseUrl;
}
public AccessToken fetch(String appId, String appSecret) {
Map<String, String> body = new LinkedHashMap<String, String>();
body.put("appId", appId);
body.put("appSecret", appSecret);
HttpRequest req = HttpRequest.builder()
.method("POST")
.url(baseUrl + LingxingConstants.PATH_ACCESS_TOKEN)
.header("Content-Type", "application/json")
.body(json.toJson(body))
.operation("token.refresh")
.build();
HttpResponse resp = transport.execute(req);
Responses.throwIfNotSuccess(resp, "token.refresh");
String token = json.stringAt(resp.body(), "data.access_token");
if (token == null) {
// 兼容部分版本的 data 为数组
token = json.stringAt(resp.body(), "data.0.access_token");
}
String accessToken = json.stringAt(resp.body(), "access_token");
if (accessToken == null) {
accessToken = token;
}
String refreshToken = json.stringAt(resp.body(), "data.refresh_token");
String expiresIn = json.stringAt(resp.body(), "data.expires_in");
long seconds = expiresIn == null ? 7199L : Long.parseLong(expiresIn);
return AccessToken.builder()
.value(accessToken)
.refreshToken(refreshToken)
.expiresAt(Instant.now().plusSeconds(seconds))
.tokenType("Bearer")
.build();
}
}

196
lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderDto.java

@ -0,0 +1,196 @@ @@ -0,0 +1,196 @@
package common.ecommerce.lingxing.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.ArrayList;
import java.util.List;
/**
* 领星多平台订单列表条目。
*
* <p><b>待核对</b>:字段名依据领星 OpenAPI 文档摘录,联调时以官方最新文档
* 与真实响应为准;调整集中在本 DTO 与 {@code LingxingOrderMapper}。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public class LingxingOrderDto {
/** 领星内部订单 ID。 */
@JsonProperty("order_id")
private String orderId;
/** 平台订单号(Amazon / Walmart PO / eBay 等)。 */
@JsonProperty("platform_order_no")
private String platformOrderNo;
/** 部分接口返回平台单号数组,eBay 需用 platform_order_names 查询。 */
@JsonProperty("platform_order_names")
private List<String> platformOrderNames = new ArrayList<String>();
/** 领星平台码,如 10008=Walmart。 */
@JsonProperty("platform_code")
private Integer platformCode;
/** 领星店铺 ID。 */
@JsonProperty("store_id")
private String storeId;
/** 平台侧订单状态。 */
@JsonProperty("order_status")
private String orderStatus;
/** 买家名称。 */
@JsonProperty("buyer_name")
private String buyerName;
/** 收货国家二字码。 */
@JsonProperty("country_code")
private String countryCode;
/** 订单币种。 */
@JsonProperty("currency_code")
private String currencyCode;
/** 订单总额。 */
@JsonProperty("order_total")
private String orderTotal;
/** 站点本地下单时间字符串。 */
@JsonProperty("purchase_time_locale")
private String purchaseTimeLocale;
/** epoch 秒下单时间。 */
@JsonProperty("purchase_time")
private Long purchaseTime;
/** epoch 秒更新时间。 */
@JsonProperty("update_time")
private Long updateTime;
/** 站点本地更新时间字符串。 */
@JsonProperty("update_time_locale")
private String updateTimeLocale;
@JsonProperty("item_list")
private List<LingxingOrderItemDto> itemList = new ArrayList<LingxingOrderItemDto>();
public String getOrderId() {
return orderId;
}
public void setOrderId(String orderId) {
this.orderId = orderId;
}
public String getPlatformOrderNo() {
return platformOrderNo;
}
public void setPlatformOrderNo(String platformOrderNo) {
this.platformOrderNo = platformOrderNo;
}
public List<String> getPlatformOrderNames() {
return platformOrderNames;
}
public void setPlatformOrderNames(List<String> platformOrderNames) {
this.platformOrderNames = platformOrderNames;
}
public Integer getPlatformCode() {
return platformCode;
}
public void setPlatformCode(Integer platformCode) {
this.platformCode = platformCode;
}
public String getStoreId() {
return storeId;
}
public void setStoreId(String storeId) {
this.storeId = storeId;
}
public String getOrderStatus() {
return orderStatus;
}
public void setOrderStatus(String orderStatus) {
this.orderStatus = orderStatus;
}
public String getBuyerName() {
return buyerName;
}
public void setBuyerName(String buyerName) {
this.buyerName = buyerName;
}
public String getCountryCode() {
return countryCode;
}
public void setCountryCode(String countryCode) {
this.countryCode = countryCode;
}
public String getCurrencyCode() {
return currencyCode;
}
public void setCurrencyCode(String currencyCode) {
this.currencyCode = currencyCode;
}
public String getOrderTotal() {
return orderTotal;
}
public void setOrderTotal(String orderTotal) {
this.orderTotal = orderTotal;
}
public String getPurchaseTimeLocale() {
return purchaseTimeLocale;
}
public void setPurchaseTimeLocale(String purchaseTimeLocale) {
this.purchaseTimeLocale = purchaseTimeLocale;
}
public Long getPurchaseTime() {
return purchaseTime;
}
public void setPurchaseTime(Long purchaseTime) {
this.purchaseTime = purchaseTime;
}
public Long getUpdateTime() {
return updateTime;
}
public void setUpdateTime(Long updateTime) {
this.updateTime = updateTime;
}
public String getUpdateTimeLocale() {
return updateTimeLocale;
}
public void setUpdateTimeLocale(String updateTimeLocale) {
this.updateTimeLocale = updateTimeLocale;
}
public List<LingxingOrderItemDto> getItemList() {
return itemList;
}
public void setItemList(List<LingxingOrderItemDto> itemList) {
this.itemList = itemList;
}
}

88
lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderItemDto.java

@ -0,0 +1,88 @@ @@ -0,0 +1,88 @@
package common.ecommerce.lingxing.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
/** 领星订单明细行。字段名待官方文档核对。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public class LingxingOrderItemDto {
@JsonProperty("order_item_id")
private String orderItemId;
/** 领星 MSKU,需映射回平台 SKU 才能与直连对齐。 */
@JsonProperty("sku")
private String sku;
/** 平台 SKU(部分接口返回)。 */
@JsonProperty("platform_sku")
private String platformSku;
@JsonProperty("quantity")
private Integer quantity;
@JsonProperty("item_price")
private String itemPrice;
@JsonProperty("tax")
private String tax;
@JsonProperty("discount")
private String discount;
public String getOrderItemId() {
return orderItemId;
}
public void setOrderItemId(String orderItemId) {
this.orderItemId = orderItemId;
}
public String getSku() {
return sku;
}
public void setSku(String sku) {
this.sku = sku;
}
public String getPlatformSku() {
return platformSku;
}
public void setPlatformSku(String platformSku) {
this.platformSku = platformSku;
}
public Integer getQuantity() {
return quantity;
}
public void setQuantity(Integer quantity) {
this.quantity = quantity;
}
public String getItemPrice() {
return itemPrice;
}
public void setItemPrice(String itemPrice) {
this.itemPrice = itemPrice;
}
public String getTax() {
return tax;
}
public void setTax(String tax) {
this.tax = tax;
}
public String getDiscount() {
return discount;
}
public void setDiscount(String discount) {
this.discount = discount;
}
}

191
lingxing/src/test/java/common/ecommerce/lingxing/LingxingAdapterTest.java

@ -0,0 +1,191 @@ @@ -0,0 +1,191 @@
package common.ecommerce.lingxing;
import common.ecommerce.model.Capability;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.model.account.AccountKey;
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.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.sdk.ChannelContext;
import common.ecommerce.spi.ChannelSecret;
import common.ecommerce.sync.SyncEngine;
import common.ecommerce.sync.SyncResult;
import common.ecommerce.sync.SyncSpec;
import common.ecommerce.testkit.FakeTransport;
import common.ecommerce.testkit.Fixtures;
import common.ecommerce.testkit.InMemoryAccounts;
import common.ecommerce.testkit.InMemoryCursorStore;
import common.ecommerce.testkit.InMemoryLockProvider;
import common.ecommerce.testkit.InMemorySink;
import common.ecommerce.testkit.InMemoryTokenStore;
import common.ecommerce.testkit.Responses;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.Collections;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 领星订单拉取的契约测试:不依赖网络、数据库、Spring。
*/
class LingxingAdapterTest {
private static final String CREDENTIAL_REF = "kms://test/lingxing/001";
private FakeTransport transport;
private InMemoryTokenStore tokenStore;
private InMemoryAccounts accounts;
private InMemoryLockProvider locks;
private LingxingAdapter adapter;
private ChannelAccount account;
private ChannelContext ctx;
@BeforeEach
void setUp() {
transport = FakeTransport.create();
tokenStore = new InMemoryTokenStore();
accounts = new InMemoryAccounts();
locks = new InMemoryLockProvider();
account = ChannelAccount.builder()
.key(AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001"))
.externalStoreId("1108413237731")
.platformCode(10008)
.credentialRef(CREDENTIAL_REF)
.marketplaceZone("America/Los_Angeles")
.currency("USD")
.build();
accounts.put(account).putSecret(CREDENTIAL_REF, ChannelSecret.builder()
.appKey("test-app-key")
.appSecret("test-app-secret")
.build());
Clock clock = Clock.fixed(Instant.parse("2026-10-29T00:00:00Z"), ZoneOffset.UTC);
adapter = new LingxingAdapter(LingxingConstants.DEFAULT_BASE_URL, transport, new JacksonJsonCodec(),
accounts, tokenStore, locks, clock);
ctx = ChannelContext.of(account, "req-1", clock);
String tokenJson = Fixtures.load(LingxingAdapterTest.class, "lingxing", "token", "success");
String orderJson = Fixtures.load(LingxingAdapterTest.class, "lingxing", "orderList", "success");
transport.route(LingxingConstants.PATH_ACCESS_TOKEN, "POST", r -> Responses.ok(tokenJson));
transport.route(LingxingConstants.PATH_ORDER_LIST, "POST", r -> Responses.ok(orderJson));
}
@Test
void pullsOrdersAndMapsToUnifiedModel() {
Page<SalesOrder> page = adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-10-25T00:00:00Z"))
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z"))
.pageSize(100)
.build());
assertEquals(3, page.size());
assertEquals("PO-123456789", page.items().get(0).channelOrderId());
assertEquals(ChannelProvider.LINGXING, page.items().get(0).sourceProvider());
// total=3, offset 0 + 3 = 3 → 结束
assertNull(page.nextCursor());
}
@Test
void tokenFetchedOnceAndReused() {
SalesOrderQuery q = SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-10-25T00:00:00Z"))
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z"))
.build();
adapter.pull(ctx, q);
adapter.pull(ctx, q);
assertEquals(1, tokenStore.saveCount(), "token should be refreshed only once");
assertEquals(1, locks.acquireCount("token-refresh:lingxing:1108413237731"));
assertNotNull(tokenStore.get("lingxing:1108413237731").orElse(null));
}
@Test
void requestCarriesSignAndBearerToken() {
adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-10-25T00:00:00Z"))
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z"))
.build());
common.ecommerce.http.HttpRequest last = transport.lastRequest();
assertTrue(last.url().contains("app_key=test-app-key"), last.url());
assertTrue(last.url().contains("sign="), last.url());
assertEquals("Bearer lx-access-token-abc", last.headers().get("Authorization"));
assertEquals("req-1", last.headers().get("X-Request-Id"));
assertTrue(last.body().contains("\"platform_code\":10008"), last.body());
assertTrue(last.body().contains("\"store_id\":\"1108413237731\""), last.body());
}
@Test
void queryWindowClampedTo31Days() {
adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-01-01T00:00:00Z"))
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z"))
.build());
String body = transport.lastRequest().body();
long end = Instant.parse("2026-10-26T00:00:00Z").getEpochSecond();
long expectedStart = Instant.parse("2026-10-26T00:00:00Z").minus(Duration.ofDays(31)).getEpochSecond();
assertTrue(body.contains("\"update_time_end\":" + end), body);
assertTrue(body.contains("\"update_time_start\":" + expectedStart), body);
}
@Test
void syncEngineAdvancesWatermarkOnlyAfterWholeBatch() {
InMemoryCursorStore cursors = new InMemoryCursorStore();
InMemorySink sink = new InMemorySink();
SyncSpec spec = SyncSpec.of(ChannelProvider.LINGXING, "oms-wm-001",
SyncSpec.STREAM_SALES_ORDERS, Duration.ofMinutes(10));
cursors.seed(ChannelProvider.LINGXING, "oms-wm-001", SyncSpec.STREAM_SALES_ORDERS,
Instant.parse("2026-10-25T00:00:00Z"));
Instant to = Instant.parse("2026-10-26T00:00:00Z");
SyncResult result = new SyncEngine(cursors, sink).syncSalesOrders(spec, to,
(from, cursor) -> adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(from).updatedBefore(to).build()));
assertEquals(1, result.pages());
assertEquals(3, result.items());
assertTrue(result.watermarkAdvanced());
assertEquals(to, cursors.watermark(ChannelProvider.LINGXING, "oms-wm-001",
SyncSpec.STREAM_SALES_ORDERS));
assertEquals(3, sink.salesOrders().size());
}
@Test
void capabilityIsAccountScoped() {
ChannelAccount ebay = ChannelAccount.builder()
.key(AccountKey.of(ChannelProvider.LINGXING, Platform.EBAY, "oms-ebay-001"))
.externalStoreId("1108413237731")
.platformCode(10003)
.credentialRef(CREDENTIAL_REF)
.marketplaceZone("America/New_York")
.currency("USD")
.build();
assertTrue(adapter.supports(account, Capability.SALES_ORDER));
assertTrue(adapter.supports(ebay, Capability.SALES_ORDER));
// eBay 在领星侧未见账单与退货接口
assertEquals(false, adapter.supports(ebay, Capability.BILLING));
assertEquals(false, adapter.supports(ebay, Capability.REFUND));
}
@Test
void subChannelsReflectAccount() {
assertEquals(1, adapter.listSubChannels(account).size());
assertEquals(10008, adapter.listSubChannels(account).get(0).platformCode());
}
}

73
lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java

@ -0,0 +1,73 @@ @@ -0,0 +1,73 @@
package common.ecommerce.lingxing;
import common.ecommerce.model.Platform;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.lingxing.dto.LingxingOrderDto;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.testkit.Fixtures;
import org.junit.jupiter.api.Test;
import java.time.ZoneId;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
class LingxingOrderMapperTest {
private final JacksonJsonCodec json = new JacksonJsonCodec();
private final LingxingOrderMapper mapper = new LingxingOrderMapper(json);
private List<LingxingOrderDto> fixture() {
String body = Fixtures.load(LingxingOrderMapperTest.class, "lingxing", "orderList", "success");
return json.listAt(body, "data.list", LingxingOrderDto.class);
}
@Test
void mapsWalmartOrder() {
SalesOrder o = mapper.toSalesOrder(fixture().get(0), "oms-wm-001", ZoneId.of("America/Los_Angeles"));
assertEquals("oms-wm-001", o.omsStoreId());
assertEquals("PO-123456789", o.channelOrderId());
assertEquals("Shipped", o.status());
assertEquals("US", o.shipToCountryCode());
assertEquals(2, o.lines().size());
assertEquals("SKU-RED-M", o.lines().get(0).platformSku());
assertEquals(2, o.lines().get(0).quantity());
assertEquals("59.97 USD", o.totalAmount().toString());
assertEquals(ChannelProvider.LINGXING, o.sourceProvider());
assertEquals("1108413237731", o.sourceAccountId());
// epoch 秒 1793001600 → UTC 2026-10-26T08:00:00Z
assertEquals(1793001600L, o.occurredAt().utc().getEpochSecond());
}
@Test
void fallsBackToSkuWhenPlatformSkuMissing() {
SalesOrder o = mapper.toSalesOrder(fixture().get(1), "oms-ebay-001", ZoneId.of("America/New_York"));
assertEquals("MSKU-GREEN-S", o.lines().get(0).platformSku());
assertNull(o.lines().get(0).tax());
}
@Test
void platformOrderNamesSortedForStableCanonicalKey() {
// 返回顺序是 EBAY-2222, EBAY-1111,取排序后第一个,保证多次同步 key 稳定
SalesOrder o = mapper.toSalesOrder(fixture().get(1), "oms-ebay-001", ZoneId.of("America/New_York"));
assertEquals("EBAY-1111", o.channelOrderId());
}
@Test
void fallsBackToLingxingOrderIdWhenNoPlatformNo() {
SalesOrder o = mapper.toSalesOrder(fixture().get(2), "oms-tts-001", ZoneId.of("Europe/London"));
assertEquals("LX-1003", o.channelOrderId());
}
@Test
void platformCodeMapsToUnifiedPlatform() {
assertEquals(Platform.WALMART_SC, LingxingConstants.toPlatform(10008));
assertEquals(Platform.EBAY, LingxingConstants.toPlatform(10003));
assertEquals(Platform.SHEIN, LingxingConstants.toPlatform(10027));
assertEquals(Platform.CUSTOM, LingxingConstants.toPlatform(99999));
assertNull(LingxingConstants.toPlatform(null));
}
}

54
lingxing/src/test/java/common/ecommerce/lingxing/LingxingSignerTest.java

@ -0,0 +1,54 @@ @@ -0,0 +1,54 @@
package common.ecommerce.lingxing;
import common.ecommerce.http.JsonCodec;
import org.junit.jupiter.api.Test;
import java.util.LinkedHashMap;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
class LingxingSignerTest {
@Test
void signatureIsOrderIndependent() {
Map<String, String> a = new LinkedHashMap<String, String>();
a.put("app_key", "k1");
a.put("timestamp", "1793001600");
Map<String, String> b = new LinkedHashMap<String, String>();
b.put("timestamp", "1793001600");
b.put("app_key", "k1");
assertEquals(LingxingSigner.sign(a, "secret"), LingxingSigner.sign(b, "secret"));
}
@Test
void signatureIs32LowercaseHex() {
Map<String, String> p = new LinkedHashMap<String, String>();
p.put("app_key", "k1");
p.put("timestamp", "1793001600");
String sign = LingxingSigner.sign(p, "secret");
assertEquals(32, sign.length());
assertEquals(sign.toLowerCase(), sign);
assertEquals(true, sign.matches("[0-9a-f]{32}"));
}
@Test
void differentSecretDifferentSignature() {
Map<String, String> p = new LinkedHashMap<String, String>();
p.put("app_key", "k1");
assertNotEquals(LingxingSigner.sign(p, "a"), LingxingSigner.sign(p, "b"));
}
@Test
void knownVector() {
// 固定向量:appSecret + "app_key" + "k1" + "timestamp" + "1793001600" + appSecret
Map<String, String> p = new LinkedHashMap<String, String>();
p.put("app_key", "k1");
p.put("timestamp", "1793001600");
assertEquals(LingxingSigner.md5Hex("secretapp_keyk1timestamp1793001600secret"),
LingxingSigner.sign(p, "secret"));
}
}

85
testkit/src/main/java/common/ecommerce/testkit/FakeTransport.java

@ -0,0 +1,85 @@ @@ -0,0 +1,85 @@
package common.ecommerce.testkit;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.function.Function;
/**
* 可编程传输。适配器单测直接返回录制的响应,不需要网络或 mock server。
*
* <pre>
* FakeTransport t = FakeTransport.create()
* .route("lingxing", "order/v2/list", body -&gt; HttpResponse.of(200, null, json, 5));
* </pre>
*/
public final class FakeTransport implements HttpTransport {
private final List<HttpRequest> recorded = new ArrayList<HttpRequest>();
private final List<Route> routes = new ArrayList<Route>();
private Function<HttpRequest, HttpResponse> fallback;
public static FakeTransport create() {
return new FakeTransport();
}
/** 按 URL 子串 + 方法匹配。 */
public FakeTransport route(String urlContains, String method, Function<HttpRequest, HttpResponse> responder) {
routes.add(new Route(urlContains, method, responder));
return this;
}
public FakeTransport route(String urlContains, Function<HttpRequest, HttpResponse> responder) {
return route(urlContains, null, responder);
}
public FakeTransport fallback(Function<HttpRequest, HttpResponse> responder) {
this.fallback = responder;
return this;
}
@Override
public HttpResponse execute(HttpRequest request) {
recorded.add(request);
for (Route r : routes) {
if (request.url().contains(r.urlContains)
&& (r.method == null || r.method.equalsIgnoreCase(request.method()))) {
return r.responder.apply(request);
}
}
if (fallback != null) {
return fallback.apply(request);
}
throw new IllegalStateException("no fake route for " + request.method() + " " + request.url());
}
public List<HttpRequest> recorded() {
return Collections.unmodifiableList(recorded);
}
/** 最后一次请求;无请求时返回 null。 */
public HttpRequest lastRequest() {
return recorded.isEmpty() ? null : recorded.get(recorded.size() - 1);
}
public void clear() {
recorded.clear();
}
private static final class Route {
private final String urlContains;
private final String method;
private final Function<HttpRequest, HttpResponse> responder;
private Route(String urlContains, String method, Function<HttpRequest, HttpResponse> responder) {
this.urlContains = urlContains;
this.method = method;
this.responder = responder;
}
}
}

36
testkit/src/main/java/common/ecommerce/testkit/Fixtures.java

@ -0,0 +1,36 @@ @@ -0,0 +1,36 @@
package common.ecommerce.testkit;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.util.Scanner;
/**
* 夹具加载器。
*
* <p>约定目录:{@code src/test/resources/fixtures/{platform}/{operation}/{case}.json}。
* 适配器测试只依赖录制报文,不依赖网络。</p>
*/
public final class Fixtures {
private Fixtures() {
}
public static String load(Class<?> anchor, String path) {
String resource = path.startsWith("/") ? path : "/" + path;
try (InputStream in = anchor.getResourceAsStream(resource)) {
if (in == null) {
throw new IllegalStateException("fixture not found: " + resource);
}
Scanner scanner = new Scanner(in, StandardCharsets.UTF_8.name()).useDelimiter("\\A");
return scanner.hasNext() ? scanner.next() : "";
} catch (IOException e) {
throw new IllegalStateException("read fixture failed: " + resource, e);
}
}
/** 按约定拼路径。 */
public static String load(Class<?> anchor, String platform, String operation, String caseName) {
return load(anchor, "fixtures/" + platform + "/" + operation + "/" + caseName + ".json");
}
}

59
testkit/src/main/java/common/ecommerce/testkit/InMemoryAccounts.java

@ -0,0 +1,59 @@ @@ -0,0 +1,59 @@
package common.ecommerce.testkit;
import common.ecommerce.spi.ChannelAccountRepository;
import common.ecommerce.spi.ChannelSecret;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.spi.SecretProvider;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
/** 内存版账户仓库与凭证提供者。 */
public final class InMemoryAccounts implements ChannelAccountRepository, SecretProvider {
private final Map<String, ChannelAccount> accounts = new HashMap<String, ChannelAccount>();
private final Map<String, ChannelSecret> secrets = new HashMap<String, ChannelSecret>();
public InMemoryAccounts put(ChannelAccount account) {
accounts.put(id(account.provider().name(), account.platform().name(), account.omsStoreId()), account);
return this;
}
public InMemoryAccounts putSecret(String credentialRef, ChannelSecret secret) {
secrets.put(credentialRef, secret);
return this;
}
@Override
public Optional<ChannelAccount> findByKey(String provider, String platform, String omsStoreId) {
return Optional.ofNullable(accounts.get(id(provider, platform, omsStoreId)));
}
@Override
public List<ChannelAccount> findByOmsStoreId(String omsStoreId) {
List<ChannelAccount> out = new ArrayList<ChannelAccount>();
for (ChannelAccount a : accounts.values()) {
if (a.omsStoreId().equals(omsStoreId)) {
out.add(a);
}
}
return Collections.unmodifiableList(out);
}
@Override
public ChannelSecret get(String credentialRef) {
ChannelSecret s = secrets.get(credentialRef);
if (s == null) {
throw new IllegalStateException("no fake secret for " + credentialRef);
}
return s;
}
private static String id(String provider, String platform, String omsStoreId) {
return provider + '|' + platform + '|' + omsStoreId;
}
}

37
testkit/src/main/java/common/ecommerce/testkit/InMemoryCursorStore.java

@ -0,0 +1,37 @@ @@ -0,0 +1,37 @@
package common.ecommerce.testkit;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.spi.SyncCursorStore;
import java.time.Instant;
import java.util.HashMap;
import java.util.Map;
/** 内存版水位线存储。 */
public final class InMemoryCursorStore implements SyncCursorStore {
private final Map<String, Instant> cursors = new HashMap<String, Instant>();
@Override
public Instant get(ChannelProvider provider, String accountKey, String stream) {
return cursors.get(id(provider, accountKey, stream));
}
@Override
public void advance(ChannelProvider provider, String accountKey, String stream, Instant watermark) {
cursors.put(id(provider, accountKey, stream), watermark);
}
public void seed(ChannelProvider provider, String accountKey, String stream, Instant watermark) {
advance(provider, accountKey, stream, watermark);
}
/** 断言用:读取当前水位线。 */
public Instant watermark(ChannelProvider provider, String accountKey, String stream) {
return get(provider, accountKey, stream);
}
private static String id(ChannelProvider provider, String accountKey, String stream) {
return provider.name() + '|' + accountKey + '|' + stream;
}
}

52
testkit/src/main/java/common/ecommerce/testkit/InMemoryLockProvider.java

@ -0,0 +1,52 @@ @@ -0,0 +1,52 @@
package common.ecommerce.testkit;
import common.ecommerce.spi.LockProvider;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
/** 单线程内存锁,足以验证防击穿分支。 */
public final class InMemoryLockProvider implements LockProvider {
private final Set<String> held = new HashSet<String>();
private final Map<String, Integer> acquireCounts = new HashMap<String, Integer>();
@Override
public synchronized Optional<Lock> tryLock(String key, long ttlSeconds) {
if (held.contains(key)) {
return Optional.empty();
}
held.add(key);
Integer c = acquireCounts.get(key);
acquireCounts.put(key, c == null ? 1 : c + 1);
return Optional.<Lock>of(new Handle(key));
}
public synchronized int acquireCount(String key) {
Integer c = acquireCounts.get(key);
return c == null ? 0 : c;
}
public synchronized boolean isHeld(String key) {
return held.contains(key);
}
private final class Handle implements Lock {
private final String key;
private Handle(String key) {
this.key = key;
}
@Override
public void close() {
synchronized (InMemoryLockProvider.this) {
held.remove(key);
}
}
}
}

47
testkit/src/main/java/common/ecommerce/testkit/InMemorySink.java

@ -0,0 +1,47 @@ @@ -0,0 +1,47 @@
package common.ecommerce.testkit;
import common.ecommerce.model.support.Page;
import common.ecommerce.model.product.ProductListing;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.spi.Sink;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/** 内存版落库 Sink,记录每次 upsert。 */
public final class InMemorySink implements Sink {
private final List<SalesOrder> salesOrders = new ArrayList<SalesOrder>();
private final List<ProductListing> products = new ArrayList<ProductListing>();
private int salesOrderUpsertCalls;
private int productUpsertCalls;
@Override
public void upsertSalesOrders(Page<SalesOrder> page) {
salesOrders.addAll(page.items());
salesOrderUpsertCalls++;
}
@Override
public void upsertProducts(Page<ProductListing> page) {
products.addAll(page.items());
productUpsertCalls++;
}
public List<SalesOrder> salesOrders() {
return Collections.unmodifiableList(salesOrders);
}
public List<ProductListing> products() {
return Collections.unmodifiableList(products);
}
public int salesOrderUpsertCalls() {
return salesOrderUpsertCalls;
}
public int productUpsertCalls() {
return productUpsertCalls;
}
}

36
testkit/src/main/java/common/ecommerce/testkit/InMemoryTokenStore.java

@ -0,0 +1,36 @@ @@ -0,0 +1,36 @@
package common.ecommerce.testkit;
import common.ecommerce.spi.AccessToken;
import common.ecommerce.spi.TokenStore;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;
/** 内存版令牌存储。 */
public final class InMemoryTokenStore implements TokenStore {
private final Map<String, AccessToken> tokens = new HashMap<String, AccessToken>();
private int saveCount;
@Override
public Optional<AccessToken> get(String tokenKey) {
return Optional.ofNullable(tokens.get(tokenKey));
}
@Override
public void save(String tokenKey, AccessToken token) {
tokens.put(tokenKey, token);
saveCount++;
}
@Override
public void remove(String tokenKey) {
tokens.remove(tokenKey);
}
/** 刷新写入次数,用于断言「防击穿只刷新一次」。 */
public int saveCount() {
return saveCount;
}
}

25
testkit/src/main/java/common/ecommerce/testkit/Responses.java

@ -0,0 +1,25 @@ @@ -0,0 +1,25 @@
package common.ecommerce.testkit;
import common.ecommerce.http.HttpResponse;
import java.util.Collections;
/** 快捷构造响应。 */
public final class Responses {
private Responses() {
}
public static HttpResponse ok(String body) {
return HttpResponse.of(200, Collections.<String, String>emptyMap(), body, 1);
}
public static HttpResponse status(int code, String body) {
return HttpResponse.of(code, Collections.<String, String>emptyMap(), body, 1);
}
public static HttpResponse rateLimited(String retryAfterSeconds) {
return HttpResponse.of(429,
Collections.singletonMap("Retry-After", retryAfterSeconds), "", 1);
}
}

32
testkit/src/main/java/common/ecommerce/testkit/TestData.java

@ -0,0 +1,32 @@ @@ -0,0 +1,32 @@
package common.ecommerce.testkit;
import common.ecommerce.model.support.Page;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.spi.SyncCursorStore;
import java.time.Duration;
import java.time.Instant;
/** 测试夹具:常用账户与同步维度。 */
public final class TestData {
private TestData() {
}
public static Instant utc(String iso) {
return Instant.parse(iso);
}
public static Duration overlapMinutes(int minutes) {
return Duration.ofMinutes(minutes);
}
/** 已推进过的水位线,避免测试里每次走全量。 */
public static void seedWatermark(SyncCursorStore store, common.ecommerce.sync.SyncSpec spec, String iso) {
store.advance(spec.provider(), spec.accountKey(), spec.stream(), Instant.parse(iso));
}
public static Page<SalesOrder> pageOf(SalesOrder... orders) {
return Page.last(java.util.Arrays.asList(orders));
}
}
Loading…
Cancel
Save