# common-ecommerce 操作手册 > 面向接入本 SDK 的宿主开发者。本文只讲**怎么调、参数怎么传**。 > 设计原理见 [`GUIDE.md`](GUIDE.md),架构图与包结构见 [`README.md`](README.md)。 --- ## 目录 1. [依赖与坐标](#一依赖与坐标) 2. [三个第一步](#二三个第一步) 3. [连接信息:域名与密钥](#三连接信息域名与密钥) 4. [拉取订单](#四拉取订单) 5. [拉取商品 / Listing](#五拉取商品--listing) 6. [拉取店铺列表(聚合器)](#六拉取店铺列表聚合器) 7. [增量同步与水位线](#七增量同步与水位线) 8. [写操作与幂等](#八写操作与幂等) 9. [查询能力矩阵](#九查询能力矩阵) 10. [异常与重试](#十异常与重试) 11. [宿主必须实现的 SPI](#十一宿主必须实现的-spi) 12. [常见错误对照表](#十二常见错误对照表) --- ## 一、依赖与坐标 ```xml ecommerce channel-sdk-core 1.0.0-SNAPSHOT ecommerce common-ecommerce-lingxing 1.0.0-SNAPSHOT ecommerce sdk-testkit 1.0.0-SNAPSHOT test ``` 要求 JDK 1.8。 --- ## 二、三个第一步 调用任何接口之前,宿主必须先提供三样东西。 ### 2.1 账户仓库 `ChannelAccountRepository` SDK 靠它把 `AccountKey` 解析成账户配置。 ```java public interface ChannelAccountRepository { Optional findByKey(String provider, String platform, String omsStoreId); List findByOmsStoreId(String omsStoreId); } ``` **注意**:`provider` / `platform` 传的是**枚举 name**,如 `"LINGXING"` / `"WALMART_SC"`。 ### 2.2 账户配置 `ChannelAccount` ```java ChannelAccount account = ChannelAccount.builder() // 三件套:通道 + 平台 + 你自己的店铺 ID .key(AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001")) // 平台侧店铺 ID(领星是 store_id / 亚马逊是 sid) .externalStoreId("1108413237731") // 领星 platform_code;直连账户不填 .platformCode(10008) // 密钥引用(宿主侧密钥条目的标识);真实密钥经 ChannelConnection 传入,见第三节 .credentialRef("kms://oms/lingxing/store-001") // 市场当地时区,必须是合法 IANA 时区 .marketplaceZone("America/Los_Angeles") // 店铺币种 .currency("USD") .build(); ``` | 字段 | 必填 | 说明 | |:---|:---:|:---| | `key` | ✅ | `provider + platform + omsStoreId`,SDK 的隔离维度 | | `externalStoreId` | ✅ | 平台店铺 ID。领星传 `store_id`;亚马逊 SC 传 `sid` | | `platformCode` | 领星必填 | 见 [platform_code 对照](#领星-platform_code-对照) | | `credentialRef` | ✅ | 密钥引用标识,不是密钥本身;真实密钥经 `ChannelConnection` 传入 | | `marketplaceZone` | ✅ | 必须是 `ZoneId.of(...)` 能解析的值 | | `currency` | ✅ | ISO 4217 | ### 2.3 构建门面 ```java ChannelSdk sdk = ChannelSdk.builder() .accountRepository(accountRepo) // 必需 .clock(Clock.systemUTC()) // 可选,默认 UTC .idempotencyStore(idempotencyStore) // 写操作必需 .idempotencyOwner("oms-node-1") // 多实例时区分 .register(new LingxingAdapterFactory(tokenStore, lockProvider, Clock.systemUTC())) .build(); ``` **`build()` 立刻失败的情况**: | 缺失 | 异常 | |:---|:---| | `accountRepository` | `ChannelSdk requires an accountRepository` | | 一个适配器都没注册 | `ChannelSdk requires at least one adapter or adapter factory` | | 同一 `provider + platform` 注册两次 | `duplicate adapter for ...` | > **门面是单例**。适配器里缓存了限流器状态,每次调用都 `new` 会导致限流失效。 --- ## 三、连接信息:域名与密钥 **SDK 不保存端点、不读配置、不读环境变量。** 每次调用都要由调用方传入。 ```java ChannelConnection conn = ChannelConnection.of( "https://openapi.lingxing.com", // 端点 ChannelSecret.builder() .appKey("你的 appId") // 领星 AppID .appSecret("你的 appSecret") // 领星 AppSecret .build()); ``` `credentialRef` 只是账户上的标识,SDK **不会**拿它去取密钥;真实密钥就在上面的 `ChannelSecret` 里。 ### 各平台需要的凭据字段 | 平台 | 需要的字段 | |:---|:---| | 领星 | `appKey`(= AppID)、`appSecret` | | 亚马逊直连 | `clientId`、`clientSecret`、`refreshToken` | | 沃尔玛 | `clientId`、`clientSecret` | **安全要求**: - `ChannelSecret` 的 `toString()` 不打印密钥;日志里只用 `fingerprint()` - 不要把 `ChannelSecret` 序列化进日志或异常信息 - 生产环境从 KMS / Vault 取,不要硬编码 --- ## 四、拉取订单 ### 4.1 单次查询 ```java AccountKey key = AccountKey.of(ChannelProvider.LINGXING, Platform.WALMART_SC, "oms-wm-001"); Page 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")) // 可选,缺省取现在 .pageSize(100) // 平台上限内自动截断 .build()); for (SalesOrder order : page.items()) { order.channelOrderId(); // 平台单号,参与 canonicalKey order.status(); // 平台原始状态(见下方说明) order.totalAmount(); // Money:BigDecimal + Currency order.occurredAt().utc(); // 下单时间,UTC 真值 order.lines(); // 明细行 } ``` ### 4.2 翻页 ```java while (page.nextCursor() != null) { page = sdk.salesOrders(key, conn).pull( query.toBuilder().cursor(page.nextCursor()).build()); } ``` `nextCursor == null` 表示结束。**游标是不透明字符串**,不要解析它的内容。 ### 4.3 入参说明 `SalesOrderQuery` | 参数 | 类型 | 必填 | 说明 | |:---|:---|:---:|:---| | `updatedAfter` | `Instant` | ✅ | 时间窗起点,UTC。领星按「更新时间」过滤 | | `updatedBefore` | `Instant` | | 时间窗终点,UTC;缺省取调用时刻 | | `pageSize` | `int` | | 每页条数。领星订单上限 500,Listing 上限 1000 | | `cursor` | `String` | | 上一页返回的 `nextCursor` | ### 4.4 出参说明 `SalesOrder` | 字段 | 类型 | 说明 | |:---|:---|:---| | `omsStoreId` | `String` | 你的店铺 ID | | `channelOrderId` | `String` | 平台单号。**canonicalKey 的一部分** | | `status` | `String` | 平台原始状态值,**未归一化** | | `buyerName` | `String` | 领星订单列表接口不返回,为 null | | `shipToCountryCode` | `String` | 收货国家二字码 | | `lines` | `List` | 明细行 | | `totalAmount` | `Money` | 订单总额 | | `occurredAt` | `PlatformTime` | 下单时间(UTC / 当地 / 北京三轴) | | `sourceProvider` | `ChannelProvider` | 来源通道,**不进业务主键** | | `sourceAccountId` | `String` | 平台侧店铺 ID | **关于 `status`**:目前保留平台原值,没做跨平台归一。领星订单返回数字(`1` 同步中 … `6` 已发货 … `9` 平台发货),宿主需要自己映射。 ### 4.5 单条详情 ```java SalesOrder order = sdk.salesOrders(key, conn).get("PO-123456789"); ``` 只有亚马逊 SC / VC(含 FBM 路由)实现了详情;其它子平台抛 `UnsupportedCapabilityException`。商品详情(`sdk.products(key, conn).get(sku)`)**全部未实现**, 会抛 `ChannelException: lingxing product detail is not implemented yet`。 --- ## 五、拉取商品 / Listing ```java Page page = sdk.products(key, conn).pull( ProductQuery.builder() .updatedAfter(Instant.parse("2026-10-01T00:00:00Z")) // 可选 .updatedBefore(Instant.parse("2026-10-30T00:00:00Z")) // 可选 .pageSize(100) .build()); for (ProductListing p : page.items()) { p.platformSku(); // 平台侧 SKU(领星亚马逊取 seller_sku) p.title(); // 标题 p.status(); // 原始状态值 p.updatedAt(); // 更新时间 p.imageUrls(); // 图片列表 } ``` ### 入参说明 `ProductQuery` | 参数 | 类型 | 必填 | 说明 | |:---|:---|:---:|:---| | `updatedAfter` | `Instant` | | 按「报表更新时间」过滤;亚马逊按 UTC 时间 | | `updatedBefore` | `Instant` | | 同上 | | `pageSize` | `int` | | 亚马逊 Listing 上限 1000 | | `cursor` | `String` | | 上一页游标 | | `searchField` | `ProductSearchField` | | 按 SKU 搜索的维度:`PLATFORM_SKU` / `LOCAL_SKU`;不传表示不按 SKU 搜 | | `searchValue` | `String` | | 单个**模糊**匹配值;设了 `searchField` 才能用 | | `searchValues` | `List` | | 多个**精确**匹配值;与 `searchValue` 互斥(同时设置时会抛异常) | 按 SKU 搜索的示例: ```java Page page = sdk.products(key, conn).pull( ProductQuery.builder() .searchField(ProductSearchField.PLATFORM_SKU) .searchValues(Arrays.asList("SKU-1", "SKU-2")) .build()); ``` 领星会把上面的维度翻译成各子平台自己的 `searchField` 编码(见 `LingxingProductSearchMapper`)。 Target 的 `LOCAL_SKU` 编码尚未实测确认,目前会显式抛 `UnsupportedOperationException`,不会静默返回错数据。 ### 当前支持范围 | provider | 平台 | 是否支持 | |:---|:---|:---:| | LINGXING | 亚马逊 SC | ✅ | | LINGXING | 亚马逊 VC / 沃尔玛 / eBay / Temu / SHEIN / TikTok / Target / AliExpress | ✅ | | LINGXING | 其它子平台(BestBuy / AEPH / Michaels / Echo / Losdlius / Custom …) | ❌ 商品接口未接入 | | DIRECT | — | ❌ 暂无直连适配器 | 不支持时会抛 `ChannelException.UnsupportedCapabilityException: PRODUCT`。 --- ## 六、拉取店铺列表(聚合器) 聚合器(领星)下挂多家子店铺,调用方需要先把它们拉出来,再逐店构造 `ChannelAccount`。 ```java AccountKey aggregatorKey = AccountKey.of( ChannelProvider.LINGXING, Platform.AMAZON_SC, "oms-amz-parent"); ```java List shops = sdk.subChannels(aggregatorKey, conn); for (SubChannel shop : shops) { shop.platformCode(); // 10001(亚马逊 SC) shop.externalStoreId(); // 领星店铺 sid,如 "1519" shop.platform(); // Platform.AMAZON_SC shop.name(); // 店铺名 shop.status(); // 授权状态原值 shop.region(); // 站点简称,如 na // 用它构造账户 ChannelAccount account = ChannelAccount.builder() .key(AccountKey.of(ChannelProvider.LINGXING, shop.platform(), "oms-amz-" + shop.externalStoreId())) .externalStoreId(shop.externalStoreId()) .platformCode(shop.platformCode()) .credentialRef("kms://oms/lingxing/amz") .marketplaceZone("America/Los_Angeles") .currency("USD") .build(); accountRepo.save(account); } ``` ### 当前支持范围 | provider | 平台 | 接口 | |:---|:---|:---| | LINGXING | 亚马逊 SC / VC | `/erp/sc/data/seller/lists` ✅ | | LINGXING | 沃尔玛 / eBay / Temu / SHEIN / TikTok / Target / AliExpress / Wayfair / Mirakl / BestBuy / AEPH / Michaels / Echo / Losdlius / Custom | 多平台店铺接口 `/pb/mp/shop/v2/getSellerList` ✅ | 返回的店铺会**过滤掉非正常状态**(领星 `status != 1` 的店铺)。 --- ## 七、增量同步与水位线 单次查询不推进水位线;需要增量就用 `SyncEngine`。 ```java String stream = SyncSpec.STREAM_SALES_ORDERS; // ① 首次:先写一个起点,否则 SyncEngine 会抛 IllegalStateException if (cursorStore.get(ChannelProvider.LINGXING, "oms-wm-001", stream) == null) { cursorStore.advance(ChannelProvider.LINGXING, "oms-wm-001", stream, Instant.parse("2026-01-01T00:00:00Z")); } // ② 配置同步维度 SyncSpec spec = SyncSpec.of( ChannelProvider.LINGXING, "oms-wm-001", stream, Duration.ofMinutes(10)); // 重叠窗口,防边界丢单 // ③ 跑一次 Instant to = Instant.now(); SyncResult result = new SyncEngine(cursorStore, sink).syncSalesOrders(spec, to, (from, cursor) -> sdk.salesOrders(key, conn).pull( SalesOrderQuery.builder() .updatedAfter(from) .updatedBefore(to) .cursor(cursor) .build())); result.pages(); // 拉了几页 result.items(); // 落了几条 result.watermarkAdvanced(); // 水位线是否推进 ``` ### 行为说明 | 行为 | 说明 | |:---|:---| | 起点计算 | `from = 上次水位线 - overlap` | | 终点 | 你传入的 `to`,**不是** `now()` | | 推进时机 | **整批成功才推进**;中途抛异常水位线不动 | | 调度 | SDK 不持有线程,由宿主调度器触发 | ### `Sink` 实现要点 ```java public void upsertSalesOrders(Page page) { for (SalesOrder o : page.items()) { String key = CanonicalKeys.salesOrder(platform, o.omsStoreId(), o.channelOrderId()); // INSERT ... ON DUPLICATE KEY UPDATE // 唯一索引建在 canonicalKey 上 } } ``` **必须按 `canonicalKey` upsert**,否则直连和领星拉到同一单会变成两行。 --- ## 八、写操作与幂等 所有写操作必须过 `IdempotencyGuard`。 ```java WriteScope scope = WriteScope.of( ChannelProvider.LINGXING, // 本次走哪条通道 Platform.WALMART_SC, "oms-wm-001", // 业务店铺 "1108413237731", // 平台店铺 ID "markShipped", // 动作名 "PO-123456789:pkg-1"); // 业务自然键 WriteResult result = sdk.writes().execute( scope, () -> adapter.markShipped(ctx, command), // 真正调平台 ShipResult::shipmentId); // 结果引用 if (result.alreadyCompleted()) { // 之前已成功,用 result.resultRef() 返回给上游,不算失败 } ``` ### 参数说明 `WriteScope.of` | 参数 | 说明 | |:---|:---| | `provider` | 本次通道 | | `platform` | 业务平台 | | `omsStoreId` | 业务店铺(**跨 provider**) | | `externalStoreId` | 平台店铺 ID(**单 provider 内**) | | `action` | 动作名,如 `markShipped` / `refund` | | `businessRef` | 业务自然键。**退款禁止用金额**,用 `returnId:itemId:refundRequestId` | ### 行为表 | 情形 | 结果 | |:---|:---| | 首次调用 | `EXECUTED` | | 同 provider 重复 | `ALREADY_COMPLETED`,不调平台 | | 另一 provider 重复 | `CrossProviderConflictException` | | 并发 | `IdempotencyConflictException` | | 抛 `retryable=true` 异常 | 记 `FAILED_RETRYABLE`,可重跑 | | 抛 `retryable=false` 异常 | 记 `FAILED_FINAL`,需人工 | | 崩溃窗口(平台已写、业务键未记) | provider 键命中,回放,不重复写 | --- ## 九、查询能力矩阵 只读,不发请求。 ```java CapabilityReport caps = sdk.capabilities(key); caps.supports(Capability.SALES_ORDER); // true / false caps.supported(); // 支持的能力集合 caps.unsupported(); // 不支持的能力集合 ``` 聚合器按**子平台**判断:同一个领星适配器,沃尔玛店和 eBay 店的答案不同。 **SDK 不会自动换 provider**。能力不足时抛 `UnsupportedCapabilityException`,由调用方决定换账户还是走人工。 --- ## 十、异常与重试 | 异常 | 触发 | 可重试 | |:---|:---|:---:| | `AuthException` | 401/403、token 失效、签名错误 | 刷新后 1 次 | | `RateLimitException` | 429 / 领星 `3001008` | 是,带 `retryAfterMillis()` | | `TransientException` | 5xx / 网络 / 超时 | 是 | | `ValidationException` | 4xx / 映射失败 | 否 | | `PlatformBusinessException` | 平台业务码 | 视码 | | `ChannelException.UnsupportedCapabilityException` | 能力缺失 | 否 | | `IdempotencyConflictException` | 并发重复写 | 否 | | `CrossProviderConflictException` | 已由另一 provider 完成 | 否 | 所有异常都带 `provider / omsStoreId / operation / requestId / rawResponse`,排查时先看这几个字段。 ```java try { sdk.salesOrders(key, conn).pull(query); } catch (RateLimitException e) { Thread.sleep(e.retryAfterMillis()); } catch (TransientException e) { // 退避后重试 } catch (AuthException e) { // 刷新 token 后重试一次,仍失败则停用账户 } ``` **SDK 自身不做重试**,退避策略由宿主决定。 --- ## 十一、宿主必须实现的 SPI | SPI | 作用 | 哪个操作需要 | |:---|:---|:---| | `ChannelAccountRepository` | 读账户配置 | 全部 | | `TokenStore` | token 读写(宿主加密) | 全部 | | `LockProvider` | token 刷新防击穿 | 全部 | | `SyncCursorStore` | 水位线 | 增量同步 | | `Sink` | 领域对象落库 | 增量同步 | | `IdempotencyStore` | 幂等键抢占与结果 | 写操作 | **SDK 不碰数据库**。所有持久化都由宿主实现上述接口。 --- ## 十二、常见错误对照表 | 现象 | 原因 | 处理 | |:---|:---|:---| | `channel account not configured` | `findByKey` 没查到 | 检查 `provider/platform/omsStoreId` 三个值是否与账户一致 | | `no adapter registered for ...` | 该 `provider + platform` 没注册适配器 | 检查 `register(...)`;领星工厂覆盖 16 个子平台,不含 `WALMART_1P` | | `duplicate adapter for ...` | 同一 `provider + platform` 注册了两次 | 去掉重复的 `register` | | `UnsupportedCapabilityException` | 适配器不声明该能力 | 先 `capabilities()` 判断,或换 provider | | `lingxing sub platform not implemented: X` | 该子平台没有注册到 `LingxingSubPlatforms` | 对照 `LingxingSubPlatformDefaults.all(...)` 的注册清单 | | `lingxing code=102 msg=参数不合法` | 请求参数不对 | 检查 `sid` / `platform_code` / 时间格式 | | `lingxing code=2001013 app authentication failed` | AppID/AppSecret 错误 | 检查凭据;确认出口 IP 在白名单 | | `lingxing code=3001008` | 触发限流 | 该接口 qps=1,必须串行调用 | | `lingxing code=2001006/2001007` | 签名错误/过期 | 检查签名参数与系统时间 | | `token refresh in progress` | 另一实例正在刷新 | 属于正常并发保护,稍后重试 | | `previous attempt failed permanently` | 幂等记录为 `FAILED_FINAL` | 人工介入后清理记录 | --- ## 附录:领星 platform_code 对照 | platform_code | Platform | |:---:|:---| | 10001 | `AMAZON_SC` | | 10035 | `AMAZON_VC` | | 10003 | `EBAY` | | 10005 / 10031 | `AEPH` | | 10008 | `WALMART_SC` | | 10010 | `WAYFAIR` | | 10011 | `TIKTOK` | | 10021 / 10027 / 10028 | `SHEIN` | | 10022 / 10024 | `TEMU` | | 10029 / 10030 | `ALIEXPRESS` | | 10034 | `MIRAKL` | | 10009 / 10017 / 其它 | `CUSTOM`(同一码下混有多个业务平台,无法用一个枚举表示) | > 业务平台以账户的 `AccountKey.platform` 为准,这张表只用于从店铺列表 / 订单行反推。 > Target / BestBuy / Michaels / ECHO / LOS-DLI-US 在领星侧没有独立平台码。 --- ## 附录:当前实现状态 | 能力 | 亚马逊 SC | 亚马逊 VC | 沃尔玛 | Temu / SHEIN / eBay / TikTok / Target / AliExpress 等 | Direct | |:---|:---:|:---:|:---:|:---:|:---:| | 订单列表 | ✅ | ✅ | ✅ | ✅(多平台统一订单) | ❌ | | 订单详情 | ✅(含 FBM) | ✅ | ❌ | ❌ | ❌ | | 商品 / Listing | ✅ | ✅ | ✅ | ✅(8 个平台) | ❌ | | 店铺列表 | ✅ | ✅ | ✅ | ✅ | — | | 账单 / 结算 | ✅ | ❌ | ❌ | ❌ | ❌ | | 售后(只读) | ✅ | ❌ | ❌ | ❌ | ❌ | | 快速出库(写) | ✅ | ✅ | ✅ | ✅ | ❌ | | 出库单 / 面单 / 审核发货 | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ | | 订单编辑(写) | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ | 写接口没有测试环境,联调时**只跑查询**。