|
|
|
|
# common-ecommerce 开发指南
|
|
|
|
|
|
|
|
|
|
> 面向「要接入一个新平台」和「要写业务调用」的人。
|
|
|
|
|
> 读完之后你应该能回答三个问题:SDK 的分层是什么、加一个供应商要动哪些文件、加完之后怎么测。
|
|
|
|
|
>
|
|
|
|
|
> 配套材料:`README.md`(架构图、包结构与调用方式速查)、`D:\woker\文档\01需求分析\2026-10-28-电商平台\2026-10-26-cross-border-fulfillment-sdk-design.md`(Spec 0 总体设计)。
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 目录
|
|
|
|
|
|
|
|
|
|
1. [一句话心智模型](#一一句话心智模型)
|
|
|
|
|
2. [三个维度:平台、通道、店铺](#二三个维度平台通道店铺)
|
|
|
|
|
3. [核心类型速查](#三核心类型速查)
|
|
|
|
|
4. [三条流水线逐段讲](#四三条流水线逐段讲)
|
|
|
|
|
5. [加一个供应商:8 步](#五加一个供应商8-步)
|
|
|
|
|
6. [加完之后怎么测](#六加完之后怎么测)
|
|
|
|
|
7. [验收清单](#七验收清单)
|
|
|
|
|
8. [已知缺口与坑](#八已知缺口与坑)
|
|
|
|
|
9. [上手顺序](#九上手顺序)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 一、一句话心智模型
|
|
|
|
|
|
|
|
|
|
这个 SDK 是**一层翻译 + 三条流水线**。
|
|
|
|
|
|
|
|
|
|
每个平台说话方式都不同:字段名、签名算法、分页方式、时间格式、错误码。SDK 把这些差异**全部关进一个类**(适配器),对外只吐统一模型 `SalesOrder`、`ProductListing`。
|
|
|
|
|
|
|
|
|
|
业务代码永远只跟统一模型打交道,不出现任何平台字段名、URL、签名。
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
业务代码
|
|
|
|
|
│ 只认 AccountKey + 统一模型
|
|
|
|
|
▼
|
|
|
|
|
ChannelSdk 门面 ──── 查账户 / 找适配器 / 查能力
|
|
|
|
|
│
|
|
|
|
|
▼
|
|
|
|
|
适配器(每个平台一个模块)
|
|
|
|
|
│ 平台协议全在这里
|
|
|
|
|
▼
|
|
|
|
|
HttpTransport → 平台 API
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
三条流水线:
|
|
|
|
|
|
|
|
|
|
| 流水线 | 干什么 | 失败语义 |
|
|
|
|
|
|:---|:---|:---|
|
|
|
|
|
| **读**(单次) | `sdk.salesOrders(key, conn).pull(query)` | 可重跑,靠 canonicalKey upsert 去重 |
|
|
|
|
|
| **批量读** | `SyncEngine` 翻页 + 落库 + 水位线 | 整批成功才推进,失败不推进 |
|
|
|
|
|
| **写** | `sdk.writes().execute(...)` | 必须幂等,重跑不能重复发货/退款 |
|
|
|
|
|
|
|
|
|
|
读和写没有共用执行器,因为失败语义相反:读可以放心重跑,写不能。
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 二、三个维度:平台、通道、店铺
|
|
|
|
|
|
|
|
|
|
这是整个设计的地基,混了后面全乱。
|
|
|
|
|
|
|
|
|
|
| 维度 | 类型 | 是什么 | 例子 |
|
|
|
|
|
|:---|:---|:---|:---|
|
|
|
|
|
| 业务平台 | `Platform` | 你卖货的地方 | `WALMART_SC`、`AMAZON_SC`、`EBAY` |
|
|
|
|
|
| 接入通道 | `ChannelProvider` | 你**通过谁**去连这个平台 | `DIRECT`(直连)、`LINGXING`(领星聚合) |
|
|
|
|
|
| 店铺 | `omsStoreId` | **你自己的**渠道店铺 ID | `oms-wm-001` |
|
|
|
|
|
|
|
|
|
|
三者拼成 `AccountKey`,是所有调用的隔离维度:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001");
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 为什么要拆开
|
|
|
|
|
|
|
|
|
|
同一个沃尔玛店铺,可能**既直连、又走领星**。业务上它是一个店,接入上是两条路。
|
|
|
|
|
|
|
|
|
|
由此推出两条硬规则:
|
|
|
|
|
|
|
|
|
|
1. **业务主键 `canonicalKey` 不带 provider**
|
|
|
|
|
否则切换接入方式时,同一张订单会变成两行。
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
CanonicalKeys.salesOrder(Platform.WALMART_SC, "oms-wm-001", "PO-123");
|
|
|
|
|
// 不管从直连还是领星拉到,都是 "WALMART_SC:oms-wm-001:PO-123"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
2. **水位线、令牌、限流按 provider 分开**
|
|
|
|
|
两条路各自维护进度,不能复用。`SyncSpec` 的维度是 `provider + accountKey + stream`。
|
|
|
|
|
|
|
|
|
|
### 三级标识
|
|
|
|
|
|
|
|
|
|
| 标识 | 组成 | 用途 |
|
|
|
|
|
|:---|:---|:---|
|
|
|
|
|
| `omsStoreId` | OMS 渠道店铺 ID | 业务归属 |
|
|
|
|
|
| `canonicalKey` | `platform + omsStoreId + 平台实体 ID` | upsert、去重、状态流转 |
|
|
|
|
|
| `sourceKey` | `provider + platform + externalStoreId + 平台实体 ID` | 原始报文、审计、水位线 |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 三、核心类型速查
|
|
|
|
|
|
|
|
|
|
### 3.1 基接口 `PlatformAdapter`
|
|
|
|
|
|
|
|
|
|
**不是抽象基类,是接口**。每个适配器必须回答 5 个问题。
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public interface PlatformAdapter {
|
|
|
|
|
String adapterId(); // 我是谁:"lingxing"
|
|
|
|
|
ChannelProvider provider(); // 哪条通道:DIRECT / LINGXING
|
|
|
|
|
Set<Platform> platforms(); // 覆盖哪些平台
|
|
|
|
|
EnumSet<Capability> capabilities(); // 我会什么
|
|
|
|
|
default boolean supports(ChannelAccount a, Capability c) {
|
|
|
|
|
return capabilities().contains(c);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| 动作 | 谁调用 | 你要做什么 |
|
|
|
|
|
|:---|:---|:---|
|
|
|
|
|
| `adapterId()` | 日志、报错、注册冲突检测 | 唯一短名 |
|
|
|
|
|
| `provider()` | 门面路由 | 直连固定 `DIRECT` |
|
|
|
|
|
| `platforms()` | 门面注册、能力报告 | 列全覆盖的平台 |
|
|
|
|
|
| `capabilities()` | 能力报告、门面拦截 | **只声明真实现的** |
|
|
|
|
|
| `supports(account, cap)` | 每次门面调用前 | 直连不用覆写;聚合器**必须**覆写 |
|
|
|
|
|
|
|
|
|
|
`capabilities()` 是**声明**,不是猜测。声明了没实现,第一次调用就炸,比不声明更糟。
|
|
|
|
|
|
|
|
|
|
### 3.2 能力接口
|
|
|
|
|
|
|
|
|
|
供应商实现哪些接口,就声明哪些能力。接口都继承 `PlatformAdapter`:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public interface SalesOrderCapable extends PlatformAdapter {
|
|
|
|
|
Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query);
|
|
|
|
|
SalesOrder get(ChannelContext ctx, SalesOrderRef ref);
|
|
|
|
|
default void requireCapability(); // 未声明即抛 UnsupportedCapabilityException
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
public interface ProductCapable extends PlatformAdapter {
|
|
|
|
|
ProductSyncStrategy syncStrategy(); // INCREMENTAL_TIME_WINDOW / FULL_PULL_DIFF / REPORT
|
|
|
|
|
Page<ProductListing> pull(ChannelContext ctx, ProductQuery query);
|
|
|
|
|
ProductListing get(ChannelContext ctx, ProductRef ref);
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
其余能力接口(按需实现,不实现就不声明):
|
|
|
|
|
|
|
|
|
|
| 接口 | 读/写 | 关键方法 |
|
|
|
|
|
|:---|:---:|:---|
|
|
|
|
|
| `SettlementCapable` | 读 | `pull(ctx, SettlementQuery)` |
|
|
|
|
|
| `AfterSaleCapable` | 读 | `pull(ctx, AfterSaleQuery)` |
|
|
|
|
|
| `OutboundOrderCapable` | 读 | `pull(ctx, OutboundOrderQuery)` |
|
|
|
|
|
| `ShippingLabelCapable` | 读 | `labels(ctx, LabelQuery)` |
|
|
|
|
|
| `OutboundCapable` | **写** | `submit(ctx, packages)` / `results(ctx, globalOrderNos)` |
|
|
|
|
|
| `ShipmentReviewCapable` | **写** | `review(ctx, globalOrderNos)` |
|
|
|
|
|
| `OrderEditCapable` | **写** | `edit(ctx, requests)` |
|
|
|
|
|
| `AggregatorCapable` | — | `listSubChannels(ctx)`,聚合器额外实现 |
|
|
|
|
|
|
|
|
|
|
**为什么 `get` 的参数是 `SalesOrderRef` / `ProductRef` 而不是 `String`?**
|
|
|
|
|
|
|
|
|
|
Java 擦除后两个 `get(ctx, String)` 是同一个签名。一个同时实现订单和商品的适配器(比如直连沃尔玛)**无法同时实现**,编译器直接报名称冲突。所以包成两个不同的类。对外的门面视图仍收 `String`(`sdk.salesOrders(key, conn).get("PO-123")`),由视图负责包装。
|
|
|
|
|
|
|
|
|
|
> 对应的 import 路径:`common.ecommerce.channel.model.order.SalesOrderRef`、`common.ecommerce.channel.model.product.ProductRef`。`channel.model` 按职责拆成 `account` / `order` / `product` / `fulfillment` / `aftersale` / `settlement` 六个子包;枚举在 `common.ecommerce.shared.model` 根包。
|
|
|
|
|
|
|
|
|
|
**为什么 `pull` 返回 `Page<T>` 而不是 `List<T>`?**
|
|
|
|
|
|
|
|
|
|
`Page` 带 `nextCursor`,`null` 表示没有下一页。翻页方式各平台不同(offset / cursor / pageToken),差异留在适配器里,SDK 只认这个统一信封。
|
|
|
|
|
|
|
|
|
|
### 3.3 门面 `ChannelSdk`
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public final class ChannelSdk implements ProviderResolver {
|
|
|
|
|
public CapabilityReport capabilities(AccountKey key); // 只读,不发请求
|
|
|
|
|
public SalesOrders salesOrders(AccountKey key, ChannelConnection conn); // 订单视图
|
|
|
|
|
public Products products(AccountKey key, ChannelConnection conn); // 商品视图
|
|
|
|
|
public Settlements settlements(AccountKey key, ChannelConnection conn); // 账单视图(读)
|
|
|
|
|
public AfterSales afterSales(AccountKey key, ChannelConnection conn); // 售后视图(读)
|
|
|
|
|
public Outbounds outbounds(AccountKey key, ChannelConnection conn); // 出库/面单/审核视图
|
|
|
|
|
public List<AggregatorCapable.SubChannel> subChannels(AccountKey key, ChannelConnection conn);
|
|
|
|
|
public IdempotencyGuard writes(); // 写操作守卫
|
|
|
|
|
public PlatformAdapter resolve(AccountKey key); // 按 key 找适配器
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
写类能力(`submit` / `review` / `edit`)挂在 `Outbounds` 视图上,**仍必须经 `sdk.writes()` 包一层幂等**再调用。
|
|
|
|
|
|
|
|
|
|
门面**不做**:不选 provider、不自动兜底、不重试、不缓存。
|
|
|
|
|
|
|
|
|
|
每次调用固定三步:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
key → accountRepository.findByKey(provider, platform, omsStoreId)
|
|
|
|
|
→ adapters.get(provider|platform)
|
|
|
|
|
→ adapter.supports(account, capability)
|
|
|
|
|
→ 交给适配器
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`build()` 会立刻失败的情况:
|
|
|
|
|
|
|
|
|
|
| 缺失 | 异常 |
|
|
|
|
|
|:---|:---|
|
|
|
|
|
| `accountRepository` | `ChannelSdk requires an accountRepository` |
|
|
|
|
|
| 一个适配器都没注册 | `ChannelSdk requires at least one adapter or adapter factory` |
|
|
|
|
|
| 同一 `provider + platform` 注册两次 | `duplicate adapter for ...` |
|
|
|
|
|
|
|
|
|
|
**能力不够不会自动换 provider。** 换路意味着可能重复发货,必须业务代码显式决定。
|
|
|
|
|
|
|
|
|
|
### 3.4 存量 SPI(宿主必须实现)
|
|
|
|
|
|
|
|
|
|
| SPI | 作用 | 读要用 | 写要用 |
|
|
|
|
|
|:---|:---|:---:|:---:|
|
|
|
|
|
| `ChannelAccountRepository`(channel) | 读渠道账户 | ✅ | ✅ |
|
|
|
|
|
| `ChannelSecret` | 凭据载体,调用时经 `ChannelConnection` 传入 | ✅ | ✅ |
|
|
|
|
|
| `SecretProvider` | ~~按 credentialRef 取密钥~~ **已废弃**:凭据由调用方传入 | — | — |
|
|
|
|
|
| `TokenStore` | token 读写(宿主加密) | ✅ | ✅ |
|
|
|
|
|
| `LockProvider` | token 刷新防击穿 | ✅ | ✅ |
|
|
|
|
|
| `SyncCursorStore` | 水位线 | 批量读 | — |
|
|
|
|
|
| `Sink`(channel) | 领域对象落库 | 批量读 | — |
|
|
|
|
|
| `IdempotencyStore` | 幂等键抢占与结果 | — | ✅ |
|
|
|
|
|
|
|
|
|
|
### 3.5 错误类型
|
|
|
|
|
|
|
|
|
|
全部继承 `ChannelException`,字段:`platform / provider / omsStoreId / operation / requestId / platformCode / retryable / rawResponse`。
|
|
|
|
|
|
|
|
|
|
| 异常 | 触发 | 可重试 |
|
|
|
|
|
|:---|:---|:---:|
|
|
|
|
|
| `AuthException` | 401 / 403 | 刷新后 1 次 |
|
|
|
|
|
| `RateLimitException` | 429,带 `retryAfterMillis()` | 是 |
|
|
|
|
|
| `TransientException` | 5xx / 网络 / 超时 | 是 |
|
|
|
|
|
| `ValidationException` | 其它 4xx | 否 |
|
|
|
|
|
| `PlatformBusinessException` | 平台业务错误码 | 视码 |
|
|
|
|
|
| `ChannelException.UnsupportedCapabilityException` | 能力缺失 | 否 |
|
|
|
|
|
| `IdempotencyConflictException` | 并发重复写 | 否 |
|
|
|
|
|
| `CrossProviderConflictException` | 已由另一 provider 完成 | 否,人工确认 |
|
|
|
|
|
|
|
|
|
|
> `UnsupportedCapabilityException` 是 `ChannelException` 的**静态内部类**,必须写全名。
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 四、三条流水线逐段讲
|
|
|
|
|
|
|
|
|
|
### 4.1 单次读:`sdk.salesOrders(key, conn).pull(query)`
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
Page<SalesOrder> page = sdk.salesOrders(key, conn).pull(SalesOrderQuery.builder()
|
|
|
|
|
.updatedAfter(Instant.parse("2026-10-25T00:00:00Z")) // 必填,UTC
|
|
|
|
|
.updatedBefore(Instant.parse("2026-10-26T00:00:00Z")) // 可选,缺省取 now
|
|
|
|
|
.pageSize(100) // 会被截到平台上限
|
|
|
|
|
.build());
|
|
|
|
|
|
|
|
|
|
while (page.nextCursor() != null) {
|
|
|
|
|
page = sdk.salesOrders(key, conn).pull(
|
|
|
|
|
SalesOrderQuery.builder()...cursor(page.nextCursor()).build());
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`SalesOrderQuery` 有 `toBuilder()`,翻页时直接改游标。
|
|
|
|
|
|
|
|
|
|
内部发生了什么:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
ChannelSdk
|
|
|
|
|
→ requireAccount(找不到抛 IllegalStateException)
|
|
|
|
|
→ resolve(找不到适配器抛 IllegalStateException)
|
|
|
|
|
→ SalesOrders.requireSalesOrderCapable(能力缺失抛 UnsupportedCapabilityException)
|
|
|
|
|
→ adapter.pull(ctx, query)
|
|
|
|
|
├─ 取 token(TokenManager)
|
|
|
|
|
├─ 签名
|
|
|
|
|
├─ transport.execute(req)
|
|
|
|
|
├─ Responses.throwIfNotSuccess(resp, "salesOrders.pull")
|
|
|
|
|
└─ Mapper → Page<SalesOrder>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 4.2 批量读:`SyncEngine`
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
SyncSpec spec = SyncSpec.of(
|
|
|
|
|
ChannelProvider.LINGXING, "oms-wm-001",
|
|
|
|
|
SyncSpec.STREAM_SALES_ORDERS,
|
|
|
|
|
Duration.ofMinutes(10)); // 重叠窗口
|
|
|
|
|
|
|
|
|
|
Instant to = Instant.now();
|
|
|
|
|
SyncResult r = new SyncEngine(cursorStore, sink).syncSalesOrders(spec, to,
|
|
|
|
|
(from, cursor) -> sdk.salesOrders(key, conn).pull(SalesOrderQuery.builder()
|
|
|
|
|
.updatedAfter(from).updatedBefore(to)
|
|
|
|
|
.cursor(cursor).build()));
|
|
|
|
|
|
|
|
|
|
r.pages(); // 拉了几页
|
|
|
|
|
r.items(); // 落了几条
|
|
|
|
|
r.watermarkAdvanced(); // 是否推进
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
引擎做的事就一个循环:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
watermark = cursorStore.get(provider, accountKey, stream)
|
|
|
|
|
from = watermark - overlap // 回退重叠窗口
|
|
|
|
|
loop:
|
|
|
|
|
page = fetch(from, cursor)
|
|
|
|
|
if page 空: break
|
|
|
|
|
sink.upsertSalesOrders(page) // 落库
|
|
|
|
|
cursor = page.nextCursor()
|
|
|
|
|
if cursor == null: break
|
|
|
|
|
cursorStore.advance(provider, accountKey, stream, to) // 全成功才推进
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| 关键点 | 原因 |
|
|
|
|
|
|:---|:---|
|
|
|
|
|
| 起点回退 `overlap` | 平台有延迟、时钟有偏差,边界那一秒的单可能上一轮没拉到 |
|
|
|
|
|
| 终点是**传入的 `to`**,不是 `now()` | 拉取可能持续几分钟,用 `now()` 会越拉越远 |
|
|
|
|
|
| 中途抛异常 → 水位线不动 | 安全重跑,靠 upsert 去重 |
|
|
|
|
|
| 没有水位线 → 抛 `IllegalStateException` | 逼迫先做全量建底,不偷偷丢数据 |
|
|
|
|
|
| 不持有线程 | 调度归宿主(Quartz / XXL-Job / Spring Scheduler) |
|
|
|
|
|
|
|
|
|
|
**首次全量**要自己回填水位线:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
if (cursorStore.get(provider, accountKey, stream) == null) {
|
|
|
|
|
cursorStore.advance(provider, accountKey, stream, Instant.parse("2026-01-01T00:00:00Z"));
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**`Sink` 怎么写**:SDK 只给 `Page<SalesOrder>`,upsert 的键要自己算:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public void upsertSalesOrders(Page<SalesOrder> page) {
|
|
|
|
|
for (SalesOrder o : page.items()) {
|
|
|
|
|
String key = CanonicalKeys.salesOrder(platform, o.omsStoreId(), o.channelOrderId());
|
|
|
|
|
// INSERT ... ON DUPLICATE KEY UPDATE,唯一索引建在 canonicalKey 上
|
|
|
|
|
// sourceProvider / sourceAccountId 只更新来源字段,不产生新行
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 4.3 写:`IdempotencyGuard`
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
WriteScope scope = WriteScope.of(
|
|
|
|
|
ChannelProvider.LINGXING, Platform.WALMART_SC,
|
|
|
|
|
"oms-wm-001", // 业务店铺
|
|
|
|
|
"1108413237731", // 平台店铺 ID,只用于 provider 请求键
|
|
|
|
|
"markShipped",
|
|
|
|
|
"PO-1:pkg-1"); // 业务自然键
|
|
|
|
|
|
|
|
|
|
WriteResult<ShipResult> r = sdk.writes().execute(scope,
|
|
|
|
|
() -> adapter.markShipped(ctx, cmd), // 真正打平台
|
|
|
|
|
ShipResult::shipmentId); // 结果引用,回放时返回
|
|
|
|
|
|
|
|
|
|
if (r.alreadyCompleted()) {
|
|
|
|
|
// 之前已发过,用 r.resultRef() 返回给上游,不算失败
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
内部是两把锁:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
1. 抢业务键(不带 provider) → 已成功?→ 回放 / 别的 provider 做的?→ 冲突
|
|
|
|
|
2. 抢 provider 键(带 provider)→ 已成功?→ 平台写过但没记账 → 回放
|
|
|
|
|
3. 执行
|
|
|
|
|
4. 先记 provider 键成功,再记业务键成功
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| 情形 | 结果 |
|
|
|
|
|
|:---|:---|
|
|
|
|
|
| 首次调用 | `EXECUTED` |
|
|
|
|
|
| 同 provider 重复 | `ALREADY_COMPLETED`,不调平台 |
|
|
|
|
|
| 另一 provider 重复 | `CrossProviderConflictException` |
|
|
|
|
|
| 并发 | `IdempotencyConflictException` |
|
|
|
|
|
| 抛 `retryable=true` 异常 | 两把锁记 `FAILED_RETRYABLE`,可重跑 |
|
|
|
|
|
| 抛 `retryable=false` 异常 | 记 `FAILED_FINAL`,之后拒绝,等人工 |
|
|
|
|
|
| 崩溃窗口(平台已写、业务键未记) | provider 键命中,回放,不重复写 |
|
|
|
|
|
|
|
|
|
|
**业务键规则**:
|
|
|
|
|
- 退款用 `returnId:itemId:refundRequestId`,**禁止用金额**(金额只做校验)。
|
|
|
|
|
- `IdempotencyStore.claim` 必须原子(唯一索引 / Redis SETNX),否则并发语义不成立。
|
|
|
|
|
- 不注入 `idempotencyStore` 时 `sdk.writes()` 直接抛异常,**没有「无幂等」降级路径**。
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 五、加一个供应商:8 步
|
|
|
|
|
|
|
|
|
|
以新增 `acme` 直连平台为例。**核心原则:不改 channel、不改门面、不改宿主。**
|
|
|
|
|
|
|
|
|
|
### 第 0 步:先想清楚三件事
|
|
|
|
|
|
|
|
|
|
| 问题 | 影响 |
|
|
|
|
|
|:---|:---|
|
|
|
|
|
| 它属于哪个 `Platform`? | 枚举里有直接用;没有才加(唯一允许改 `shared` 的地方) |
|
|
|
|
|
| 走 `DIRECT` 还是新聚合器? | 新聚合器才加 `ChannelProvider` 枚举值 |
|
|
|
|
|
| 它会哪些能力? | 只列真能做的 |
|
|
|
|
|
|
|
|
|
|
现有枚举(`common.ecommerce.shared.model`):
|
|
|
|
|
|
|
|
|
|
- `Platform`:`AMAZON_SC` `AMAZON_VC` `WALMART_SC` `WALMART_1P` `TIKTOK` `TEMU` `EBAY` `SHEIN` `ALIEXPRESS` `MIRAKL` `TARGET` `BESTBUY` `AEPH` `WAYFAIR` `MICHAELS` `ECHO` `LOSDLIUS` `CUSTOM`
|
|
|
|
|
- `ChannelProvider`:`DIRECT` `LINGXING` `TEAPPLIX` `CUSTOM`
|
|
|
|
|
|
|
|
|
|
### 第 1 步:建模块
|
|
|
|
|
|
|
|
|
|
`pom.xml` 加 `<module>acme</module>`,模块依赖:
|
|
|
|
|
|
|
|
|
|
```xml
|
|
|
|
|
<dependency>
|
|
|
|
|
<groupId>ecommerce</groupId>
|
|
|
|
|
<artifactId>sdk-common</artifactId>
|
|
|
|
|
</dependency>
|
|
|
|
|
<dependency>
|
|
|
|
|
<groupId>ecommerce</groupId>
|
|
|
|
|
<artifactId>channel-sdk-core</artifactId>
|
|
|
|
|
</dependency>
|
|
|
|
|
<dependency>
|
|
|
|
|
<groupId>ecommerce</groupId>
|
|
|
|
|
<artifactId>sdk-testkit</artifactId>
|
|
|
|
|
<scope>test</scope>
|
|
|
|
|
</dependency>
|
|
|
|
|
<dependency>
|
|
|
|
|
<groupId>org.junit.jupiter</groupId>
|
|
|
|
|
<artifactId>junit-jupiter</artifactId>
|
|
|
|
|
<scope>test</scope>
|
|
|
|
|
</dependency>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
> 红线:适配器模块里不许出现 Spring / JDBC / Redis / MQ。
|
|
|
|
|
|
|
|
|
|
### 第 2 步:常量类
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
package common.ecommerce.acme;
|
|
|
|
|
|
|
|
|
|
// 枚举在 shared.model,渠道域模型在 channel.model
|
|
|
|
|
import common.ecommerce.shared.model.Capability;
|
|
|
|
|
import common.ecommerce.shared.model.ChannelProvider;
|
|
|
|
|
import common.ecommerce.shared.model.Platform;
|
|
|
|
|
import common.ecommerce.channel.model.account.ChannelAccount;
|
|
|
|
|
import common.ecommerce.channel.model.order.SalesOrder;
|
|
|
|
|
import common.ecommerce.channel.model.order.SalesOrderQuery;
|
|
|
|
|
import common.ecommerce.channel.model.order.SalesOrderRef;
|
|
|
|
|
import common.ecommerce.shared.support.Money;
|
|
|
|
|
import common.ecommerce.shared.support.Page;
|
|
|
|
|
import common.ecommerce.shared.support.PlatformTime;
|
|
|
|
|
|
|
|
|
|
public final class AcmeConstants {
|
|
|
|
|
|
|
|
|
|
public static final String ADAPTER_ID = "acme";
|
|
|
|
|
public static final String DEFAULT_BASE_URL = "https://api.acme.example.com";
|
|
|
|
|
public static final String PATH_TOKEN = "/oauth/token";
|
|
|
|
|
public static final String PATH_ORDERS = "/v1/orders";
|
|
|
|
|
|
|
|
|
|
public static final int MAX_PAGE_SIZE = 100;
|
|
|
|
|
public static final int MAX_QUERY_DAYS = 31;
|
|
|
|
|
|
|
|
|
|
private AcmeConstants() {
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
平台端点必须是**代码**,不是配置表:配置化会让线上和测试跑不同协议,出问题查不出来。
|
|
|
|
|
|
|
|
|
|
### 第 3 步:DTO —— 平台字段名的唯一落点
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
@Getter
|
|
|
|
|
@Setter
|
|
|
|
|
@JsonIgnoreProperties(ignoreUnknown = true)
|
|
|
|
|
public final class AcmeOrderDto {
|
|
|
|
|
|
|
|
|
|
@JsonProperty("order_sn") private String orderSn;
|
|
|
|
|
@JsonProperty("order_status") private String orderStatus;
|
|
|
|
|
@JsonProperty("buyer_country") private String buyerCountry;
|
|
|
|
|
@JsonProperty("total_amount") private String totalAmount;
|
|
|
|
|
@JsonProperty("currency") private String currency;
|
|
|
|
|
@JsonProperty("created_at") private Long createdAt; // 注意秒/毫秒
|
|
|
|
|
@JsonProperty("lines") private List<AcmeOrderLineDto> lines;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**平台字段名只允许出现在 DTO 和 Mapper 里。**
|
|
|
|
|
|
|
|
|
|
**DTO 用 Lombok,领域模型不用。** DTO 是纯数据容器,没有不变量要保护,`@Getter`/`@Setter`
|
|
|
|
|
省掉全部样板;`channel` 的模型是不可变 + Builder,本来就没有 setter,且 `channel` 要尽量少依赖
|
|
|
|
|
编译期工具。Lombok 声明为 `scope=provided`,不进宿主运行时。
|
|
|
|
|
|
|
|
|
|
**端点和路径写成常量,不做配置。** 协议细节(URL、字段名、限流值)是代码的一部分——
|
|
|
|
|
配置化会让线上和测试跑不同协议,出问题无法从代码复现。`AdapterConfig` 不是配置项,
|
|
|
|
|
它只承载「测试时替换目标地址」这一种由调用方显式传入的参数。
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public final class AcmeConstants {
|
|
|
|
|
/** 生产基址;仅测试/联调时由 AdapterConfig 覆盖。 */
|
|
|
|
|
public static final String DEFAULT_BASE_URL = "https://api.acme.example.com";
|
|
|
|
|
public static final String PATH_TOKEN = "/oauth/token";
|
|
|
|
|
public static final String PATH_ORDERS = "/v1/orders";
|
|
|
|
|
public static final int MAX_PAGE_SIZE = 100;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**SDK 不碰存储、不读配置。** 账户、密钥、token、水位线、幂等记录全部经 SPI 由宿主提供;
|
|
|
|
|
适配器构造函数里只接收这些 SPI 与 `Clock`,不接收 `DataSource`、`Properties` 之类的对象。
|
|
|
|
|
|
|
|
|
|
### 第 4 步:Mapper —— DTO → 统一模型
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public final class AcmeOrderMapper {
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* @param externalStoreId 平台店铺 ID,写入 sourceAccountId 供追溯(不进业务主键)
|
|
|
|
|
*/
|
|
|
|
|
public SalesOrder toSalesOrder(AcmeOrderDto dto, String omsStoreId, String externalStoreId, ZoneId zone) {
|
|
|
|
|
String currency = dto.getCurrency() == null ? "USD" : dto.getCurrency();
|
|
|
|
|
|
|
|
|
|
List<OrderLine> lines = new ArrayList<OrderLine>();
|
|
|
|
|
for (AcmeOrderLineDto l : safe(dto.getLines())) {
|
|
|
|
|
lines.add(OrderLine.builder()
|
|
|
|
|
.lineId(l.getLineId())
|
|
|
|
|
.platformSku(l.getSku())
|
|
|
|
|
.quantity(l.getQty() == null ? 0 : l.getQty())
|
|
|
|
|
.unitPrice(moneyOrNull(l.getPrice(), currency))
|
|
|
|
|
.build());
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return SalesOrder.builder()
|
|
|
|
|
.omsStoreId(omsStoreId)
|
|
|
|
|
.channelOrderId(dto.getOrderSn()) // ★ 平台自己的稳定单号
|
|
|
|
|
.status(dto.getOrderStatus())
|
|
|
|
|
.buyerName(dto.getBuyerName())
|
|
|
|
|
.shipToCountryCode(dto.getBuyerCountry())
|
|
|
|
|
.lines(lines)
|
|
|
|
|
.totalAmount(moneyOrNull(dto.getTotalAmount(), currency))
|
|
|
|
|
.occurredAt(PlatformTime.of(Instant.ofEpochSecond(dto.getCreatedAt()), zone))
|
|
|
|
|
.sourceProvider(ChannelProvider.DIRECT) // ★ 只标来源,不进主键
|
|
|
|
|
.sourceAccountId(externalStoreId)
|
|
|
|
|
.build();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
private static <T> List<T> safe(List<T> in) {
|
|
|
|
|
return in == null ? Collections.<T>emptyList() : in;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
private static Money moneyOrNull(String value, String currency) {
|
|
|
|
|
if (value == null || value.trim().isEmpty()) {
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
return Money.of(value.trim(), currency);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Mapper 里最容易错的三处:
|
|
|
|
|
|
|
|
|
|
1. `channelOrderId` 选了会变的字段(撤销后重下、批次号)→ 每次同步产生新行
|
|
|
|
|
2. 时间没转 UTC → 水位线错位
|
|
|
|
|
3. 金额用了 `double` → 精度丢失(`Money` 只接受 `BigDecimal` 或字符串)
|
|
|
|
|
|
|
|
|
|
### 第 5 步:认证与签名
|
|
|
|
|
|
|
|
|
|
**只用 token 的**(像领星),继承 `TokenManager` 只写换 token 的逻辑:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
TokenManager tm = new TokenManager(tokenStore, lockProvider, clock, 600) {
|
|
|
|
|
@Override
|
|
|
|
|
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) {
|
|
|
|
|
return tokenClient.fetch(secret.appKey(), secret.appSecret());
|
|
|
|
|
}
|
|
|
|
|
};
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
防击穿、提前续期、日志只打指纹,模板都写好了。
|
|
|
|
|
|
|
|
|
|
**要签名的**,写静态工具类:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public final class AcmeSigner {
|
|
|
|
|
public static String sign(Map<String, String> params, String appSecret) { ... }
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
签名实现集中在一处,联调时只改这里。
|
|
|
|
|
|
|
|
|
|
### 第 6 步:Adapter —— 干活的类
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public final class AcmeAdapter implements SalesOrderCapable {
|
|
|
|
|
|
|
|
|
|
private final HttpTransport transport;
|
|
|
|
|
private final JacksonJsonCodec json;
|
|
|
|
|
private final Clock clock;
|
|
|
|
|
private final TokenManager tokenManager;
|
|
|
|
|
private final AcmeOrderMapper mapper = new AcmeOrderMapper();
|
|
|
|
|
|
|
|
|
|
// 适配器只持有协议与基础设施:端点与凭据随每次调用的 ChannelContext 进来
|
|
|
|
|
public AcmeAdapter(HttpTransport transport, JacksonJsonCodec json,
|
|
|
|
|
TokenStore tokenStore, LockProvider lockProvider, Clock clock) {
|
|
|
|
|
this.transport = transport;
|
|
|
|
|
this.json = json;
|
|
|
|
|
this.clock = clock;
|
|
|
|
|
final AcmeTokenClient tokenClient = new AcmeTokenClient(transport, json, clock);
|
|
|
|
|
this.tokenManager = new TokenManager(tokenStore, lockProvider, clock, 600) {
|
|
|
|
|
@Override
|
|
|
|
|
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) {
|
|
|
|
|
return tokenClient.fetch(secret.endpointBaseUrl(), secret.appKey(), secret.appSecret());
|
|
|
|
|
}
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override public String adapterId() { return AcmeConstants.ADAPTER_ID; }
|
|
|
|
|
@Override public ChannelProvider provider() { return ChannelProvider.DIRECT; }
|
|
|
|
|
@Override public Set<Platform> platforms() { return EnumSet.of(Platform.AMAZON_SC); }
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public EnumSet<Capability> capabilities() {
|
|
|
|
|
return EnumSet.of(Capability.SALES_ORDER);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) {
|
|
|
|
|
requireCapability(); // 自己再兜一层
|
|
|
|
|
|
|
|
|
|
ChannelAccount account = ctx.account();
|
|
|
|
|
int size = Math.min(query.pageSize() <= 0 ? 100 : query.pageSize(),
|
|
|
|
|
AcmeConstants.MAX_PAGE_SIZE);
|
|
|
|
|
|
|
|
|
|
HttpRequest req = HttpRequest.builder()
|
|
|
|
|
.method("POST")
|
|
|
|
|
.url(ctx.endpointBaseUrl() + AcmeConstants.PATH_ORDERS) // ★ 端点来自 ctx
|
|
|
|
|
.header("Content-Type", "application/json")
|
|
|
|
|
.header("Authorization", authHeader(ctx))
|
|
|
|
|
.header("X-Request-Id", ctx.requestId())
|
|
|
|
|
.body(buildBody(account, query, size))
|
|
|
|
|
.operation("salesOrders.pull")
|
|
|
|
|
.build();
|
|
|
|
|
|
|
|
|
|
HttpResponse resp = transport.execute(req);
|
|
|
|
|
Responses.throwIfNotSuccess(resp, "salesOrders.pull"); // ★ 必须调
|
|
|
|
|
|
|
|
|
|
List<AcmeOrderDto> dtos = json.listAt(resp.body(), "data.orders", AcmeOrderDto.class);
|
|
|
|
|
List<SalesOrder> out = new ArrayList<SalesOrder>(dtos.size());
|
|
|
|
|
for (AcmeOrderDto dto : dtos) {
|
|
|
|
|
out.add(mapper.toSalesOrder(dto, account.omsStoreId(), account.externalStoreId(),
|
|
|
|
|
ZoneId.of(account.marketplaceZone())));
|
|
|
|
|
}
|
|
|
|
|
return Page.of(out, json.stringAt(resp.body(), "data.next_cursor"));
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) {
|
|
|
|
|
// 没有详情接口就显式抛,不要返回 null
|
|
|
|
|
throw ChannelException.builder()
|
|
|
|
|
.message("acme order detail is not implemented yet")
|
|
|
|
|
.operation("salesOrders.get")
|
|
|
|
|
.provider(provider().name())
|
|
|
|
|
.omsStoreId(ctx.omsStoreId())
|
|
|
|
|
.requestId(ctx.requestId())
|
|
|
|
|
.platformCode(ref.channelOrderId())
|
|
|
|
|
.build();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
// ---------------------------------------------------------------- internals
|
|
|
|
|
|
|
|
|
|
private String authHeader(ChannelContext ctx) {
|
|
|
|
|
ChannelAccount account = ctx.account();
|
|
|
|
|
// 凭据由调用方经 ChannelConnection 传入,适配器不自己去找
|
|
|
|
|
AccessToken token = tokenManager.getOrRefresh("acme:" + account.externalStoreId(), ctx.secret());
|
|
|
|
|
return token.tokenType() + " " + token.value();
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
private String buildBody(ChannelAccount account, SalesOrderQuery query, int size) {
|
|
|
|
|
Map<String, Object> body = new LinkedHashMap<String, Object>();
|
|
|
|
|
body.put("store_id", account.externalStoreId());
|
|
|
|
|
body.put("page_size", size);
|
|
|
|
|
if (query.cursor() != null) {
|
|
|
|
|
body.put("cursor", query.cursor());
|
|
|
|
|
}
|
|
|
|
|
body.put("updated_after", query.updatedAfter().getEpochSecond());
|
|
|
|
|
Instant to = query.updatedBefore() != null ? query.updatedBefore() : Instant.now(clock);
|
|
|
|
|
body.put("updated_before", to.getEpochSecond());
|
|
|
|
|
return json.toJson(body);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Adapter 的四条规矩**:
|
|
|
|
|
|
|
|
|
|
1. `Responses.throwIfNotSuccess` 必须调 —— 否则 500 会被当成功解析,报错信息全错。
|
|
|
|
|
2. 不自己造 `ChannelContext` —— 由门面传入,里面有 requestId 和可测试时钟。
|
|
|
|
|
3. 不用 `Instant.now()`,用 `ctx.clock()` 或注入的 `clock`,否则测试无法固定时间。
|
|
|
|
|
4. 不支持的方法显式抛异常,不返回 `null`、不返回空 `Page`。
|
|
|
|
|
|
|
|
|
|
### 第 7 步:Factory —— 注册入口
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public final class AcmeAdapterFactory implements AdapterFactory {
|
|
|
|
|
|
|
|
|
|
private final TokenStore tokenStore;
|
|
|
|
|
private final LockProvider lockProvider;
|
|
|
|
|
private final Clock clock;
|
|
|
|
|
|
|
|
|
|
public AcmeAdapterFactory(TokenStore tokenStore, LockProvider lockProvider, Clock clock) { ... }
|
|
|
|
|
|
|
|
|
|
@Override public String adapterId() { return AcmeConstants.ADAPTER_ID; }
|
|
|
|
|
@Override public ChannelProvider provider() { return ChannelProvider.DIRECT; }
|
|
|
|
|
@Override public EnumSet<Platform> platforms() { return EnumSet.of(Platform.AMAZON_SC); }
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public PlatformAdapter create(AdapterConfig config) {
|
|
|
|
|
// 生产端点由调用方的 ChannelConnection 提供;config 只用于测试/联调时覆盖目标地址
|
|
|
|
|
return new AcmeAdapter(new OkHttpTransport("common-ecommerce/1.0.0 (acme)"),
|
|
|
|
|
new JacksonJsonCodec(), tokenStore, lockProvider, clock);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
工厂的意义:把「怎么 new」和「业务怎么用」隔开。宿主只注册工厂,不需要知道构造参数。
|
|
|
|
|
**工厂不持有凭据**——凭据随每次调用的 `ChannelConnection` 进来。
|
|
|
|
|
|
|
|
|
|
### 第 8 步:接进门面
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
ChannelSdk sdk = ChannelSdk.builder()
|
|
|
|
|
.accountRepository(accountRepo)
|
|
|
|
|
.idempotencyStore(idempotencyStore) // 要写操作就必须
|
|
|
|
|
.idempotencyOwner(hostName) // 多实例时区分抢占方
|
|
|
|
|
.register(new AcmeAdapterFactory(tokenStore, lockProvider, clock))
|
|
|
|
|
.build();
|
|
|
|
|
|
|
|
|
|
AccountKey key = AccountKey.of(ChannelProvider.DIRECT, Platform.AMAZON_SC, "oms-amz-001");
|
|
|
|
|
Page<SalesOrder> page = sdk.salesOrders(key, conn).pull(query);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**如果你发现要改 `ChannelSdk` 或 `SyncEngine` 才能加进去,说明走歪了。**
|
|
|
|
|
|
|
|
|
|
### 聚合器的额外差异
|
|
|
|
|
|
|
|
|
|
聚合器(领星这类)与直连只差两点:
|
|
|
|
|
|
|
|
|
|
1. 实现 `AggregatorCapable`,覆写 `supports(account, capability)`,按子平台细化:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
@Override
|
|
|
|
|
public boolean supports(ChannelAccount account, Capability capability) {
|
|
|
|
|
if (!capabilities().contains(capability)) {
|
|
|
|
|
return false;
|
|
|
|
|
}
|
|
|
|
|
Platform p = toPlatform(account.platformCode());
|
|
|
|
|
if (p == Platform.EBAY) {
|
|
|
|
|
return capability == Capability.SALES_ORDER; // eBay 只有订单
|
|
|
|
|
}
|
|
|
|
|
return true;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
2. 实现 `listSubChannels(account)` 列出子渠道。
|
|
|
|
|
|
|
|
|
|
**不要为每个子平台建模块** —— 子平台是配置(`platformCode + externalStoreId`),不是代码。
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 六、加完之后怎么测
|
|
|
|
|
|
|
|
|
|
五层,按成本从低到高。**前四层必须全绿才能进真实环境。**
|
|
|
|
|
|
|
|
|
|
### 第 1 层:纯计算单测(毫秒级)
|
|
|
|
|
|
|
|
|
|
测 Mapper 和签名器,性价比最高。
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
@Test
|
|
|
|
|
void mapsAcmeOrder() {
|
|
|
|
|
AcmeOrderDto dto = json.fromJson(fixtureJson, AcmeOrderDto.class);
|
|
|
|
|
SalesOrder o = mapper.toSalesOrder(dto, "oms-amz-001", ZoneId.of("America/Los_Angeles"));
|
|
|
|
|
|
|
|
|
|
assertEquals("ACME-1001", o.channelOrderId());
|
|
|
|
|
assertEquals("59.97 USD", o.totalAmount().toString());
|
|
|
|
|
assertEquals(1793001600L, o.occurredAt().utc().getEpochSecond()); // 秒级时间没转错
|
|
|
|
|
assertEquals(ChannelProvider.DIRECT, o.sourceProvider());
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
签名器用**固定向量**:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
assertEquals(md5Hex("secretapp_keyk1"), AcmeSigner.sign(params, "secret"));
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
时间相关的用 DST 边界:2026-03-08 美国太平洋时区进入夏令时,前后各测一次。
|
|
|
|
|
|
|
|
|
|
### 第 2 层:契约测试(主力)
|
|
|
|
|
|
|
|
|
|
用 `RecordingTransport` + 夹具断言「请求怎么拼、响应怎么解」,**不联网**:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
RecordingTransport transport = new RecordingTransport()
|
|
|
|
|
.tokenResponse("{\"data\":{\"access_token\":\"t-1\",\"expires_in\":7200}}")
|
|
|
|
|
.route("/v1/orders", "POST",
|
|
|
|
|
r -> Responses.ok(JsonFixture.load("fixtures/acme/orderList/success.json")));
|
|
|
|
|
|
|
|
|
|
AcmeAdapter adapter = new AcmeAdapter(transport, json, new InMemoryTokenStore(), locks, fixedClock);
|
|
|
|
|
ChannelContext ctx = ChannelContext.of(account, connection, "req-1", fixedClock);
|
|
|
|
|
|
|
|
|
|
Page<SalesOrder> page = adapter.pull(ctx, query);
|
|
|
|
|
|
|
|
|
|
HttpRequest last = transport.lastRequest();
|
|
|
|
|
assertTrue(last.body().contains("\"updated_after\""));
|
|
|
|
|
assertEquals("ACME-1001", page.items().get(0).channelOrderId());
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
夹具按 `src/test/resources/fixtures/{platform}/{operation}/{case}.json` 存放,每个平台至少「正常 + 异常」两套。
|
|
|
|
|
真实报文跑通后存成新夹具,以后改代码不用再连真实环境。
|
|
|
|
|
|
|
|
|
|
### 第 3 层:真实环境冒烟(手动,不进 CI)
|
|
|
|
|
|
|
|
|
|
做法:凭据用**系统属性**传入(不要写成常量提交),未提供时用 `Assumptions` 跳过:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
mvn -pl lingxing -am test -Dtest=AcmeLiveSmokeTest \
|
|
|
|
|
-Dacme.probe.appKey=xxx -Dacme.probe.appSecret=yyy
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
class AcmeLiveSmokeTest {
|
|
|
|
|
|
|
|
|
|
private static final String APP_KEY = System.getProperty("acme.probe.appKey", "");
|
|
|
|
|
private static final String APP_SECRET = System.getProperty("acme.probe.appSecret", "");
|
|
|
|
|
|
|
|
|
|
private final HttpTransport transport = new OkHttpTransport("common-ecommerce-smoke");
|
|
|
|
|
|
|
|
|
|
@Test
|
|
|
|
|
void tokenCanBeFetched() {
|
|
|
|
|
Assumptions.assumeTrue(!APP_KEY.isEmpty() && !APP_SECRET.isEmpty(), "未提供凭据,跳过");
|
|
|
|
|
AccessToken token = new AcmeTokenClient(transport, json, Clock.systemUTC())
|
|
|
|
|
.fetch(BASE_URL, APP_KEY, APP_SECRET);
|
|
|
|
|
assertNotNull(token.value());
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
联调时把请求和响应打出来(token 打码),签名或字段名不对时靠日志定位。
|
|
|
|
|
**凭证不要提交到仓库**(提交历史里的密钥要轮换),联调完重置。
|
|
|
|
|
|
|
|
|
|
> 领星尤其注意:真实环境**只跑查询类接口**。出库、审核发货这类写接口没有测试环境,误操作不可回滚。
|
|
|
|
|
|
|
|
|
|
### 第 4 层:分页与水位线
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
@Test
|
|
|
|
|
void pagesThroughAllOrdersAndAdvancesWatermarkOnce() {
|
|
|
|
|
transport.route(AcmeConstants.PATH_ORDERS, "POST", r ->
|
|
|
|
|
r.body().contains("\"cursor\":\"c1\"")
|
|
|
|
|
? Responses.ok(page2Json)
|
|
|
|
|
: Responses.ok(page1Json));
|
|
|
|
|
|
|
|
|
|
InMemoryCursorStore cursors = new InMemoryCursorStore();
|
|
|
|
|
InMemorySink sink = new InMemorySink();
|
|
|
|
|
cursors.seed(ChannelProvider.DIRECT, "oms-amz-001",
|
|
|
|
|
SyncSpec.STREAM_SALES_ORDERS, Instant.parse("2026-10-28T00:00:00Z"));
|
|
|
|
|
|
|
|
|
|
SyncSpec spec = SyncSpec.of(ChannelProvider.DIRECT, "oms-amz-001",
|
|
|
|
|
SyncSpec.STREAM_SALES_ORDERS, Duration.ofMinutes(10));
|
|
|
|
|
Instant to = Instant.parse("2026-10-29T00:00:00Z");
|
|
|
|
|
|
|
|
|
|
SyncResult r = new SyncEngine(cursors, sink).syncSalesOrders(spec, to,
|
|
|
|
|
(from, cursor) -> adapter.pull(ctx, SalesOrderQuery.builder()
|
|
|
|
|
.updatedAfter(from).updatedBefore(to).cursor(cursor).build()));
|
|
|
|
|
|
|
|
|
|
assertEquals(2, r.pages());
|
|
|
|
|
assertEquals(5, r.items());
|
|
|
|
|
assertTrue(r.watermarkAdvanced());
|
|
|
|
|
assertEquals(to, cursors.watermark(ChannelProvider.DIRECT, "oms-amz-001",
|
|
|
|
|
SyncSpec.STREAM_SALES_ORDERS));
|
|
|
|
|
assertEquals(5, sink.salesOrders().size());
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
必测的失败路径:
|
|
|
|
|
|
|
|
|
|
- 第二页返回 500 → 抛异常,**水位线不推进**
|
|
|
|
|
- 返回空页 → 立刻结束,不无限循环
|
|
|
|
|
- 没有水位线 → 抛 `IllegalStateException`
|
|
|
|
|
|
|
|
|
|
### 第 5 层:门面 + 能力
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
@Test
|
|
|
|
|
void facadeRejectsUnsupportedCapability() {
|
|
|
|
|
ChannelSdk sdk = ChannelSdk.builder()
|
|
|
|
|
.accountRepository(inMemoryAccounts)
|
|
|
|
|
.register(adapter)
|
|
|
|
|
.build();
|
|
|
|
|
|
|
|
|
|
assertTrue(sdk.capabilities(key).supports(Capability.SALES_ORDER));
|
|
|
|
|
assertFalse(sdk.capabilities(key).supports(Capability.REFUND));
|
|
|
|
|
assertThrows(ChannelException.UnsupportedCapabilityException.class,
|
|
|
|
|
() -> sdk.products(key).pull(ProductQuery.builder().build()));
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
聚合器还要额外测:同一适配器,Walmart 账户和 eBay 账户的 `supports` 结果不同。
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 七、验收清单
|
|
|
|
|
|
|
|
|
|
加完一个供应商,逐条打勾:
|
|
|
|
|
|
|
|
|
|
| # | 检查项 | 怎么验 |
|
|
|
|
|
|:--:|:---|:---|
|
|
|
|
|
| 1 | 声明能力 = 实际实现 | 每个能力一条断言 |
|
|
|
|
|
| 2 | 不支持的能力抛异常 | 门面断言 `UnsupportedCapabilityException` |
|
|
|
|
|
| 3 | canonicalKey 只依赖平台单号 | 拉两次同一条,key 相同 |
|
|
|
|
|
| 4 | 分页能停 | 最后一页 `nextCursor == null` |
|
|
|
|
|
| 5 | 错误映射正确 | 401 / 429 / 500 / 400 各一个夹具 |
|
|
|
|
|
| 6 | token 只刷一次 | `tokenStore.saveCount() == 1` |
|
|
|
|
|
| 7 | 超长时间窗会截断 | 断言 body 里的起止时间 |
|
|
|
|
|
| 8 | 写操作只执行一次 | `adapter.writeCallCount() == 1` |
|
|
|
|
|
| 9 | 水位线失败不推进 | 第二页抛异常后断言水位线不变 |
|
|
|
|
|
| 10 | channel / shared 零改动 | `git diff channel/ shared/` 应只有 `shared/model/Platform` 枚举 |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 八、已知缺口与坑
|
|
|
|
|
|
|
|
|
|
### 当前实现状态(2026-11-06)
|
|
|
|
|
|
|
|
|
|
| 模块 | 状态 |
|
|
|
|
|
|:---|:---|
|
|
|
|
|
| shared | 枚举、异常、SPI 契约、幂等守卫、审计、水位线通用类型全部可用 |
|
|
|
|
|
| channel | 领域模型、能力接口、门面、SyncEngine、账户/落库 SPI 全部可用 |
|
|
|
|
|
| http | OkHttp 传输、Jackson 编解码、签名接口、TokenManager 模板可用 |
|
|
|
|
|
| testkit | InMemory SPI、FakeDirectAdapter、MutableClock 可用 |
|
|
|
|
|
| lingxing | 16 个子平台:订单 / 店铺全量;商品 8 个平台;结算、售后目前只有亚马逊 SC;出库单 / 面单 / 审核发货 / 订单编辑为 ERP 级、全平台共用 |
|
|
|
|
|
| 其它平台 | 未开始 |
|
|
|
|
|
|
|
|
|
|
### 编码坑(按踩到概率排序)
|
|
|
|
|
|
|
|
|
|
1. **字段名对不上**:DTO 的 `@JsonProperty` 和真实报文不一致 → 解析出 null。用真实报文做夹具最能防。
|
|
|
|
|
2. **`capabilities()` 写多了**:声明 `PRODUCT` 但没实现 `ProductCapable` → 门面 `ClassCastException`。
|
|
|
|
|
3. **`get` 用裸 `String`**:同时实现订单 + 商品就编译不过。用 `SalesOrderRef` / `ProductRef`。
|
|
|
|
|
4. **忘记 `Responses.throwIfNotSuccess`**:500 被当成功解析,报错变成「字段为 null」,排查方向全错。
|
|
|
|
|
5. **用了 `Instant.now()` 而不是 `clock`**:测试无法固定时间,水位线断言随机失败。
|
|
|
|
|
6. **canonicalKey 用了会变的字段**:同一订单每次同步产生新行。
|
|
|
|
|
7. **`Responses` import 错**:`http.Responses`(状态码→异常)和 `testkit.Responses`(造响应)是两个类。
|
|
|
|
|
8. **`UnsupportedCapabilityException` 单独 import**:它是 `ChannelException` 的静态内部类,必须写全名。
|
|
|
|
|
|
|
|
|
|
### 设计层面的已知缺口
|
|
|
|
|
|
|
|
|
|
| 缺口 | 影响 | 建议 |
|
|
|
|
|
|:---|:---|:---|
|
|
|
|
|
| `SalesOrder` 没有 `platform` 字段 | `Sink` 算 canonicalKey 时要额外查平台 | 给模型加 `platform`,或让 `Sink` 接收上下文 |
|
|
|
|
|
| 适配器不重试 | 401/429/5xx 只分类不重试 | 宿主在调用层包退避,或补通用重试器 |
|
|
|
|
|
| `RawPayloadStore` 未实现 | 原始报文无留痕 | 新增 SPI + 脱敏 |
|
|
|
|
|
| `RefundLedger` 未实现 | 无超退校验 | 与 `IdempotencyGuard` 配合 |
|
|
|
|
|
| `DuplicateOrderGuard` 未实现 | 跨 provider 重复订单无告警 | 新增 SPI |
|
|
|
|
|
| 领星时间窗超 31 天被静默截断 | 水位线落后太多会漏中间段 | 调用方分段补拉 |
|
|
|
|
|
| 领星单订单详情未实现 | 除亚马逊 SC / VC 外的子平台 `get()` 直接抛异常 | 用 `pull` + 时间窗捞 |
|
|
|
|
|
| 领星限流器用 `Thread.sleep` | 多店并发时按实例数放大 | 按账户拆适配器实例,或换通用限流器 |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 九、上手顺序
|
|
|
|
|
|
|
|
|
|
1. **读三个文件**:`PlatformAdapter`、`SalesOrderCapable`、`ChannelSdk`。不到 150 行,看懂这三个就懂一半。
|
|
|
|
|
2. **跑一遍现有测试**:`mvn -pl lingxing -am test`,对照看 `LingxingSdkListingCallTest`(门面 + 契约)与 `LingxingAfterSaleListSourceTest`(Source + 夹具)—— 它们就是「加一个供应商」的完整范例。
|
|
|
|
|
3. **抄领星的结构**建新模块:`Constants → Dto → Mapper → Adapter → Factory → Test`。
|
|
|
|
|
4. **先用夹具跑通,再连真实环境。** 不要反过来。
|
|
|
|
|
|
|
|
|
|
### 常用命令
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
mvn clean test # 全部
|
|
|
|
|
mvn -pl lingxing -am test # 单模块(含依赖)
|
|
|
|
|
mvn -pl lingxing -am test -Dtest=LingxingSdkListingCallTest # 单个测试类
|
|
|
|
|
mvn -pl lingxing -am test -Dtest=LingxingLiveSmokeTest # 真实环境冒烟(需环境变量)
|
|
|
|
|
```
|