diff --git a/README.md b/README.md index 5379ba7..5c9759c 100644 --- a/README.md +++ b/README.md @@ -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 总体设计) diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RawSalesOrderCapable.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RawSalesOrderCapable.java new file mode 100644 index 0000000..26c4809 --- /dev/null +++ b/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; + +/** + * 可回传原始报文的订单能力。 + * + *

与 {@link SalesOrderCapable} 分开声明:不需要原文的适配器(如沃尔玛直连) + * 不必被迫实现;门面在能力检查阶段就会拒绝,而不是返回一个没有原文的空壳。

+ * + *

实现方只需在发请求时让 {@code LingxingCall} 带上采集器,业务映射代码不用改。

+ */ +public interface RawSalesOrderCapable extends SalesOrderCapable { + + /** + * 分页拉取销售订单,并带回原始响应。 + * + * @param ctx 调用上下文 + * @param query 时间窗与分页条件 + * @param policy 采集策略;传 null 时由适配器使用默认策略 + * @return 业务结果 + 整页原文 + 逐条原文 + */ + RawPage pullRaw(ChannelContext ctx, SalesOrderQuery query, RawCapturePolicy policy); +} diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java index e770aca..6a75904 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java +++ b/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.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 { } /** + * 分页拉取销售订单,同时带回平台原始报文。 + * + *

与 {@link #pull(SalesOrderQuery)} 是两条独立路径:只有本方法会采集原文, + * {@code pull()} 永远不分配采集缓冲。未实现 {@link RawSalesOrderCapable} 的适配器 + * 会明确拒绝,不返回没有原文的结果。

+ * + * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 SALES_ORDER 或未实现 SalesOrderCapable + * @throws ChannelException 适配器不支持原文回传 + */ + public RawPage pullWithRaw(final SalesOrderQuery query) { + return pullWithRaw(query, RawCapturePolicy.defaults()); + } + + /** + * 同上,可指定采集策略(体积上限、是否带请求体、是否逐条切片)。 + * + * @param policy 为 null 时使用 {@link RawCapturePolicy#defaults()} + */ + public RawPage 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 { throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER); } } + + /** + * 原文回传的能力检查:先要支持订单,再要求实现了 {@link RawSalesOrderCapable}。 + * + *

不支持原文时抛普通 {@link ChannelException} 而不是 + * {@code UnsupportedCapabilityException}——订单能力本身是有的, + * 缺的是「回传原文」这个扩展,报错要说清楚,别让人误以为是订单不支持。

+ */ + 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(); + } + } } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java index 97e5205..139ab72 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java +++ b/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.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; 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; 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; * 具体的「拼请求体 + 解析响应」由各子平台的 Source 实现,见 * {@link LingxingSubPlatform}。

*/ -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, filters == null ? LingxingOrderFilters.none() : filters); } + /** + * 分页拉取订单,同时回传原始报文;门面 {@code pullWithRaw} 的落点。 + * + *

采集器只在本次调用内存在,业务映射代码完全不用改。

+ */ + @Override + public RawPage pullRaw(ChannelContext ctx, SalesOrderQuery query, RawCapturePolicy policy) { + return pullRaw(ctx, query, LingxingOrderFilters.none(), policy); + } + + /** + * 同上,附加领星专有过滤条件(按平台单号 / 系统单号 / 跟踪号精确回查时用)。 + * + *

门面不暴露领星专有参数,需要精确回查时直接调本方法。

+ */ + public RawPage 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 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, /** 取 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); } /** diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/http/LingxingEnvelope.java b/lingxing/src/main/java/common/ecommerce/lingxing/http/LingxingEnvelope.java index ac8e5b7..b5d7cd9 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/http/LingxingEnvelope.java +++ b/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 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 { 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 { return message; } + /** 平台工单号(领星顶层 {@code request_id});响应里没有时为 null。 */ + public String platformRequestId() { + return platformRequestId; + } + /** 总数;响应里没有 total 时为 -1。 */ public int total() { return total; diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingCall.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingCall.java index 1504bdc..78b213e 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingCall.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingCall.java @@ -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 { /** 发请求。传输层由子平台持有,这里只做一次转发,避免每个子平台重复写。 */ 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; } } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderSource.java index 75dd424..6978c78 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderSource.java +++ b/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( common.ecommerce.shared.model.Capability.SALES_ORDER); } + + /** + * 列表响应中订单数组的点路径,供原始报文逐条切片。 + * + *

默认是多平台统一订单的 {@code data.list};亚马逊系三个接口的 {@code data} + * 本身就是数组,需要各自覆盖。只有「回传原文」用得到,普通拉单不看这个值。

+ */ + default String rawItemPath() { + return "data.list"; + } } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/RawRecorder.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/RawRecorder.java new file mode 100644 index 0000000..5d920ca --- /dev/null +++ b/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}。 + * + *

