From ff9ec456c2cdb47592ba7a3ca20850038989b3f1 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Fri, 30 Oct 2026 14:17:05 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E5=8C=85=E5=90=8D=E5=8E=BB?= =?UTF-8?q?=E6=8E=89=20apelet=20=E5=89=8D=E7=BC=80=E5=B9=B6=E6=8C=89?= =?UTF-8?q?=E8=81=8C=E8=B4=A3=E6=8B=86=E5=88=86=20model=20=E5=AD=90?= =?UTF-8?q?=E5=8C=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 包路径 apelet.common.ecommerce → common.ecommerce(四个模块的 main/test 全量迁移) - model 拆为 account / order / product / support 四个子包,枚举留在根包 - 同步更新 README 包结构与导入路径 行为无变化,仅重命名与目录调整。 Co-Authored-By: Claude --- README.md | 152 +++++++++--- .../capability/AdapterCapabilityReport.java | 60 +++++ .../ecommerce/capability/AggregatorCapable.java | 54 +++++ .../ecommerce/capability/CapabilityReport.java | 19 ++ .../ecommerce/capability/PlatformAdapter.java | 36 +++ .../ecommerce/capability/ProductCapable.java | 25 ++ .../java/common/ecommerce/capability/Products.java | 39 +++ .../ecommerce/capability/SalesOrderCapable.java | 29 +++ .../common/ecommerce/capability/SalesOrders.java | 41 ++++ .../java/common/ecommerce/error/AuthException.java | 17 ++ .../common/ecommerce/error/ChannelException.java | 154 ++++++++++++ .../error/CrossProviderConflictException.java | 22 ++ .../error/IdempotencyConflictException.java | 18 ++ .../ecommerce/error/PlatformBusinessException.java | 13 + .../common/ecommerce/error/RateLimitException.java | 20 ++ .../common/ecommerce/error/TransientException.java | 13 + .../ecommerce/error/ValidationException.java | 17 ++ .../java/common/ecommerce/model/Capability.java | 45 ++++ .../common/ecommerce/model/ChannelProvider.java | 23 ++ .../common/ecommerce/model/FulfillmentMode.java | 12 + .../main/java/common/ecommerce/model/Platform.java | 42 ++++ .../common/ecommerce/model/account/AccountKey.java | 69 ++++++ .../ecommerce/model/account/ChannelAccount.java | 170 +++++++++++++ .../common/ecommerce/model/order/OrderLine.java | 99 ++++++++ .../common/ecommerce/model/order/SalesOrder.java | 155 ++++++++++++ .../ecommerce/model/order/SalesOrderQuery.java | 82 +++++++ .../ecommerce/model/product/ProductListing.java | 115 +++++++++ .../ecommerce/model/product/ProductQuery.java | 74 ++++++ .../model/product/ProductSyncStrategy.java | 12 + .../ecommerce/model/support/CanonicalKeys.java | 115 +++++++++ .../java/common/ecommerce/model/support/Money.java | 104 ++++++++ .../java/common/ecommerce/model/support/Page.java | 52 ++++ .../ecommerce/model/support/PlatformTime.java | 85 +++++++ .../java/common/ecommerce/sdk/AdapterFactory.java | 47 ++++ .../java/common/ecommerce/sdk/ChannelContext.java | 48 ++++ .../main/java/common/ecommerce/sdk/ChannelSdk.java | 169 +++++++++++++ .../common/ecommerce/sdk/ProviderResolver.java | 14 ++ .../java/common/ecommerce/spi/AccessToken.java | 84 +++++++ .../ecommerce/spi/ChannelAccountRepository.java | 16 ++ .../java/common/ecommerce/spi/ChannelSecret.java | 91 +++++++ .../java/common/ecommerce/spi/LockProvider.java | 24 ++ .../java/common/ecommerce/spi/SecretProvider.java | 14 ++ core/src/main/java/common/ecommerce/spi/Sink.java | 18 ++ .../java/common/ecommerce/spi/SyncCursorStore.java | 18 ++ .../main/java/common/ecommerce/spi/TokenStore.java | 15 ++ .../java/common/ecommerce/sync/SyncEngine.java | 77 ++++++ .../java/common/ecommerce/sync/SyncResult.java | 43 ++++ .../main/java/common/ecommerce/sync/SyncSpec.java | 59 +++++ .../ecommerce/model/support/CanonicalKeysTest.java | 80 +++++++ .../java/common/ecommerce/sdk/ChannelSdkTest.java | 183 ++++++++++++++ .../java/common/ecommerce/http/HttpRequest.java | 110 +++++++++ .../java/common/ecommerce/http/HttpResponse.java | 69 ++++++ .../java/common/ecommerce/http/HttpTransport.java | 9 + .../common/ecommerce/http/JacksonJsonCodec.java | 86 +++++++ .../main/java/common/ecommerce/http/JsonCodec.java | 17 ++ .../common/ecommerce/http/OkHttpTransport.java | 70 ++++++ .../main/java/common/ecommerce/http/Responses.java | 56 +++++ .../main/java/common/ecommerce/http/Signer.java | 10 + .../java/common/ecommerce/http/TokenManager.java | 85 +++++++ .../java/common/ecommerce/http/ResponsesTest.java | 43 ++++ .../common/ecommerce/lingxing/LingxingAdapter.java | 262 +++++++++++++++++++++ .../ecommerce/lingxing/LingxingAdapterFactory.java | 58 +++++ .../ecommerce/lingxing/LingxingConstants.java | 61 +++++ .../ecommerce/lingxing/LingxingOrderMapper.java | 112 +++++++++ .../common/ecommerce/lingxing/LingxingSigner.java | 58 +++++ .../ecommerce/lingxing/LingxingTokenClient.java | 67 ++++++ .../ecommerce/lingxing/dto/LingxingOrderDto.java | 196 +++++++++++++++ .../lingxing/dto/LingxingOrderItemDto.java | 88 +++++++ .../ecommerce/lingxing/LingxingAdapterTest.java | 191 +++++++++++++++ .../lingxing/LingxingOrderMapperTest.java | 73 ++++++ .../ecommerce/lingxing/LingxingSignerTest.java | 54 +++++ .../common/ecommerce/testkit/FakeTransport.java | 85 +++++++ .../java/common/ecommerce/testkit/Fixtures.java | 36 +++ .../common/ecommerce/testkit/InMemoryAccounts.java | 59 +++++ .../ecommerce/testkit/InMemoryCursorStore.java | 37 +++ .../ecommerce/testkit/InMemoryLockProvider.java | 52 ++++ .../common/ecommerce/testkit/InMemorySink.java | 47 ++++ .../ecommerce/testkit/InMemoryTokenStore.java | 36 +++ .../java/common/ecommerce/testkit/Responses.java | 25 ++ .../java/common/ecommerce/testkit/TestData.java | 32 +++ 80 files changed, 5139 insertions(+), 28 deletions(-) create mode 100644 core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java create mode 100644 core/src/main/java/common/ecommerce/capability/AggregatorCapable.java create mode 100644 core/src/main/java/common/ecommerce/capability/CapabilityReport.java create mode 100644 core/src/main/java/common/ecommerce/capability/PlatformAdapter.java create mode 100644 core/src/main/java/common/ecommerce/capability/ProductCapable.java create mode 100644 core/src/main/java/common/ecommerce/capability/Products.java create mode 100644 core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java create mode 100644 core/src/main/java/common/ecommerce/capability/SalesOrders.java create mode 100644 core/src/main/java/common/ecommerce/error/AuthException.java create mode 100644 core/src/main/java/common/ecommerce/error/ChannelException.java create mode 100644 core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java create mode 100644 core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java create mode 100644 core/src/main/java/common/ecommerce/error/PlatformBusinessException.java create mode 100644 core/src/main/java/common/ecommerce/error/RateLimitException.java create mode 100644 core/src/main/java/common/ecommerce/error/TransientException.java create mode 100644 core/src/main/java/common/ecommerce/error/ValidationException.java create mode 100644 core/src/main/java/common/ecommerce/model/Capability.java create mode 100644 core/src/main/java/common/ecommerce/model/ChannelProvider.java create mode 100644 core/src/main/java/common/ecommerce/model/FulfillmentMode.java create mode 100644 core/src/main/java/common/ecommerce/model/Platform.java create mode 100644 core/src/main/java/common/ecommerce/model/account/AccountKey.java create mode 100644 core/src/main/java/common/ecommerce/model/account/ChannelAccount.java create mode 100644 core/src/main/java/common/ecommerce/model/order/OrderLine.java create mode 100644 core/src/main/java/common/ecommerce/model/order/SalesOrder.java create mode 100644 core/src/main/java/common/ecommerce/model/order/SalesOrderQuery.java create mode 100644 core/src/main/java/common/ecommerce/model/product/ProductListing.java create mode 100644 core/src/main/java/common/ecommerce/model/product/ProductQuery.java create mode 100644 core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java create mode 100644 core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java create mode 100644 core/src/main/java/common/ecommerce/model/support/Money.java create mode 100644 core/src/main/java/common/ecommerce/model/support/Page.java create mode 100644 core/src/main/java/common/ecommerce/model/support/PlatformTime.java create mode 100644 core/src/main/java/common/ecommerce/sdk/AdapterFactory.java create mode 100644 core/src/main/java/common/ecommerce/sdk/ChannelContext.java create mode 100644 core/src/main/java/common/ecommerce/sdk/ChannelSdk.java create mode 100644 core/src/main/java/common/ecommerce/sdk/ProviderResolver.java create mode 100644 core/src/main/java/common/ecommerce/spi/AccessToken.java create mode 100644 core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java create mode 100644 core/src/main/java/common/ecommerce/spi/ChannelSecret.java create mode 100644 core/src/main/java/common/ecommerce/spi/LockProvider.java create mode 100644 core/src/main/java/common/ecommerce/spi/SecretProvider.java create mode 100644 core/src/main/java/common/ecommerce/spi/Sink.java create mode 100644 core/src/main/java/common/ecommerce/spi/SyncCursorStore.java create mode 100644 core/src/main/java/common/ecommerce/spi/TokenStore.java create mode 100644 core/src/main/java/common/ecommerce/sync/SyncEngine.java create mode 100644 core/src/main/java/common/ecommerce/sync/SyncResult.java create mode 100644 core/src/main/java/common/ecommerce/sync/SyncSpec.java create mode 100644 core/src/test/java/common/ecommerce/model/support/CanonicalKeysTest.java create mode 100644 core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java create mode 100644 http/src/main/java/common/ecommerce/http/HttpRequest.java create mode 100644 http/src/main/java/common/ecommerce/http/HttpResponse.java create mode 100644 http/src/main/java/common/ecommerce/http/HttpTransport.java create mode 100644 http/src/main/java/common/ecommerce/http/JacksonJsonCodec.java create mode 100644 http/src/main/java/common/ecommerce/http/JsonCodec.java create mode 100644 http/src/main/java/common/ecommerce/http/OkHttpTransport.java create mode 100644 http/src/main/java/common/ecommerce/http/Responses.java create mode 100644 http/src/main/java/common/ecommerce/http/Signer.java create mode 100644 http/src/main/java/common/ecommerce/http/TokenManager.java create mode 100644 http/src/test/java/common/ecommerce/http/ResponsesTest.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapterFactory.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/LingxingSigner.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/LingxingTokenClient.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderDto.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderItemDto.java create mode 100644 lingxing/src/test/java/common/ecommerce/lingxing/LingxingAdapterTest.java create mode 100644 lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java create mode 100644 lingxing/src/test/java/common/ecommerce/lingxing/LingxingSignerTest.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/FakeTransport.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/Fixtures.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/InMemoryAccounts.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/InMemoryCursorStore.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/InMemoryLockProvider.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/InMemorySink.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/InMemoryTokenStore.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/Responses.java create mode 100644 testkit/src/main/java/common/ecommerce/testkit/TestData.java diff --git a/README.md b/README.md index 638a1ae..01f3e35 100644 --- a/README.md +++ b/README.md @@ -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` | 分页载体,`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` | 载体 | 分页载体,`nextCursor == null` 表示结束 | ### `capability` —— 能力接口 @@ -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 **注意** `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 | `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 | `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 | 类 | 职责 | |:---|:---| | `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 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 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 缺失能力时抛 `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 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 } @Override public Page 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 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()); 完整示例见 `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 | 项 | 说明 | |:---|:---| -| `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`,四个子模块的 `` 与依赖坐标,`GUIDE.md` 第三章的三处示例 | 会影响宿主 OMS 引入依赖的 Maven 坐标 | + **待核对(需官方文档 + 真实沙箱,联调时集中修改)** | 位置 | 内容 | @@ -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 总体设计) diff --git a/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java b/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java new file mode 100644 index 0000000..1af635c --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java @@ -0,0 +1,60 @@ +package common.ecommerce.capability; + +import common.ecommerce.model.Capability; +import common.ecommerce.model.account.ChannelAccount; + +import java.util.EnumSet; + +/** + * 由适配器与账户推导出的能力报告。 + * + *

逐项询问 {@link PlatformAdapter#supports(ChannelAccount, Capability)}, + * 因此聚合器能按子平台给出精确结果,而直连适配器等价于 {@code capabilities()}。

+ */ +public final class AdapterCapabilityReport implements CapabilityReport { + + private final PlatformAdapter adapter; + private final ChannelAccount account; + private final EnumSet 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 supported() { + return EnumSet.copyOf(supported); + } + + @Override + public EnumSet unsupported() { + EnumSet 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; + } +} diff --git a/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java b/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java new file mode 100644 index 0000000..8132c85 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java @@ -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; + +/** + * 聚合器扩展:列出子渠道(如领星店铺/平台码)。 + * + *

子渠道由 {@code ChannelAccount.platformCode} + {@code externalStoreId} 配置, + * 不新增平台模块。

+ */ +public interface AggregatorCapable extends PlatformAdapter { + + List 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; + } + } +} diff --git a/core/src/main/java/common/ecommerce/capability/CapabilityReport.java b/core/src/main/java/common/ecommerce/capability/CapabilityReport.java new file mode 100644 index 0000000..46d212a --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/CapabilityReport.java @@ -0,0 +1,19 @@ +package common.ecommerce.capability; + +import common.ecommerce.model.Capability; + +import java.util.EnumSet; + +/** + * 能力报告:只读,不触发真实 API。 + * + *

调用方据此决定是否换账户、走直连或人工,SDK 不做推荐与兜底。

+ */ +public interface CapabilityReport { + + boolean supports(Capability capability); + + EnumSet supported(); + + EnumSet unsupported(); +} diff --git a/core/src/main/java/common/ecommerce/capability/PlatformAdapter.java b/core/src/main/java/common/ecommerce/capability/PlatformAdapter.java new file mode 100644 index 0000000..8bf94b9 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/PlatformAdapter.java @@ -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 platforms(); + + /** 适配器能力并集。 */ + EnumSet capabilities(); + + /** + * 按账户细化能力。 + * + *

直连适配器默认使用 {@link #capabilities()};聚合器按账户的子平台覆盖, + * 例如领星对 Walmart 支持标发、对 eBay 只支持订单。

+ */ + default boolean supports(ChannelAccount account, Capability capability) { + return capabilities().contains(capability); + } +} diff --git a/core/src/main/java/common/ecommerce/capability/ProductCapable.java b/core/src/main/java/common/ecommerce/capability/ProductCapable.java new file mode 100644 index 0000000..98a6bef --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/ProductCapable.java @@ -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 pull(ChannelContext ctx, ProductQuery query); + + ProductListing get(ChannelContext ctx, String platformSku); + + default Capability requiredCapability() { + return Capability.PRODUCT; + } +} diff --git a/core/src/main/java/common/ecommerce/capability/Products.java b/core/src/main/java/common/ecommerce/capability/Products.java new file mode 100644 index 0000000..e18691a --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/Products.java @@ -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 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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java b/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java new file mode 100644 index 0000000..7761c41 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java @@ -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 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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrders.java b/core/src/main/java/common/ecommerce/capability/SalesOrders.java new file mode 100644 index 0000000..b21ff47 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/SalesOrders.java @@ -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 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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/error/AuthException.java b/core/src/main/java/common/ecommerce/error/AuthException.java new file mode 100644 index 0000000..1f8acf3 --- /dev/null +++ b/core/src/main/java/common/ecommerce/error/AuthException.java @@ -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); + } +} diff --git a/core/src/main/java/common/ecommerce/error/ChannelException.java b/core/src/main/java/common/ecommerce/error/ChannelException.java new file mode 100644 index 0000000..289a570 --- /dev/null +++ b/core/src/main/java/common/ecommerce/error/ChannelException.java @@ -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; + } + } +} diff --git a/core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java b/core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java new file mode 100644 index 0000000..879dd8c --- /dev/null +++ b/core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java @@ -0,0 +1,22 @@ +package common.ecommerce.error; + +/** + * 跨 provider 冲突:同一业务动作已由另一个 provider 完成。 + * + *

不自动跨 provider 重试,必须人工确认。

+ */ +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; + } +} diff --git a/core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java b/core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java new file mode 100644 index 0000000..e270b25 --- /dev/null +++ b/core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java @@ -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; + } +} diff --git a/core/src/main/java/common/ecommerce/error/PlatformBusinessException.java b/core/src/main/java/common/ecommerce/error/PlatformBusinessException.java new file mode 100644 index 0000000..63ac702 --- /dev/null +++ b/core/src/main/java/common/ecommerce/error/PlatformBusinessException.java @@ -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); + } +} diff --git a/core/src/main/java/common/ecommerce/error/RateLimitException.java b/core/src/main/java/common/ecommerce/error/RateLimitException.java new file mode 100644 index 0000000..d1be84d --- /dev/null +++ b/core/src/main/java/common/ecommerce/error/RateLimitException.java @@ -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; + } +} diff --git a/core/src/main/java/common/ecommerce/error/TransientException.java b/core/src/main/java/common/ecommerce/error/TransientException.java new file mode 100644 index 0000000..14f597c --- /dev/null +++ b/core/src/main/java/common/ecommerce/error/TransientException.java @@ -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); + } +} diff --git a/core/src/main/java/common/ecommerce/error/ValidationException.java b/core/src/main/java/common/ecommerce/error/ValidationException.java new file mode 100644 index 0000000..6597f45 --- /dev/null +++ b/core/src/main/java/common/ecommerce/error/ValidationException.java @@ -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); + } +} diff --git a/core/src/main/java/common/ecommerce/model/Capability.java b/core/src/main/java/common/ecommerce/model/Capability.java new file mode 100644 index 0000000..a2fdb4d --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/Capability.java @@ -0,0 +1,45 @@ +package common.ecommerce.model; + +/** + * 能力枚举。 + * + *

适配器实现哪些能力接口,就声明哪些能力;门面据此在调用前做能力检查, + * 缺失时抛 UnsupportedCapabilityException,而不是静默失败。

+ */ +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 +} diff --git a/core/src/main/java/common/ecommerce/model/ChannelProvider.java b/core/src/main/java/common/ecommerce/model/ChannelProvider.java new file mode 100644 index 0000000..32da2c9 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/ChannelProvider.java @@ -0,0 +1,23 @@ +package common.ecommerce.model; + +/** + * 接入 provider 枚举。 + * + *

provider 是接入通道,不是业务渠道。同一个平台店铺可以同时存在 + * {@link #DIRECT} 与 {@link #LINGXING} 两条接入通道,由调用方显式选择; + * SDK 不做推荐、不自动选路、不自动兜底。

+ */ +public enum ChannelProvider { + + /** 平台直连 */ + DIRECT, + /** 领星聚合 */ + LINGXING, + /** Teapplix 订单源 */ + TEAPPLIX, + /** 其他聚合器或自建通道 */ + CUSTOM; + + /** 直连账户的 platformCode 哨兵值,避免 {@code (provider, externalStoreId, platformCode)} 唯一索引因 NULL 失效。 */ + public static final int NO_PLATFORM_CODE = 0; +} diff --git a/core/src/main/java/common/ecommerce/model/FulfillmentMode.java b/core/src/main/java/common/ecommerce/model/FulfillmentMode.java new file mode 100644 index 0000000..859d9a2 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/FulfillmentMode.java @@ -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 +} diff --git a/core/src/main/java/common/ecommerce/model/Platform.java b/core/src/main/java/common/ecommerce/model/Platform.java new file mode 100644 index 0000000..2572ca5 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/Platform.java @@ -0,0 +1,42 @@ +package common.ecommerce.model; + +/** + * 业务平台枚举。 + * + *

不含 provider:直连与领星等聚合器都映射到同一个平台值, + * 保证业务主键(canonicalKey)在 provider 切换时不变。

+ */ +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; + } +} diff --git a/core/src/main/java/common/ecommerce/model/account/AccountKey.java b/core/src/main/java/common/ecommerce/model/account/AccountKey.java new file mode 100644 index 0000000..1f27609 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/account/AccountKey.java @@ -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}。 + * + *

这是所有门面调用的隔离维度。同一 omsStoreId 可以同时绑定直连与聚合器账户, + * 业务实体不会因此重复——provider 不进入业务主键,见 {@link CanonicalKeys}。

+ */ +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; + } +} diff --git a/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java b/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java new file mode 100644 index 0000000..2efe426 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java @@ -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 账户。 + * + *

凭证不落配置:本对象只保存 {@code credentialRef},真实密钥由宿主 + * {@code SecretProvider} 按引用取出。

+ */ +public final class ChannelAccount { + + private final AccountKey key; + private final String externalStoreId; + private final Integer platformCode; + private final String region; + private final List 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(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 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 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 marketplaceIds) { + this.marketplaceIds = marketplaceIds == null ? Collections.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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/order/OrderLine.java b/core/src/main/java/common/ecommerce/model/order/OrderLine.java new file mode 100644 index 0000000..8f8f068 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/order/OrderLine.java @@ -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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/order/SalesOrder.java b/core/src/main/java/common/ecommerce/model/order/SalesOrder.java new file mode 100644 index 0000000..2c3858c --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/order/SalesOrder.java @@ -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 销售订单。 + * + *

统一带 {@code omsStoreId + sourceProvider + sourceAccountId}, + * 用于跨 provider 去重与追溯。

+ */ +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 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(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 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 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 lines) { + this.lines = lines == null ? Collections.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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/order/SalesOrderQuery.java b/core/src/main/java/common/ecommerce/model/order/SalesOrderQuery.java new file mode 100644 index 0000000..2d1fb9a --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/order/SalesOrderQuery.java @@ -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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/product/ProductListing.java b/core/src/main/java/common/ecommerce/model/product/ProductListing.java new file mode 100644 index 0000000..af6e14d --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/product/ProductListing.java @@ -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 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(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 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 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 imageUrls) { + this.imageUrls = imageUrls == null ? Collections.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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/product/ProductQuery.java b/core/src/main/java/common/ecommerce/model/product/ProductQuery.java new file mode 100644 index 0000000..9230da6 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/product/ProductQuery.java @@ -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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java b/core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java new file mode 100644 index 0000000..c6dc1e2 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java @@ -0,0 +1,12 @@ +package common.ecommerce.model.product; + +/** 商品同步策略,适配器声明自己支持哪一种。 */ +public enum ProductSyncStrategy { + + /** 时间窗增量 */ + INCREMENTAL_TIME_WINDOW, + /** 全量拉取 + 差异比对 */ + FULL_PULL_DIFF, + /** 报告 / 文件 */ + REPORT +} diff --git a/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java b/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java new file mode 100644 index 0000000..5dbf7e4 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java @@ -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; + +/** + * 三级标识计算。 + * + *
    + *
  • omsStoreId:业务归属,直连与聚合器都映射到同一个店铺
  • + *
  • canonicalKey:platform + omsStoreId + 平台实体 ID,用于 upsert、去重、状态流转
  • + *
  • sourceKey:provider + platform + externalStoreId + 平台实体 ID,用于原始报文、水位线、审计
  • + *
+ * + *

provider 不得进入 canonicalKey,否则直连与聚合器切换会把同一实体变成两条。

+ */ +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)。 + * + *

刻意不含金额,避免不同 provider 的舍入差异造成重复账单;金额差异由 SourceConflict 记录。

+ */ + 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。 + * + *

不带 provider,直连与聚合器共用,保证同一业务动作只成功一次。

+ */ + 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。 + * + *

带 provider,用于单 provider 内的重复请求/重试去重。

+ */ + 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(); + } +} diff --git a/core/src/main/java/common/ecommerce/model/support/Money.java b/core/src/main/java/common/ecommerce/model/support/Money.java new file mode 100644 index 0000000..0c28893 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/support/Money.java @@ -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}。 + * + *

禁止使用 double。保留平台原始精度与币种,不做隐式舍入。

+ */ +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(); + } +} diff --git a/core/src/main/java/common/ecommerce/model/support/Page.java b/core/src/main/java/common/ecommerce/model/support/Page.java new file mode 100644 index 0000000..4592c65 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/support/Page.java @@ -0,0 +1,52 @@ +package common.ecommerce.model.support; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 分页结果的通用载体。 + * + * @param 条目类型 + */ +public final class Page { + + private final List items; + private final String nextCursor; + private final boolean hasMore; + + private Page(List items, String nextCursor, boolean hasMore) { + this.items = Collections.unmodifiableList(new ArrayList(items)); + this.nextCursor = nextCursor; + this.hasMore = hasMore; + } + + public static Page of(List items, String nextCursor) { + return new Page(items, nextCursor, nextCursor != null && !nextCursor.isEmpty()); + } + + public static Page last(List items) { + return new Page(items, null, false); + } + + public static Page empty() { + return new Page(Collections.emptyList(), null, false); + } + + public List items() { + return items; + } + + /** 下一页游标;null 表示结束。 */ + public String nextCursor() { + return nextCursor; + } + + public boolean hasMore() { + return hasMore; + } + + public int size() { + return items.size(); + } +} diff --git a/core/src/main/java/common/ecommerce/model/support/PlatformTime.java b/core/src/main/java/common/ecommerce/model/support/PlatformTime.java new file mode 100644 index 0000000..54e965f --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/support/PlatformTime.java @@ -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 是唯一真值,市场当地时间与北京时间是派生/物化视图。 + * + *

夏令时一律通过 {@link ZoneId} 解析,禁止使用固定偏移量。

+ */ +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 + ")"; + } +} diff --git a/core/src/main/java/common/ecommerce/sdk/AdapterFactory.java b/core/src/main/java/common/ecommerce/sdk/AdapterFactory.java new file mode 100644 index 0000000..7a8ca5d --- /dev/null +++ b/core/src/main/java/common/ecommerce/sdk/AdapterFactory.java @@ -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 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(); + } +} diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelContext.java b/core/src/main/java/common/ecommerce/sdk/ChannelContext.java new file mode 100644 index 0000000..b1cc9cc --- /dev/null +++ b/core/src/main/java/common/ecommerce/sdk/ChannelContext.java @@ -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; + } +} diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java new file mode 100644 index 0000000..154ade2 --- /dev/null +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -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 统一门面。 + * + *

业务层只依赖本类,不直接感知平台协议。所有外部副作用经 SPI 注入, + * SDK 自身不访问数据库 / Redis / MQ,也不持有线程或定时器。

+ * + *

provider 由调用方在 {@link AccountKey} 中显式指定,SDK 不推荐、 + * 不自动选路、不自动兜底;能力缺失时抛 + * {@code ChannelException.UnsupportedCapabilityException}。

+ */ +public final class ChannelSdk implements ProviderResolver { + + private final Map adapters; + private final ChannelAccountRepository accountRepository; + private final Clock clock; + + private ChannelSdk(Builder b) { + this.adapters = Collections.unmodifiableMap(new LinkedHashMap(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 adapters = new LinkedHashMap(); + private final List factories = new ArrayList(); + 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 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; + } + + /** + * 构建门面。 + * + *

缺必需配置时立刻失败,而不是返回一个不可用的空对象。

+ */ + 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()); + } + } + } +} diff --git a/core/src/main/java/common/ecommerce/sdk/ProviderResolver.java b/core/src/main/java/common/ecommerce/sdk/ProviderResolver.java new file mode 100644 index 0000000..d9a6b06 --- /dev/null +++ b/core/src/main/java/common/ecommerce/sdk/ProviderResolver.java @@ -0,0 +1,14 @@ +package common.ecommerce.sdk; + +import common.ecommerce.capability.PlatformAdapter; +import common.ecommerce.model.account.AccountKey; + +/** + * 按 AccountKey 解析适配器。 + * + *

不自动选路、不自动兜底:provider 由调用方在 AccountKey 中显式指定。

+ */ +public interface ProviderResolver { + + PlatformAdapter resolve(AccountKey key); +} diff --git a/core/src/main/java/common/ecommerce/spi/AccessToken.java b/core/src/main/java/common/ecommerce/spi/AccessToken.java new file mode 100644 index 0000000..5d00ee1 --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/AccessToken.java @@ -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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java b/core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java new file mode 100644 index 0000000..3b36b90 --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java @@ -0,0 +1,16 @@ +package common.ecommerce.spi; + +import common.ecommerce.model.account.ChannelAccount; + +import java.util.Optional; + +/** + * 渠道账户读取 SPI。由宿主实现(典型 MySQL)。 + */ +public interface ChannelAccountRepository { + + Optional findByKey(String provider, String platform, String omsStoreId); + + /** 同一 omsStoreId 下所有 provider 账户。 */ + java.util.List findByOmsStoreId(String omsStoreId); +} diff --git a/core/src/main/java/common/ecommerce/spi/ChannelSecret.java b/core/src/main/java/common/ecommerce/spi/ChannelSecret.java new file mode 100644 index 0000000..378dd4d --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/ChannelSecret.java @@ -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); + } + } +} diff --git a/core/src/main/java/common/ecommerce/spi/LockProvider.java b/core/src/main/java/common/ecommerce/spi/LockProvider.java new file mode 100644 index 0000000..f149e1a --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/LockProvider.java @@ -0,0 +1,24 @@ +package common.ecommerce.spi; + +import java.util.Optional; + +/** + * 锁 SPI。用于 token 刷新防击穿、账户级同步互斥。 + */ +public interface LockProvider { + + /** + * 尝试获取锁,不阻塞。 + * + * @param key 锁键 + * @param ttlSeconds 锁自动过期时间 + * @return 锁句柄;未获取到返回 empty + */ + Optional tryLock(String key, long ttlSeconds); + + interface Lock extends AutoCloseable { + + @Override + void close(); + } +} diff --git a/core/src/main/java/common/ecommerce/spi/SecretProvider.java b/core/src/main/java/common/ecommerce/spi/SecretProvider.java new file mode 100644 index 0000000..8e4f6b4 --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/SecretProvider.java @@ -0,0 +1,14 @@ +package common.ecommerce.spi; + +/** + * 凭证读取 SPI。{@code credentialRef} 由 {@code ChannelAccount} 提供。 + * + *

真实密钥只在内存中出现,禁止落配置、禁止写日志。

+ */ +public interface SecretProvider { + + /** + * @param credentialRef 形如 {@code kms://oms/lingxing/store-001} + */ + ChannelSecret get(String credentialRef); +} diff --git a/core/src/main/java/common/ecommerce/spi/Sink.java b/core/src/main/java/common/ecommerce/spi/Sink.java new file mode 100644 index 0000000..3b45f4d --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/Sink.java @@ -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 只调用,不碰数据库。 + * + *

实现方必须按 canonicalKey 做 upsert:同一实体从直连与聚合器同步时 + * 不得产生两条记录。

+ */ +public interface Sink { + + void upsertSalesOrders(Page page); + + void upsertProducts(Page page); +} diff --git a/core/src/main/java/common/ecommerce/spi/SyncCursorStore.java b/core/src/main/java/common/ecommerce/spi/SyncCursorStore.java new file mode 100644 index 0000000..5ca8efe --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/SyncCursorStore.java @@ -0,0 +1,18 @@ +package common.ecommerce.spi; + +import common.ecommerce.model.ChannelProvider; + +import java.time.Instant; + +/** + * 增量水位线 SPI。 + * + *

按 {@code provider + account + stream} 分开维护;只在整个批次成功后推进。

+ */ +public interface SyncCursorStore { + + /** 返回 null 表示还没有水位线,需要首次全量建底。 */ + Instant get(ChannelProvider provider, String accountKey, String stream); + + void advance(ChannelProvider provider, String accountKey, String stream, Instant watermark); +} diff --git a/core/src/main/java/common/ecommerce/spi/TokenStore.java b/core/src/main/java/common/ecommerce/spi/TokenStore.java new file mode 100644 index 0000000..ee0604f --- /dev/null +++ b/core/src/main/java/common/ecommerce/spi/TokenStore.java @@ -0,0 +1,15 @@ +package common.ecommerce.spi; + +import java.util.Optional; + +/** + * 访问令牌读取/写入 SPI。宿主负责加密存储。 + */ +public interface TokenStore { + + Optional get(String tokenKey); + + void save(String tokenKey, AccessToken token); + + void remove(String tokenKey); +} diff --git a/core/src/main/java/common/ecommerce/sync/SyncEngine.java b/core/src/main/java/common/ecommerce/sync/SyncEngine.java new file mode 100644 index 0000000..1027bcf --- /dev/null +++ b/core/src/main/java/common/ecommerce/sync/SyncEngine.java @@ -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; + +/** + * 增量同步引擎。 + * + *
+ * from = lastWatermark - overlapWindow
+ * to   = now
+ * loop 拉一页 → 经 Sink upsert → cursor = page.nextCursor
+ * 直到 cursor == null
+ * 全部成功才推进水位线,失败不推进
+ * 
+ * + *

引擎不持有线程或定时器,由宿主调度触发。

+ */ +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> 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 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); + } +} diff --git a/core/src/main/java/common/ecommerce/sync/SyncResult.java b/core/src/main/java/common/ecommerce/sync/SyncResult.java new file mode 100644 index 0000000..867122a --- /dev/null +++ b/core/src/main/java/common/ecommerce/sync/SyncResult.java @@ -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 + '}'; + } +} diff --git a/core/src/main/java/common/ecommerce/sync/SyncSpec.java b/core/src/main/java/common/ecommerce/sync/SyncSpec.java new file mode 100644 index 0000000..9b04f62 --- /dev/null +++ b/core/src/main/java/common/ecommerce/sync/SyncSpec.java @@ -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; + } + + /** + * 计算增量起点。 + * + *

没有水位线时返回 null,由调用方走首次全量。

+ */ + public Instant from(Instant watermark) { + return watermark == null ? null : watermark.minus(overlap); + } +} diff --git a/core/src/test/java/common/ecommerce/model/support/CanonicalKeysTest.java b/core/src/test/java/common/ecommerce/model/support/CanonicalKeysTest.java new file mode 100644 index 0000000..82c1e21 --- /dev/null +++ b/core/src/test/java/common/ecommerce/model/support/CanonicalKeysTest.java @@ -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()); + } +} diff --git a/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java b/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java new file mode 100644 index 0000000..4d77026 --- /dev/null +++ b/core/src/test/java/common/ecommerce/sdk/ChannelSdkTest.java @@ -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 platforms() { + return EnumSet.of(Platform.WALMART_SC); + } + + @Override + public EnumSet capabilities() { + return EnumSet.of(Capability.SALES_ORDER); + } + + @Override + public Page 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 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.empty(); + } + + @Override + public java.util.List 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 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())); + } +} diff --git a/http/src/main/java/common/ecommerce/http/HttpRequest.java b/http/src/main/java/common/ecommerce/http/HttpRequest.java new file mode 100644 index 0000000..46a9618 --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/HttpRequest.java @@ -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 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(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 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 headers = new LinkedHashMap(); + 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 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); + } + } +} diff --git a/http/src/main/java/common/ecommerce/http/HttpResponse.java b/http/src/main/java/common/ecommerce/http/HttpResponse.java new file mode 100644 index 0000000..58a3ac2 --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/HttpResponse.java @@ -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 headers; + private final String body; + private final long latencyMillis; + + private HttpResponse(int statusCode, Map headers, String body, long latencyMillis) { + this.statusCode = statusCode; + this.headers = Collections.unmodifiableMap(new LinkedHashMap(headers)); + this.body = body; + this.latencyMillis = latencyMillis; + } + + public static HttpResponse of(int statusCode, Map headers, String body, long latencyMillis) { + return new HttpResponse(statusCode, headers == null ? Collections.emptyMap() : headers, + body, latencyMillis); + } + + public int statusCode() { + return statusCode; + } + + public Map 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 e : headers.entrySet()) { + if (e.getKey().equalsIgnoreCase(name)) { + return e.getValue(); + } + } + return null; + } +} diff --git a/http/src/main/java/common/ecommerce/http/HttpTransport.java b/http/src/main/java/common/ecommerce/http/HttpTransport.java new file mode 100644 index 0000000..5fb4163 --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/HttpTransport.java @@ -0,0 +1,9 @@ +package common.ecommerce.http; + +/** + * HTTP 传输接口。默认实现 OkHttp,可替换为 Apache HttpClient 或测试用 Fake。 + */ +public interface HttpTransport { + + HttpResponse execute(HttpRequest request); +} diff --git a/http/src/main/java/common/ecommerce/http/JacksonJsonCodec.java b/http/src/main/java/common/ecommerce/http/JacksonJsonCodec.java new file mode 100644 index 0000000..a150775 --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/JacksonJsonCodec.java @@ -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 fromJson(String json, Class 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 List listAt(String json, String pointer, Class type) { + JsonNode node = nodeAt(json, pointer); + if (node == null || !node.isArray()) { + return new ArrayList(); + } + List out = new ArrayList(node.size()); + for (JsonNode item : (ArrayNode) node) { + out.add(mapper.convertValue(item, type)); + } + return out; + } +} diff --git a/http/src/main/java/common/ecommerce/http/JsonCodec.java b/http/src/main/java/common/ecommerce/http/JsonCodec.java new file mode 100644 index 0000000..c2ddb33 --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/JsonCodec.java @@ -0,0 +1,17 @@ +package common.ecommerce.http; + +/** + * 够用的最小 JSON 读写抽象,避免 core 层绑死 Jackson。 + */ +public interface JsonCodec { + + String toJson(Object value); + + T fromJson(String json, Class type); + + /** + * 按点路径取字段值,用于解析平台响应里的 data.list 这类结构。 + * 找不到返回 null。 + */ + String stringAt(String json, String pointer); +} diff --git a/http/src/main/java/common/ecommerce/http/OkHttpTransport.java b/http/src/main/java/common/ecommerce/http/OkHttpTransport.java new file mode 100644 index 0000000..771df62 --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/OkHttpTransport.java @@ -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 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 headers = new java.util.LinkedHashMap(); + 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)); + } + } +} diff --git a/http/src/main/java/common/ecommerce/http/Responses.java b/http/src/main/java/common/ecommerce/http/Responses.java new file mode 100644 index 0000000..a78711f --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/Responses.java @@ -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; + +/** + * 响应判定与重试分类。 + * + *
    + *
  • 2xx:成功
  • + *
  • 401/403:{@link AuthException},刷新后重试一次
  • + *
  • 429:{@link RateLimitException},遵守 Retry-After
  • + *
  • 5xx / 网络:{@link TransientException},退避加抖动
  • + *
  • 其他 4xx:业务错误,不在此层重试
  • + *
+ */ +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; + } + } +} diff --git a/http/src/main/java/common/ecommerce/http/Signer.java b/http/src/main/java/common/ecommerce/http/Signer.java new file mode 100644 index 0000000..87bc457 --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/Signer.java @@ -0,0 +1,10 @@ +package common.ecommerce.http; + +/** + * 签名器。按平台实现,差异收敛在适配器内。 + */ +public interface Signer { + + /** 在请求上补齐签名相关的 header / query。 */ + HttpRequest sign(HttpRequest request, common.ecommerce.spi.ChannelSecret secret); +} diff --git a/http/src/main/java/common/ecommerce/http/TokenManager.java b/http/src/main/java/common/ecommerce/http/TokenManager.java new file mode 100644 index 0000000..ac92ac8 --- /dev/null +++ b/http/src/main/java/common/ecommerce/http/TokenManager.java @@ -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; + +/** + * 令牌管理模板。 + * + *
    + *
  • 按账户隔离缓存
  • + *
  • 提前 {@code earlyRefreshSeconds} 续期
  • + *
  • 刷新用 {@link LockProvider} 防击穿
  • + *
  • 刷新失败不返回旧 token(除显式宽限窗口)
  • + *
  • 日志只打印指纹
  • + *
+ */ +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 cached = tokenStore.get(tokenKey); + if (cached.isPresent() && !cached.get().needsRefresh(now, earlyRefreshSeconds)) { + return cached.get(); + } + + Optional lock = lockProvider.tryLock("token-refresh:" + tokenKey, 30); + if (!lock.isPresent()) { + // 别的线程在刷新:再读一次,读不到就短等待后重读 + Optional 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 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); +} diff --git a/http/src/test/java/common/ecommerce/http/ResponsesTest.java b/http/src/test/java/common/ecommerce/http/ResponsesTest.java new file mode 100644 index 0000000..a05e02a --- /dev/null +++ b/http/src/test/java/common/ecommerce/http/ResponsesTest.java @@ -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")); + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java new file mode 100644 index 0000000..d8c15e8 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapter.java @@ -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; + +/** + * 领星聚合适配器。 + * + *

一个适配器服务多个子平台,子平台由 {@code ChannelAccount.platformCode} 决定, + * 能力按子平台细化({@link #supports})。首期只实现订单列表拉取。

+ * + *

领星字段名与签名细节标注为「待核对」的地方集中在 {@code dto} 与 + * {@link LingxingSigner},联调时只改这两处。

+ */ +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 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 capabilities() { + return EnumSet.of(Capability.SALES_ORDER); + } + + /** + * 聚合器按子平台细化能力。 + * + *

eBay / SHEIN / Mirakl / 自定义平台在领星侧只有订单,未见账单与售后接口, + * 因此只声明 SALES_ORDER,缺口由能力报告显式暴露,不假装支持。

+ */ + @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 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 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 dtos = mapper.parseList(resp.body()); + int total = mapper.parseTotal(resp.body()); + + List orders = new ArrayList(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 body = new LinkedHashMap(); + 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 common = new LinkedHashMap(); + 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")) + + "×tamp=" + 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; + } + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapterFactory.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapterFactory.java new file mode 100644 index 0000000..b375068 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingAdapterFactory.java @@ -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 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); + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java new file mode 100644 index 0000000..b3d6aaa --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java @@ -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。 + * + *

10034 同时对应 Mirakl / BestBuy;Target、AEPH 未独立枚举, + * 按文档需要到领星后台确认,此处先映射到 CUSTOM,待核对。

+ */ + 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; + } + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java new file mode 100644 index 0000000..bd8bba4 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java @@ -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; + +/** + * 领星订单 → 统一模型。 + * + *

领星订单是唯一的映射入口,平台差异全部收敛在这里。

+ */ +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 lines = new ArrayList(); + 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 的一部分,必须稳定。 + * + *

优先平台单号;缺失时退回领星 order_id(此时跨 provider 无法去重, + * 会由 DuplicateOrderGuard 记录差异)。

+ */ + static String resolveChannelOrderId(LingxingOrderDto dto) { + if (dto.getPlatformOrderNo() != null && !dto.getPlatformOrderNo().trim().isEmpty()) { + return dto.getPlatformOrderNo().trim(); + } + List names = dto.getPlatformOrderNames(); + if (names != null && !names.isEmpty()) { + List sorted = new ArrayList(names); + Collections.sort(sorted, new Comparator() { + @Override + public int compare(String a, String b) { + return a.compareTo(b); + } + }); + return sorted.get(0); + } + return dto.getOrderId(); + } + + public List 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 List safe(List in) { + return in == null ? Collections.emptyList() : in; + } + + private static Money moneyOrNull(String value, String currency) { + if (value == null || value.trim().isEmpty()) { + return null; + } + return Money.of(value.trim(), currency); + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingSigner.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingSigner.java new file mode 100644 index 0000000..86ce876 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingSigner.java @@ -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 小写。 + * + *

待核对:官方文档对 sign 的大小写与大写规则未在需求文档中固化, + * 实现集中在 {@link #sign(Map, String)} 一处,便于联调时调整。

+ */ +public final class LingxingSigner { + + private LingxingSigner() { + } + + /** + * @param params 参与签名的参数(不含 sign),值不得为 null + * @param appSecret 应用密钥 + */ + public static String sign(Map params, String appSecret) { + List keys = new ArrayList(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 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); + } + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingTokenClient.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingTokenClient.java new file mode 100644 index 0000000..7bd7eec --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingTokenClient.java @@ -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}。 + * + *

请求体字段名以官方文档为准(appId/appSecret),这里集中在一处便于联调调整。

+ */ +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 body = new LinkedHashMap(); + 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(); + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderDto.java new file mode 100644 index 0000000..363187d --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderDto.java @@ -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; + +/** + * 领星多平台订单列表条目。 + * + *

待核对:字段名依据领星 OpenAPI 文档摘录,联调时以官方最新文档 + * 与真实响应为准;调整集中在本 DTO 与 {@code LingxingOrderMapper}。

+ */ +@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 platformOrderNames = new ArrayList(); + + /** 领星平台码,如 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 itemList = new ArrayList(); + + 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 getPlatformOrderNames() { + return platformOrderNames; + } + + public void setPlatformOrderNames(List 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 getItemList() { + return itemList; + } + + public void setItemList(List itemList) { + this.itemList = itemList; + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderItemDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderItemDto.java new file mode 100644 index 0000000..3a0e485 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingOrderItemDto.java @@ -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; + } +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/LingxingAdapterTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/LingxingAdapterTest.java new file mode 100644 index 0000000..3cbc3f8 --- /dev/null +++ b/lingxing/src/test/java/common/ecommerce/lingxing/LingxingAdapterTest.java @@ -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 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()); + } +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java new file mode 100644 index 0000000..9c0c6b9 --- /dev/null +++ b/lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java @@ -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 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)); + } +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/LingxingSignerTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/LingxingSignerTest.java new file mode 100644 index 0000000..be439af --- /dev/null +++ b/lingxing/src/test/java/common/ecommerce/lingxing/LingxingSignerTest.java @@ -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 a = new LinkedHashMap(); + a.put("app_key", "k1"); + a.put("timestamp", "1793001600"); + + Map b = new LinkedHashMap(); + b.put("timestamp", "1793001600"); + b.put("app_key", "k1"); + + assertEquals(LingxingSigner.sign(a, "secret"), LingxingSigner.sign(b, "secret")); + } + + @Test + void signatureIs32LowercaseHex() { + Map p = new LinkedHashMap(); + 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 p = new LinkedHashMap(); + 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 p = new LinkedHashMap(); + p.put("app_key", "k1"); + p.put("timestamp", "1793001600"); + assertEquals(LingxingSigner.md5Hex("secretapp_keyk1timestamp1793001600secret"), + LingxingSigner.sign(p, "secret")); + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/FakeTransport.java b/testkit/src/main/java/common/ecommerce/testkit/FakeTransport.java new file mode 100644 index 0000000..72702cb --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/FakeTransport.java @@ -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。 + * + *
+ * FakeTransport t = FakeTransport.create()
+ *     .route("lingxing", "order/v2/list", body -> HttpResponse.of(200, null, json, 5));
+ * 
+ */ +public final class FakeTransport implements HttpTransport { + + private final List recorded = new ArrayList(); + private final List routes = new ArrayList(); + private Function fallback; + + public static FakeTransport create() { + return new FakeTransport(); + } + + /** 按 URL 子串 + 方法匹配。 */ + public FakeTransport route(String urlContains, String method, Function responder) { + routes.add(new Route(urlContains, method, responder)); + return this; + } + + public FakeTransport route(String urlContains, Function responder) { + return route(urlContains, null, responder); + } + + public FakeTransport fallback(Function 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 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 responder; + + private Route(String urlContains, String method, Function responder) { + this.urlContains = urlContains; + this.method = method; + this.responder = responder; + } + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/Fixtures.java b/testkit/src/main/java/common/ecommerce/testkit/Fixtures.java new file mode 100644 index 0000000..8b4d86b --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/Fixtures.java @@ -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; + +/** + * 夹具加载器。 + * + *

约定目录:{@code src/test/resources/fixtures/{platform}/{operation}/{case}.json}。 + * 适配器测试只依赖录制报文,不依赖网络。

+ */ +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"); + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/InMemoryAccounts.java b/testkit/src/main/java/common/ecommerce/testkit/InMemoryAccounts.java new file mode 100644 index 0000000..b9879f2 --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/InMemoryAccounts.java @@ -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 accounts = new HashMap(); + private final Map secrets = new HashMap(); + + 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 findByKey(String provider, String platform, String omsStoreId) { + return Optional.ofNullable(accounts.get(id(provider, platform, omsStoreId))); + } + + @Override + public List findByOmsStoreId(String omsStoreId) { + List out = new ArrayList(); + 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; + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/InMemoryCursorStore.java b/testkit/src/main/java/common/ecommerce/testkit/InMemoryCursorStore.java new file mode 100644 index 0000000..f1c6815 --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/InMemoryCursorStore.java @@ -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 cursors = new HashMap(); + + @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; + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/InMemoryLockProvider.java b/testkit/src/main/java/common/ecommerce/testkit/InMemoryLockProvider.java new file mode 100644 index 0000000..9d05724 --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/InMemoryLockProvider.java @@ -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 held = new HashSet(); + private final Map acquireCounts = new HashMap(); + + @Override + public synchronized Optional 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.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); + } + } + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/InMemorySink.java b/testkit/src/main/java/common/ecommerce/testkit/InMemorySink.java new file mode 100644 index 0000000..91fc505 --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/InMemorySink.java @@ -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 salesOrders = new ArrayList(); + private final List products = new ArrayList(); + private int salesOrderUpsertCalls; + private int productUpsertCalls; + + @Override + public void upsertSalesOrders(Page page) { + salesOrders.addAll(page.items()); + salesOrderUpsertCalls++; + } + + @Override + public void upsertProducts(Page page) { + products.addAll(page.items()); + productUpsertCalls++; + } + + public List salesOrders() { + return Collections.unmodifiableList(salesOrders); + } + + public List products() { + return Collections.unmodifiableList(products); + } + + public int salesOrderUpsertCalls() { + return salesOrderUpsertCalls; + } + + public int productUpsertCalls() { + return productUpsertCalls; + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/InMemoryTokenStore.java b/testkit/src/main/java/common/ecommerce/testkit/InMemoryTokenStore.java new file mode 100644 index 0000000..9b97224 --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/InMemoryTokenStore.java @@ -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 tokens = new HashMap(); + private int saveCount; + + @Override + public Optional 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; + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/Responses.java b/testkit/src/main/java/common/ecommerce/testkit/Responses.java new file mode 100644 index 0000000..e8f1acb --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/Responses.java @@ -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.emptyMap(), body, 1); + } + + public static HttpResponse status(int code, String body) { + return HttpResponse.of(code, Collections.emptyMap(), body, 1); + } + + public static HttpResponse rateLimited(String retryAfterSeconds) { + return HttpResponse.of(429, + Collections.singletonMap("Retry-After", retryAfterSeconds), "", 1); + } +} diff --git a/testkit/src/main/java/common/ecommerce/testkit/TestData.java b/testkit/src/main/java/common/ecommerce/testkit/TestData.java new file mode 100644 index 0000000..155f773 --- /dev/null +++ b/testkit/src/main/java/common/ecommerce/testkit/TestData.java @@ -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 pageOf(SalesOrder... orders) { + return Page.last(java.util.Arrays.asList(orders)); + } +}