Browse Source

feat(lingxing): 订单列表回传原始报文

- sdk-common 新增 shared.raw:RawExchange / RawItem / RawPage / RawCapturePolicy
  - 门面新增 SalesOrders.pullWithRaw 与 RawSalesOrderCapable,pull() 行为与开销不变
  - LingxingCall 支持可选 RawRecorder:execute 时采集请求/响应,envelope 回填业务码与 platform_request_id
  - 四条订单列表路由声明 rawItemPath(多平台 data.list,SC/FBM/VC 为 data),适配器提供 pullRaw(含 filters 重载)
  - 修复 MultiPlatformOrderSource 绕过 call.execute 的问题,否则多平台路由采集不到报文
  - 新增 25 条单测/契约测试;真实冒烟测试补原文回传用例
master
lml 11 hours ago
parent
commit
793776f654
  1. 3
      README.md
  2. 28
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RawSalesOrderCapable.java
  3. 60
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java
  4. 47
      lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java
  5. 11
      lingxing/src/main/java/common/ecommerce/lingxing/http/LingxingEnvelope.java
  6. 32
      lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingCall.java
  7. 10
      lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderSource.java
  8. 159
      lingxing/src/main/java/common/ecommerce/lingxing/platform/RawRecorder.java
  9. 6
      lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonFbmOrderSource.java
  10. 6
      lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonOrderSource.java
  11. 6
      lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/order/VcOrderSource.java
  12. 10
      lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformOrderSource.java
  13. 77
      lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java
  14. 218
      lingxing/src/test/java/common/ecommerce/lingxing/platform/RawRecorderTest.java
  15. 88
      lingxing/src/test/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformRawPullTest.java
  16. 24
      lingxing/src/test/java/common/ecommerce/lingxing/support/LingxingTestSupport.java
  17. 99
      sdk-common/src/main/java/common/ecommerce/shared/raw/RawCapturePolicy.java
  18. 352
      sdk-common/src/main/java/common/ecommerce/shared/raw/RawExchange.java
  19. 52
      sdk-common/src/main/java/common/ecommerce/shared/raw/RawItem.java
  20. 117
      sdk-common/src/main/java/common/ecommerce/shared/raw/RawPage.java
  21. 74
      sdk-common/src/test/java/common/ecommerce/shared/raw/RawExchangeTest.java
  22. 73
      sdk-common/src/test/java/common/ecommerce/shared/raw/RawPageTest.java
  23. 161
      sdk-testkit/src/test/java/common/ecommerce/shared/testkit/RawSalesOrderFacadeTest.java
  24. 16
      操作手册.md

3
README.md

@ -1125,4 +1125,7 @@ mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 渠道 / 商品 / 出 @@ -1125,4 +1125,7 @@ mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 渠道 / 商品 / 出
## 设计文档
- [`GUIDE.md`](GUIDE.md):开发指南 —— 心智模型、基接口逐个讲、接入新平台 8 步、5 层测试
- [`操作手册.md`](操作手册.md):宿主接入必读 —— 依赖坐标、装配、各能力调用、异常与 SPI
- [`docs/lingxing-order-raw-integration-guide.md`](docs/lingxing-order-raw-integration-guide.md):领星订单原始报文回传接入指南(宿主调用方)
- [`docs/design/lingxing-order-raw-payload.md`](docs/design/lingxing-order-raw-payload.md):原始报文回传的设计与实现(含表结构、二期规划)
- OMS 侧 `cross-border-fulfillment-sdk-design.md`(Spec 0 总体设计)

28
channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RawSalesOrderCapable.java

@ -0,0 +1,28 @@ @@ -0,0 +1,28 @@
package common.ecommerce.channel.capability;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.shared.raw.RawCapturePolicy;
import common.ecommerce.shared.raw.RawPage;
/**
* 可回传原始报文的订单能力。
*
* <p>与 {@link SalesOrderCapable} 分开声明:不需要原文的适配器(如沃尔玛直连)
* 不必被迫实现;门面在能力检查阶段就会拒绝,而不是返回一个没有原文的空壳。</p>
*
* <p>实现方只需在发请求时让 {@code LingxingCall} 带上采集器,业务映射代码不用改。</p>
*/
public interface RawSalesOrderCapable extends SalesOrderCapable {
/**
* 分页拉取销售订单,并带回原始响应。
*
* @param ctx 调用上下文
* @param query 时间窗与分页条件
* @param policy 采集策略;传 null 时由适配器使用默认策略
* @return 业务结果 + 整页原文 + 逐条原文
*/
RawPage<SalesOrder> pullRaw(ChannelContext ctx, SalesOrderQuery query, RawCapturePolicy policy);
}

60
channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java

@ -12,6 +12,8 @@ import common.ecommerce.channel.model.order.SalesOrderQuery; @@ -12,6 +12,8 @@ import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.order.SalesOrderRef;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.audit.CallSupport;
import common.ecommerce.shared.raw.RawCapturePolicy;
import common.ecommerce.shared.raw.RawPage;
import common.ecommerce.channel.sdk.ChannelContext;
import java.util.List;
@ -79,6 +81,40 @@ public final class SalesOrders { @@ -79,6 +81,40 @@ public final class SalesOrders {
}
/**
* 分页拉取销售订单,同时带回平台原始报文。
*
* <p>与 {@link #pull(SalesOrderQuery)} 是两条独立路径:只有本方法会采集原文,
* {@code pull()} 永远不分配采集缓冲。未实现 {@link RawSalesOrderCapable} 的适配器
* 会明确拒绝,不返回没有原文的结果。</p>
*
* @throws ChannelException.UnsupportedCapabilityException 适配器未声明 SALES_ORDER 或未实现 SalesOrderCapable
* @throws ChannelException 适配器不支持原文回传
*/
public RawPage<SalesOrder> pullWithRaw(final SalesOrderQuery query) {
return pullWithRaw(query, RawCapturePolicy.defaults());
}
/**
* 同上,可指定采集策略(体积上限、是否带请求体、是否逐条切片)。
*
* @param policy 为 null 时使用 {@link RawCapturePolicy#defaults()}
*/
public RawPage<SalesOrder> pullWithRaw(final SalesOrderQuery query, final RawCapturePolicy policy) {
final RawCapturePolicy effective = policy == null ? RawCapturePolicy.defaults() : policy;
return CallSupport.observe(observer, ctx, "salesOrders.pullWithRaw",
CallSupport.params(
"updatedAfter", query.updatedAfter(),
"updatedBefore", query.updatedBefore(),
"pageSize", query.pageSize(),
"cursor", query.cursor()),
page -> page.size(),
() -> {
requireRawSalesOrderCapable();
return ((RawSalesOrderCapable) adapter).pullRaw(ctx, query, effective);
});
}
/**
* 按平台订单号取单个订单。
*
* @throws ChannelException.UnsupportedCapabilityException 适配器未声明 SALES_ORDER 或未实现 SalesOrderCapable
@ -166,4 +202,28 @@ public final class SalesOrders { @@ -166,4 +202,28 @@ public final class SalesOrders {
throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER);
}
}
/**
* 原文回传的能力检查:先要支持订单,再要求实现了 {@link RawSalesOrderCapable}。
*
* <p>不支持原文时抛普通 {@link ChannelException} 而不是
* {@code UnsupportedCapabilityException}——订单能力本身是有的,
* 缺的是「回传原文」这个扩展,报错要说清楚,别让人误以为是订单不支持。</p>
*/
private void requireRawSalesOrderCapable() {
if (!adapter.supports(account, Capability.SALES_ORDER)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER);
}
if (!(adapter instanceof RawSalesOrderCapable)) {
throw ChannelException.builder()
.message("adapter " + adapter.adapterId() + " does not support raw payload return")
.operation("salesOrders.pullWithRaw")
.provider(account.provider().name())
.omsStoreId(account.omsStoreId())
.platform(account.platform())
.requestId(ctx.requestId())
.retryable(false)
.build();
}
}
}

47
lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java