为什么放在这一层:全仓 30+ 个 Source 都经过 {@code LingxingCall.execute}, + * 在这里采集不需要改任何业务映射代码;换成在 Source 内部组装,则每个能力都要重写一遍。

+ * + *

生命周期:一次业务调用新建一个,只在当前线程使用,不做同步。 + * 只有显式走 {@code pullRaw} 时才创建;{@code pull()} 路径为 null,不产生任何分配。

+ */ +public final class RawRecorder { + + /** 采集策略,非 null。 */ + private final RawCapturePolicy policy; + + /** 本次调用上下文,用于链路 ID 与时钟。 */ + private final ChannelContext ctx; + + /** JSON 工具,与调用方共用同一个 ObjectMapper。 */ + private final JacksonJsonCodec json; + + /** 按发生顺序累积的往返草稿。 */ + private final List drafts = new ArrayList(); + + 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))); + } + + /** + * 回填平台业务码、消息与工单号。 + * + *

由 {@link LingxingCall#envelope} 在校验通过后调用;失败路径不进这里, + * 由 {@code ChannelException.rawResponse} 携带原文。

+ */ + 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; + } + + /** + * 组装列表结果。 + * + *

逐条原文按响应数组下标与 {@code page.items()} 对齐;条数不一致或某条 + * 业务键为空时 {@code itemsAligned=false},调用方不得把逐条数据入库。

+ * + * @param page 映射后的业务结果 + * @param itemPath 响应数组的点路径(多平台 {@code data.list},亚马逊系 {@code data}) + */ + public RawPage toPage(Page 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 items = new ArrayList(); + 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 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(); + } + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonFbmOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonFbmOrderSource.java index 0e0e9d9..fac452a 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonFbmOrderSource.java +++ b/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_GET = "salesOrders.get.fbm"; + /** FBM 列表的订单数组在 {@code data},不是多平台的 {@code data.list}。 */ + @Override + public String rawItemPath() { + return "data"; + } + @Override public Page orders(LingxingCall call, SalesOrderQuery query) { ChannelAccount account = call.ctx().account(); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonOrderSource.java index fc77579..88c6fc1 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonOrderSource.java +++ b/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_GET = "salesOrders.get.amazon"; + /** 亚马逊 SC 列表的订单数组就在 {@code data},不是多平台的 {@code data.list}。 */ + @Override + public String rawItemPath() { + return "data"; + } + @Override public Page orders(LingxingCall call, SalesOrderQuery query) { ChannelAccount account = call.ctx().account(); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/order/VcOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/order/VcOrderSource.java index d5eae54..36d3ce2 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/order/VcOrderSource.java +++ b/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_GET = "salesOrders.get.vc"; + /** VC 列表的订单数组在 {@code data},不是多平台的 {@code data.list}。 */ + @Override + public String rawItemPath() { + return "data"; + } + @Override public Page orders(LingxingCall call, SalesOrderQuery query) { ChannelAccount account = call.ctx().account(); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformOrderSource.java index 0a49699..ca5d6bf 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformOrderSource.java +++ b/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 { - 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 { Map 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 dtos = mapper.parseList(envelope.body()); diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java index 499c166..9a5a747 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java @@ -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; 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 { assertTrue(hit.size() >= 1, "按平台单号回查没命中,检查 platform_order_no 参数名或时间窗"); } + /** + * 第 3 步(订单 · 原文回传):与 {@link #pullsOnePageOfOrders()} 同一条路由, + * 但走 {@code pullRaw},验证真实响应能被完整采集、切条并对齐。 + * + *

断言:有往返记录、正文完整、含领星 {@code code} 字段、逐条与订单号对齐。 + * 样本会写到模块下的 {@code target/lingxing-raw-sample.json},便于人工核对字段; + * 该文件含买家 PII,只在本机查看,别提交。

+ */ + @Test + void pullsOnePageOfOrdersWithRawPayload() throws Exception { + requireCredentials(); + List 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 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,跳过冒烟"); } + /** 控制台预览用:截断长文本,避免整页报文刷屏。 */ + 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} 列店铺,并打印该子平台下已授权的店铺。 * diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/RawRecorderTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/RawRecorderTest.java new file mode 100644 index 0000000..6bee65c --- /dev/null +++ b/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(), body, 3); + } + + private static Page page(String... orderIds) { + List orders = new ArrayList(); + 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 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 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 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 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 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 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 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 raw = recorder.toPage(Page.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 raw = recorder.toPage(page("A-001"), "data.list"); + + assertTrue(raw.rawItemOf(0).json().contains("undocumented")); + assertEquals(Collections.singletonList("A-001"), + new ArrayList(raw.rawItemsByOrderId().keySet())); + } + + @Test + void pageOrderIsPreserved() { + RawRecorder recorder = recorder(RawCapturePolicy.defaults()); + recorder.record(request(), response(TWO_ITEMS), System.nanoTime()); + + RawPage raw = recorder.toPage(page("A-001", "B-002"), "data.list"); + + List keys = new ArrayList(raw.rawItemsByOrderId().keySet()); + assertEquals(Arrays.asList("A-001", "B-002"), keys); + } +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformRawPullTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/multiplatform/order/MultiPlatformRawPullTest.java new file mode 100644 index 0000000..7983789 --- /dev/null +++ b/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; + +/** + * 多平台订单列表的原文回传全链路。 + * + *

兼作回归:{@code MultiPlatformOrderSource} 曾经直接用 {@code transport.execute} + * 绕过 {@code LingxingCall},那样采集器拿不到任何往返,这里的 exchange 会是 null。

+ */ +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 page = new MultiPlatformOrderSource(transport, JSON).orders(lxCall, query()); + RawPage 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()); + } +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/support/LingxingTestSupport.java b/lingxing/src/test/java/common/ecommerce/lingxing/support/LingxingTestSupport.java index d002e64..3b03b3d 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/support/LingxingTestSupport.java +++ b/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.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 { *

token 请求走 {@link RecordingTransport} 的默认响应,不占业务路由。

*/ 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); } /** 取最后一次业务请求的请求体;没有业务请求时报错。 */ diff --git a/sdk-common/src/main/java/common/ecommerce/shared/raw/RawCapturePolicy.java b/sdk-common/src/main/java/common/ecommerce/shared/raw/RawCapturePolicy.java new file mode 100644 index 0000000..c53469c --- /dev/null +++ b/sdk-common/src/main/java/common/ecommerce/shared/raw/RawCapturePolicy.java @@ -0,0 +1,99 @@ +package common.ecommerce.shared.raw; + +/** + * 原始报文采集策略。 + * + *

只在显式调用 {@code pullWithRaw} 时生效;{@code pull()} 路径不采集, + * 也不分配任何缓冲。

+ * + *

默认值取舍:单页原文上限 4 MiB(领星多平台单页 500 条、单条 2~4 KB, + * 正常一页 1~2 MB);请求体默认不采集,因为领星请求体含 {@code sign}; + * 逐条切片默认开启。

+ */ +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); + } + } +} diff --git a/sdk-common/src/main/java/common/ecommerce/shared/raw/RawExchange.java b/sdk-common/src/main/java/common/ecommerce/shared/raw/RawExchange.java new file mode 100644 index 0000000..ee33e8a --- /dev/null +++ b/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 往返的原始留痕(不可变)。 + * + *

