From 71a451f3b9c12ddebd004dc0a8619b625bcc6fba Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Mon, 2 Nov 2026 17:51:12 +0800 Subject: [PATCH] =?UTF-8?q?feat(sdk):=20listSubChannels=20=E6=94=B6=20Chan?= =?UTF-8?q?nelContext=EF=BC=8C=E6=96=B0=E5=A2=9E=20subChannels=20=E9=97=A8?= =?UTF-8?q?=E9=9D=A2=E4=B8=8E=E6=93=8D=E4=BD=9C=E6=89=8B=E5=86=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AggregatorCapable.listSubChannels 改为 (ChannelContext), 此前只收 ChannelAccount,拿不到端点与凭据,无法真实调店铺接口 - ChannelSdk.subChannels(key, conn):聚合器子店铺列表入口 - LingxingAdapter.listSubChannels 分派到子平台的 shopSource - 新增《操作手册.md》:依赖、连接信息、订单/商品/店铺、增量同步、 写操作幂等、异常对照、SPI 清单 Co-Authored-By: Claude --- .../ecommerce/capability/AggregatorCapable.java | 10 +- .../main/java/common/ecommerce/sdk/ChannelSdk.java | 19 + .../lingxing/adapter/LingxingAdapter.java | 28 +- 操作手册.md | 519 +++++++++++++++++++++ 4 files changed, 564 insertions(+), 12 deletions(-) create mode 100644 操作手册.md diff --git a/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java b/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java index 8132c85..51aa9dc 100644 --- a/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java +++ b/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java @@ -3,6 +3,7 @@ package common.ecommerce.capability; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.model.Platform; +import common.ecommerce.sdk.ChannelContext; import java.util.List; @@ -14,7 +15,14 @@ import java.util.List; */ public interface AggregatorCapable extends PlatformAdapter { - List listSubChannels(ChannelAccount account); + /** + * 列出企业在该聚合器下已授权的全部子店铺。 + * + *

需要真实调接口,所以要收 {@link ChannelContext}(含端点与凭据)。 + * 返回的 {@code platformCode + externalStoreId} 可直接用于构造 + * {@link ChannelAccount}。

+ */ + List listSubChannels(ChannelContext ctx); /** 聚合器通过子平台的 platform_code 细化能力。 */ @Override diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java index 78ba54a..90506b1 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -2,6 +2,9 @@ package common.ecommerce.sdk; import common.ecommerce.model.Platform; import common.ecommerce.capability.AdapterCapabilityReport; +import common.ecommerce.capability.AggregatorCapable; +import common.ecommerce.error.ChannelException; +import common.ecommerce.model.Capability; import common.ecommerce.capability.CapabilityReport; import common.ecommerce.capability.PlatformAdapter; import common.ecommerce.capability.Products; @@ -77,6 +80,22 @@ public final class ChannelSdk implements ProviderResolver { } /** + * 聚合器的子店铺列表(如领星下已授权的亚马逊 / 沃尔玛店铺)。 + * + *

调用方拿到 {@code platformCode + externalStoreId} 后,用来构造 + * {@link ChannelAccount},业务调用仍走 {@link AccountKey}。 + * 非聚合器适配器会抛 {@code UnsupportedCapabilityException}。

+ */ + public List subChannels(AccountKey key, ChannelConnection connection) { + ChannelAccount account = requireAccount(key); + PlatformAdapter adapter = resolve(key); + if (!(adapter instanceof AggregatorCapable)) { + throw new IllegalStateException("adapter is not an aggregator: " + key); + } + return ((AggregatorCapable) adapter).listSubChannels(newContext(account, connection)); + } + + /** * 写操作幂等守卫(业务键 + provider 请求键双锁)。 * *

写操作必须经守卫执行;未注入 {@code IdempotencyStore} 时直接失败, diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java index 8e18099..c17329e 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java @@ -138,19 +138,25 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, } /** - * 店铺(子渠道)列表尚未接入:当前签名拿不到 {@code ChannelConnection}, - * 无法调用领星接口。改为显式失败,不再返回由账户拼出来的假子渠道。 + * 店铺(子渠道)列表:按子平台分派到各自的实现。 */ @Override - public List listSubChannels(ChannelAccount account) { - throw ChannelException.builder() - .message("lingxing shop list is not implemented yet") - .operation("listSubChannels") - .provider(provider().name()) - .omsStoreId(account.omsStoreId()) - .platform(LingxingConstants.toPlatform(account.platformCode())) - .retryable(false) - .build(); + public List listSubChannels(ChannelContext ctx) { + ChannelSecret secret = ctx.secret(); + AccessToken token = tokenManager.getOrRefresh(tokenKey(secret), secret); + LingxingCall call = new LingxingCall(ctx, token, requestFactory, rateLimiter, json, transport); + LingxingSubPlatform impl = LingxingSubPlatforms.of(ctx.platform()); + if (impl.shopSource() == null) { + throw ChannelException.builder() + .message("lingxing shop list is not supported for " + ctx.platform()) + .operation("listSubChannels") + .provider(provider().name()) + .omsStoreId(ctx.omsStoreId()) + .platform(ctx.platform()) + .retryable(false) + .build(); + } + return impl.shopSource().shops(call); } @Override diff --git a/操作手册.md b/操作手册.md new file mode 100644 index 0000000..1e56061 --- /dev/null +++ b/操作手册.md @@ -0,0 +1,519 @@ +# 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 + common-ecommerce-core + 1.0.0-SNAPSHOT + + + ecommerce + common-ecommerce-http + 1.0.0-SNAPSHOT + + + ecommerce + common-ecommerce-lingxing + 1.0.0-SNAPSHOT + + + + ecommerce + common-ecommerce-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) + // 密钥引用(如果宿主仍用 SecretProvider 取密钥) + .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` | ✅ | 密钥引用,不是密钥本身 | +| `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()); +``` + +### 各平台需要的凭据字段 + +| 平台 | 需要的字段 | +|:---|:---| +| 领星 | `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"); +``` + +**领星暂未实现**,会抛 `ChannelException: lingxing order 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` | | 上一页游标 | + +### 当前支持范围 + +| provider | 平台 | 是否支持 | +|:---|:---|:---:| +| LINGXING | 亚马逊 SC | ✅ | +| LINGXING | 沃尔玛 | ❌(未接入) | +| LINGXING | eBay / SHEIN 等 | ❌ | + +不支持时会抛 `ChannelException.UnsupportedCapabilityException: PRODUCT`。 + +--- + +## 六、拉取店铺列表(聚合器) + +聚合器(领星)下挂多家子店铺,调用方需要先把它们拉出来,再逐店构造 `ChannelAccount`。 + +```java +AccountKey aggregatorKey = AccountKey.of( + ChannelProvider.LINGXING, Platform.AMAZON_SC, "oms-amz-parent"); + +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(); // 店铺名 + + // 用它构造账户 + 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 | `/erp/sc/data/seller/lists` ✅ | +| LINGXING | 沃尔玛 / eBay / … | ❌ | + +返回的店铺会**过滤掉非正常状态**(领星 `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(...)`;领星只覆盖 8 个平台 | +| `duplicate adapter for ...` | 同一 `provider + platform` 注册了两次 | 去掉重复的 `register` | +| `UnsupportedCapabilityException` | 适配器不声明该能力 | 先 `capabilities()` 判断,或换 provider | +| `lingxing sub platform not implemented: X` | 该子平台没有实现类 | 目前只有 `WALMART_SC` / `AMAZON_SC` | +| `lingxing shop list is not supported for X` | 该子平台没有店铺接口 | 目前只有亚马逊 SC 有 | +| `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` | +| 10008 | `WALMART_SC` | +| 10011 | `TIKTOK` | +| 10022 / 10024 | `TEMU` | +| 10003 | `EBAY` | +| 10021 / 10027 / 10028 | `SHEIN` | +| 10034 | `MIRAKL` | +| 其它 | `CUSTOM`(调用时会因未注册子平台而失败) | + +--- + +## 附录:当前实现状态 + +| 能力 | 领星·亚马逊 SC | 领星·沃尔玛 | 直连 | +|:---|:---:|:---:|:---:| +| 订单列表 | ❌ | ✅ | ❌ | +| 订单详情 | ❌ | ❌ | ❌ | +| 商品 / Listing | ✅ | ❌ | ❌ | +| 店铺列表 | ✅ | ❌ | — | +| 写操作 | ❌ | ❌ | ❌ |