You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
chenchuchuan 802613ffff test(lingxing): 新增 listing 联调探针,凭据改为系统属性传入 2 weeks ago
core docs(core): 为公开模型、门面与 SPI 补齐字段与方法注释 2 weeks ago
http test(http): TokenManager 等锁超时可注入,测试从 5s 降到 50ms 3 weeks ago
lingxing test(lingxing): 新增 listing 联调探针,凭据改为系统属性传入 2 weeks ago
testkit test: 每个平台补 listing / 售后契约测试,新增 SDK 门面调用测试 2 weeks ago
.gitattributes feat(core): 领域模型、能力接口、SPI 与同步引擎骨架 3 weeks ago
.gitignore feat(lingxing): 接入多平台店铺与订单查询并补齐长尾平台 2 weeks ago
GUIDE.md refactor(lingxing): 搭子平台分派骨架,删除全部假数据 3 weeks ago
README.md refactor(lingxing): 搭子平台分派骨架,删除全部假数据 3 weeks ago
pom.xml build(lingxing): DTO 使用 Lombok 生成访问器 3 weeks ago
操作手册.md feat(sdk): listSubChannels 收 ChannelContext,新增 subChannels 门面与操作手册 3 weeks ago

README.md

common-ecommerce

多渠道电商履约对接 SDK。把亚马逊、沃尔玛、TikTok、Temu、领星聚合等渠道的商品、订单、履约、标发、面单、账单、售后统一成一套 API。

定位

纯 SDK 库,嵌入宿主(OMS)进程运行。不访问数据库、不访问 Redis、不访问 MQ、不私起线程或定时器。所有外部副作用通过 SPI 注入,由宿主实现。

① 统一入口    ChannelSdk / 各能力门面
② 能力接口    ProductCapable / SalesOrderCapable / FulfillmentCapable / ...
③ 平台适配    amazon-sc / walmart-sc / tiktok / temu / lingxing / ...
④ 基础设施    HttpTransport / Signer / TokenManager / RateLimiter / SyncEngine / Idempotency
⑤ 宿主 SPI    AccountRepository / TokenStore / SyncCursorStore / Sink / Clock / LockProvider / ...

模块

模块 职责
common-ecommerce-core 领域模型、能力接口、门面、管道、SPI。零第三方运行时依赖
common-ecommerce-http HTTP 传输、签名、令牌管理、JSON 编解码
common-ecommerce-testkit InMemory SPI 与测试替身
common-ecommerce-lingxing 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器

