From b6c0bbbdd341971f14db1ae97383fbb1ccb3df99 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Fri, 20 Nov 2026 09:47:38 +0800 Subject: [PATCH] =?UTF-8?q?fix(walmart):=20shipDateTime=20=E5=93=8D?= =?UTF-8?q?=E5=BA=94=E7=B1=BB=E5=9E=8B=E6=8C=89=E5=AE=98=E6=96=B9=20schema?= =?UTF-8?q?=20=E4=BF=AE=E6=AD=A3=E4=B8=BA=20int64?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 官方 Orders spec 里 trackingInfo.shipDateTime 在请求与响应中都是 {"type":"integer","format":"int64"},实测响应示例为 1580821866000。 原实现把响应字段声明成 String 并注释为「ISO-8601 字符串」,导致: - getShipping 侥幸能用(Jackson 把数字转成 "1580821866000"), 但返回值形态与官方语义不符 - markShipped 的 ShipmentResult.shippedAt 恒为 null: Instant.parse("1580821866000") 抛异常后被吞掉 【改动】 - TrackingInfo.shipDateTime 改为 Object,同时接住 int64 与 ISO-8601 - WalmartShipmentMapper 增加 shipTimeOf:统一转成字符串原值, 保留平台原值不做时区换算 - WalmartShipmentWriteMapper 的 parseShipTime 兼容 epoch 毫秒(Number 与数字串) 和 ISO-8601,解析失败返回 null - 三个测试夹具从 ISO 字符串改成官方形态的 epoch 毫秒—— 原来的夹具是错的,所以错的实现一直测不出来 【其它】 - 修正 WalmartShipmentMapper javadoc 里指向已删除方法 toShipmentLines 的链接 - 删除 WalmartRefundMapper 未使用的 import - ITEM_CURSOR_INITIAL / ITEM_CURSOR_TTL_SECONDS 补注释: 适配器不显式传初始游标,常量供宿主的游标缓存参考 【测试】159 个全过。 Co-Authored-By: Claude Code --- .../common/ecommerce/walmart/WalmartConstants.java | 13 +++++++---- .../ecommerce/walmart/dto/WalmartOrderDtos.java | 10 ++++++-- .../walmart/mapper/WalmartRefundMapper.java | 1 - .../walmart/mapper/WalmartShipmentMapper.java | 21 +++++++++++++++-- .../walmart/mapper/WalmartShipmentWriteMapper.java | 27 +++++++++++++++++----- .../walmart/adapter/WalmartExtraQueryTest.java | 7 +++--- .../walmart/adapter/WalmartMarkShippedTest.java | 2 +- 7 files changed, 62 insertions(+), 19 deletions(-) diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java index 2c6a081..ea15da3 100644 --- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java @@ -93,14 +93,19 @@ public final class WalmartConstants { public static final int MAX_ITEM_PAGE_SIZE = 1000; /** - * 商品列表 {@code nextCursor} 的初始值。 + * 商品列表 {@code nextCursor} 的初始值(官方 schema 的 default 与 example)。 * - *

官方 schema 的 {@code default} 与 {@code example} 都是 {@code *}。 - * 不过首页不传也能用平台默认,适配器选择不显式传,避免平台版本差异导致 400。

+ *

适配器不显式传它:首页不传即可用平台默认,显式传 {@code *} 反而可能 + * 因平台版本差异被拒。这个常量供宿主做游标缓存时参考。

*/ public static final String ITEM_CURSOR_INITIAL = "*"; - /** 商品游标有效期(秒);过期平台返回 400 Invalid Cursor。 */ + /** + * 商品游标有效期(秒)。 + * + *

官方原文:{@code The cursor remains the same across all page requests and is valid + * for 2 minutes.} 过期返回 400 Invalid Cursor。宿主缓存游标时不要超过这个时长。

+ */ public static final int ITEM_CURSOR_TTL_SECONDS = 120; /** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */ diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java index 097a51f..422a6aa 100644 --- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java @@ -336,9 +336,15 @@ public final class WalmartOrderDtos { @JsonIgnoreProperties(ignoreUnknown = true) public static final class TrackingInfo { - /** 发货时间,ISO-8601 字符串(与订单其它时间是 epoch 毫秒不同)。 */ + /** + * 发货时间。 + * + *

官方 Orders schema 里是 {@code integer / int64}(epoch 毫秒), + * 但部分旧响应与第三方资料给的是 ISO-8601 字符串。用 {@link Object} 接住两种形态, + * 由 {@link common.ecommerce.walmart.mapper.WalmartShipmentMapper} 统一转成字符串。

+ */ @JsonProperty("shipDateTime") - public String shipDateTime; + public Object shipDateTime; /** 承运商。 */ @JsonProperty("carrierName") diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java index 6cb618d..c2b2dc4 100644 --- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java @@ -6,7 +6,6 @@ import common.ecommerce.walmart.dto.WalmartRefundDtos; import common.ecommerce.walmart.dto.WalmartReturnDtos; import java.util.ArrayList; -import java.util.List; /** * 退款:{@link RefundCommand} → 沃尔玛请求体;沃尔玛响应 → {@link RefundResult}。 diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java index 26ed820..981f827 100644 --- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java @@ -25,7 +25,7 @@ public final class WalmartShipmentMapper { * *

沃尔玛没有「查询发货信息」的 GET 路由,发货信息本来就在订单详情的 * {@code orderLines[].orderLineStatuses[].trackingInfo} 里。这个方法把订单体 - * 转成与 {@link #toShipmentLines} 相同的结构,所以调用方不用关心数据来自哪条路由。

+ * 转成统一的 {@link ShipmentLine},所以调用方不用关心数据来自哪条路由。

* *

只输出有 {@code trackingInfo} 的行;未发货的行不出现。

* @@ -55,13 +55,30 @@ public final class WalmartShipmentMapper { : tracking.carrierName.otherCarrier), tracking.methodCode, tracking.trackingNumber, - tracking.shipDateTime)); + shipTimeOf(tracking.shipDateTime))); break; } } return out; } + /** + * 发货时间的字符串形态。 + * + *

官方 schema 是 epoch 毫秒(int64),Jackson 会反序列化成 {@link Number}; + * 也兼容 ISO-8601 字符串。统一输出字符串,保留平台原值不做时区换算。

+ */ + static String shipTimeOf(Object raw) { + if (raw == null) { + return null; + } + if (raw instanceof Number) { + return String.valueOf(((Number) raw).longValue()); + } + String text = String.valueOf(raw).trim(); + return text.isEmpty() ? null : text; + } + /** 一行的发货记录。 */ public static final class ShipmentLine { diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java index c36802b..fa30287 100644 --- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java @@ -8,7 +8,6 @@ import common.ecommerce.walmart.dto.WalmartShipmentWriteDtos; import java.time.Clock; import java.time.Instant; import java.util.ArrayList; -import java.util.List; /** * 标发:{@link ShipmentCommand} → 沃尔玛请求体;沃尔玛订单响应 → {@link ShipmentResult}。 @@ -136,9 +135,9 @@ public final class WalmartShipmentWriteMapper { if (!trackingSet && s.trackingInfo.trackingNumber != null) { tracking = s.trackingInfo.trackingNumber; } - // shipDateTime 是 ISO-8601 字符串,与订单其它时间的 epoch 毫秒不同 + // 官方 schema 是 epoch 毫秒(int64),也兼容 ISO-8601 字符串 if (!trackingSet && s.trackingInfo.shipDateTime != null) { - builder.shippedAt(parseInstant(s.trackingInfo.shipDateTime)); + builder.shippedAt(parseShipTime(s.trackingInfo.shipDateTime)); } } } @@ -193,11 +192,27 @@ public final class WalmartShipmentWriteMapper { } /** ISO-8601 字符串 → Instant;解析失败返回 null,不让脏时间卡住结果。 */ - private static Instant parseInstant(String iso) { + /** 发货时间:官方是 epoch 毫秒,也兼容 ISO-8601 字符串;解析失败返回 null。 */ + private static Instant parseShipTime(Object raw) { + if (raw == null) { + return null; + } + if (raw instanceof Number) { + return Instant.ofEpochMilli(((Number) raw).longValue()); + } + String text = String.valueOf(raw).trim(); + if (text.isEmpty()) { + return null; + } try { - return Instant.parse(iso.trim()); + return Instant.parse(text); } catch (RuntimeException e) { - return null; + // 纯数字字符串也按 epoch 毫秒处理 + try { + return Instant.ofEpochMilli(Long.parseLong(text)); + } catch (NumberFormatException ignored) { + return null; + } } } } diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java index e7ab41f..b77987b 100644 --- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java +++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java @@ -57,7 +57,7 @@ class WalmartExtraQueryTest { + "{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},\"trackingInfo\":null}," + "{\"status\":\"Shipped\",\"statusQuantity\":" + "{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},\"trackingInfo\":{" - + "\"shipDateTime\":\"2026-11-16T07:00:00.000Z\"," + + "\"shipDateTime\":1580821866000," + "\"carrierName\":{\"carrier\":\"UPS\"}," + "\"methodCode\":\"Standard\"," + "\"trackingNumber\":\"1Z999AA10123456784\"}}]}}]}}}"; @@ -185,7 +185,8 @@ class WalmartExtraQueryTest { assertEquals("UPS", lines.get(0).carrier()); assertEquals("Standard", lines.get(0).methodCode()); assertEquals("1Z999AA10123456784", lines.get(0).trackingNumber()); - assertEquals("2026-11-16T07:00:00.000Z", lines.get(0).shipDateTime()); + // 官方 schema 是 epoch 毫秒;适配器统一转成字符串原值 + assertEquals("1580821866000", lines.get(0).shipDateTime()); } @Test @@ -196,7 +197,7 @@ class WalmartExtraQueryTest { + "\"orderLineQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"}," + "\"orderLineStatuses\":{\"orderLineStatus\":[{\"status\":\"Shipped\"," + "\"statusQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"}," - + "\"trackingInfo\":{\"shipDateTime\":\"2026-11-16T08:00:00.000Z\"," + + "\"trackingInfo\":{\"shipDateTime\":1580822466000," + "\"carrierName\":{\"otherCarrier\":\"Local Courier\"}," + "\"methodCode\":\"Freight\",\"trackingNumber\":\"LC-1\"}}]}}]}}}"; RecordingTransport transport = RecordingTransport.create() diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java index fd66230..dffde7b 100644 --- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java +++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java @@ -39,7 +39,7 @@ class WalmartMarkShippedTest { + "\"orderLineQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"2\"}," + "\"orderLineStatuses\":{\"orderLineStatus\":[" + "{\"status\":\"Shipped\",\"statusQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"2\"}," - + "\"trackingInfo\":{\"shipDateTime\":\"2026-11-19T02:00:00.000Z\"," + + "\"trackingInfo\":{\"shipDateTime\":1795053600000," + "\"carrierName\":{\"carrier\":\"UPS\"},\"methodCode\":\"Standard\"," + "\"trackingNumber\":\"1Z999AA10123456784\"}}]}}]}}}"; }