@ -6,6 +6,7 @@ import common.ecommerce.channel.capability.OrderEditCapable; @@ -6,6 +6,7 @@ import common.ecommerce.channel.capability.OrderEditCapable;
import common.ecommerce.channel.capability.OutboundCapable;
import common.ecommerce.channel.capability.OutboundOrderCapable;
import common.ecommerce.channel.capability.ProductCapable;
import common.ecommerce.channel.capability.RawSalesOrderCapable;
import common.ecommerce.channel.capability.SalesOrderCapable;
import common.ecommerce.channel.capability.SettlementCapable;
import common.ecommerce.channel.capability.ShipmentReviewCapable;
@ -30,6 +31,7 @@ import common.ecommerce.lingxing.platform.LingxingSubPlatform; @@ -30,6 +31,7 @@ import common.ecommerce.lingxing.platform.LingxingSubPlatform;
import common.ecommerce.lingxing.platform.LingxingSubPlatformDefaults;
import common.ecommerce.lingxing.platform.LingxingOutboundSource;
import common.ecommerce.lingxing.platform.LingxingSubPlatforms;
import common.ecommerce.lingxing.platform.RawRecorder;
import common.ecommerce.lingxing.platform.multiplatform.order.LingxingOrderFilters;
import common.ecommerce.lingxing.platform.wms.OrderEditSource;
import common.ecommerce.lingxing.platform.wms.ShipmentReviewSource;
@ -64,6 +66,8 @@ import common.ecommerce.channel.model.product.ProductSyncStrategy; @@ -64,6 +66,8 @@ import common.ecommerce.channel.model.product.ProductSyncStrategy;
import common.ecommerce.channel.model.settlement.SettlementQuery;
import common.ecommerce.channel.model.settlement.SettlementTransaction;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.raw.RawCapturePolicy;
import common.ecommerce.shared.raw.RawPage;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.shared.spi.ChannelSecret;
@ -85,8 +89,8 @@ import java.util.Set; @@ -85,8 +89,8 @@ import java.util.Set;
* 具体的「拼请求体 + 解析响应」由各子平台的 Source 实现,见
* {@link LingxingSubPlatform}。</p>
*/
public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, SettlementCapable,
OutboundCapable, AfterSaleCapable, OutboundOrderCapable, ShippingLabelCapable,
public final class LingxingAdapter implements SalesOrderCapable, RawSalesOrderCapable, ProductCapable,
SettlementCapable, OutboundCapable, AfterSaleCapable, OutboundOrderCapable, ShippingLabelCapable,
ShipmentReviewCapable, OrderEditCapable, InboundShipmentCapable, InboundReceiptCapable,
AggregatorCapable {
@ -298,6 +302,34 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -298,6 +302,34 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
filters == null ? LingxingOrderFilters.none() : filters);
}
/**
* 分页拉取订单,同时回传原始报文;门面 {@code pullWithRaw} 的落点。
*
* <p>采集器只在本次调用内存在,业务映射代码完全不用改。</p>
*/
@Override
public RawPage<SalesOrder> pullRaw(ChannelContext ctx, SalesOrderQuery query, RawCapturePolicy policy) {
return pullRaw(ctx, query, LingxingOrderFilters.none(), policy);
}
/**
* 同上,附加领星专有过滤条件(按平台单号 / 系统单号 / 跟踪号精确回查时用)。
*
* <p>门面不暴露领星专有参数,需要精确回查时直接调本方法。</p>
*/
public RawPage<SalesOrder> pullRaw(ChannelContext ctx, SalesOrderQuery query,
LingxingOrderFilters filters, RawCapturePolicy policy) {
requireCapability();
LingxingSubPlatform impl = subPlatforms.of(ctx.platform());
if (impl.orderSource() == null) {
throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER);
}
RawRecorder recorder = RawRecorder.enabled(policy, ctx, json);
Page<SalesOrder> page = impl.orderSource().orders(call(ctx, recorder), query,
filters == null ? LingxingOrderFilters.none() : filters);
return recorder.toPage(page, impl.orderSource().rawItemPath());
}
@Override
public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) {
LingxingSubPlatform impl = subPlatforms.of(ctx.platform());
@ -449,9 +481,18 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -449,9 +481,18 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
/** 取 token 并装配本次调用所需的公共设施。 */
private LingxingCall call(ChannelContext ctx) {
return call(ctx, null);
}
/**
* 同上,可挂原始报文采集器。
*
* @param recorder 为 null 表示不采集({@code pull()} 路径)
*/
private LingxingCall call(ChannelContext ctx, RawRecorder recorder) {
ChannelSecret secret = ctx.secret();
AccessToken token = tokenManager.getOrRefresh(tokenKey(secret), secret);
return new LingxingCall(ctx, token, requestFactory, rateLimiter, json, transport);
return new LingxingCall(ctx, token, requestFactory, rateLimiter, json, transport, recorder);
}
/**

11
lingxing/src/main/java/common/ecommerce/lingxing/http/LingxingEnvelope.java

@ -37,12 +37,14 @@ public final class LingxingEnvelope { @@ -37,12 +37,14 @@ public final class LingxingEnvelope {
private final String body;
private final String code;
private final String message;
private final String platformRequestId;
private final int total;
private LingxingEnvelope(String body, String code, String message, int total) {
private LingxingEnvelope(String body, String code, String message, String platformRequestId, int total) {
this.body = body;
this.code = code;
this.message = message;
this.platformRequestId = platformRequestId;
this.total = total;
}
@ -78,7 +80,7 @@ public final class LingxingEnvelope { @@ -78,7 +80,7 @@ public final class LingxingEnvelope {
if (!"0".equals(code) && !"200".equals(code)) {
throw failure(code, b);
}
return new LingxingEnvelope(body, code, message, parseTotal(body, json));
return new LingxingEnvelope(body, code, message, platformRequestId, parseTotal(body, json));
}
private static ChannelException failure(String code, ChannelException.Builder b) {
@ -120,6 +122,11 @@ public final class LingxingEnvelope { @@ -120,6 +122,11 @@ public final class LingxingEnvelope {
return message;
}
/** 平台工单号(领星顶层 {@code request_id});响应里没有时为 null。 */
public String platformRequestId() {
return platformRequestId;
}
/** 总数;响应里没有 total 时为 -1。 */
public int total() {
return total;

32
lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingCall.java

@ -28,15 +28,28 @@ public final class LingxingCall { @@ -28,15 +28,28 @@ public final class LingxingCall {
private final JacksonJsonCodec json;
private final common.ecommerce.http.HttpTransport transport;
/** 原始报文采集器;null 表示本次调用不采集(默认路径,零额外开销)。 */
private final RawRecorder recorder;
public LingxingCall(ChannelContext ctx, AccessToken token, LingxingRequestFactory requestFactory,
LingxingRateLimiter rateLimiter, JacksonJsonCodec json,
common.ecommerce.http.HttpTransport transport) {
this(ctx, token, requestFactory, rateLimiter, json, transport, null);
}
/**
* @param recorder 原文采集器;传 null 等价于不采集
*/
public LingxingCall(ChannelContext ctx, AccessToken token, LingxingRequestFactory requestFactory,
LingxingRateLimiter rateLimiter, JacksonJsonCodec json,
common.ecommerce.http.HttpTransport transport, RawRecorder recorder) {
this.ctx = ctx;
this.token = token;
this.requestFactory = requestFactory;
this.rateLimiter = rateLimiter;
this.json = json;
this.transport = transport;
this.recorder = recorder;
}
public ChannelContext ctx() {
@ -70,16 +83,29 @@ public final class LingxingCall { @@ -70,16 +83,29 @@ public final class LingxingCall {
/** 发请求。传输层由子平台持有,这里只做一次转发,避免每个子平台重复写。 */
public HttpResponse execute(HttpRequest request) {
return transport.execute(request);
if (recorder == null) {
return transport.execute(request);
}
// 采集点放在这里:全仓唯一同时持有请求与响应的地方,且详情这类多次调用都能逐次记录
long startNanos = System.nanoTime();
HttpResponse response = transport.execute(request);
recorder.record(request, response, startNanos);
return response;
}
/** 校验 HTTP 状态与业务码,返回原始 body 供子平台解析。 */
public String body(HttpResponse response, String operation) {
return LingxingEnvelope.of(response, json, operation, ctx.omsStoreId(), ctx.requestId()).body();
return envelope(response, operation).body();
}
/** 同上,同时给出 data.total;接口没有 total 时为负数。 */
public LingxingEnvelope envelope(HttpResponse response, String operation) {
return LingxingEnvelope.of(response, json, operation, ctx.omsStoreId(), ctx.requestId());
LingxingEnvelope envelope = LingxingEnvelope.of(response, json, operation,
ctx.omsStoreId(), ctx.requestId());
if (recorder != null) {
// 校验通过后再回填业务码与平台工单号;失败路径由异常携带 rawResponse,不在此重复
recorder.enrich(envelope.code(), envelope.message(), envelope.platformRequestId());
}
return envelope;
}
}

10
lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderSource.java

@ -34,4 +34,14 @@ public interface LingxingOrderSource { @@ -34,4 +34,14 @@ public interface LingxingOrderSource {
throw new common.ecommerce.shared.error.ChannelException.UnsupportedCapabilityException(
common.ecommerce.shared.model.Capability.SALES_ORDER);
}
/**
* 列表响应中订单数组的点路径,供原始报文逐条切片。
*
* <p>默认是多平台统一订单的 {@code data.list};亚马逊系三个接口的 {@code data}
* 本身就是数组,需要各自覆盖。只有「回传原文」用得到,普通拉单不看这个值。</p>
*/
default String rawItemPath() {
return "data.list";
}
}

159
lingxing/src/main/java/common/ecommerce/lingxing/platform/RawRecorder.java

@ -0,0 +1,159 @@ @@ -0,0 +1,159 @@
package common.ecommerce.lingxing.platform;
import com.fasterxml.jackson.databind.JsonNode;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.raw.RawCapturePolicy;
import common.ecommerce.shared.raw.RawExchange;
import common.ecommerce.shared.raw.RawItem;
import common.ecommerce.shared.raw.RawPage;
import common.ecommerce.shared.support.Page;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
/**
* 领星原始报文采集器:把 {@link LingxingCall#execute} 的请求/响应攒起来,
* 再组装成 {@link RawPage}。
*
* <p>为什么放在这一层:全仓 30+ 个 Source 都经过 {@code LingxingCall.execute},
* 在这里采集不需要改任何业务映射代码;换成在 Source 内部组装,则每个能力都要重写一遍。</p>
*
* <p><b>生命周期</b>:一次业务调用新建一个,只在当前线程使用,不做同步。
* 只有显式走 {@code pullRaw} 时才创建;{@code pull()} 路径为 null,不产生任何分配。</p>
*/
public final class RawRecorder {
/** 采集策略,非 null。 */
private final RawCapturePolicy policy;
/** 本次调用上下文,用于链路 ID 与时钟。 */
private final ChannelContext ctx;
/** JSON 工具,与调用方共用同一个 ObjectMapper。 */
private final JacksonJsonCodec json;
/** 按发生顺序累积的往返草稿。 */
private final List<Draft> drafts = new ArrayList<Draft>();
private RawRecorder(RawCapturePolicy policy, ChannelContext ctx, JacksonJsonCodec json) {
this.policy = policy;
this.ctx = ctx;
this.json = json;
}
/**
* @param policy 采集策略;null 时取默认值
* @param ctx 本次调用上下文
* @param json JSON 工具;null 时新建一个(仅测试会这样用)
*/
public static RawRecorder enabled(RawCapturePolicy policy, ChannelContext ctx, JacksonJsonCodec json) {
return new RawRecorder(policy == null ? RawCapturePolicy.defaults() : policy, ctx,
json == null ? new JacksonJsonCodec() : json);
}
/** 记下一次往返。由 {@link LingxingCall#execute} 调用。 */
public void record(HttpRequest request, HttpResponse response, long startNanos) {
long durationMillis = (System.nanoTime() - startNanos) / 1_000_000L;
drafts.add(new Draft(request, response, Math.max(0L, durationMillis)));
}
/**
* 回填平台业务码、消息与工单号。
*
* <p>由 {@link LingxingCall#envelope} 在校验通过后调用;失败路径不进这里,
* 由 {@code ChannelException.rawResponse} 携带原文。</p>
*/
public void enrich(String code, String message, String platformRequestId) {
if (drafts.isEmpty()) {
return;
}
Draft last = drafts.get(drafts.size() - 1);
last.code = code;
last.message = message;
last.platformRequestId = platformRequestId;
}
/**
* 组装列表结果。
*
* <p>逐条原文按响应数组下标与 {@code page.items()} 对齐;条数不一致或某条
* 业务键为空时 {@code itemsAligned=false},调用方不得把逐条数据入库。</p>
*
* @param page 映射后的业务结果
* @param itemPath 响应数组的点路径(多平台 {@code data.list},亚马逊系 {@code data})
*/
public RawPage<SalesOrder> toPage(Page<SalesOrder> page, String itemPath) {
Draft last = drafts.isEmpty() ? null : drafts.get(drafts.size() - 1);
RawExchange exchange = last == null ? null : last.toExchange(policy, ctx, drafts.size());
List<RawItem> items = new ArrayList<RawItem>();
boolean aligned = false;
// 正文被判定超限而丢弃时不再切片:同一份数据既然没留,就别给一半
if (exchange != null && policy.includeItems()
&& exchange.bodyState() == RawExchange.BodyState.FULL) {
JsonNode array = json.nodeAt(exchange.responseBody(), itemPath);
if (array != null && array.isArray()) {
for (int i = 0; i < array.size(); i++) {
String key = i < page.size() ? page.items().get(i).channelOrderId() : null;
items.add(RawItem.of(i, key, array.get(i).toString()));
}
aligned = aligned(items, page.size());
}
}
return RawPage.of(page, exchange, items, aligned);
}
/** 条数一致且每条业务键非空,才算对齐。 */
private static boolean aligned(List<RawItem> items, int expectedSize) {
if (items.size() != expectedSize) {
return false;
}
for (RawItem item : items) {
String key = item.key();
if (key == null || key.trim().isEmpty()) {
return false;
}
}
return true;
}
/** 一次往返的可变草稿;{@code enrich} 需要回填,组装时才冻结成 {@link RawExchange}。 */
private static final class Draft {
private final HttpRequest request;
private final HttpResponse response;
private final long durationMillis;
private String code;
private String message;
private String platformRequestId;
private Draft(HttpRequest request, HttpResponse response, long durationMillis) {
this.request = request;
this.response = response;
this.durationMillis = durationMillis;
}
private RawExchange toExchange(RawCapturePolicy policy, ChannelContext ctx, int sequence) {
return RawExchange.builder()
.sequence(sequence)
.operation(request.operation())
.httpMethod(request.method())
.url(request.url())
.requestBody(policy.includeRequest() ? request.body() : null)
.httpStatus(response.statusCode())
.platformCode(code)
.platformMessage(message)
.platformRequestId(platformRequestId)
.requestId(ctx.requestId())
.fetchedAt(Instant.now(ctx.clock()))
.durationMillis(durationMillis)
.body(response.body(), policy.maxBytes())
.build();
}
}
}

6
lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonFbmOrderSource.java

@ -64,6 +64,12 @@ public final class AmazonFbmOrderSource implements LingxingOrderSource { @@ -64,6 +64,12 @@ public final class AmazonFbmOrderSource implements LingxingOrderSource {
private static final String OP_PULL = "salesOrders.pull.fbm";
private static final String OP_GET = "salesOrders.get.fbm";
/** FBM 列表的订单数组在 {@code data},不是多平台的 {@code data.list}。 */
@Override
public String rawItemPath() {
return "data";
}
@Override
public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) {
ChannelAccount account = call.ctx().account();

6
lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonOrderSource.java

@ -61,6 +61,12 @@ public final class AmazonOrderSource implements LingxingOrderSource { @@ -61,6 +61,12 @@ public final class AmazonOrderSource implements LingxingOrderSource {
private static final String OP_PULL = "salesOrders.pull.amazon";
private static final String OP_GET = "salesOrders.get.amazon";
/** 亚马逊 SC 列表的订单数组就在 {@code data},不是多平台的 {@code data.list}。 */
@Override
public String rawItemPath() {
return "data";
}
@Override
public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) {
ChannelAccount account = call.ctx().account();

6
lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/order/VcOrderSource.java

@ -74,6 +74,12 @@ public final class VcOrderSource implements LingxingOrderSource { @@ -74,6 +74,12 @@ public final class VcOrderSource implements LingxingOrderSource {
private static final String OP_PULL = "salesOrders.pull.vc";
private static final String OP_GET = "salesOrders.get.vc";
/** VC 列表的订单数组在 {@code data},不是多平台的 {@code data.list}。 */
@Override
public String rawItemPath() {
return "data";
}
@Override
public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) {
ChannelAccount account = call.ctx().account();

10
lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformOrderSource.java

@ -82,11 +82,14 @@ import java.util.Map; @@ -82,11 +82,14 @@ import java.util.Map;
*/
public class MultiPlatformOrderSource implements LingxingOrderSource {
private final HttpTransport transport;
private final LingxingOrderMapper mapper;
/**
* @param transport 已不再直连使用:请求统一经 {@link LingxingCall#execute} 发出,
* 否则挂在调用上的原始报文采集会漏掉本路由。参数保留是为了
* 各子平台装配签名稳定。
*/
public MultiPlatformOrderSource(HttpTransport transport, JacksonJsonCodec json) {
this.transport = transport;
this.mapper = new LingxingOrderMapper(json);
}
@ -125,7 +128,8 @@ public class MultiPlatformOrderSource implements LingxingOrderSource { @@ -125,7 +128,8 @@ public class MultiPlatformOrderSource implements LingxingOrderSource {
Map<String, Object> body = orderBody(account, from, to, offset, length, effective);
HttpRequest req = call.signed(orderApi(), body, "salesOrders.pull");
HttpResponse resp = transport.execute(req);
// 必须走 call.execute:原文采集挂在 LingxingCall 上,绕过它就采不到多平台订单报文
HttpResponse resp = call.execute(req);
LingxingEnvelope envelope = call.envelope(resp, "salesOrders.pull");
List<LingxingOrderDto> dtos = mapper.parseList(envelope.body());

77
lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java

@ -1,6 +1,9 @@ @@ -1,6 +1,9 @@
package common.ecommerce.lingxing.adapter;
import common.ecommerce.channel.capability.AggregatorCapable.SubChannel;
import common.ecommerce.shared.raw.RawExchange;
import common.ecommerce.shared.raw.RawItem;
import common.ecommerce.shared.raw.RawPage;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
@ -70,6 +73,7 @@ import java.util.List; @@ -70,6 +73,7 @@ import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
@ -511,6 +515,71 @@ class LingxingLiveSmokeTest { @@ -511,6 +515,71 @@ class LingxingLiveSmokeTest {
assertTrue(hit.size() >= 1, "按平台单号回查没命中,检查 platform_order_no 参数名或时间窗");
}
/**
* 第 3 步(订单 · 原文回传):与 {@link #pullsOnePageOfOrders()} 同一条路由,
* 但走 {@code pullRaw},验证真实响应能被完整采集、切条并对齐。
*
* <p>断言:有往返记录、正文完整、含领星 {@code code} 字段、逐条与订单号对齐。
* 样本会写到模块下的 {@code target/lingxing-raw-sample.json},便于人工核对字段;
* 该文件含买家 PII,只在本机查看,别提交。</p>
*/
@Test
void pullsOnePageOfOrdersWithRawPayload() throws Exception {
requireCredentials();
List<SubChannel> shops = listShops(adapter);
String storeId = resolveStoreId(shops);
if (storeId == null) {
return;
}
ChannelContext ctx = context(account(storeId), "smoke-raw-");
Instant to = Instant.now();
Instant from = to.minus(Duration.ofDays(2));
RawPage<SalesOrder> raw = adapter.pullRaw(ctx, SalesOrderQuery.builder()
.updatedAfter(from)
.updatedBefore(to)
.pageSize(20)
.build(), null);
RawExchange exchange = raw.exchange();
assertNotNull(exchange, "没有记录到任何 HTTP 往返,检查 Source 是否绕过了 call.execute");
assertEquals(RawExchange.BodyState.FULL, exchange.bodyState(),
"正文被判定超限,检查 maxBytes:bytes=" + exchange.bodyBytes());
assertNotNull(exchange.responseBody(), "原始响应为空");
assertTrue(exchange.responseBody().contains("\"code\""), "响应不是领星信封,检查端点/网关");
System.out.println("[raw] store_id=" + storeId
+ " window=" + from + " .. " + to
+ " items=" + raw.size()
+ " rawItems=" + raw.rawItems().size()
+ " aligned=" + raw.itemsAligned());
System.out.println("[raw] http=" + exchange.httpStatus()
+ " code=" + exchange.platformCode()
+ " platformRequestId=" + exchange.platformRequestId()
+ " bytes=" + exchange.bodyBytes()
+ " cost=" + exchange.durationMillis() + "ms"
+ " sha256=" + exchange.bodySha256());
if (raw.itemsAligned() && !raw.rawItems().isEmpty()) {
RawItem first = raw.rawItemOf(0);
assertEquals(raw.items().get(0).channelOrderId(), first.key(),
"逐条原文与订单号未对齐");
System.out.println("[raw] first item key=" + first.key()
+ " json=" + head(first.json()));
} else if (!raw.items().isEmpty()) {
System.out.println("[raw] 未对齐(rawItems=" + raw.rawItems().size()
+ " items=" + raw.size() + "),只存整页,逐条不入库");
}
java.nio.file.Path sample = java.nio.file.Paths.get("target", "lingxing-raw-sample.json");
java.nio.file.Files.createDirectories(sample.getParent());
java.nio.file.Files.write(sample, exchange.responseBody()
.getBytes(java.nio.charset.StandardCharsets.UTF_8));
System.out.println("[raw] 样本已写入 " + sample.toAbsolutePath()
+ "(含买家个人信息,仅本机查看)");
}
// ================================================================ 结算 / 售后
/**
@ -574,6 +643,14 @@ class LingxingLiveSmokeTest { @@ -574,6 +643,14 @@ class LingxingLiveSmokeTest {
"未提供 -Dlingxing.probe.appKey / -Dlingxing.probe.appSecret,跳过冒烟");
}
/** 控制台预览用:截断长文本,避免整页报文刷屏。 */
private static String head(String text) {
if (text == null) {
return "null";
}
return text.length() <= 500 ? text : text.substring(0, 500) + "...(" + text.length() + " chars)";
}
/**
* 按 {@code PLATFORM_CODE} 列店铺,并打印该子平台下已授权的店铺。
*

218
lingxing/src/test/java/common/ecommerce/lingxing/platform/RawRecorderTest.java

@ -0,0 +1,218 @@ @@ -0,0 +1,218 @@
package common.ecommerce.lingxing.platform;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.raw.RawCapturePolicy;
import common.ecommerce.shared.raw.RawExchange;
import common.ecommerce.shared.raw.RawPage;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.support.PlatformTime;
import common.ecommerce.lingxing.support.LingxingTestSupport;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import java.time.ZoneId;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import static common.ecommerce.lingxing.support.LingxingTestSupport.account;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 采集器:请求默认不采集、业务码回填、数组切片与对齐判定。
*/
class RawRecorderTest {
private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
private static final String TWO_ITEMS =
"{\"code\":0,\"message\":\"success\",\"data\":{\"total\":2,\"list\":["
+ "{\"platform_order_no\":\"A-001\"},"
+ "{\"platform_order_no\":\"B-002\"}]}}";
private static final ZoneId ZONE = ZoneId.of("America/Los_Angeles");
private static ChannelContext context() {
return LingxingTestSupport.context(account(Platform.WALMART_SC, 10008, "s1"));
}
private static HttpRequest request() {
return HttpRequest.builder()
.method("POST")
.url("https://openapi.lingxing.com/pb/mp/order/v2/list")
.body("{\"offset\":0,\"length\":100}")
.operation("salesOrders.pull")
.build();
}
private static HttpResponse response(String body) {
return HttpResponse.of(200, new HashMap<String, String>(), body, 3);
}
private static Page<SalesOrder> page(String... orderIds) {
List<SalesOrder> orders = new ArrayList<SalesOrder>();
for (String id : orderIds) {
orders.add(SalesOrder.builder()
.omsStoreId("oms-walmart_sc")
.channelOrderId(id)
.occurredAt(PlatformTime.of(Instant.parse("2026-11-04T00:00:00Z"), ZONE))
.sourceProvider(ChannelProvider.LINGXING)
.build());
}
return Page.of(orders, null);
}
private static RawRecorder recorder(RawCapturePolicy policy) {
return RawRecorder.enabled(policy, context(), JSON);
}
@Test
void capturesResponseAndPlatformMeta() {
RawRecorder recorder = recorder(RawCapturePolicy.defaults());
recorder.record(request(), response(TWO_ITEMS), System.nanoTime());
recorder.enrich("0", "success", "lx-request-9");
RawPage<SalesOrder> raw = recorder.toPage(page("A-001", "B-002"), "data.list");
RawExchange exchange = raw.exchange();
assertNotNull(exchange);
assertEquals(TWO_ITEMS, exchange.responseBody());
assertEquals(RawExchange.BodyState.FULL, exchange.bodyState());
assertEquals("0", exchange.platformCode());
assertEquals("success", exchange.platformMessage());
assertEquals("lx-request-9", exchange.platformRequestId());
assertEquals("req-1", exchange.requestId());
assertEquals("salesOrders.pull", exchange.operation());
assertEquals("POST", exchange.httpMethod());
assertEquals(1, exchange.sequence());
assertEquals(200, exchange.httpStatus());
assertNotNull(exchange.fetchedAt());
}
@Test
void requestBodyIsNotCapturedByDefault() {
RawRecorder recorder = recorder(RawCapturePolicy.defaults());
recorder.record(request(), response(TWO_ITEMS), System.nanoTime());
RawPage<SalesOrder> raw = recorder.toPage(page("A-001", "B-002"), "data.list");
assertNull(raw.exchange().requestBody());
}
@Test
void includeRequestKeepsRawRequestBody() {
RawCapturePolicy policy = RawCapturePolicy.builder().includeRequest(true).build();
RawRecorder recorder = recorder(policy);
recorder.record(request(), response(TWO_ITEMS), System.nanoTime());
RawPage<SalesOrder> raw = recorder.toPage(page("A-001", "B-002"), "data.list");
assertEquals("{\"offset\":0,\"length\":100}", raw.exchange().requestBody());
}
@Test
void slicesItemsAndAlignsWithPage() {
RawRecorder recorder = recorder(RawCapturePolicy.defaults());
recorder.record(request(), response(TWO_ITEMS), System.nanoTime());
RawPage<SalesOrder> raw = recorder.toPage(page("A-001", "B-002"), "data.list");
assertEquals(2, raw.rawItems().size());
assertEquals("A-001", raw.rawItemOf(0).key());
assertEquals("B-002", raw.rawItemOf(1).key());
assertTrue(raw.rawItemOf(0).json().contains("A-001"));
assertEquals(2, raw.rawItemsByOrderId().size());
assertTrue(raw.itemsAligned());
}
@Test
void marksUnalignedWhenCountsDiffer() {
RawRecorder recorder = recorder(RawCapturePolicy.defaults());
recorder.record(request(), response(TWO_ITEMS), System.nanoTime());
RawPage<SalesOrder> raw = recorder.toPage(page("A-001"), "data.list");
assertEquals(2, raw.rawItems().size());
assertFalse(raw.itemsAligned());
// 对不齐时仍保留整页原文,只是逐条数据不可信
assertNotNull(raw.exchange());
assertEquals(TWO_ITEMS, raw.exchange().responseBody());
}
@Test
void omitsOversizedBodyAndSkipsItems() {
RawCapturePolicy policy = RawCapturePolicy.builder().maxBytes(8).build();
RawRecorder recorder = recorder(policy);
recorder.record(request(), response(TWO_ITEMS), System.nanoTime());
RawPage<SalesOrder> raw = recorder.toPage(page("A-001", "B-002"), "data.list");
assertTrue(raw.exchange().truncated());
assertNull(raw.exchange().responseBody());
assertEquals(TWO_ITEMS.getBytes(java.nio.charset.StandardCharsets.UTF_8).length,
raw.exchange().bodyBytes());
assertTrue(raw.rawItems().isEmpty());
assertFalse(raw.itemsAligned());
}
@Test
void missingEnvelopeKeepsRawPageUsable() {
RawRecorder recorder = recorder(RawCapturePolicy.defaults());
RawPage<SalesOrder> raw = recorder.toPage(page("A-001"), "data.list");
assertNull(raw.exchange());
assertEquals(1, raw.size());
assertTrue(raw.rawItems().isEmpty());
assertFalse(raw.itemsAligned());
}
@Test
void emptyArrayIsAlignedWithEmptyPage() {
RawRecorder recorder = recorder(RawCapturePolicy.defaults());
recorder.record(request(), response("{\"code\":0,\"data\":{\"list\":[]}}"), System.nanoTime());
RawPage<SalesOrder> raw = recorder.toPage(Page.<SalesOrder>empty(), "data.list");
assertNotNull(raw.exchange());
assertTrue(raw.rawItems().isEmpty());
assertTrue(raw.itemsAligned());
}
@Test
void keepsFieldsNotDeclaredByDto() {
String body = "{\"code\":0,\"data\":{\"list\":[{\"platform_order_no\":\"A-001\","
+ "\"undocumented\":{\"keep\":true}}]}}";
RawRecorder recorder = recorder(RawCapturePolicy.defaults());
recorder.record(request(), response(body), System.nanoTime());
RawPage<SalesOrder> raw = recorder.toPage(page("A-001"), "data.list");
assertTrue(raw.rawItemOf(0).json().contains("undocumented"));
assertEquals(Collections.singletonList("A-001"),
new ArrayList<String>(raw.rawItemsByOrderId().keySet()));
}
@Test
void pageOrderIsPreserved() {
RawRecorder recorder = recorder(RawCapturePolicy.defaults());
recorder.record(request(), response(TWO_ITEMS), System.nanoTime());
RawPage<SalesOrder> raw = recorder.toPage(page("A-001", "B-002"), "data.list");
List<String> keys = new ArrayList<String>(raw.rawItemsByOrderId().keySet());
assertEquals(Arrays.asList("A-001", "B-002"), keys);
}
}

88
lingxing/src/test/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformRawPullTest.java

@ -0,0 +1,88 @@ @@ -0,0 +1,88 @@
package common.ecommerce.lingxing.platform.multiplatform.order;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.lingxing.LingxingApi;
import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.RawRecorder;
import common.ecommerce.lingxing.platform.amazon.order.AmazonFbmOrderSource;
import common.ecommerce.lingxing.platform.amazon.order.AmazonOrderSource;
import common.ecommerce.lingxing.platform.amazon.vc.order.VcOrderSource;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.raw.RawCapturePolicy;
import common.ecommerce.shared.raw.RawPage;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import static common.ecommerce.lingxing.support.LingxingTestSupport.account;
import static common.ecommerce.lingxing.support.LingxingTestSupport.call;
import static common.ecommerce.lingxing.support.LingxingTestSupport.context;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 多平台订单列表的原文回传全链路。
*
* <p>兼作回归:{@code MultiPlatformOrderSource} 曾经直接用 {@code transport.execute}
* 绕过 {@code LingxingCall},那样采集器拿不到任何往返,这里的 exchange 会是 null。</p>
*/
class MultiPlatformRawPullTest {
private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
private static final String TWO_ORDERS =
"{\"code\":0,\"message\":\"success\",\"data\":{\"total\":2,\"list\":["
+ "{\"global_order_no\":\"G1\",\"platform_order_no\":\"A-001\","
+ "\"store_id\":\"s1\",\"platform_code\":\"10008\",\"order_status\":6,"
+ "\"undocumented_field\":{\"keep\":true}},"
+ "{\"global_order_no\":\"G2\",\"platform_order_no\":\"B-002\","
+ "\"store_id\":\"s1\",\"platform_code\":\"10008\",\"order_status\":6}"
+ "]}}";
private final RecordingTransport transport = RecordingTransport.create()
.route(LingxingApi.ORDER_LIST.path(), r -> Responses.ok(TWO_ORDERS));
private static SalesOrderQuery query() {
return SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-11-04T00:00:00Z"))
.updatedBefore(Instant.parse("2026-11-05T00:00:00Z"))
.pageSize(20)
.build();
}
@Test
void capturesPageAndPerOrderPayload() {
ChannelAccount account = account(Platform.WALMART_SC, 10008, "s1");
RawRecorder recorder = RawRecorder.enabled(RawCapturePolicy.defaults(), context(account), JSON);
LingxingCall lxCall = call(transport, account, recorder);
Page<SalesOrder> page = new MultiPlatformOrderSource(transport, JSON).orders(lxCall, query());
RawPage<SalesOrder> raw = recorder.toPage(page, "data.list");
assertEquals(2, page.size());
assertNotNull(raw.exchange());
assertEquals(TWO_ORDERS, raw.exchange().responseBody());
assertEquals("0", raw.exchange().platformCode());
assertTrue(raw.itemsAligned());
assertEquals(2, raw.rawItems().size());
assertEquals(page.items().get(0).channelOrderId(), raw.rawItemOf(0).key());
assertEquals(page.items().get(1).channelOrderId(), raw.rawItemOf(1).key());
// DTO 未声明的字段也要保留,这是「原文」的意义
assertTrue(raw.rawItemOf(0).json().contains("undocumented_field"));
}
@Test
void rawItemPathMatchesEachOrderRoute() {
assertEquals("data.list", new MultiPlatformOrderSource(transport, JSON).rawItemPath());
assertEquals("data", new AmazonOrderSource().rawItemPath());
assertEquals("data", new AmazonFbmOrderSource().rawItemPath());
assertEquals("data", new VcOrderSource().rawItemPath());
}
}

24
lingxing/src/test/java/common/ecommerce/lingxing/support/LingxingTestSupport.java

@ -6,6 +6,7 @@ import common.ecommerce.lingxing.auth.LingxingTokenClient; @@ -6,6 +6,7 @@ import common.ecommerce.lingxing.auth.LingxingTokenClient;
import common.ecommerce.lingxing.http.LingxingRateLimiter;
import common.ecommerce.lingxing.http.LingxingRequestFactory;
import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.RawRecorder;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.channel.model.account.AccountKey;
@ -72,13 +73,28 @@ public final class LingxingTestSupport { @@ -72,13 +73,28 @@ public final class LingxingTestSupport {
* <p>token 请求走 {@link RecordingTransport} 的默认响应,不占业务路由。</p>
*/
public static LingxingCall call(RecordingTransport transport, ChannelAccount account) {
ChannelSecret secret = ChannelSecret.builder().appKey(APP_KEY).appSecret(APP_SECRET).build();
ChannelConnection conn = ChannelConnection.of(ENDPOINT, secret);
ChannelContext ctx = ChannelContext.of(account, conn, "req-1", CLOCK);
return call(transport, account, null);
}
/**
* 同上,可挂原始报文采集器。
*
* @param recorder 传 null 等价于不采集
*/
public static LingxingCall call(RecordingTransport transport, ChannelAccount account,
RawRecorder recorder) {
ChannelContext ctx = context(account);
AccessToken token = new LingxingTokenClient(transport, JSON, CLOCK)
.fetch(ENDPOINT, APP_KEY, APP_SECRET);
return new LingxingCall(ctx, token, new LingxingRequestFactory(JSON, CLOCK),
new LingxingRateLimiter(), JSON, transport);
new LingxingRateLimiter(), JSON, transport, recorder);
}
/** 与 {@link #call(RecordingTransport, ChannelAccount)} 同一套账户/连接/链路 ID。 */
public static ChannelContext context(ChannelAccount account) {
ChannelSecret secret = ChannelSecret.builder().appKey(APP_KEY).appSecret(APP_SECRET).build();
ChannelConnection conn = ChannelConnection.of(ENDPOINT, secret);
return ChannelContext.of(account, conn, "req-1", CLOCK);
}
/** 取最后一次业务请求的请求体;没有业务请求时报错。 */

99
sdk-common/src/main/java/common/ecommerce/shared/raw/RawCapturePolicy.java

@ -0,0 +1,99 @@ @@ -0,0 +1,99 @@
package common.ecommerce.shared.raw;
/**
* 原始报文采集策略。
*
* <p>只在显式调用 {@code pullWithRaw} 时生效;{@code pull()} 路径不采集,
* 也不分配任何缓冲。</p>
*
* <p><b>默认值取舍</b>:单页原文上限 4 MiB(领星多平台单页 500 条、单条 2~4 KB,
* 正常一页 1~2 MB);请求体<b>默认不采集</b>,因为领星请求体含 {@code sign};
* 逐条切片默认开启。</p>
*/
public final class RawCapturePolicy {
/** 单份原文的默认字节上限:4 MiB。 */
public static final int DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
private static final RawCapturePolicy DEFAULTS =
new RawCapturePolicy(DEFAULT_MAX_BYTES, false, true);
/** 单份原文的字节上限;0 表示不限制。 */
private final int maxBytes;
/** 是否采集请求体。 */
private final boolean includeRequest;
/** 是否把列表响应对应成逐条 JSON。 */
private final boolean includeItems;
private RawCapturePolicy(int maxBytes, boolean includeRequest, boolean includeItems) {
this.maxBytes = maxBytes;
this.includeRequest = includeRequest;
this.includeItems = includeItems;
}
/** 默认策略:4 MiB、不带请求体、逐条切片开启。 */
public static RawCapturePolicy defaults() {
return DEFAULTS;
}
public static Builder builder() {
return new Builder();
}
/** 单份原文的字节上限;0 表示不限制。 */
public int maxBytes() {
return maxBytes;
}
/** 是否采集请求体;默认 false。 */
public boolean includeRequest() {
return includeRequest;
}
/** 是否把列表响应对应成逐条 JSON;默认 true。 */
public boolean includeItems() {
return includeItems;
}
@Override
public String toString() {
return "RawCapturePolicy{maxBytes=" + maxBytes
+ ", includeRequest=" + includeRequest
+ ", includeItems=" + includeItems + '}';
}
/** 可变构建器;默认值与 {@link #defaults()} 一致。 */
public static final class Builder {
private int maxBytes = DEFAULT_MAX_BYTES;
private boolean includeRequest;
private boolean includeItems = true;
/** 单份原文上限;0 表示不限制,负数非法。 */
public Builder maxBytes(int maxBytes) {
if (maxBytes < 0) {
throw new IllegalArgumentException("maxBytes must not be negative");
}
this.maxBytes = maxBytes;
return this;
}
/** 是否采集请求体;开启后原始请求体会原样返回,需自行承担签名落库风险。 */
public Builder includeRequest(boolean includeRequest) {
this.includeRequest = includeRequest;
return this;
}
/** 是否把列表响应对应成逐条 JSON。 */
public Builder includeItems(boolean includeItems) {
this.includeItems = includeItems;
return this;
}
public RawCapturePolicy build() {
return new RawCapturePolicy(maxBytes, includeRequest, includeItems);
}
}
}

352
sdk-common/src/main/java/common/ecommerce/shared/raw/RawExchange.java

@ -0,0 +1,352 @@ @@ -0,0 +1,352 @@
package common.ecommerce.shared.raw;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.Instant;
/**
* 一次 HTTP 往返的原始留痕(不可变)。
*
* <p>只承载「平台真正回了什么」,不做业务解释:请求元信息、响应原文、
* 体积摘要与耗时。原文超过上限时<b>整份丢弃</b>而不截断——半截 JSON
* 既不能入库也不能排查,还会让人误以为拿到了完整数据,因此只保留
* 字节数与 SHA-256,由 {@link BodyState} 显式表达。</p>
*
* <p><b>敏感信息约定</b>:{@link #toString()} 不输出正文;正文里可能含买家
* 姓名、地址、电话等个人信息,禁止直接打日志。请求体默认不采集
* ({@link RawCapturePolicy#includeRequest()} 默认 false),因为领星请求体含签名。</p>
*/
public final class RawExchange {
/** 响应原文的保留状态。 */
public enum BodyState {
/** 平台没有返回响应体。 */
EMPTY,
/** 原文完整保留,见 {@link #responseBody()}。 */
FULL,
/** 超过体积上限,正文已丢弃;只有 {@link #bodyBytes()} 与 {@link #bodySha256()} 可信。 */
OMITTED_TOO_LARGE
}
/** 同一业务调用内的往返序号,从 1 开始;列表接口恒为 1。 */
private final int sequence;
/** 操作名,如 {@code salesOrders.pull}。 */
private final String operation;
/** HTTP 方法。 */
private final String httpMethod;
/** 请求地址;领星没有 query token,可原样保留。 */
private final String url;
/** 请求体;未开启采集时为 null。 */
private final String requestBody;
/** HTTP 状态码。 */
private final int httpStatus;
/** 平台业务码,如领星 {@code code=0};无则为 null。 */
private final String platformCode;
/** 平台业务消息。 */
private final String platformMessage;
/** 平台侧工单号(领星顶层 {@code request_id});无则为 null。 */
private final String platformRequestId;
/** 我方链路 ID。 */
private final String requestId;
/** 响应到达时间。 */
private final Instant fetchedAt;
/** 本次往返耗时(毫秒)。 */
private final long durationMillis;
/** 响应原文;超限或为空时为 null。 */
private final String responseBody;
/** 响应原文的 UTF-8 字节数(丢弃前)。 */
private final long bodyBytes;
/** 响应原文全文的 SHA-256(丢弃前),用于去重与校验。 */
private final String bodySha256;
/** 原文保留状态。 */
private final BodyState bodyState;
/** 由 Builder 装配;无必填字段,缺失即为 null。 */
private RawExchange(Builder b) {
this.sequence = b.sequence;
this.operation = b.operation;
this.httpMethod = b.httpMethod;
this.url = b.url;
this.requestBody = b.requestBody;
this.httpStatus = b.httpStatus;
this.platformCode = b.platformCode;
this.platformMessage = b.platformMessage;
this.platformRequestId = b.platformRequestId;
this.requestId = b.requestId;
this.fetchedAt = b.fetchedAt;
this.durationMillis = b.durationMillis;
this.responseBody = b.responseBody;
this.bodyBytes = b.bodyBytes;
this.bodySha256 = b.bodySha256;
this.bodyState = b.bodyState;
}
public static Builder builder() {
return new Builder();
}
/** 往返序号,从 1 开始;列表接口恒为 1。 */
public int sequence() {
return sequence;
}
/** 操作名,如 {@code salesOrders.pull}。 */
public String operation() {
return operation;
}
/** HTTP 方法。 */
public String httpMethod() {
return httpMethod;
}
/** 请求地址。 */
public String url() {
return url;
}
/** 请求体;未开启采集时为 null。 */
public String requestBody() {
return requestBody;
}
/** HTTP 状态码。 */
public int httpStatus() {
return httpStatus;
}
/** 平台业务码;无则为 null。 */
public String platformCode() {
return platformCode;
}
/** 平台业务消息。 */
public String platformMessage() {
return platformMessage;
}
/** 平台侧工单号;无则为 null。 */
public String platformRequestId() {
return platformRequestId;
}
/** 我方链路 ID。 */
public String requestId() {
return requestId;
}
/** 响应到达时间。 */
public Instant fetchedAt() {
return fetchedAt;
}
/** 本次往返耗时(毫秒)。 */
public long durationMillis() {
return durationMillis;
}
/** 响应原文;超限或为空时为 null。 */
public String responseBody() {
return responseBody;
}
/** 响应原文的 UTF-8 字节数(丢弃前)。 */
public long bodyBytes() {
return bodyBytes;
}
/** 响应原文全文的 SHA-256(丢弃前)。 */
public String bodySha256() {
return bodySha256;
}
/** 原文保留状态。 */
public BodyState bodyState() {
return bodyState;
}
/** 是否因超限丢弃了正文。 */
public boolean truncated() {
return bodyState == BodyState.OMITTED_TOO_LARGE;
}
/** 只有元信息与摘要,不含正文——可直接用于日志排查。 */
@Override
public String toString() {
return "RawExchange{" + (httpMethod == null ? "?" : httpMethod) + " " + url
+ " op=" + operation
+ " seq=" + sequence
+ " status=" + httpStatus
+ " code=" + platformCode
+ " requestId=" + requestId
+ " platformRequestId=" + platformRequestId
+ " bytes=" + bodyBytes
+ " sha256=" + bodySha256
+ " body=" + bodyState
+ " cost=" + durationMillis + "ms"
+ '}';
}
/** 可变构建器;{@link #body(String, int)} 负责算体积、摘要与保留状态。 */
public static final class Builder {
private int sequence = 1;
private String operation;
private String httpMethod;
private String url;
private String requestBody;
private int httpStatus;
private String platformCode;
private String platformMessage;
private String platformRequestId;
private String requestId;
private Instant fetchedAt;
private long durationMillis;
private String responseBody;
private long bodyBytes;
private String bodySha256;
private BodyState bodyState = BodyState.EMPTY;
/** 往返序号,从 1 开始。 */
public Builder sequence(int sequence) {
this.sequence = sequence;
return this;
}
/** 操作名,如 {@code salesOrders.pull}。 */
public Builder operation(String operation) {
this.operation = operation;
return this;
}
/** HTTP 方法。 */
public Builder httpMethod(String httpMethod) {
this.httpMethod = httpMethod;
return this;
}
/** 请求地址。 */
public Builder url(String url) {
this.url = url;
return this;
}
/** 请求体;不采集时传 null。 */
public Builder requestBody(String requestBody) {
this.requestBody = requestBody;
return this;
}
/** HTTP 状态码。 */
public Builder httpStatus(int httpStatus) {
this.httpStatus = httpStatus;
return this;
}
/** 平台业务码。 */
public Builder platformCode(String platformCode) {
this.platformCode = platformCode;
return this;
}
/** 平台业务消息。 */
public Builder platformMessage(String platformMessage) {
this.platformMessage = platformMessage;
return this;
}
/** 平台侧工单号。 */
public Builder platformRequestId(String platformRequestId) {
this.platformRequestId = platformRequestId;
return this;
}
/** 我方链路 ID。 */
public Builder requestId(String requestId) {
this.requestId = requestId;
return this;
}
/** 响应到达时间。 */
public Builder fetchedAt(Instant fetchedAt) {
this.fetchedAt = fetchedAt;
return this;
}
/** 本次往返耗时(毫秒)。 */
public Builder durationMillis(long durationMillis) {
this.durationMillis = durationMillis;
return this;
}
/**
* 记录响应原文,同时算体积、SHA-256 与保留状态。
*
* <p>{@code maxBytes} 为正且原文超过它时,正文整份丢弃、状态为
* {@link BodyState#OMITTED_TOO_LARGE};传 0 或负数表示不限制。</p>
*
* @param rawBody 平台原始响应体,可为 null
* @param maxBytes 单份原文的字节上限
*/
public Builder body(String rawBody, int maxBytes) {
if (rawBody == null) {
this.responseBody = null;
this.bodyBytes = 0L;
this.bodySha256 = null;
this.bodyState = BodyState.EMPTY;
return this;
}
byte[] bytes = rawBody.getBytes(StandardCharsets.UTF_8);
this.bodyBytes = bytes.length;
this.bodySha256 = sha256Hex(bytes);
if (maxBytes > 0 && bytes.length > maxBytes) {
this.responseBody = null;
this.bodyState = BodyState.OMITTED_TOO_LARGE;
} else {
this.responseBody = rawBody;
this.bodyState = BodyState.FULL;
}
return this;
}
public RawExchange build() {
return new RawExchange(this);
}
/** 十六进制 SHA-256;JDK 自带实现,不引额外依赖。 */
private static String sha256Hex(byte[] bytes) {
try {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(bytes);
StringBuilder sb = new StringBuilder(hash.length * 2);
for (byte b : hash) {
sb.append(Character.forDigit((b >> 4) & 0xF, 16));
sb.append(Character.forDigit(b & 0xF, 16));
}
return sb.toString();
} catch (NoSuchAlgorithmException e) {
// JDK 必须提供 SHA-256;走到这里说明运行环境异常
throw new IllegalStateException("SHA-256 is not available", e);
}
}
}
}

52
sdk-common/src/main/java/common/ecommerce/shared/raw/RawItem.java

@ -0,0 +1,52 @@ @@ -0,0 +1,52 @@
package common.ecommerce.shared.raw;
/**
* 列表响应里单条原始 JSON(不可变)。
*
* <p>用 {@code JsonNode.toString()} 切片,<b>保真</b>:平台返回了 DTO 未声明的
* 字段也会原样保留。{@link #key()} 是按下标对齐后回填的业务键(订单号),
* 对齐不成立时为 null,见 {@link RawPage#itemsAligned()}。</p>
*/
public final class RawItem {
/** 在响应数组中的下标,从 0 开始。 */
private final int index;
/** 对齐后的业务键(channelOrderId);无法确认时为 null。 */
private final String key;
/** 该条原始 JSON 文本。 */
private final String json;
private RawItem(int index, String key, String json) {
this.index = index;
this.key = key;
this.json = json;
}
/** 构造一条切片;{@code key} 允许为 null。 */
public static RawItem of(int index, String key, String json) {
return new RawItem(index, key, json);
}
/** 在响应数组中的下标,从 0 开始。 */
public int index() {
return index;
}
/** 对齐后的业务键;无法确认时为 null。 */
public String key() {
return key;
}
/** 该条原始 JSON 文本。 */
public String json() {
return json;
}
/** 只输出下标与业务键,不含正文。 */
@Override
public String toString() {
return "RawItem{index=" + index + ", key=" + key + '}';
}
}

117
sdk-common/src/main/java/common/ecommerce/shared/raw/RawPage.java

@ -0,0 +1,117 @@ @@ -0,0 +1,117 @@
package common.ecommerce.shared.raw;
import common.ecommerce.shared.support.Page;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 带领原始报文的列表结果。
*
* <p>业务照旧读 {@link #page()} / {@link #items()},留档读
* {@link #exchange()}(整页原文)与 {@link #rawItems()}(逐条原文)。</p>
*
* <p><b>逐条原文只在 {@link #itemsAligned()} 为 true 时才保证与
* {@code items()} 一一对应</b>:两者靠响应数组下标关联,一旦切片条数与
* 结果条数不一致(或某条业务键为空),对齐即不成立,此时逐条数据不得入库,
* 只用整页原文——宁可没有,也不能把 A 单的报文挂到 B 单上。</p>
*
* @param <T> 业务条目类型
*/
public final class RawPage<T> {
/** 原有分页结果。 */
private final Page<T> page;
/** 整页往返;异常路径或未采集时为 null。 */
private final RawExchange exchange;
/** 逐条原始 JSON;不可变。 */
private final List<RawItem> rawItems;
/** 逐条原文与 {@code page.items()} 是否一一对应。 */
private final boolean itemsAligned;
private RawPage(Page<T> page, RawExchange exchange, List<RawItem> rawItems, boolean itemsAligned) {
this.page = page == null ? Page.<T>empty() : page;
this.exchange = exchange;
this.rawItems = Collections.unmodifiableList(
rawItems == null ? new ArrayList<RawItem>() : new ArrayList<RawItem>(rawItems));
this.itemsAligned = itemsAligned;
}
/**
* @param page 业务结果,不能为 null
* @param exchange 整页往返,可为 null
* @param rawItems 逐条原文,可为 null
* @param itemsAligned 逐条原文是否与业务结果一一对应
*/
public static <T> RawPage<T> of(Page<T> page, RawExchange exchange,
List<RawItem> rawItems, boolean itemsAligned) {
return new RawPage<T>(page, exchange, rawItems, itemsAligned);
}
/** 原有分页结果。 */
public Page<T> page() {
return page;
}
/** 当前页业务条目;不可变。 */
public List<T> items() {
return page.items();
}
/** 下一页游标;null 表示结束。 */
public String nextCursor() {
return page.nextCursor();
}
/** 当前页条目数。 */
public int size() {
return page.size();
}
/** 整页往返;未采集时为 null。 */
public RawExchange exchange() {
return exchange;
}
/** 逐条原始 JSON;不可变,按下标顺序。 */
public List<RawItem> rawItems() {
return rawItems;
}
/** 按下标取逐条原文;越界或未采集时返回 null。 */
public RawItem rawItemOf(int index) {
return index < 0 || index >= rawItems.size() ? null : rawItems.get(index);
}
/** 按业务键索引逐条原文;只含 key 非空的条目,顺序与响应一致。 */
public Map<String, RawItem> rawItemsByOrderId() {
Map<String, RawItem> out = new LinkedHashMap<String, RawItem>();
for (RawItem item : rawItems) {
if (item.key() != null && !item.key().trim().isEmpty()) {
out.put(item.key(), item);
}
}
return out;
}
/** 逐条原文是否与 {@link #items()} 一一对应;false 时逐条数据不得入库。 */
public boolean itemsAligned() {
return itemsAligned;
}
/** 只输出条数与对齐状态,不含正文。 */
@Override
public String toString() {
return "RawPage{items=" + page.size()
+ ", rawItems=" + rawItems.size()
+ ", aligned=" + itemsAligned
+ ", bodyBytes=" + (exchange == null ? 0L : exchange.bodyBytes())
+ '}';
}
}

74
sdk-common/src/test/java/common/ecommerce/shared/raw/RawExchangeTest.java

@ -0,0 +1,74 @@ @@ -0,0 +1,74 @@
package common.ecommerce.shared.raw;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 原始往返的保留语义:完整保留 / 超限整份丢弃 / 空响应。
*/
class RawExchangeTest {
@Test
void keepsFullBodyWithDigest() {
RawExchange exchange = RawExchange.builder()
.operation("salesOrders.pull")
.body("{\"a\":1}", 1024)
.build();
assertEquals(RawExchange.BodyState.FULL, exchange.bodyState());
assertEquals("{\"a\":1}", exchange.responseBody());
assertEquals(7L, exchange.bodyBytes());
assertEquals(64, exchange.bodySha256().length());
assertFalse(exchange.truncated());
}
@Test
void omitsOversizedBodyButKeepsDigest() {
RawExchange exchange = RawExchange.builder()
.body("{\"a\":1}", 4)
.build();
assertEquals(RawExchange.BodyState.OMITTED_TOO_LARGE, exchange.bodyState());
assertNull(exchange.responseBody());
assertEquals(7L, exchange.bodyBytes());
assertTrue(exchange.truncated());
assertEquals(64, exchange.bodySha256().length());
}
@Test
void treatsNullBodyAsEmpty() {
RawExchange exchange = RawExchange.builder().body(null, 1024).build();
assertEquals(RawExchange.BodyState.EMPTY, exchange.bodyState());
assertNull(exchange.responseBody());
assertEquals(0L, exchange.bodyBytes());
assertNull(exchange.bodySha256());
}
@Test
void zeroMaxBytesMeansUnlimited() {
RawExchange exchange = RawExchange.builder().body("{\"a\":1}", 0).build();
assertEquals(RawExchange.BodyState.FULL, exchange.bodyState());
assertEquals("{\"a\":1}", exchange.responseBody());
}
@Test
void toStringNeverLeaksBody() {
RawExchange exchange = RawExchange.builder()
.url("https://openapi.lingxing.com/pb/mp/order/v2/list")
.httpMethod("POST")
.requestBody("{\"buyer_name\":\"张三\"}")
.body("{\"buyer_name\":\"张三\"}", 1024)
.build();
String text = exchange.toString();
assertFalse(text.contains("张三"));
assertTrue(text.contains("openapi.lingxing.com"));
assertTrue(text.contains("bytes=23"));
}
}

73
sdk-common/src/test/java/common/ecommerce/shared/raw/RawPageTest.java

@ -0,0 +1,73 @@ @@ -0,0 +1,73 @@
package common.ecommerce.shared.raw;
import common.ecommerce.shared.support.Page;
import org.junit.jupiter.api.Test;
import java.util.Arrays;
import java.util.Collections;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 列表结果载体:下标索引、按业务键索引、对齐标记。
*/
class RawPageTest {
private static RawPage<String> twoRows(boolean aligned) {
Page<String> page = Page.of(Arrays.asList("A-001", "B-002"), null);
return RawPage.of(page, null, Arrays.asList(
RawItem.of(0, "A-001", "{\"no\":\"A-001\"}"),
RawItem.of(1, "B-002", "{\"no\":\"B-002\"}")), aligned);
}
@Test
void indexesItemsByPositionAndKey() {
RawPage<String> raw = twoRows(true);
assertEquals(2, raw.size());
assertEquals("{\"no\":\"B-002\"}", raw.rawItemOf(1).json());
assertEquals(2, raw.rawItemsByOrderId().size());
assertEquals("{\"no\":\"A-001\"}", raw.rawItemsByOrderId().get("A-001").json());
assertTrue(raw.itemsAligned());
}
@Test
void outOfRangeIndexReturnsNull() {
RawPage<String> raw = twoRows(true);
assertNull(raw.rawItemOf(-1));
assertNull(raw.rawItemOf(2));
}
@Test
void skipsBlankKeysInKeyIndex() {
Page<String> page = Page.of(Collections.singletonList("A-001"), null);
RawPage<String> raw = RawPage.of(page, null, Arrays.asList(
RawItem.of(0, null, "{}"),
RawItem.of(1, " ", "{}")), false);
assertTrue(raw.rawItemsByOrderId().isEmpty());
assertFalse(raw.itemsAligned());
}
@Test
void emptyRawItemsAreSafe() {
Page<String> page = Page.<String>empty();
RawPage<String> raw = RawPage.of(page, null, null, false);
assertEquals(0, raw.size());
assertTrue(raw.rawItems().isEmpty());
assertNull(raw.exchange());
}
@Test
void toStringNeverLeaksJson() {
RawPage<String> raw = twoRows(true);
assertFalse(raw.toString().contains("no"));
assertTrue(raw.toString().contains("aligned=true"));
}
}

161
sdk-testkit/src/test/java/common/ecommerce/shared/testkit/RawSalesOrderFacadeTest.java

@ -0,0 +1,161 @@ @@ -0,0 +1,161 @@
package common.ecommerce.shared.testkit;
import common.ecommerce.channel.capability.RawSalesOrderCapable;
import common.ecommerce.channel.model.account.AccountKey;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.order.SalesOrderRef;
import common.ecommerce.channel.sdk.ChannelConnection;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.channel.sdk.ChannelSdk;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.model.Capability;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.raw.RawCapturePolicy;
import common.ecommerce.shared.raw.RawExchange;
import common.ecommerce.shared.raw.RawPage;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.support.PlatformTime;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.Collections;
import java.util.EnumSet;
import java.util.Set;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 门面契约:原文回传的委派与拒绝。
*
* <p>两条边界最重要:实现了 {@link RawSalesOrderCapable} 才允许调
* {@code pullWithRaw};普通 {@code pull()} 不受影响。</p>
*/
class RawSalesOrderFacadeTest {
private static final AccountKey KEY =
AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-raw-001");
private static final ChannelConnection CONNECTION = ChannelConnection.of(
"https://api.example.com",
ChannelSecret.builder().appKey("test-app-id-1234").appSecret("test-secret").build());
private static ChannelSdk sdkWith(common.ecommerce.channel.capability.PlatformAdapter adapter) {
ChannelAccount account = FakeDirectAdapter.account(Platform.WALMART_SC, "oms-raw-001");
return ChannelSdk.builder()
.accountRepository(new InMemoryAccounts().put(account))
.clock(Clock.fixed(Instant.parse("2026-11-04T00:00:00Z"), ZoneOffset.UTC))
.register(adapter)
.build();
}
private static SalesOrderQuery query() {
return SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-11-04T00:00:00Z"))
.build();
}
@Test
void pullWithRawDelegatesToAdapter() {
RecordingRawAdapter adapter = new RecordingRawAdapter();
ChannelSdk sdk = sdkWith(adapter);
RawPage<SalesOrder> raw = sdk.salesOrders(KEY, CONNECTION).pullWithRaw(query());
assertTrue(adapter.pullRawCalled, "门面应委派到 pullRaw");
assertEquals(1, raw.size());
assertNotNull(raw.exchange());
assertEquals("{\"code\":0,\"data\":{\"list\":[]}}", raw.exchange().responseBody());
assertEquals(RawCapturePolicy.defaults().maxBytes(), adapter.policy.maxBytes());
}
@Test
void pullWithRawRejectsAdapterWithoutRawSupport() {
ChannelSdk sdk = sdkWith(FakeDirectAdapter.builder().orders(1).build());
ChannelException error = assertThrows(ChannelException.class,
() -> sdk.salesOrders(KEY, CONNECTION).pullWithRaw(query()));
assertTrue(error.getMessage().contains("raw payload"),
"报错要说清是原文回传不支持,而不是订单能力不支持:" + error.getMessage());
}
@Test
void pullIsUnaffectedByRawFeature() {
ChannelSdk sdk = sdkWith(FakeDirectAdapter.builder().orders(2).build());
Page<SalesOrder> page = sdk.salesOrders(KEY, CONNECTION).pull(query());
assertEquals(2, page.size());
}
/** 只实现订单 + 原文回传的伪适配器,用来验证门面委派。 */
private static final class RecordingRawAdapter implements RawSalesOrderCapable {
private boolean pullRawCalled;
private RawCapturePolicy policy;
@Override
public String adapterId() {
return "fake-raw";
}
@Override
public ChannelProvider provider() {
return ChannelProvider.DIRECT;
}
@Override
public Set<Platform> platforms() {
return EnumSet.of(Platform.WALMART_SC);
}
@Override
public EnumSet<Capability> capabilities() {
return EnumSet.of(Capability.SALES_ORDER);
}
@Override
public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) {
return Page.of(Collections.singletonList(order(ctx)), null);
}
@Override
public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) {
return order(ctx);
}
@Override
public RawPage<SalesOrder> pullRaw(ChannelContext ctx, SalesOrderQuery query,
RawCapturePolicy policy) {
this.pullRawCalled = true;
this.policy = policy;
Page<SalesOrder> page = pull(ctx, query);
RawExchange exchange = RawExchange.builder()
.sequence(1)
.operation("salesOrders.pull")
.httpStatus(200)
.body("{\"code\":0,\"data\":{\"list\":[]}}", policy.maxBytes())
.build();
return RawPage.of(page, exchange, Collections.<common.ecommerce.shared.raw.RawItem>emptyList(), false);
}
private static SalesOrder order(ChannelContext ctx) {
return SalesOrder.builder()
.omsStoreId(ctx.omsStoreId())
.channelOrderId("A-001")
.occurredAt(PlatformTime.of(Instant.parse("2026-11-04T00:00:00Z"),
java.time.ZoneId.of("America/Los_Angeles")))
.sourceProvider(ChannelProvider.DIRECT)
.build();
}
}
}

16
操作手册.md

@ -218,6 +218,22 @@ SalesOrder order = sdk.salesOrders(key, conn).get("PO-123456789"); @@ -218,6 +218,22 @@ SalesOrder order = sdk.salesOrders(key, conn).get("PO-123456789");
`UnsupportedCapabilityException`。商品详情(`sdk.products(key, conn).get(sku)`)**全部未实现**,
会抛 `ChannelException: lingxing product detail is not implemented yet`。
### 4.6 回传原始报文(领星)
需要把领星返回的原始 JSON 一并留档时用 `pullWithRaw`;`pull` 不采集、零额外开销:
```java
RawPage<SalesOrder> raw = sdk.salesOrders(key).pullWithRaw(query);
raw.page(); // 等同于 pull() 的返回值
raw.exchange(); // 整页往返:原文、requestId、平台 request_id、耗时、sha256
raw.rawItems(); // 逐条 JSON(DTO 未声明的字段也保留)
raw.itemsAligned(); // 逐条能否与 items 一一对应,false 时只存整页
```
返回字段、落库表结构、异常分类与 FAQ 见
[`docs/lingxing-order-raw-integration-guide.md`](docs/lingxing-order-raw-integration-guide.md)。
---
## 五、拉取商品 / Listing

Loading…
Cancel
Save