|
|
|
|
# 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
|
|
|
|
|
<dependency>
|
|
|
|
|
<groupId>ecommerce</groupId>
|
|
|
|
|
<artifactId>channel-sdk-core</artifactId>
|
|
|
|
|
<version>1.0.0-SNAPSHOT</version>
|
|
|
|
|
</dependency>
|
|
|
|
|
<dependency>
|
|
|
|
|
<groupId>ecommerce</groupId>
|
|
|
|
|
<artifactId>common-ecommerce-lingxing</artifactId>
|
|
|
|
|
<version>1.0.0-SNAPSHOT</version>
|
|
|
|
|
</dependency>
|
|
|
|
|
<!-- 仅测试用 -->
|
|
|
|
|
<dependency>
|
|
|
|
|
<groupId>ecommerce</groupId>
|
|
|
|
|
<artifactId>sdk-testkit</artifactId>
|
|
|
|
|
<version>1.0.0-SNAPSHOT</version>
|
|
|
|
|
<scope>test</scope>
|
|
|
|
|
</dependency>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
要求 JDK 1.8。
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 二、三个第一步
|
|
|
|
|
|
|
|
|
|
调用任何接口之前,宿主必须先提供三样东西。
|
|
|
|
|
|
|
|
|
|
### 2.1 账户仓库 `ChannelAccountRepository`
|
|
|
|
|
|
|
|
|
|
SDK 靠它把 `AccountKey` 解析成账户配置。
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
public interface ChannelAccountRepository {
|
|
|
|
|
Optional<ChannelAccount> findByKey(String provider, String platform, String omsStoreId);
|
|
|
|
|
List<ChannelAccount> 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<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")) // 可选,缺省取现在
|
|
|
|
|
.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<OrderLine>` | 明细行 |
|
|
|
|
|
| `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<ProductListing> 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<String>` | | 多个**精确**匹配值;与 `searchValue` 互斥(同时设置时会抛异常) |
|
|
|
|
|
|
|
|
|
|
按 SKU 搜索的示例:
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
Page<ProductListing> 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<SubChannel> 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<SalesOrder> 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<ShipResult> 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 级,全平台共用) | 同左 | 同左 | 同左 | ❌ |
|
|
|
|
|
|
|
|
|
|
写接口没有测试环境,联调时**只跑查询**。
|