From e1d6621d3d024a05e8242c609004a69887e1d39f Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Fri, 6 Nov 2026 17:55:17 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20GUIDE=20/=20=E6=93=8D=E4=BD=9C=E6=89=8B?= =?UTF-8?q?=E5=86=8C=20=E5=AF=B9=E9=BD=90=20shared/channel=20=E4=B8=8E?= =?UTF-8?q?=E9=A2=86=E6=98=9F=E7=8E=B0=E7=8A=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GUIDE: - 能力接口清单补齐结算/售后/出库/面单/审核/订单编辑,门面 API 补全视图 - 接入示例改为「适配器不持凭据」,端点与密钥取自 ChannelContext - 测试分层改为 单测 → 契约(RecordingTransport+夹具)→ 真实冒烟(系统属性传凭据)→ 分页水位线 → 门面能力 - 验收与实现状态表按 channel/shared 模块名更新 操作手册: - 商品搜索维度 searchField / searchValue / searchValues,及 Target LOCAL_SKU 的显式拒绝 - 商品 / 店铺 / 订单详情的支持范围按实际子平台修正 - platform_code 对照与实现状态表按实测补齐 代码:ChannelAccount 的 credentialRef 注释去掉已废弃的 SecretProvider 说法 Co-Authored-By: Claude --- GUIDE.md | 173 +++++++++++---------- .../channel/model/account/ChannelAccount.java | 6 +- 操作手册.md | 75 ++++++--- 3 files changed, 151 insertions(+), 103 deletions(-) diff --git a/GUIDE.md b/GUIDE.md index 2a63b9d..727e78b 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -127,7 +127,7 @@ public interface PlatformAdapter { ### 3.2 能力接口 -供应商实现哪些接口,就声明哪些能力。目前有两个: +供应商实现哪些接口,就声明哪些能力。接口都继承 `PlatformAdapter`: ```java public interface SalesOrderCapable extends PlatformAdapter { @@ -143,9 +143,22 @@ public interface ProductCapable extends PlatformAdapter { } ``` +其余能力接口(按需实现,不实现就不声明): + +| 接口 | 读/写 | 关键方法 | +|:---|:---:|:---| +| `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)` 是同一个签名。一个同时实现订单和商品的适配器(比如直连沃尔玛)**无法同时实现**,编译器直接报名称冲突。所以包成两个不同的类。 +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` 根包。 @@ -157,14 +170,20 @@ Java 擦除后两个 `get(ctx, String)` 是同一个签名。一个同时实现 ```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 IdempotencyGuard writes(); // 写操作守卫 - public PlatformAdapter resolve(AccountKey key); // 按 key 找适配器 + 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 subChannels(AccountKey key, ChannelConnection conn); + public IdempotencyGuard writes(); // 写操作守卫 + public PlatformAdapter resolve(AccountKey key); // 按 key 找适配器 } ``` +写类能力(`submit` / `review` / `edit`)挂在 `Outbounds` 视图上,**仍必须经 `sdk.writes()` 包一层幂等**再调用。 + 门面**不做**:不选 provider、不自动兜底、不重试、不缓存。 每次调用固定三步: @@ -190,12 +209,13 @@ key → accountRepository.findByKey(provider, platform, omsStoreId) | SPI | 作用 | 读要用 | 写要用 | |:---|:---|:---:|:---:| -| `ChannelAccountRepository` | 读渠道账户 | ✅ | ✅ | +| `ChannelAccountRepository`(channel) | 读渠道账户 | ✅ | ✅ | +| `ChannelSecret` | 凭据载体,调用时经 `ChannelConnection` 传入 | ✅ | ✅ | | `SecretProvider` | ~~按 credentialRef 取密钥~~ **已废弃**:凭据由调用方传入 | — | — | | `TokenStore` | token 读写(宿主加密) | ✅ | ✅ | | `LockProvider` | token 刷新防击穿 | ✅ | ✅ | | `SyncCursorStore` | 水位线 | 批量读 | — | -| `Sink` | 领域对象落库 | 批量读 | — | +| `Sink`(channel) | 领域对象落库 | 批量读 | — | | `IdempotencyStore` | 幂等键抢占与结果 | — | ✅ | ### 3.5 错误类型 @@ -359,19 +379,19 @@ if (r.alreadyCompleted()) { ## 五、加一个供应商:8 步 -以新增 `acme` 直连平台为例。**核心原则:不改 core、不改门面、不改宿主。** +以新增 `acme` 直连平台为例。**核心原则:不改 channel、不改门面、不改宿主。** ### 第 0 步:先想清楚三件事 | 问题 | 影响 | |:---|:---| -| 它属于哪个 `Platform`? | 枚举里有直接用;没有才加(唯一允许改 core 的地方) | +| 它属于哪个 `Platform`? | 枚举里有直接用;没有才加(唯一允许改 `shared` 的地方) | | 走 `DIRECT` 还是新聚合器? | 新聚合器才加 `ChannelProvider` 枚举值 | | 它会哪些能力? | 只列真能做的 | -现有枚举: +现有枚举(`common.ecommerce.shared.model`): -- `Platform`:`AMAZON_SC` `AMAZON_VC` `WALMART_SC` `WALMART_1P` `TIKTOK` `TEMU` `EBAY` `SHEIN` `MIRAKL` `TARGET` `BESTBUY` `AEPH` `CUSTOM` +- `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 步:建模块 @@ -460,7 +480,7 @@ public final class AcmeOrderDto { **平台字段名只允许出现在 DTO 和 Mapper 里。** **DTO 用 Lombok,领域模型不用。** DTO 是纯数据容器,没有不变量要保护,`@Getter`/`@Setter` -省掉全部样板;`core` 的模型是不可变 + Builder,本来就没有 setter,且 `core` 要尽量少依赖 +省掉全部样板;`channel` 的模型是不可变 + Builder,本来就没有 setter,且 `channel` 要尽量少依赖 编译期工具。Lombok 声明为 `scope=provided`,不进宿主运行时。 **端点和路径写成常量,不做配置。** 协议细节(URL、字段名、限流值)是代码的一部分—— @@ -564,27 +584,23 @@ public final class AcmeSigner { ```java public final class AcmeAdapter implements SalesOrderCapable { - private final String baseUrl; private final HttpTransport transport; private final JacksonJsonCodec json; - private final SecretProvider secretProvider; private final Clock clock; private final TokenManager tokenManager; private final AcmeOrderMapper mapper = new AcmeOrderMapper(); - public AcmeAdapter(String baseUrl, HttpTransport transport, JacksonJsonCodec json, - SecretProvider secretProvider, TokenStore tokenStore, - LockProvider lockProvider, Clock clock) { - this.baseUrl = baseUrl; + // 适配器只持有协议与基础设施:端点与凭据随每次调用的 ChannelContext 进来 + public AcmeAdapter(HttpTransport transport, JacksonJsonCodec json, + TokenStore tokenStore, LockProvider lockProvider, Clock clock) { this.transport = transport; this.json = json; - this.secretProvider = secretProvider; this.clock = clock; - final AcmeTokenClient tokenClient = new AcmeTokenClient(transport, json, baseUrl); + 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.appKey(), secret.appSecret()); + return tokenClient.fetch(secret.endpointBaseUrl(), secret.appKey(), secret.appSecret()); } }; } @@ -608,7 +624,7 @@ public final class AcmeAdapter implements SalesOrderCapable { HttpRequest req = HttpRequest.builder() .method("POST") - .url(baseUrl + AcmeConstants.PATH_ORDERS) + .url(ctx.endpointBaseUrl() + AcmeConstants.PATH_ORDERS) // ★ 端点来自 ctx .header("Content-Type", "application/json") .header("Authorization", authHeader(ctx)) .header("X-Request-Id", ctx.requestId()) @@ -645,8 +661,8 @@ public final class AcmeAdapter implements SalesOrderCapable { private String authHeader(ChannelContext ctx) { ChannelAccount account = ctx.account(); - ChannelSecret secret = secretProvider.get(account.credentialRef()); - AccessToken token = tokenManager.getOrRefresh("acme:" + account.externalStoreId(), secret); + // 凭据由调用方经 ChannelConnection 传入,适配器不自己去找 + AccessToken token = tokenManager.getOrRefresh("acme:" + account.externalStoreId(), ctx.secret()); return token.tokenType() + " " + token.value(); } @@ -677,13 +693,11 @@ public final class AcmeAdapter implements SalesOrderCapable { ```java public final class AcmeAdapterFactory implements AdapterFactory { - private final SecretProvider secretProvider; private final TokenStore tokenStore; private final LockProvider lockProvider; private final Clock clock; - public AcmeAdapterFactory(SecretProvider secretProvider, TokenStore tokenStore, - LockProvider lockProvider, 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; } @@ -691,17 +705,15 @@ public final class AcmeAdapterFactory implements AdapterFactory { @Override public PlatformAdapter create(AdapterConfig config) { - String baseUrl = config.endpointBaseUrl() == null - ? AcmeConstants.DEFAULT_BASE_URL : config.endpointBaseUrl(); - return new AcmeAdapter(baseUrl, - new OkHttpTransport("common-ecommerce/1.0.0 (acme)"), - new JacksonJsonCodec(), - secretProvider, tokenStore, lockProvider, clock); + // 生产端点由调用方的 ChannelConnection 提供;config 只用于测试/联调时覆盖目标地址 + return new AcmeAdapter(new OkHttpTransport("common-ecommerce/1.0.0 (acme)"), + new JacksonJsonCodec(), tokenStore, lockProvider, clock); } } ``` 工厂的意义:把「怎么 new」和「业务怎么用」隔开。宿主只注册工厂,不需要知道构造参数。 +**工厂不持有凭据**——凭据随每次调用的 `ChannelConnection` 进来。 ### 第 8 步:接进门面 @@ -710,7 +722,7 @@ ChannelSdk sdk = ChannelSdk.builder() .accountRepository(accountRepo) .idempotencyStore(idempotencyStore) // 要写操作就必须 .idempotencyOwner(hostName) // 多实例时区分抢占方 - .register(new AcmeAdapterFactory(secretProvider, tokenStore, lockProvider, clock)) + .register(new AcmeAdapterFactory(tokenStore, lockProvider, clock)) .build(); AccountKey key = AccountKey.of(ChannelProvider.DIRECT, Platform.AMAZON_SC, "oms-amz-001"); @@ -774,24 +786,49 @@ assertEquals(md5Hex("secretapp_keyk1"), AcmeSigner.sign(params, "secret")); 时间相关的用 DST 边界:2026-03-08 美国太平洋时区进入夏令时,前后各测一次。 -### 第 2 层:真实环境冒烟(主力) +### 第 2 层:契约测试(主力) + +用 `RecordingTransport` + 夹具断言「请求怎么拼、响应怎么解」,**不联网**: -当前只保留真实环境冒烟(`LingxingLiveSmokeTest`),不再使用录制报文。 +```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); -做法:在测试类顶部写常量(本地联调时填真实值,不提交),用真实的 -`OkHttpTransport` 直接打平台接口;未填常量时用 `Assumptions` 跳过, -避免占位串打到线上。 +Page 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 = "在这里填 AppID"; - private static final String APP_SECRET = "在这里填 AppSecret"; + 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()); @@ -800,9 +837,11 @@ class AcmeLiveSmokeTest { ``` 联调时把请求和响应打出来(token 打码),签名或字段名不对时靠日志定位。 -**凭证不要提交到仓库**,联调完重置。 +**凭证不要提交到仓库**(提交历史里的密钥要轮换),联调完重置。 + +> 领星尤其注意:真实环境**只跑查询类接口**。出库、审核发货这类写接口没有测试环境,误操作不可回滚。 -### 第 3 层:分页与水位线 +### 第 4 层:分页与水位线 ```java @Test @@ -840,7 +879,7 @@ void pagesThroughAllOrdersAndAdvancesWatermarkOnce() { - 返回空页 → 立刻结束,不无限循环 - 没有水位线 → 抛 `IllegalStateException` -### 第 4 层:门面 + 能力 +### 第 5 层:门面 + 能力 ```java @Test @@ -859,33 +898,6 @@ void facadeRejectsUnsupportedCapability() { 聚合器还要额外测:同一适配器,Walmart 账户和 eBay 账户的 `supports` 结果不同。 -### 第 5 层:真实冒烟(手动,不进 CI) - -参考 `lingxing/src/test/java/common/ecommerce/lingxing/LingxingLiveSmokeTest.java`:没配环境变量时整类跳过。 - -```java -@EnabledIfEnvironmentVariable(named = "ACME_APP_KEY", matches = ".+") -class AcmeLiveSmokeTest { - - @Test - void tokenCanBeFetched() { ... } // 先验认证 - - @Test - void pullsOnePage() { ... } // 再验报文 -} -``` - -包一层 `LoggingTransport` 打印请求响应(Authorization 打码、body 截断)。 - -**排错顺序**: - -1. 401 / 403 → 先单独跑 token 测试;还失败就查出口 IP 白名单。 -2. token 通了但接口报签名错 → 只改 `Signer`,跑已知向量。 -3. 200 但 0 条 → 查时间窗、`platform_code`、`store_id` 是否属于同一店铺。 -4. 200 有数据但字段 null → 对照原始报文改 DTO 的 `@JsonProperty`,然后把真实响应存成新夹具。 - -**真实报文转夹具**:冒烟跑通后,把打印的响应存成 `fixtures/acme/orderList/real-2026-10-29.json`,加一个 Mapper 用例。以后改代码不用再连真实环境。 - --- ## 七、验收清单 @@ -903,20 +915,21 @@ class AcmeLiveSmokeTest { | 7 | 超长时间窗会截断 | 断言 body 里的起止时间 | | 8 | 写操作只执行一次 | `adapter.writeCallCount() == 1` | | 9 | 水位线失败不推进 | 第二页抛异常后断言水位线不变 | -| 10 | core 零改动 | `git diff core/` 应只有 `Platform` 枚举 | +| 10 | channel / shared 零改动 | `git diff channel/ shared/` 应只有 `shared/model/Platform` 枚举 | --- ## 八、已知缺口与坑 -### 当前实现状态(2026-10-29) +### 当前实现状态(2026-11-06) | 模块 | 状态 | |:---|:---| -| core | 模型、能力接口、门面、SyncEngine、幂等守卫、SPI 全部可用 | +| shared | 枚举、异常、SPI 契约、幂等守卫、审计、水位线通用类型全部可用 | +| channel | 领域模型、能力接口、门面、SyncEngine、账户/落库 SPI 全部可用 | | http | OkHttp 传输、Jackson 编解码、签名接口、TokenManager 模板可用 | | testkit | InMemory SPI、FakeDirectAdapter、MutableClock 可用 | -| lingxing | 订单列表拉取可用;商品、履约、面单、账单、售后未实现 | +| lingxing | 16 个子平台:订单 / 店铺全量;商品 8 个平台;结算、售后目前只有亚马逊 SC;出库单 / 面单 / 审核发货 / 订单编辑为 ERP 级、全平台共用 | | 其它平台 | 未开始 | ### 编码坑(按踩到概率排序) @@ -940,7 +953,7 @@ class AcmeLiveSmokeTest { | `RefundLedger` 未实现 | 无超退校验 | 与 `IdempotencyGuard` 配合 | | `DuplicateOrderGuard` 未实现 | 跨 provider 重复订单无告警 | 新增 SPI | | 领星时间窗超 31 天被静默截断 | 水位线落后太多会漏中间段 | 调用方分段补拉 | -| 领星单订单详情未实现 | `get()` 直接抛异常 | 用 `pull` + 时间窗捞 | +| 领星单订单详情未实现 | 除亚马逊 SC / VC 外的子平台 `get()` 直接抛异常 | 用 `pull` + 时间窗捞 | | 领星限流器用 `Thread.sleep` | 多店并发时按实例数放大 | 按账户拆适配器实例,或换通用限流器 | --- @@ -948,7 +961,7 @@ class AcmeLiveSmokeTest { ## 九、上手顺序 1. **读三个文件**:`PlatformAdapter`、`SalesOrderCapable`、`ChannelSdk`。不到 150 行,看懂这三个就懂一半。 -2. **跑一遍现有测试**:`mvn -pl lingxing -am test`,对照看 `LingxingAdapterTest` —— 它就是「加一个供应商」的完整范例。 +2. **跑一遍现有测试**:`mvn -pl lingxing -am test`,对照看 `LingxingSdkListingCallTest`(门面 + 契约)与 `LingxingAfterSaleListSourceTest`(Source + 夹具)—— 它们就是「加一个供应商」的完整范例。 3. **抄领星的结构**建新模块:`Constants → Dto → Mapper → Adapter → Factory → Test`。 4. **先用夹具跑通,再连真实环境。** 不要反过来。 @@ -957,6 +970,6 @@ class AcmeLiveSmokeTest { ```bash mvn clean test # 全部 mvn -pl lingxing -am test # 单模块(含依赖) -mvn -pl lingxing -am test -Dtest=LingxingAdapterTest # 单个测试类 +mvn -pl lingxing -am test -Dtest=LingxingSdkListingCallTest # 单个测试类 mvn -pl lingxing -am test -Dtest=LingxingLiveSmokeTest # 真实环境冒烟(需环境变量) ``` diff --git a/channel/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java b/channel/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java index b13ed24..7222d16 100644 --- a/channel/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java +++ b/channel/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java @@ -11,8 +11,8 @@ import java.util.Objects; /** * 渠道账户。一个 omsStoreId 可绑定多个 provider 账户。 * - *

凭证不落配置:本对象只保存 {@code credentialRef},真实密钥由宿主 - * {@code SecretProvider} 按引用取出。

+ *

凭证不落配置:本对象只保存 {@code credentialRef}(账户维度的标识), + * 真实密钥由调用方在每次调用时经 {@code ChannelConnection} 传入,SDK 不保存、不读取。

*/ public final class ChannelAccount { @@ -31,7 +31,7 @@ public final class ChannelAccount { /** 市场 ID 列表;单市场平台可为空列表。 */ private final List marketplaceIds; - /** 凭证引用(SecretProvider 的键),不是密钥本身。 */ + /** 凭证引用(宿主侧密钥条目的标识),不是密钥本身;真实密钥经 ChannelConnection 传入。 */ private final String credentialRef; /** 市场时区 IANA ID,如 America/Los_Angeles。 */ diff --git a/操作手册.md b/操作手册.md index 81f4d1a..29a171d 100644 --- a/操作手册.md +++ b/操作手册.md @@ -80,7 +80,7 @@ ChannelAccount account = ChannelAccount.builder() .externalStoreId("1108413237731") // 领星 platform_code;直连账户不填 .platformCode(10008) - // 密钥引用(如果宿主仍用 SecretProvider 取密钥) + // 密钥引用(宿主侧密钥条目的标识);真实密钥经 ChannelConnection 传入,见第三节 .credentialRef("kms://oms/lingxing/store-001") // 市场当地时区,必须是合法 IANA 时区 .marketplaceZone("America/Los_Angeles") @@ -94,7 +94,7 @@ ChannelAccount account = ChannelAccount.builder() | `key` | ✅ | `provider + platform + omsStoreId`,SDK 的隔离维度 | | `externalStoreId` | ✅ | 平台店铺 ID。领星传 `store_id`;亚马逊 SC 传 `sid` | | `platformCode` | 领星必填 | 见 [platform_code 对照](#领星-platform_code-对照) | -| `credentialRef` | ✅ | 密钥引用,不是密钥本身 | +| `credentialRef` | ✅ | 密钥引用标识,不是密钥本身;真实密钥经 `ChannelConnection` 传入 | | `marketplaceZone` | ✅ | 必须是 `ZoneId.of(...)` 能解析的值 | | `currency` | ✅ | ISO 4217 | @@ -135,6 +135,8 @@ ChannelConnection conn = ChannelConnection.of( .build()); ``` +`credentialRef` 只是账户上的标识,SDK **不会**拿它去取密钥;真实密钥就在上面的 `ChannelSecret` 里。 + ### 各平台需要的凭据字段 | 平台 | 需要的字段 | @@ -217,7 +219,9 @@ while (page.nextCursor() != null) { SalesOrder order = sdk.salesOrders(key, conn).get("PO-123456789"); ``` -**领星暂未实现**,会抛 `ChannelException: lingxing order detail is not implemented yet`。 +只有亚马逊 SC / VC(含 FBM 路由)实现了详情;其它子平台抛 +`UnsupportedCapabilityException`。商品详情(`sdk.products(key, conn).get(sku)`)**全部未实现**, +会抛 `ChannelException: lingxing product detail is not implemented yet`。 --- @@ -248,14 +252,31 @@ for (ProductListing p : page.items()) { | `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 | 沃尔玛 | ❌(未接入) | -| LINGXING | eBay / SHEIN 等 | ❌ | +| LINGXING | 亚马逊 VC / 沃尔玛 / eBay / Temu / SHEIN / TikTok / Target / AliExpress | ✅ | +| LINGXING | 其它子平台(BestBuy / AEPH / Michaels / Echo / Losdlius / Custom …) | ❌ 商品接口未接入 | +| DIRECT | — | ❌ 暂无直连适配器 | 不支持时会抛 `ChannelException.UnsupportedCapabilityException: PRODUCT`。 @@ -269,6 +290,7 @@ for (ProductListing p : page.items()) { AccountKey aggregatorKey = AccountKey.of( ChannelProvider.LINGXING, Platform.AMAZON_SC, "oms-amz-parent"); +```java List shops = sdk.subChannels(aggregatorKey, conn); for (SubChannel shop : shops) { @@ -276,6 +298,8 @@ for (SubChannel shop : shops) { shop.externalStoreId(); // 领星店铺 sid,如 "1519" shop.platform(); // Platform.AMAZON_SC shop.name(); // 店铺名 + shop.status(); // 授权状态原值 + shop.region(); // 站点简称,如 na // 用它构造账户 ChannelAccount account = ChannelAccount.builder() @@ -294,8 +318,8 @@ for (SubChannel shop : shops) { | provider | 平台 | 接口 | |:---|:---|:---| -| LINGXING | 亚马逊 SC | `/erp/sc/data/seller/lists` ✅ | -| LINGXING | 沃尔玛 / eBay / … | ❌ | +| 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` 的店铺)。 @@ -478,11 +502,10 @@ try { | 现象 | 原因 | 处理 | |:---|:---|:---| | `channel account not configured` | `findByKey` 没查到 | 检查 `provider/platform/omsStoreId` 三个值是否与账户一致 | -| `no adapter registered for ...` | 该 `provider + platform` 没注册适配器 | 检查 `register(...)`;领星只覆盖 8 个平台 | +| `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` | 该子平台没有实现类 | 目前只有 `WALMART_SC` / `AMAZON_SC` | -| `lingxing shop list is not supported for X` | 该子平台没有店铺接口 | 目前只有亚马逊 SC 有 | +| `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,必须串行调用 | @@ -498,22 +521,34 @@ try { |:---:|:---| | 10001 | `AMAZON_SC` | | 10035 | `AMAZON_VC` | +| 10003 | `EBAY` | +| 10005 / 10031 | `AEPH` | | 10008 | `WALMART_SC` | +| 10010 | `WAYFAIR` | | 10011 | `TIKTOK` | -| 10022 / 10024 | `TEMU` | -| 10003 | `EBAY` | | 10021 / 10027 / 10028 | `SHEIN` | +| 10022 / 10024 | `TEMU` | +| 10029 / 10030 | `ALIEXPRESS` | | 10034 | `MIRAKL` | -| 其它 | `CUSTOM`(调用时会因未注册子平台而失败) | +| 10009 / 10017 / 其它 | `CUSTOM`(同一码下混有多个业务平台,无法用一个枚举表示) | + +> 业务平台以账户的 `AccountKey.platform` 为准,这张表只用于从店铺列表 / 订单行反推。 +> Target / BestBuy / Michaels / ECHO / LOS-DLI-US 在领星侧没有独立平台码。 --- ## 附录:当前实现状态 -| 能力 | 领星·亚马逊 SC | 领星·沃尔玛 | 直连 | -|:---|:---:|:---:|:---:| -| 订单列表 | ❌ | ✅ | ❌ | -| 订单详情 | ❌ | ❌ | ❌ | -| 商品 / Listing | ✅ | ❌ | ❌ | -| 店铺列表 | ✅ | ❌ | — | -| 写操作 | ❌ | ❌ | ❌ | +| 能力 | 亚马逊 SC | 亚马逊 VC | 沃尔玛 | Temu / SHEIN / eBay / TikTok / Target / AliExpress 等 | Direct | +|:---|:---:|:---:|:---:|:---:|:---:| +| 订单列表 | ✅ | ✅ | ✅ | ✅(多平台统一订单) | ❌ | +| 订单详情 | ✅(含 FBM) | ✅ | ❌ | ❌ | ❌ | +| 商品 / Listing | ✅ | ✅ | ✅ | ✅(8 个平台) | ❌ | +| 店铺列表 | ✅ | ✅ | ✅ | ✅ | — | +| 账单 / 结算 | ✅ | ❌ | ❌ | ❌ | ❌ | +| 售后(只读) | ✅ | ❌ | ❌ | ❌ | ❌ | +| 快速出库(写) | ✅ | ✅ | ✅ | ✅ | ❌ | +| 出库单 / 面单 / 审核发货 | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ | +| 订单编辑(写) | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ | + +写接口没有测试环境,联调时**只跑查询**。