只承载「平台真正回了什么」,不做业务解释:请求元信息、响应原文、 + * 体积摘要与耗时。原文超过上限时整份丢弃而不截断——半截 JSON + * 既不能入库也不能排查,还会让人误以为拿到了完整数据,因此只保留 + * 字节数与 SHA-256,由 {@link BodyState} 显式表达。

+ * + *

敏感信息约定:{@link #toString()} 不输出正文;正文里可能含买家 + * 姓名、地址、电话等个人信息,禁止直接打日志。请求体默认不采集 + * ({@link RawCapturePolicy#includeRequest()} 默认 false),因为领星请求体含签名。

+ */ +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 与保留状态。 + * + *

{@code maxBytes} 为正且原文超过它时,正文整份丢弃、状态为 + * {@link BodyState#OMITTED_TOO_LARGE};传 0 或负数表示不限制。

+ * + * @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); + } + } + } +} diff --git a/sdk-common/src/main/java/common/ecommerce/shared/raw/RawItem.java b/sdk-common/src/main/java/common/ecommerce/shared/raw/RawItem.java new file mode 100644 index 0000000..d6c694e --- /dev/null +++ b/sdk-common/src/main/java/common/ecommerce/shared/raw/RawItem.java @@ -0,0 +1,52 @@ +package common.ecommerce.shared.raw; + +/** + * 列表响应里单条原始 JSON(不可变)。 + * + *

用 {@code JsonNode.toString()} 切片,保真:平台返回了 DTO 未声明的 + * 字段也会原样保留。{@link #key()} 是按下标对齐后回填的业务键(订单号), + * 对齐不成立时为 null,见 {@link RawPage#itemsAligned()}。

+ */ +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 + '}'; + } +} diff --git a/sdk-common/src/main/java/common/ecommerce/shared/raw/RawPage.java b/sdk-common/src/main/java/common/ecommerce/shared/raw/RawPage.java new file mode 100644 index 0000000..4ebb012 --- /dev/null +++ b/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; + +/** + * 带领原始报文的列表结果。 + * + *

业务照旧读 {@link #page()} / {@link #items()},留档读 + * {@link #exchange()}(整页原文)与 {@link #rawItems()}(逐条原文)。

+ * + *

逐条原文只在 {@link #itemsAligned()} 为 true 时才保证与 + * {@code items()} 一一对应:两者靠响应数组下标关联,一旦切片条数与 + * 结果条数不一致(或某条业务键为空),对齐即不成立,此时逐条数据不得入库, + * 只用整页原文——宁可没有,也不能把 A 单的报文挂到 B 单上。

+ * + * @param 业务条目类型 + */ +public final class RawPage { + + /** 原有分页结果。 */ + private final Page page; + + /** 整页往返;异常路径或未采集时为 null。 */ + private final RawExchange exchange; + + /** 逐条原始 JSON;不可变。 */ + private final List rawItems; + + /** 逐条原文与 {@code page.items()} 是否一一对应。 */ + private final boolean itemsAligned; + + private RawPage(Page page, RawExchange exchange, List rawItems, boolean itemsAligned) { + this.page = page == null ? Page.empty() : page; + this.exchange = exchange; + this.rawItems = Collections.unmodifiableList( + rawItems == null ? new ArrayList() : new ArrayList(rawItems)); + this.itemsAligned = itemsAligned; + } + + /** + * @param page 业务结果,不能为 null + * @param exchange 整页往返,可为 null + * @param rawItems 逐条原文,可为 null + * @param itemsAligned 逐条原文是否与业务结果一一对应 + */ + public static RawPage of(Page page, RawExchange exchange, + List rawItems, boolean itemsAligned) { + return new RawPage(page, exchange, rawItems, itemsAligned); + } + + /** 原有分页结果。 */ + public Page page() { + return page; + } + + /** 当前页业务条目;不可变。 */ + public List 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 rawItems() { + return rawItems; + } + + /** 按下标取逐条原文;越界或未采集时返回 null。 */ + public RawItem rawItemOf(int index) { + return index < 0 || index >= rawItems.size() ? null : rawItems.get(index); + } + + /** 按业务键索引逐条原文;只含 key 非空的条目,顺序与响应一致。 */ + public Map rawItemsByOrderId() { + Map out = new LinkedHashMap(); + 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()) + + '}'; + } +} diff --git a/sdk-common/src/test/java/common/ecommerce/shared/raw/RawExchangeTest.java b/sdk-common/src/test/java/common/ecommerce/shared/raw/RawExchangeTest.java new file mode 100644 index 0000000..de9fe0f --- /dev/null +++ b/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")); + } +} diff --git a/sdk-common/src/test/java/common/ecommerce/shared/raw/RawPageTest.java b/sdk-common/src/test/java/common/ecommerce/shared/raw/RawPageTest.java new file mode 100644 index 0000000..6df3614 --- /dev/null +++ b/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 twoRows(boolean aligned) { + Page 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 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 raw = twoRows(true); + + assertNull(raw.rawItemOf(-1)); + assertNull(raw.rawItemOf(2)); + } + + @Test + void skipsBlankKeysInKeyIndex() { + Page page = Page.of(Collections.singletonList("A-001"), null); + RawPage 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 page = Page.empty(); + RawPage raw = RawPage.of(page, null, null, false); + + assertEquals(0, raw.size()); + assertTrue(raw.rawItems().isEmpty()); + assertNull(raw.exchange()); + } + + @Test + void toStringNeverLeaksJson() { + RawPage raw = twoRows(true); + + assertFalse(raw.toString().contains("no")); + assertTrue(raw.toString().contains("aligned=true")); + } +} diff --git a/sdk-testkit/src/test/java/common/ecommerce/shared/testkit/RawSalesOrderFacadeTest.java b/sdk-testkit/src/test/java/common/ecommerce/shared/testkit/RawSalesOrderFacadeTest.java new file mode 100644 index 0000000..d801d84 --- /dev/null +++ b/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; + +/** + * 门面契约:原文回传的委派与拒绝。 + * + *

两条边界最重要:实现了 {@link RawSalesOrderCapable} 才允许调 + * {@code pullWithRaw};普通 {@code pull()} 不受影响。

+ */ +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 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 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 platforms() { + return EnumSet.of(Platform.WALMART_SC); + } + + @Override + public EnumSet capabilities() { + return EnumSet.of(Capability.SALES_ORDER); + } + + @Override + public Page 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 pullRaw(ChannelContext ctx, SalesOrderQuery query, + RawCapturePolicy policy) { + this.pullRawCalled = true; + this.policy = policy; + Page 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.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(); + } + } +} diff --git a/操作手册.md b/操作手册.md index 28c0a0b..6616798 100644 --- a/操作手册.md +++ b/操作手册.md @@ -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 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