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 {
### 3.2 能力接口 ### 3.2 能力接口
供应商实现哪些接口,就声明哪些能力。目前有两个: 供应商实现哪些接口,就声明哪些能力。接口都继承 `PlatformAdapter`:
```java ```java
public interface SalesOrderCapable extends PlatformAdapter { 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`?** **为什么 `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` 根包。 > 对应的 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 ```java
public final class ChannelSdk implements ProviderResolver { public final class ChannelSdk implements ProviderResolver {
public CapabilityReport capabilities(AccountKey key); // 只读,不发请求 public CapabilityReport capabilities(AccountKey key); // 只读,不发请求
public SalesOrders salesOrders(AccountKey key, ChannelConnection conn); // 订单视图 public SalesOrders salesOrders(AccountKey key, ChannelConnection conn); // 订单视图
public Products products(AccountKey key, ChannelConnection conn); // 商品视图 public Products products(AccountKey key, ChannelConnection conn); // 商品视图
public IdempotencyGuard writes(); // 写操作守卫 public Settlements settlements(AccountKey key, ChannelConnection conn); // 账单视图(读)
public PlatformAdapter resolve(AccountKey key); // 按 key 找适配器 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、不自动兜底、不重试、不缓存。 门面**不做**:不选 provider、不自动兜底、不重试、不缓存。
每次调用固定三步: 每次调用固定三步:
@ -190,12 +209,13 @@ key → accountRepository.findByKey(provider, platform, omsStoreId)
| SPI | 作用 | 读要用 | 写要用 | | SPI | 作用 | 读要用 | 写要用 |
|:---|:---|:---:|:---:| |:---|:---|:---:|:---:|
| `ChannelAccountRepository` | 读渠道账户 | ✅ | ✅ | | `ChannelAccountRepository`(channel) | 读渠道账户 | ✅ | ✅ |
| `ChannelSecret` | 凭据载体,调用时经 `ChannelConnection` 传入 | ✅ | ✅ |
| `SecretProvider` | ~~按 credentialRef 取密钥~~ **已废弃**:凭据由调用方传入 | — | — | | `SecretProvider` | ~~按 credentialRef 取密钥~~ **已废弃**:凭据由调用方传入 | — | — |
| `TokenStore` | token 读写(宿主加密) | ✅ | ✅ | | `TokenStore` | token 读写(宿主加密) | ✅ | ✅ |
| `LockProvider` | token 刷新防击穿 | ✅ | ✅ | | `LockProvider` | token 刷新防击穿 | ✅ | ✅ |
| `SyncCursorStore` | 水位线 | 批量读 | — | | `SyncCursorStore` | 水位线 | 批量读 | — |
| `Sink` | 领域对象落库 | 批量读 | — | | `Sink`(channel) | 领域对象落库 | 批量读 | — |
| `IdempotencyStore` | 幂等键抢占与结果 | — | ✅ | | `IdempotencyStore` | 幂等键抢占与结果 | — | ✅ |
### 3.5 错误类型 ### 3.5 错误类型
@ -359,19 +379,19 @@ if (r.alreadyCompleted()) {
## 五、加一个供应商:8 步 ## 五、加一个供应商:8 步
以新增 `acme` 直连平台为例。**核心原则:不改 core、不改门面、不改宿主。** 以新增 `acme` 直连平台为例。**核心原则:不改 channel、不改门面、不改宿主。**
### 第 0 步:先想清楚三件事 ### 第 0 步:先想清楚三件事
| 问题 | 影响 | | 问题 | 影响 |
|:---|:---| |:---|:---|
| 它属于哪个 `Platform`? | 枚举里有直接用;没有才加(唯一允许改 core 的地方) | | 它属于哪个 `Platform`? | 枚举里有直接用;没有才加(唯一允许改 `shared` 的地方) |
| 走 `DIRECT` 还是新聚合器? | 新聚合器才加 `ChannelProvider` 枚举值 | | 走 `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` - `ChannelProvider`:`DIRECT` `LINGXING` `TEAPPLIX` `CUSTOM`
### 第 1 步:建模块 ### 第 1 步:建模块
@ -460,7 +480,7 @@ public final class AcmeOrderDto {
**平台字段名只允许出现在 DTO 和 Mapper 里。** **平台字段名只允许出现在 DTO 和 Mapper 里。**
**DTO 用 Lombok,领域模型不用。** DTO 是纯数据容器,没有不变量要保护,`@Getter`/`@Setter` **DTO 用 Lombok,领域模型不用。** DTO 是纯数据容器,没有不变量要保护,`@Getter`/`@Setter`
省掉全部样板;`core` 的模型是不可变 + Builder,本来就没有 setter,且 `core` 要尽量少依赖 省掉全部样板;`channel` 的模型是不可变 + Builder,本来就没有 setter,且 `channel` 要尽量少依赖
编译期工具。Lombok 声明为 `scope=provided`,不进宿主运行时。 编译期工具。Lombok 声明为 `scope=provided`,不进宿主运行时。
**端点和路径写成常量,不做配置。** 协议细节(URL、字段名、限流值)是代码的一部分—— **端点和路径写成常量,不做配置。** 协议细节(URL、字段名、限流值)是代码的一部分——
@ -564,27 +584,23 @@ public final class AcmeSigner {
```java ```java
public final class AcmeAdapter implements SalesOrderCapable { public final class AcmeAdapter implements SalesOrderCapable {
private final String baseUrl;
private final HttpTransport transport; private final HttpTransport transport;
private final JacksonJsonCodec json; private final JacksonJsonCodec json;
private final SecretProvider secretProvider;
private final Clock clock; private final Clock clock;
private final TokenManager tokenManager; private final TokenManager tokenManager;
private final AcmeOrderMapper mapper = new AcmeOrderMapper(); private final AcmeOrderMapper mapper = new AcmeOrderMapper();
public AcmeAdapter(String baseUrl, HttpTransport transport, JacksonJsonCodec json, // 适配器只持有协议与基础设施:端点与凭据随每次调用的 ChannelContext 进来
SecretProvider secretProvider, TokenStore tokenStore, public AcmeAdapter(HttpTransport transport, JacksonJsonCodec json,
LockProvider lockProvider, Clock clock) { TokenStore tokenStore, LockProvider lockProvider, Clock clock) {
this.baseUrl = baseUrl;
this.transport = transport; this.transport = transport;
this.json = json; this.json = json;
this.secretProvider = secretProvider;
this.clock = clock; 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) { this.tokenManager = new TokenManager(tokenStore, lockProvider, clock, 600) {
@Override @Override
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) { 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() HttpRequest req = HttpRequest.builder()
.method("POST") .method("POST")
.url(baseUrl + AcmeConstants.PATH_ORDERS) .url(ctx.endpointBaseUrl() + AcmeConstants.PATH_ORDERS) // ★ 端点来自 ctx
.header("Content-Type", "application/json") .header("Content-Type", "application/json")
.header("Authorization", authHeader(ctx)) .header("Authorization", authHeader(ctx))
.header("X-Request-Id", ctx.requestId()) .header("X-Request-Id", ctx.requestId())
@ -645,8 +661,8 @@ public final class AcmeAdapter implements SalesOrderCapable {
private String authHeader(ChannelContext ctx) { private String authHeader(ChannelContext ctx) {
ChannelAccount account = ctx.account(); ChannelAccount account = ctx.account();
ChannelSecret secret = secretProvider.get(account.credentialRef()); // 凭据由调用方经 ChannelConnection 传入,适配器不自己去找
AccessToken token = tokenManager.getOrRefresh("acme:" + account.externalStoreId(), secret); AccessToken token = tokenManager.getOrRefresh("acme:" + account.externalStoreId(), ctx.secret());
return token.tokenType() + " " + token.value(); return token.tokenType() + " " + token.value();
} }
@ -677,13 +693,11 @@ public final class AcmeAdapter implements SalesOrderCapable {
```java ```java
public final class AcmeAdapterFactory implements AdapterFactory { public final class AcmeAdapterFactory implements AdapterFactory {
private final SecretProvider secretProvider;
private final TokenStore tokenStore; private final TokenStore tokenStore;
private final LockProvider lockProvider; private final LockProvider lockProvider;
private final Clock clock; private final Clock clock;
public AcmeAdapterFactory(SecretProvider secretProvider, TokenStore tokenStore, public AcmeAdapterFactory(TokenStore tokenStore, LockProvider lockProvider, Clock clock) { ... }
LockProvider lockProvider, Clock clock) { ... }
@Override public String adapterId() { return AcmeConstants.ADAPTER_ID; } @Override public String adapterId() { return AcmeConstants.ADAPTER_ID; }
@Override public ChannelProvider provider() { return ChannelProvider.DIRECT; } @Override public ChannelProvider provider() { return ChannelProvider.DIRECT; }
@ -691,17 +705,15 @@ public final class AcmeAdapterFactory implements AdapterFactory {
@Override @Override
public PlatformAdapter create(AdapterConfig config) { public PlatformAdapter create(AdapterConfig config) {
String baseUrl = config.endpointBaseUrl() == null // 生产端点由调用方的 ChannelConnection 提供;config 只用于测试/联调时覆盖目标地址
? AcmeConstants.DEFAULT_BASE_URL : config.endpointBaseUrl(); return new AcmeAdapter(new OkHttpTransport("common-ecommerce/1.0.0 (acme)"),
return new AcmeAdapter(baseUrl, new JacksonJsonCodec(), tokenStore, lockProvider, clock);
new OkHttpTransport("common-ecommerce/1.0.0 (acme)"),
new JacksonJsonCodec(),
secretProvider, tokenStore, lockProvider, clock);
} }
} }
``` ```
工厂的意义:把「怎么 new」和「业务怎么用」隔开。宿主只注册工厂,不需要知道构造参数。 工厂的意义:把「怎么 new」和「业务怎么用」隔开。宿主只注册工厂,不需要知道构造参数。
**工厂不持有凭据**——凭据随每次调用的 `ChannelConnection` 进来。
### 第 8 步:接进门面 ### 第 8 步:接进门面
@ -710,7 +722,7 @@ ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(accountRepo) .accountRepository(accountRepo)
.idempotencyStore(idempotencyStore) // 要写操作就必须 .idempotencyStore(idempotencyStore) // 要写操作就必须
.idempotencyOwner(hostName) // 多实例时区分抢占方 .idempotencyOwner(hostName) // 多实例时区分抢占方
.register(new AcmeAdapterFactory(secretProvider, tokenStore, lockProvider, clock)) .register(new AcmeAdapterFactory(tokenStore, lockProvider, clock))
.build(); .build();
AccountKey key = AccountKey.of(ChannelProvider.DIRECT, Platform.AMAZON_SC, "oms-amz-001"); 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 美国太平洋时区进入夏令时,前后各测一次。 时间相关的用 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);
做法:在测试类顶部写常量(本地联调时填真实值,不提交),用真实的 Page<SalesOrder> page = adapter.pull(ctx, query);
`OkHttpTransport` 直接打平台接口;未填常量时用 `Assumptions` 跳过,
避免占位串打到线上。 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 ```java
class AcmeLiveSmokeTest { class AcmeLiveSmokeTest {
private static final String APP_KEY = "在这里填 AppID"; private static final String APP_KEY = System.getProperty("acme.probe.appKey", "");
private static final String APP_SECRET = "在这里填 AppSecret"; private static final String APP_SECRET = System.getProperty("acme.probe.appSecret", "");
private final HttpTransport transport = new OkHttpTransport("common-ecommerce-smoke"); private final HttpTransport transport = new OkHttpTransport("common-ecommerce-smoke");
@Test @Test
void tokenCanBeFetched() { void tokenCanBeFetched() {
Assumptions.assumeTrue(!APP_KEY.isEmpty() && !APP_SECRET.isEmpty(), "未提供凭据,跳过");
AccessToken token = new AcmeTokenClient(transport, json, Clock.systemUTC()) AccessToken token = new AcmeTokenClient(transport, json, Clock.systemUTC())
.fetch(BASE_URL, APP_KEY, APP_SECRET); .fetch(BASE_URL, APP_KEY, APP_SECRET);
assertNotNull(token.value()); assertNotNull(token.value());
@ -800,9 +837,11 @@ class AcmeLiveSmokeTest {
``` ```
联调时把请求和响应打出来(token 打码),签名或字段名不对时靠日志定位。 联调时把请求和响应打出来(token 打码),签名或字段名不对时靠日志定位。
**凭证不要提交到仓库**,联调完重置。 **凭证不要提交到仓库**(提交历史里的密钥要轮换),联调完重置。
> 领星尤其注意:真实环境**只跑查询类接口**。出库、审核发货这类写接口没有测试环境,误操作不可回滚。
### 第 3 层:分页与水位线 ### 第 4 层:分页与水位线
```java ```java
@Test @Test
@ -840,7 +879,7 @@ void pagesThroughAllOrdersAndAdvancesWatermarkOnce() {
- 返回空页 → 立刻结束,不无限循环 - 返回空页 → 立刻结束,不无限循环
- 没有水位线 → 抛 `IllegalStateException` - 没有水位线 → 抛 `IllegalStateException`
### 第 4 层:门面 + 能力 ### 第 5 层:门面 + 能力
```java ```java
@Test @Test
@ -859,33 +898,6 @@ void facadeRejectsUnsupportedCapability() {
聚合器还要额外测:同一适配器,Walmart 账户和 eBay 账户的 `supports` 结果不同。 聚合器还要额外测:同一适配器,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 里的起止时间 | | 7 | 超长时间窗会截断 | 断言 body 里的起止时间 |
| 8 | 写操作只执行一次 | `adapter.writeCallCount() == 1` | | 8 | 写操作只执行一次 | `adapter.writeCallCount() == 1` |
| 9 | 水位线失败不推进 | 第二页抛异常后断言水位线不变 | | 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 模板可用 | | http | OkHttp 传输、Jackson 编解码、签名接口、TokenManager 模板可用 |
| testkit | InMemory SPI、FakeDirectAdapter、MutableClock 可用 | | testkit | InMemory SPI、FakeDirectAdapter、MutableClock 可用 |
| lingxing | 订单列表拉取可用;商品、履约、面单、账单、售后未实现 | | lingxing | 16 个子平台:订单 / 店铺全量;商品 8 个平台;结算、售后目前只有亚马逊 SC;出库单 / 面单 / 审核发货 / 订单编辑为 ERP 级、全平台共用 |
| 其它平台 | 未开始 | | 其它平台 | 未开始 |
### 编码坑(按踩到概率排序) ### 编码坑(按踩到概率排序)
@ -940,7 +953,7 @@ class AcmeLiveSmokeTest {
| `RefundLedger` 未实现 | 无超退校验 | 与 `IdempotencyGuard` 配合 | | `RefundLedger` 未实现 | 无超退校验 | 与 `IdempotencyGuard` 配合 |
| `DuplicateOrderGuard` 未实现 | 跨 provider 重复订单无告警 | 新增 SPI | | `DuplicateOrderGuard` 未实现 | 跨 provider 重复订单无告警 | 新增 SPI |
| 领星时间窗超 31 天被静默截断 | 水位线落后太多会漏中间段 | 调用方分段补拉 | | 领星时间窗超 31 天被静默截断 | 水位线落后太多会漏中间段 | 调用方分段补拉 |
| 领星单订单详情未实现 | `get()` 直接抛异常 | 用 `pull` + 时间窗捞 | | 领星单订单详情未实现 | 除亚马逊 SC / VC 外的子平台 `get()` 直接抛异常 | 用 `pull` + 时间窗捞 |
| 领星限流器用 `Thread.sleep` | 多店并发时按实例数放大 | 按账户拆适配器实例,或换通用限流器 | | 领星限流器用 `Thread.sleep` | 多店并发时按实例数放大 | 按账户拆适配器实例,或换通用限流器 |
--- ---
@ -948,7 +961,7 @@ class AcmeLiveSmokeTest {
## 九、上手顺序 ## 九、上手顺序
1. **读三个文件**:`PlatformAdapter`、`SalesOrderCapable`、`ChannelSdk`。不到 150 行,看懂这三个就懂一半。 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`。 3. **抄领星的结构**建新模块:`Constants → Dto → Mapper → Adapter → Factory → Test`。
4. **先用夹具跑通,再连真实环境。** 不要反过来。 4. **先用夹具跑通,再连真实环境。** 不要反过来。
@ -957,6 +970,6 @@ class AcmeLiveSmokeTest {
```bash ```bash
mvn clean test # 全部 mvn clean test # 全部
mvn -pl lingxing -am 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 # 真实环境冒烟(需环境变量) 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;
/** /**
* 渠道账户。一个 omsStoreId 可绑定多个 provider 账户。 * 渠道账户。一个 omsStoreId 可绑定多个 provider 账户。
* *
* <p>凭证不落配置:本对象只保存 {@code credentialRef},真实密钥由宿主 * <p>凭证不落配置:本对象只保存 {@code credentialRef}(账户维度的标识),
* {@code SecretProvider} 按引用取出。</p> * 真实密钥由调用方在每次调用时经 {@code ChannelConnection} 传入,SDK 不保存、不读取。</p>
*/ */
public final class ChannelAccount { public final class ChannelAccount {
@ -31,7 +31,7 @@ public final class ChannelAccount {
/** 市场 ID 列表;单市场平台可为空列表。 */ /** 市场 ID 列表;单市场平台可为空列表。 */
private final List<String> marketplaceIds; private final List<String> marketplaceIds;
/** 凭证引用(SecretProvider 的键),不是密钥本身。 */ /** 凭证引用(宿主侧密钥条目的标识),不是密钥本身;真实密钥经 ChannelConnection 传入。 */
private final String credentialRef; private final String credentialRef;
/** 市场时区 IANA ID,如 America/Los_Angeles。 */ /** 市场时区 IANA ID,如 America/Los_Angeles。 */

75
操作手册.md

@ -80,7 +80,7 @@ ChannelAccount account = ChannelAccount.builder()
.externalStoreId("1108413237731") .externalStoreId("1108413237731")
// 领星 platform_code;直连账户不填 // 领星 platform_code;直连账户不填
.platformCode(10008) .platformCode(10008)
// 密钥引用(如果宿主仍用 SecretProvider 取密钥) // 密钥引用(宿主侧密钥条目的标识);真实密钥经 ChannelConnection 传入,见第三节
.credentialRef("kms://oms/lingxing/store-001") .credentialRef("kms://oms/lingxing/store-001")
// 市场当地时区,必须是合法 IANA 时区 // 市场当地时区,必须是合法 IANA 时区
.marketplaceZone("America/Los_Angeles") .marketplaceZone("America/Los_Angeles")
@ -94,7 +94,7 @@ ChannelAccount account = ChannelAccount.builder()
| `key` | ✅ | `provider + platform + omsStoreId`,SDK 的隔离维度 | | `key` | ✅ | `provider + platform + omsStoreId`,SDK 的隔离维度 |
| `externalStoreId` | ✅ | 平台店铺 ID。领星传 `store_id`;亚马逊 SC 传 `sid` | | `externalStoreId` | ✅ | 平台店铺 ID。领星传 `store_id`;亚马逊 SC 传 `sid` |
| `platformCode` | 领星必填 | 见 [platform_code 对照](#领星-platform_code-对照) | | `platformCode` | 领星必填 | 见 [platform_code 对照](#领星-platform_code-对照) |
| `credentialRef` | ✅ | 密钥引用,不是密钥本身 | | `credentialRef` | ✅ | 密钥引用标识,不是密钥本身;真实密钥经 `ChannelConnection` 传入 |
| `marketplaceZone` | ✅ | 必须是 `ZoneId.of(...)` 能解析的值 | | `marketplaceZone` | ✅ | 必须是 `ZoneId.of(...)` 能解析的值 |
| `currency` | ✅ | ISO 4217 | | `currency` | ✅ | ISO 4217 |
@ -135,6 +135,8 @@ ChannelConnection conn = ChannelConnection.of(
.build()); .build());
``` ```
`credentialRef` 只是账户上的标识,SDK **不会**拿它去取密钥;真实密钥就在上面的 `ChannelSecret` 里。
### 各平台需要的凭据字段 ### 各平台需要的凭据字段
| 平台 | 需要的字段 | | 平台 | 需要的字段 |
@ -217,7 +219,9 @@ while (page.nextCursor() != null) {
SalesOrder order = sdk.salesOrders(key, conn).get("PO-123456789"); 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` | | 同上 | | `updatedBefore` | `Instant` | | 同上 |
| `pageSize` | `int` | | 亚马逊 Listing 上限 1000 | | `pageSize` | `int` | | 亚马逊 Listing 上限 1000 |
| `cursor` | `String` | | 上一页游标 | | `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 | 平台 | 是否支持 | | provider | 平台 | 是否支持 |
|:---|:---|:---:| |:---|:---|:---:|
| LINGXING | 亚马逊 SC | ✅ | | LINGXING | 亚马逊 SC | ✅ |
| LINGXING | 沃尔玛 | ❌(未接入) | | LINGXING | 亚马逊 VC / 沃尔玛 / eBay / Temu / SHEIN / TikTok / Target / AliExpress | ✅ |
| LINGXING | eBay / SHEIN 等 | ❌ | | LINGXING | 其它子平台(BestBuy / AEPH / Michaels / Echo / Losdlius / Custom …) | ❌ 商品接口未接入 |
| DIRECT | — | ❌ 暂无直连适配器 |
不支持时会抛 `ChannelException.UnsupportedCapabilityException: PRODUCT`。 不支持时会抛 `ChannelException.UnsupportedCapabilityException: PRODUCT`。
@ -269,6 +290,7 @@ for (ProductListing p : page.items()) {
AccountKey aggregatorKey = AccountKey.of( AccountKey aggregatorKey = AccountKey.of(
ChannelProvider.LINGXING, Platform.AMAZON_SC, "oms-amz-parent"); ChannelProvider.LINGXING, Platform.AMAZON_SC, "oms-amz-parent");
```java
List<SubChannel> shops = sdk.subChannels(aggregatorKey, conn); List<SubChannel> shops = sdk.subChannels(aggregatorKey, conn);
for (SubChannel shop : shops) { for (SubChannel shop : shops) {
@ -276,6 +298,8 @@ for (SubChannel shop : shops) {
shop.externalStoreId(); // 领星店铺 sid,如 "1519" shop.externalStoreId(); // 领星店铺 sid,如 "1519"
shop.platform(); // Platform.AMAZON_SC shop.platform(); // Platform.AMAZON_SC
shop.name(); // 店铺名 shop.name(); // 店铺名
shop.status(); // 授权状态原值
shop.region(); // 站点简称,如 na
// 用它构造账户 // 用它构造账户
ChannelAccount account = ChannelAccount.builder() ChannelAccount account = ChannelAccount.builder()
@ -294,8 +318,8 @@ for (SubChannel shop : shops) {
| provider | 平台 | 接口 | | provider | 平台 | 接口 |
|:---|:---|:---| |:---|:---|:---|
| LINGXING | 亚马逊 SC | `/erp/sc/data/seller/lists` ✅ | | LINGXING | 亚马逊 SC / VC | `/erp/sc/data/seller/lists` ✅ |
| LINGXING | 沃尔玛 / eBay / … | ❌ | | LINGXING | 沃尔玛 / eBay / Temu / SHEIN / TikTok / Target / AliExpress / Wayfair / Mirakl / BestBuy / AEPH / Michaels / Echo / Losdlius / Custom | 多平台店铺接口 `/pb/mp/shop/v2/getSellerList` ✅ |
返回的店铺会**过滤掉非正常状态**(领星 `status != 1` 的店铺)。 返回的店铺会**过滤掉非正常状态**(领星 `status != 1` 的店铺)。
@ -478,11 +502,10 @@ try {
| 现象 | 原因 | 处理 | | 现象 | 原因 | 处理 |
|:---|:---|:---| |:---|:---|:---|
| `channel account not configured` | `findByKey` 没查到 | 检查 `provider/platform/omsStoreId` 三个值是否与账户一致 | | `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` | | `duplicate adapter for ...` | 同一 `provider + platform` 注册了两次 | 去掉重复的 `register` |
| `UnsupportedCapabilityException` | 适配器不声明该能力 | 先 `capabilities()` 判断,或换 provider | | `UnsupportedCapabilityException` | 适配器不声明该能力 | 先 `capabilities()` 判断,或换 provider |
| `lingxing sub platform not implemented: X` | 该子平台没有实现类 | 目前只有 `WALMART_SC` / `AMAZON_SC` | | `lingxing sub platform not implemented: X` | 该子平台没有注册到 `LingxingSubPlatforms` | 对照 `LingxingSubPlatformDefaults.all(...)` 的注册清单 |
| `lingxing shop list is not supported for X` | 该子平台没有店铺接口 | 目前只有亚马逊 SC 有 |
| `lingxing code=102 msg=参数不合法` | 请求参数不对 | 检查 `sid` / `platform_code` / 时间格式 | | `lingxing code=102 msg=参数不合法` | 请求参数不对 | 检查 `sid` / `platform_code` / 时间格式 |
| `lingxing code=2001013 app authentication failed` | AppID/AppSecret 错误 | 检查凭据;确认出口 IP 在白名单 | | `lingxing code=2001013 app authentication failed` | AppID/AppSecret 错误 | 检查凭据;确认出口 IP 在白名单 |
| `lingxing code=3001008` | 触发限流 | 该接口 qps=1,必须串行调用 | | `lingxing code=3001008` | 触发限流 | 该接口 qps=1,必须串行调用 |
@ -498,22 +521,34 @@ try {
|:---:|:---| |:---:|:---|
| 10001 | `AMAZON_SC` | | 10001 | `AMAZON_SC` |
| 10035 | `AMAZON_VC` | | 10035 | `AMAZON_VC` |
| 10003 | `EBAY` |
| 10005 / 10031 | `AEPH` |
| 10008 | `WALMART_SC` | | 10008 | `WALMART_SC` |
| 10010 | `WAYFAIR` |
| 10011 | `TIKTOK` | | 10011 | `TIKTOK` |
| 10022 / 10024 | `TEMU` |
| 10003 | `EBAY` |
| 10021 / 10027 / 10028 | `SHEIN` | | 10021 / 10027 / 10028 | `SHEIN` |
| 10022 / 10024 | `TEMU` |
| 10029 / 10030 | `ALIEXPRESS` |
| 10034 | `MIRAKL` | | 10034 | `MIRAKL` |
| 其它 | `CUSTOM`(调用时会因未注册子平台而失败) | | 10009 / 10017 / 其它 | `CUSTOM`(同一码下混有多个业务平台,无法用一个枚举表示) |
> 业务平台以账户的 `AccountKey.platform` 为准,这张表只用于从店铺列表 / 订单行反推。
> Target / BestBuy / Michaels / ECHO / LOS-DLI-US 在领星侧没有独立平台码。
--- ---
## 附录:当前实现状态 ## 附录:当前实现状态
| 能力 | 领星·亚马逊 SC | 领星·沃尔玛 | 直连 | | 能力 | 亚马逊 SC | 亚马逊 VC | 沃尔玛 | Temu / SHEIN / eBay / TikTok / Target / AliExpress 等 | Direct |
|:---|:---:|:---:|:---:| |:---|:---:|:---:|:---:|:---:|:---:|
| 订单列表 | ❌ | ✅ | ❌ | | 订单列表 | ✅ | ✅ | ✅ | ✅(多平台统一订单) | ❌ |
| 订单详情 | ❌ | ❌ | ❌ | | 订单详情 | ✅(含 FBM) | ✅ | ❌ | ❌ | ❌ |
| 商品 / Listing | ✅ | ❌ | ❌ | | 商品 / Listing | ✅ | ✅ | ✅ | ✅(8 个平台) | ❌ |
| 店铺列表 | ✅ | ❌ | — | | 店铺列表 | ✅ | ✅ | ✅ | ✅ | — |
| 写操作 | ❌ | ❌ | ❌ | | 账单 / 结算 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 售后(只读) | ✅ | ❌ | ❌ | ❌ | ❌ |
| 快速出库(写) | ✅ | ✅ | ✅ | ✅ | ❌ |
| 出库单 / 面单 / 审核发货 | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ |
| 订单编辑(写) | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ |
写接口没有测试环境,联调时**只跑查询**。

Loading…
Cancel
Save