Browse Source

docs: GUIDE / 操作手册 对齐 shared/channel 与领星现状

GUIDE:
- 能力接口清单补齐结算/售后/出库/面单/审核/订单编辑,门面 API 补全视图
- 接入示例改为「适配器不持凭据」,端点与密钥取自 ChannelContext
- 测试分层改为 单测 → 契约(RecordingTransport+夹具)→ 真实冒烟(系统属性传凭据)→ 分页水位线 → 门面能力
- 验收与实现状态表按 channel/shared 模块名更新

操作手册:
- 商品搜索维度 searchField / searchValue / searchValues,及 Target LOCAL_SKU 的显式拒绝
- 商品 / 店铺 / 订单详情的支持范围按实际子平台修正
- platform_code 对照与实现状态表按实测补齐

代码:ChannelAccount 的 credentialRef 注释去掉已废弃的 SecretProvider 说法

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
e1d6621d3d
  1. 173
      GUIDE.md
  2. 6
      channel/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java
  3. 75
      操作手册.md

173
GUIDE.md

@ -127,7 +127,7 @@ public interface PlatformAdapter { @@ -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 { @@ -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)` 是同一个签名。一个同时实现 @@ -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<AggregatorCapable.SubChannel> 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) @@ -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()) { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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() @@ -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")); @@ -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<SalesOrder> 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 { @@ -800,9 +837,11 @@ class AcmeLiveSmokeTest {
```
联调时把请求和响应打出来(token 打码),签名或字段名不对时靠日志定位。
**凭证不要提交到仓库**,联调完重置。
**凭证不要提交到仓库**(提交历史里的密钥要轮换),联调完重置。
> 领星尤其注意:真实环境**只跑查询类接口**。出库、审核发货这类写接口没有测试环境,误操作不可回滚。
### 第 3 层:分页与水位线
### 第 4 层:分页与水位线
```java
@Test
@ -840,7 +879,7 @@ void pagesThroughAllOrdersAndAdvancesWatermarkOnce() { @@ -840,7 +879,7 @@ void pagesThroughAllOrdersAndAdvancesWatermarkOnce() {
- 返回空页 → 立刻结束,不无限循环
- 没有水位线 → 抛 `IllegalStateException`
### 第 4 层:门面 + 能力
### 第 5 层:门面 + 能力
```java
@Test
@ -859,33 +898,6 @@ void facadeRejectsUnsupportedCapability() { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 # 真实环境冒烟(需环境变量)
```

6
channel/src/main/java/common/ecommerce/channel/model/account/ChannelAccount.java

@ -11,8 +11,8 @@ import java.util.Objects; @@ -11,8 +11,8 @@ import java.util.Objects;
/**
* 渠道账户。一个 omsStoreId 可绑定多个 provider 账户。
*
* <p>凭证不落配置:本对象只保存 {@code credentialRef},真实密钥由宿主
* {@code SecretProvider} 按引用取出。</p>
* <p>凭证不落配置:本对象只保存 {@code credentialRef}(账户维度的标识),
* 真实密钥由调用方在每次调用时经 {@code ChannelConnection} 传入,SDK 不保存、不读取。</p>
*/
public final class ChannelAccount {
@ -31,7 +31,7 @@ public final class ChannelAccount { @@ -31,7 +31,7 @@ public final class ChannelAccount {
/** 市场 ID 列表;单市场平台可为空列表。 */
private final List<String> marketplaceIds;
/** 凭证引用(SecretProvider 的键),不是密钥本身。 */
/** 凭证引用(宿主侧密钥条目的标识),不是密钥本身;真实密钥经 ChannelConnection 传入。 */
private final String credentialRef;
/** 市场时区 IANA ID,如 America/Los_Angeles。 */

75
操作手册.md

@ -80,7 +80,7 @@ ChannelAccount account = ChannelAccount.builder() @@ -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() @@ -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( @@ -135,6 +135,8 @@ ChannelConnection conn = ChannelConnection.of(
.build());
```
`credentialRef` 只是账户上的标识,SDK **不会**拿它去取密钥;真实密钥就在上面的 `ChannelSecret` 里。
### 各平台需要的凭据字段
| 平台 | 需要的字段 |
@ -217,7 +219,9 @@ while (page.nextCursor() != null) { @@ -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()) { @@ -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<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 | 沃尔玛 | ❌(未接入) |
| 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()) { @@ -269,6 +290,7 @@ for (ProductListing p : page.items()) {
AccountKey aggregatorKey = AccountKey.of(
ChannelProvider.LINGXING, Platform.AMAZON_SC, "oms-amz-parent");
```java
List<SubChannel> shops = sdk.subChannels(aggregatorKey, conn);
for (SubChannel shop : shops) {
@ -276,6 +298,8 @@ 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) { @@ -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 { @@ -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 { @@ -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 级,全平台共用) | 同左 | 同左 | 同左 | ❌ |
写接口没有测试环境,联调时**只跑查询**。

Loading…
Cancel
Save