Browse Source

fix(walmart): shipDateTime 响应类型按官方 schema 修正为 int64

官方 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 <noreply@anthropic.com>
lml 9 hours ago
parent
commit
b6c0bbbdd3
  1. 13
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java
  2. 10
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java
  3. 1
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java
  4. 21
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java
  5. 27
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java
  6. 7
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java
  7. 2
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java

13
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java

@ -93,14 +93,19 @@ public final class WalmartConstants { @@ -93,14 +93,19 @@ public final class WalmartConstants {
public static final int MAX_ITEM_PAGE_SIZE = 1000;
/**
* 商品列表 {@code nextCursor} 的初始值。
* 商品列表 {@code nextCursor} 的初始值(官方 schema 的 default 与 example)。
*
* <p>官方 schema 的 {@code default} 与 {@code example} 都是 {@code *}。
* 不过首页不传也能用平台默认,适配器选择<b>不显式传</b>,避免平台版本差异导致 400。</p>
* <p><b>适配器不显式传它</b>:首页不传即可用平台默认,显式传 {@code *} 反而可能
* 因平台版本差异被拒。这个常量供宿主做游标缓存时参考。</p>
*/
public static final String ITEM_CURSOR_INITIAL = "*";
/** 商品游标有效期(秒);过期平台返回 400 Invalid Cursor。 */
/**
* 商品游标有效期(秒)。
*
* <p>官方原文:{@code The cursor remains the same across all page requests and is valid
* for 2 minutes.} 过期返回 400 Invalid Cursor。宿主缓存游标时不要超过这个时长。</p>
*/
public static final int ITEM_CURSOR_TTL_SECONDS = 120;
/** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */

10
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java

@ -336,9 +336,15 @@ public final class WalmartOrderDtos { @@ -336,9 +336,15 @@ public final class WalmartOrderDtos {
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TrackingInfo {
/** 发货时间,ISO-8601 字符串(与订单其它时间是 epoch 毫秒不同)。 */
/**
* 发货时间。
*
* <p>官方 Orders schema 里是 {@code integer / int64}(epoch 毫秒),
* 但部分旧响应与第三方资料给的是 ISO-8601 字符串。用 {@link Object} 接住两种形态,
* 由 {@link common.ecommerce.walmart.mapper.WalmartShipmentMapper} 统一转成字符串。</p>
*/
@JsonProperty("shipDateTime")
public String shipDateTime;
public Object shipDateTime;
/** 承运商。 */
@JsonProperty("carrierName")

1
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java

@ -6,7 +6,6 @@ import common.ecommerce.walmart.dto.WalmartRefundDtos; @@ -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}。

21
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java

@ -25,7 +25,7 @@ public final class WalmartShipmentMapper { @@ -25,7 +25,7 @@ public final class WalmartShipmentMapper {
*
* <p>沃尔玛没有「查询发货信息」的 GET 路由,发货信息本来就在订单详情的
* {@code orderLines[].orderLineStatuses[].trackingInfo} 里。这个方法把订单体
* 转成与 {@link #toShipmentLines} 相同的结构,所以调用方不用关心数据来自哪条路由。</p>
* 转成统一的 {@link ShipmentLine},所以调用方不用关心数据来自哪条路由。</p>
*
* <p>只输出有 {@code trackingInfo} 的行;未发货的行不出现。</p>
*
@ -55,13 +55,30 @@ public final class WalmartShipmentMapper { @@ -55,13 +55,30 @@ public final class WalmartShipmentMapper {
: tracking.carrierName.otherCarrier),
tracking.methodCode,
tracking.trackingNumber,
tracking.shipDateTime));
shipTimeOf(tracking.shipDateTime)));
break;
}
}
return out;
}
/**
* 发货时间的字符串形态。
*
* <p>官方 schema 是 epoch 毫秒(int64),Jackson 会反序列化成 {@link Number};
* 也兼容 ISO-8601 字符串。统一输出字符串,保留平台原值不做时区换算。</p>
*/
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 {

27
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java

@ -8,7 +8,6 @@ import common.ecommerce.walmart.dto.WalmartShipmentWriteDtos; @@ -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 { @@ -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 { @@ -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;
}
}
}
}

7
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java

@ -57,7 +57,7 @@ class WalmartExtraQueryTest { @@ -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 { @@ -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 { @@ -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()

2
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java

@ -39,7 +39,7 @@ class WalmartMarkShippedTest { @@ -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\"}}]}}]}}}";
}

Loading…
Cancel
Save