|
|
|
@ -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 # 真实环境冒烟(需环境变量) |
|
|
|
``` |
|
|
|
``` |
|
|
|
|