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与 {@link #pull(SalesOrderQuery)} 是两条独立路径:只有本方法会采集原文, + * {@code pull()} 永远不分配采集缓冲。未实现 {@link RawSalesOrderCapable} 的适配器 + * 会明确拒绝,不返回没有原文的结果。
+ * + * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 SALES_ORDER 或未实现 SalesOrderCapable + * @throws ChannelException 适配器不支持原文回传 + */ + public RawPage不支持原文时抛普通 {@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门面不暴露领星专有参数,需要精确回查时直接调本方法。
+ */ + public RawPage默认是多平台统一订单的 {@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由 {@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断言:有往返记录、正文完整、含领星 {@code code} 字段、逐条与订单号对齐。 + * 样本会写到模块下的 {@code target/lingxing-raw-sample.json},便于人工核对字段; + * 该文件含买家 PII,只在本机查看,别提交。
+ */ + @Test + void pullsOnePageOfOrdersWithRawPayload() throws Exception { + requireCredentials(); + List兼作回归:{@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); + + Pagetoken 请求走 {@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两条边界最重要:实现了 {@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