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 1 day 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 # 恒健目录 / 渠道 / 商品 / 出
## 设计文档 ## 设计文档
- [`GUIDE.md`](GUIDE.md):开发指南 —— 心智模型、基接口逐个讲、接入新平台 8 步、5 层测试 - [`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 总体设计) - 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 @@
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;
import common.ecommerce.channel.model.order.SalesOrderRef; import common.ecommerce.channel.model.order.SalesOrderRef;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.audit.CallSupport; 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 common.ecommerce.channel.sdk.ChannelContext;
import java.util.List; import java.util.List;
@ -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 * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 SALES_ORDER 或未实现 SalesOrderCapable
@ -166,4 +202,28 @@ public final class SalesOrders {
throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER); 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;
import common.ecommerce.channel.capability.OutboundCapable; import common.ecommerce.channel.capability.OutboundCapable;
import common.ecommerce.channel.capability.OutboundOrderCapable; import common.ecommerce.channel.capability.OutboundOrderCapable;
import common.ecommerce.channel.capability.ProductCapable; import common.ecommerce.channel.capability.ProductCapable;
import common.ecommerce.channel.capability.RawSalesOrderCapable;
import common.ecommerce.channel.capability.SalesOrderCapable; import common.ecommerce.channel.capability.SalesOrderCapable;
import common.ecommerce.channel.capability.SettlementCapable; import common.ecommerce.channel.capability.SettlementCapable;
import common.ecommerce.channel.capability.ShipmentReviewCapable; import common.ecommerce.channel.capability.ShipmentReviewCapable;
@ -30,6 +31,7 @@ import common.ecommerce.lingxing.platform.LingxingSubPlatform;
import common.ecommerce.lingxing.platform.LingxingSubPlatformDefaults; import common.ecommerce.lingxing.platform.LingxingSubPlatformDefaults;
import common.ecommerce.lingxing.platform.LingxingOutboundSource; import common.ecommerce.lingxing.platform.LingxingOutboundSource;
import common.ecommerce.lingxing.platform.LingxingSubPlatforms; 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.multiplatform.order.LingxingOrderFilters;
import common.ecommerce.lingxing.platform.wms.OrderEditSource; import common.ecommerce.lingxing.platform.wms.OrderEditSource;
import common.ecommerce.lingxing.platform.wms.ShipmentReviewSource; import common.ecommerce.lingxing.platform.wms.ShipmentReviewSource;
@ -64,6 +66,8 @@ import common.ecommerce.channel.model.product.ProductSyncStrategy;
import common.ecommerce.channel.model.settlement.SettlementQuery; import common.ecommerce.channel.model.settlement.SettlementQuery;
import common.ecommerce.channel.model.settlement.SettlementTransaction; import common.ecommerce.channel.model.settlement.SettlementTransaction;
import common.ecommerce.shared.support.Page; 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.channel.sdk.ChannelContext;
import common.ecommerce.shared.spi.AccessToken; import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.ChannelSecret;
@ -85,8 +89,8 @@ import java.util.Set;
* 具体的「拼请求体 + 解析响应」由各子平台的 Source 实现,见 * 具体的「拼请求体 + 解析响应」由各子平台的 Source 实现,见
* {@link LingxingSubPlatform}。</p> * {@link LingxingSubPlatform}。</p>
*/ */
public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, SettlementCapable, public final class LingxingAdapter implements SalesOrderCapable, RawSalesOrderCapable, ProductCapable,
OutboundCapable, AfterSaleCapable, OutboundOrderCapable, ShippingLabelCapable, SettlementCapable, OutboundCapable, AfterSaleCapable, OutboundOrderCapable, ShippingLabelCapable,
ShipmentReviewCapable, OrderEditCapable, InboundShipmentCapable, InboundReceiptCapable, ShipmentReviewCapable, OrderEditCapable, InboundShipmentCapable, InboundReceiptCapable,
AggregatorCapable { AggregatorCapable {
@ -298,6 +302,34 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
filters == null ? LingxingOrderFilters.none() : filters); 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 @Override
public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) {
LingxingSubPlatform impl = subPlatforms.of(ctx.platform()); LingxingSubPlatform impl = subPlatforms.of(ctx.platform());
@ -449,9 +481,18 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
/** 取 token 并装配本次调用所需的公共设施。 */ /** 取 token 并装配本次调用所需的公共设施。 */
private LingxingCall call(ChannelContext ctx) { 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(); ChannelSecret secret = ctx.secret();
AccessToken token = tokenManager.getOrRefresh(tokenKey(secret), 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 {
private final String body; private final String body;
private final String code; private final String code;
private final String message; private final String message;
private final String platformRequestId;
private final int total; 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.body = body;
this.code = code; this.code = code;
this.message = message; this.message = message;
this.platformRequestId = platformRequestId;
this.total = total; this.total = total;
} }
@ -78,7 +80,7 @@ public final class LingxingEnvelope {
if (!"0".equals(code) && !"200".equals(code)) { if (!"0".equals(code) && !"200".equals(code)) {
throw failure(code, b); 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) { private static ChannelException failure(String code, ChannelException.Builder b) {
@ -120,6 +122,11 @@ public final class LingxingEnvelope {
return message; return message;
} }
/** 平台工单号(领星顶层 {@code request_id});响应里没有时为 null。 */
public String platformRequestId() {
return platformRequestId;
}
/** 总数;响应里没有 total 时为 -1。 */ /** 总数;响应里没有 total 时为 -1。 */
public int total() { public int total() {
return total; return total;

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

@ -28,15 +28,28 @@ public final class LingxingCall {
private final JacksonJsonCodec json; private final JacksonJsonCodec json;
private final common.ecommerce.http.HttpTransport transport; private final common.ecommerce.http.HttpTransport transport;
/** 原始报文采集器;null 表示本次调用不采集(默认路径,零额外开销)。 */
private final RawRecorder recorder;
public LingxingCall(ChannelContext ctx, AccessToken token, LingxingRequestFactory requestFactory, public LingxingCall(ChannelContext ctx, AccessToken token, LingxingRequestFactory requestFactory,
LingxingRateLimiter rateLimiter, JacksonJsonCodec json, LingxingRateLimiter rateLimiter, JacksonJsonCodec json,
common.ecommerce.http.HttpTransport transport) { 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.ctx = ctx;
this.token = token; this.token = token;
this.requestFactory = requestFactory; this.requestFactory = requestFactory;
this.rateLimiter = rateLimiter; this.rateLimiter = rateLimiter;
this.json = json; this.json = json;
this.transport = transport; this.transport = transport;
this.recorder = recorder;
} }
public ChannelContext ctx() { public ChannelContext ctx() {
@ -70,16 +83,29 @@ public final class LingxingCall {
/** 发请求。传输层由子平台持有,这里只做一次转发,避免每个子平台重复写。 */ /** 发请求。传输层由子平台持有,这里只做一次转发,避免每个子平台重复写。 */
public HttpResponse execute(HttpRequest request) { 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 供子平台解析。 */ /** 校验 HTTP 状态与业务码,返回原始 body 供子平台解析。 */
public String body(HttpResponse response, String operation) { 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 时为负数。 */ /** 同上,同时给出 data.total;接口没有 total 时为负数。 */
public LingxingEnvelope envelope(HttpResponse response, String operation) { 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 {
throw new common.ecommerce.shared.error.ChannelException.UnsupportedCapabilityException( throw new common.ecommerce.shared.error.ChannelException.UnsupportedCapabilityException(
common.ecommerce.shared.model.Capability.SALES_ORDER); 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 @@
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 {
private static final String OP_PULL = "salesOrders.pull.fbm"; private static final String OP_PULL = "salesOrders.pull.fbm";
private static final String OP_GET = "salesOrders.get.fbm"; private static final String OP_GET = "salesOrders.get.fbm";
/** FBM 列表的订单数组在 {@code data},不是多平台的 {@code data.list}。 */
@Override
public String rawItemPath() {
return "data";
}
@Override @Override
public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) { public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) {
ChannelAccount account = call.ctx().account(); 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 {
private static final String OP_PULL = "salesOrders.pull.amazon"; private static final String OP_PULL = "salesOrders.pull.amazon";
private static final String OP_GET = "salesOrders.get.amazon"; private static final String OP_GET = "salesOrders.get.amazon";
/** 亚马逊 SC 列表的订单数组就在 {@code data},不是多平台的 {@code data.list}。 */
@Override
public String rawItemPath() {
return "data";
}
@Override @Override
public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) { public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) {
ChannelAccount account = call.ctx().account(); 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 {
private static final String OP_PULL = "salesOrders.pull.vc"; private static final String OP_PULL = "salesOrders.pull.vc";
private static final String OP_GET = "salesOrders.get.vc"; private static final String OP_GET = "salesOrders.get.vc";
/** VC 列表的订单数组在 {@code data},不是多平台的 {@code data.list}。 */
@Override
public String rawItemPath() {
return "data";
}
@Override @Override
public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) { public Page<SalesOrder> orders(LingxingCall call, SalesOrderQuery query) {
ChannelAccount account = call.ctx().account(); 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;
*/ */
public class MultiPlatformOrderSource implements LingxingOrderSource { public class MultiPlatformOrderSource implements LingxingOrderSource {
private final HttpTransport transport;
private final LingxingOrderMapper mapper; private final LingxingOrderMapper mapper;
/**
* @param transport 已不再直连使用:请求统一经 {@link LingxingCall#execute} 发出,
* 否则挂在调用上的原始报文采集会漏掉本路由。参数保留是为了
* 各子平台装配签名稳定。
*/
public MultiPlatformOrderSource(HttpTransport transport, JacksonJsonCodec json) { public MultiPlatformOrderSource(HttpTransport transport, JacksonJsonCodec json) {
this.transport = transport;
this.mapper = new LingxingOrderMapper(json); this.mapper = new LingxingOrderMapper(json);
} }
@ -125,7 +128,8 @@ public class MultiPlatformOrderSource implements LingxingOrderSource {
Map<String, Object> body = orderBody(account, from, to, offset, length, effective); Map<String, Object> body = orderBody(account, from, to, offset, length, effective);
HttpRequest req = call.signed(orderApi(), body, "salesOrders.pull"); 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"); LingxingEnvelope envelope = call.envelope(resp, "salesOrders.pull");
List<LingxingOrderDto> dtos = mapper.parseList(envelope.body()); List<LingxingOrderDto> dtos = mapper.parseList(envelope.body());

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

@ -1,6 +1,9 @@
package common.ecommerce.lingxing.adapter; package common.ecommerce.lingxing.adapter;
import common.ecommerce.channel.capability.AggregatorCapable.SubChannel; 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.HttpRequest;
import common.ecommerce.http.HttpResponse; import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport; import common.ecommerce.http.HttpTransport;
@ -70,6 +73,7 @@ import java.util.List;
import java.util.Map; import java.util.Map;
import java.util.TreeMap; 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.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assertions.assertTrue;
@ -511,6 +515,71 @@ class LingxingLiveSmokeTest {
assertTrue(hit.size() >= 1, "按平台单号回查没命中,检查 platform_order_no 参数名或时间窗"); 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 {
"未提供 -Dlingxing.probe.appKey / -Dlingxing.probe.appSecret,跳过冒烟"); "未提供 -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} 列店铺,并打印该子平台下已授权的店铺。 * 按 {@code PLATFORM_CODE} 列店铺,并打印该子平台下已授权的店铺。
* *

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

@ -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 @@
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;
import common.ecommerce.lingxing.http.LingxingRateLimiter; import common.ecommerce.lingxing.http.LingxingRateLimiter;
import common.ecommerce.lingxing.http.LingxingRequestFactory; import common.ecommerce.lingxing.http.LingxingRequestFactory;
import common.ecommerce.lingxing.platform.LingxingCall; import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.RawRecorder;
import common.ecommerce.shared.model.ChannelProvider; import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform; import common.ecommerce.shared.model.Platform;
import common.ecommerce.channel.model.account.AccountKey; import common.ecommerce.channel.model.account.AccountKey;
@ -72,13 +73,28 @@ public final class LingxingTestSupport {
* <p>token 请求走 {@link RecordingTransport} 的默认响应,不占业务路由。</p> * <p>token 请求走 {@link RecordingTransport} 的默认响应,不占业务路由。</p>
*/ */
public static LingxingCall call(RecordingTransport transport, ChannelAccount account) { public static LingxingCall call(RecordingTransport transport, ChannelAccount account) {
ChannelSecret secret = ChannelSecret.builder().appKey(APP_KEY).appSecret(APP_SECRET).build(); return call(transport, account, null);
ChannelConnection conn = ChannelConnection.of(ENDPOINT, secret); }
ChannelContext ctx = ChannelContext.of(account, conn, "req-1", CLOCK);
/**
* 同上,可挂原始报文采集器。
*
* @param recorder 传 null 等价于不采集
*/
public static LingxingCall call(RecordingTransport transport, ChannelAccount account,
RawRecorder recorder) {
ChannelContext ctx = context(account);
AccessToken token = new LingxingTokenClient(transport, JSON, CLOCK) AccessToken token = new LingxingTokenClient(transport, JSON, CLOCK)
.fetch(ENDPOINT, APP_KEY, APP_SECRET); .fetch(ENDPOINT, APP_KEY, APP_SECRET);
return new LingxingCall(ctx, token, new LingxingRequestFactory(JSON, CLOCK), 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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");
`UnsupportedCapabilityException`。商品详情(`sdk.products(key, conn).get(sku)`)**全部未实现**, `UnsupportedCapabilityException`。商品详情(`sdk.products(key, conn).get(sku)`)**全部未实现**,
会抛 `ChannelException: lingxing product detail is not implemented yet`。 会抛 `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 ## 五、拉取商品 / Listing

Loading…
Cancel
Save