Lombok 使用范围:仅 lingxing 模块的 dto/*,scope=provided,不进宿主运行时。 core 的领域模型是不可变 + Builder,不使用 Lombok——省下的行数有限, 而 core 要尽量少依赖编译期工具。

构建

mvn clean test

要求 JDK 1.8、Maven 3.6+。

第一次接触这个库,先读 GUIDE.md:分层心智模型、三条流水线逐段讲、 接入一个新平台的 8 个步骤与 5 层测试。本文档是速查,GUIDE 是教程。


一、包职责

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)

包名统一前缀 common.ecommerce.,下表省略前缀。

model —— 领域模型

所有对象不可变,用 Builder 构造,无 setter。Java 8 不引入 record/sealed。

子包分工:

子包 内容
model(本包) 枚举:Platform / ChannelProvider / Capability / FulfillmentMode
model.account AccountKey / ChannelAccount
model.order SalesOrder / OrderLine / SalesOrderQuery / SalesOrderRef
model.product ProductListing / ProductQuery / ProductRef / ProductSyncStrategy
model.support Money / PlatformTime / Page / CanonicalKeys
类 包袱 职责
Platform 枚举 业务平台。不含 provider,直连与聚合器映射到同一值
ChannelProvider 枚举 接入通道:DIRECT / LINGXING / TEAPPLIX / CUSTOM
Capability 枚举 能力枚举,适配器声明、门面校验
FulfillmentMode 枚举 A/C/D 三种履约模式(B 平台仓只读,不在枚举内)
ProductSyncStrategy 枚举 增量 / 全量 diff / 报告(放在 model.product)
AccountKey 标识 provider + platform + omsStoreId,所有调用的隔离维度
ChannelAccount 配置 渠道账户配置。只存 credentialRef,不存密钥
CanonicalKeys 工具 三级标识与指纹计算,见下方「标识体系」
PlatformTime 值对象 三轴时间:UTC 真值 + 市场当地 + 北京时间
Money 值对象 BigDecimal + Currency,跨币种运算直接拒绝
SalesOrder / OrderLine 实体 3P 销售订单
ProductListing 实体 商品 / Listing
SalesOrderQuery / ProductQuery 查询 查询条件(时间窗 + 分页游标)
SalesOrderRef / ProductRef 引用 详情入参。不能用裸 String,否则订单+商品接口签名冲突
Page<T> 载体 分页载体,nextCursor == null 表示结束

capability —— 能力接口

适配器实现哪些接口就声明哪些能力;未实现的方法抛 UnsupportedCapabilityException,不静默返回空。

接口 关键方法
PlatformAdapter 基座:adapterId() / provider() / platforms() / capabilities() / supports(account, cap)
AggregatorCapable 聚合器扩展:listSubChannels(account),按子平台细化能力
SalesOrderCapable pull(ctx, query) / get(ctx, SalesOrderRef)
ProductCapable syncStrategy() / pull(ctx, query) / get(ctx, ProductRef)
CapabilityReport 能力报告:supports() / supported() / unsupported()
SalesOrders / Products 门面持有的视图,调用前做能力检查

error —— 异常体系

全部继承 ChannelException,带 platform / provider / omsStoreId / operation / requestId / platformCode / retryable / rawResponse。

异常 触发 可否重试
AuthException 401/403、token 失效 刷新后 1 次
RateLimitException 429,携带 retryAfterMillis() 是
TransientException 5xx / 网络 / 超时 是
ValidationException 4xx 参数或映射错误 否
PlatformBusinessException 平台业务错误码 视码
ChannelException.UnsupportedCapabilityException 能力缺失 否
IdempotencyConflictException 重复写 否,返回已完成结果
CrossProviderConflictException 已由另一 provider 完成 否,人工确认

注意 UnsupportedCapabilityException 是 ChannelException 的静态内部类,用 ChannelException.UnsupportedCapabilityException 引用。

详情参数是包装类型:SalesOrderCapable.get 收 SalesOrderRef、ProductCapable.get 收 ProductRef,不是裸 String。同一适配器同时实现两种能力时,裸 String 会擦除成相同签名而无法同时实现。

同名类 Responses 有两个:http.Responses(状态码 → 异常)与 testkit.Responses(快捷构造响应)。测试里注意 import 哪个。

sdk —— 门面与上下文

类 职责
ChannelContext 单次调用上下文:account + connection + requestId + clock。由 SDK 创建,适配器不得自造
AdapterFactory 适配器工厂:adapterId() / provider() / platforms() / create(AdapterConfig)
ProviderResolver 按 AccountKey 解析适配器,不自动选路
ChannelSdk 统一门面:capabilities() / salesOrders(key, conn) / products(key, conn) / writes();build() 校验必需项
ChannelConnection 一次调用的连接信息(端点 + 凭据)。由调用方每次传入,SDK 不保存

idempotency —— 写操作幂等

类 职责
WriteScope 一次写操作的维度:provider + platform + omsStoreId + externalStoreId + action + businessRef
WriteResult 执行结果:EXECUTED / ALREADY_COMPLETED(回放,不算失败)
IdempotencyGuard 双锁守卫:业务键(跨 provider)+ provider 请求键(单 provider 内重试)

sync —— 增量同步

类 职责
SyncSpec 同步维度:provider + accountKey + stream + overlap
SyncResult 单次结果:页数、条目数、水位线是否推进
SyncEngine 分页循环 + 落库 + 水位线推进

spi —— 宿主扩展点

SDK 只定义,宿主实现。SDK 内部不碰 JDBC / Redis / MQ。

SPI 作用 典型实现
ChannelAccountRepository 读渠道账户 MySQL
SecretProvider 已不再使用:凭据改由调用方经 ChannelConnection 传入 —
ChannelSecret 凭据载体(appKey/appSecret/clientId/… + endpointBaseUrl),fingerprint() 供日志
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

http —— 出入网层

类 职责
HttpTransport 传输接口,默认 OkHttpTransport(连接 5s / 读 30s)
HttpRequest / HttpResponse 统一请求响应,保留原始 header/body 供留痕
JsonCodec JSON 抽象,JacksonJsonCodec 提供点路径取值 nodeAt("data.list")
Signer 签名接口,各平台实现
TokenManager 令牌模板:账户隔离、提前续期、LockProvider 防击穿、日志只打指纹
Responses 状态码 → 异常映射(throwIfNotSuccess)

testkit —— 测试口子

类 职责
FakeDirectAdapter 直连假适配器:游标分页、能力并集即账户能力、记录写调用
InMemoryAccounts 内存版账户仓库 + 密钥提供者
InMemoryTokenStore / InMemoryCursorStore / InMemorySink / InMemoryLockProvider / InMemoryIdempotencyStore 全套内存 SPI
MutableClock 可推进时钟,验证 TTL / 续期 / 水位线边界
TestData 同步测试的快捷构造

lingxing —— 领星适配器

类 职责
LingxingAdapter SalesOrderCapable + AggregatorCapable,订单列表拉取
LingxingConstants 端点、限制(31 天 / length≤500)、platform_code → Platform 映射
LingxingSigner 公共参数 ASCII 升序 + appSecret 前后包裹 + MD5
LingxingTokenClient 换取 access_token
LingxingOrderMapper 领星报文 → SalesOrder
dto/* 领星原始报文结构(Jackson 映射)
LingxingAdapterFactory 工厂注册

二、标识体系(务必先读)

provider 不得进入业务主键,否则直连与聚合器切换会把同一订单变成两条。

标识 组成 用途
omsStoreId OMS 渠道店铺 ID 业务归属
canonicalKey platform + omsStoreId + 平台实体 ID upsert、去重、状态流转
sourceKey provider + platform + externalStoreId + 平台实体 ID 原始报文、水位线、审计
CanonicalKeys.salesOrder(Platform.WALMART_SC, "oms-wm-001", "PO-123");
// → "WALMART_SC:oms-wm-001:PO-123"   直连与领星算出来完全一样

写操作要两把锁:

// 业务幂等键:不带 provider,直连/领星共用,同一业务动作只能成功一次
CanonicalKeys.businessIdempotencyKey(Platform.WALMART_SC, "oms-wm-001", "PO-1:pkg-1", "shipping");
// provider 请求键:带 provider,单 provider 内重试去重
CanonicalKeys.providerRequestKey(ChannelProvider.DIRECT, Platform.WALMART_SC, "wm-seller-01", "shipping", "PO-1:pkg-1");

两把锁不要手写串联,用 IdempotencyGuard 执行(见 3.5)。


三、调用方式

状态说明

ChannelSdk 门面已可用:capabilities() / salesOrders(key, conn) / products(key, conn) / writes() 已挂接, build() 做必需项校验(缺 accountRepository、缺适配器都会抛异常)。 目前仅接入了订单与商品两种能力,其余能力随适配器逐个补齐。

两条调用路径都可以用:门面(3.3)适合业务层;适配器 + SyncEngine(3.1 / 3.2) 适合需要自己控制时间窗、翻页与落库的场景。

3.1 单次查询(不推进水位线)

适合人工排查、补偿。宿主自己决定拉哪个时间窗。

// 1) 宿主实现 SPI
ChannelAccountRepository accountRepo = ...;   // MySQL
SecretProvider secretProvider        = ...;   // KMS
TokenStore tokenStore                = ...;   // 加密存储
LockProvider lockProvider            = ...;   // Redisson / DB

// 2) 创建适配器(也可经 LingxingAdapterFactory.create)
LingxingAdapter adapter = new LingxingAdapter(
        LingxingConstants.DEFAULT_BASE_URL,
        new OkHttpTransport("common-ecommerce/1.0.0 (lingxing)"),
        new JacksonJsonCodec(),
        secretProvider, tokenStore, lockProvider,
        Clock.systemUTC());

// 3) 取账户 → 组装调用上下文
ChannelAccount account = accountRepo
        .findByKey("LINGXING", "WALMART_SC", "oms-wm-001")
        .orElseThrow(() -> new IllegalStateException("account not configured"));

ChannelContext ctx = ChannelContext.of(account, UUID.randomUUID().toString(), Clock.systemUTC());

// 4) 调用
Page<SalesOrder> page = adapter.pull(ctx, SalesOrderQuery.builder()
        .updatedAfter(Instant.parse("2026-10-25T00:00:00Z"))   // 必填,UTC
        .updatedBefore(Instant.parse("2026-10-26T00:00:00Z"))  // 可选,缺省取 now
        .pageSize(100)                                          // 平台上限内自动截断
        .build());

for (SalesOrder order : page.items()) {
    // order.channelOrderId() 是平台单号,可直接算 canonicalKey
}

翻页:拿 page.nextCursor() 填回 query.toBuilder().cursor(...)(SalesOrderQuery 提供 toBuilder()),nextCursor == null 表示结束。

3.2 增量同步(推进水位线)

适配器负责「怎么拉一页」,SyncEngine 负责「翻页 + 落库 + 水位线」。整批成功才推进,失败不推进。

// 宿主实现这两个 SPI(测试时用 InMemoryCursorStore / InMemorySink)
SyncCursorStore cursorStore = ...;
Sink sink                   = ...;

SyncSpec spec = SyncSpec.of(
        ChannelProvider.LINGXING,
        "oms-wm-001",
        SyncSpec.STREAM_SALES_ORDERS,
        Duration.ofMinutes(10));   // 重叠窗口,防边界丢单

Instant to = Instant.now();

SyncResult result = new SyncEngine(cursorStore, sink).syncSalesOrders(spec, to,
        (from, cursor) -> adapter.pull(ctx, SalesOrderQuery.builder()
                .updatedAfter(from)
                .updatedBefore(to)
                .cursor(cursor)
                .build()));

result.pages();              // 拉了几页
result.items();              // 落了几个实体
result.watermarkAdvanced();  // true == 水位线已推进到 to

要点:

  • 起点计算:from = lastWatermark - overlap,由 SyncSpec.from(watermark) 完成。
  • 必须先有水位线:cursorStore.get(...) 返回 null 时 SyncEngine 抛 IllegalStateException,提醒先做全量建底(首次全量用创建时间回溯,成功后调 advance)。
  • 水位线维度:provider + accountKey + stream,直连与领星各存各的,不能复用。
  • 调度归宿主:SDK 不持有线程和定时器,由 OMS 调度器触发 syncSalesOrders。

3.3 门面调用

ChannelSdk sdk = ChannelSdk.builder()
        .accountRepository(accountRepo)                              // 必需
        .clock(Clock.systemUTC())                                   // 可选,默认 UTC
        .idempotencyStore(idempotencyStore)                         // 写操作用;不注入则 writes() 失败
        .register(new LingxingAdapterFactory(secretProvider, tokenStore, lockProvider, Clock.systemUTC()))
        .build();                                                    // 缺必需项立刻抛异常

AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001");

// 能力矩阵只读,不触发真实 API
CapabilityReport caps = sdk.capabilities(key);
if (!caps.supports(Capability.SALES_ORDER)) { ... }

// 路由完全由调用方决定,SDK 不推荐、不自动兜底
Page<SalesOrder> page = sdk.salesOrders(key, connection).pull(query);

build() 会在以下情况立即失败,不返回不可用的空对象:

缺失 异常信息
accountRepository ChannelSdk requires an accountRepository
没有任何适配器 / 工厂 ChannelSdk requires at least one adapter or adapter factory
同一 provider + platform 注册两次 duplicate adapter for ...

调用时:

  • 账户未配置 → IllegalStateException: channel account not configured
  • provider 无对应适配器 → IllegalStateException: no adapter registered for ...
  • 适配器不支持该能力 → ChannelException.UnsupportedCapabilityException

测试中可绕过工厂直接注册适配器实例:.register(adapter)。

3.4 能力检查

聚合器必须按子平台判断,不能只用 capabilities():

// 领星上 eBay 的账户:只有订单,没有账单/售后
AccountKey ebay = AccountKey.of(ChannelProvider.LINGXING, Platform.EBAY, "oms-ebay-001");
adapter.supports(ebayAccount, Capability.BILLING);  // false

缺失能力时抛 ChannelException.UnsupportedCapabilityException,由调用方走 3PL / 人工兜底,SDK 不会自动换 provider。

3.5 写操作幂等(双锁)

所有写操作(标发、发货确认、退款、退货审批……)都经 IdempotencyGuard 执行。 业务键不带 provider,与 provider 请求键一起抢占;重复调用返回已完成结果,不算失败。

WriteScope scope = WriteScope.of(
        ChannelProvider.LINGXING,          // 本次用哪条接入通道
        Platform.WALMART_SC,
        "oms-wm-001",                      // 业务店铺维度
        "1108413237731",                   // 平台/领星店铺 ID,用于 provider 请求键
        "markShipped",
        "PO-1:pkg-1");                     // 业务自然键;退款用 returnId:itemId:refundRequestId,禁止用金额

WriteResult<ShipResult> result = sdk.writes().execute(scope,
        () -> adapter.markShipped(ctx, command),   // 真正调用平台
        ShipResult::shipmentId);                   // 结果引用,回放时返回

result.outcome();    // EXECUTED / ALREADY_COMPLETED

行为:

情形 结果
首次调用 抢两把锁 → 执行 → 两把锁都记 SUCCEEDED
重复调用(同 provider) ALREADY_COMPLETED,不调用平台
重复调用(另一 provider) CrossProviderConflictException,人工确认
并发调用 IdempotencyConflictException,拒绝重复执行
抛 retryable=true 的异常 两把锁记 FAILED_RETRYABLE,可重跑
抛 retryable=false 的异常 记 FAILED_FINAL,需人工介入
平台已写、业务键未记成功(崩溃) provider 键命中,回放结果,不重复写

IdempotencyStore.claim 必须原子(唯一索引 / Redis SETNX),否则并发语义不成立。 IdempotencyGuard 不做退避重试,重试节奏由宿主调度决定。


四、扩展方式

4.1 新增一个直连平台

以新增 amazon-sc 为例,不改 core、不改门面、不改宿主。

第 1 步:建模块,pom.xml 只依赖 core 与 http。

第 2 步:实现能力接口。只实现真正支持的,其余不实现:

public final class AmazonScAdapter implements SalesOrderCapable, FulfillmentCapable, LabelCapable {

    @Override public String adapterId()      { return "amazon-sc"; }
    @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, Capability.PRODUCT,
                          Capability.MARK_SHIPPED, Capability.LABEL, Capability.BILLING);
    }

    @Override public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) { ... }
    @Override public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { ... }
}

第 3 步:写签名器,实现 Signer(LWA 只需 Authorization: Bearer,签名器可为空实现)。

第 4 步:写报文映射,平台 JSON → 统一模型。平台字段名只出现在 DTO 和 Mapper 里。

第 5 步:实现 AdapterFactory,与直连/聚合器同一套注册机制:

public final class AmazonScAdapterFactory implements AdapterFactory {
    @Override public String adapterId()      { return "amazon-sc"; }
    @Override public ChannelProvider provider() { return ChannelProvider.DIRECT; }
    @Override public EnumSet<Platform> platforms() { return EnumSet.of(Platform.AMAZON_SC); }
    @Override public PlatformAdapter create(AdapterConfig config) { return new AmazonScAdapter(...); }
}

第 6 步:加契约测试(见第五节)。

第 7 步:ChannelSdk.builder().register(...),完成。

4.2 新增一个聚合器

与直连的唯一区别是实现 AggregatorCapable,按账户的子平台细化能力:

public final class MyAggregatorAdapter implements SalesOrderCapable, AggregatorCapable {

    @Override
    public boolean supports(ChannelAccount account, Capability capability) {
        if (!capabilities().contains(capability)) return false;
        // 按 account.platformCode() 判断,不能一刀切
        return isSupportedBySubPlatform(account.platformCode(), capability);
    }

    @Override
    public List<SubChannel> listSubChannels(ChannelAccount account) { ... }
}

不要为每个子平台新建模块——子平台是配置(platformCode + externalStoreId),不是代码。

4.3 新增一个能力(如退款)

  1. Capability 加枚举值;
  2. capability/ 下加接口(可选动作给 default 方法抛 UnsupportedCapabilityException,适配器只覆写支持的);
  3. 适配器声明能力并实现;
  4. 领域模型加实体(Refund / ReturnOrder …);
  5. Sink 加对应 upsert,testkit 加 InMemory 实现。

不会改动的:PlatformAdapter、ChannelContext、AccountKey、CanonicalKeys、SyncEngine、IdempotencyGuard。

4.4 新增一个 SPI

宿主可能需要新的副作用出口(如 RefundLedger、RawPayloadStore)。

  1. spi/ 下定义纯接口,不引入 JDBC/Redis 类型;
  2. 提供 InMemory 实现进 testkit,保证适配器可脱离宿主测试;
  3. 通过 ChannelSdk.Builder 或适配器构造器注入。

判断标准:是否需要持久化或跨进程状态?是 → 新 SPI;否 → 放管道层(http)。

4.5 扩展红线

不做 原因
core 引 Spring / JDBC / Redis / MQ SDK 要能脱离宿主单测
把平台端点、字段名做成配置表 协议是代码,配置化会让线上线下跑不同协议
密钥写入 ChannelAccount 只能存 credentialRef,密钥走 SecretProvider
provider 进 canonicalKey 直连/聚合器切换会产生重复实体
在适配器里 new Thread / 定时器 调度归宿主,SDK 不许私起线程
能力声明与实际实现不一致 验收项,缺失能力必须显式抛异常
写操作盲目重试 必须有幂等键;退款/标发超时先回查

五、测试

分层

层级 测什么 依赖
单元测试 签名、canonicalKey、时间三轴/DST、错误映射 纯计算,毫秒级
契约测试(核心) 请求是否构造对、响应是否解析对 录制夹具
集成测试 重试、限流、401 刷新 真实环境冒烟(LingxingLiveSmokeTest)
沙箱联调 端到端 手动,不进 CI

适配器测试不依赖网络、数据库、Spring。

夹具约定

src/test/resources/fixtures/{platform}/{operation}/{case}.json

例:lingxing/src/test/resources/fixtures/lingxing/orderList/success.json

每个平台至少准备「正常 + 异常」两套。

写法

// 联调直接用真实接口,见 LingxingLiveSmokeTest

LingxingAdapter adapter = new LingxingAdapter(LingxingConstants.DEFAULT_BASE_URL, transport,
        new JacksonJsonCodec(), accounts, tokenStore, locks,
        Clock.fixed(Instant.parse("2026-10-29T00:00:00Z"), ZoneOffset.UTC));

ChannelContext ctx = ChannelContext.of(account, "req-1", clock);
Page<SalesOrder> page = adapter.pull(ctx, SalesOrderQuery.builder()
        .updatedAfter(Instant.parse("2026-10-25T00:00:00Z"))
        .updatedBefore(Instant.parse("2026-10-26T00:00:00Z"))
        .build());

// 断言请求构造
HttpRequest last = transport.lastRequest();
assertTrue(last.url().contains("sign="));
assertTrue(last.body().contains("\"platform_code\":10008"));

// 断言解析结果
assertEquals("PO-123456789", page.items().get(0).channelOrderId());

完整示例见 lingxing/src/test/java/.../LingxingAdapterTest.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());

执行

mvn test                     # 全部
mvn -pl lingxing test        # 单模块
mvn -pl lingxing -Dtest=LingxingAdapterTest test

六、待办与待核对

待实现

项 说明
RawPayloadStore 原始报文留痕(脱敏)
RefundLedger 已退款金额汇总与超退校验,与 IdempotencyGuard 配合
DuplicateOrderGuard 跨 provider 重复订单告警
SalesOrder 补 platform 字段 Sink 落库时无法得知订单来自哪个平台,只能靠 omsStoreId 反查
适配器层重试 401/429/5xx 目前只分类不重试,退避由宿主包一层
写操作门面视图 只有 sdk.writes(),写之前需手动 resolve + 转型 + 查能力,缺 sdk.fulfillment(key) 这类视图
其余由文档 Spec 0 定义的能力 履约、面单、账单、售后、Webhook、异步报表

待核对(需官方文档 + 真实沙箱,联调时集中修改)

位置 内容
LingxingOrderDto 字段名:platform_order_no / platform_order_names / purchase_time / item_list
LingxingSigner 签名大小写、是否排除空值参数
LingxingTokenClient 令牌接口请求体字段名与响应嵌套层级
LingxingAdapter.get() 单订单详情接口是否存在

设计文档

  • GUIDE.md:开发指南 —— 心智模型、基接口逐个讲、接入新平台 8 步、5 层测试
  • OMS 侧 cross-border-fulfillment-sdk-design.md(Spec 0 总体设计)