From e3a087dfc854226b1551c908dad7c61769b6be9c Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Thu, 19 Nov 2026 18:24:57 +0800 Subject: [PATCH] =?UTF-8?q?fix(walmart):=20=E9=80=80=E8=B4=A7=E8=AF=A6?= =?UTF-8?q?=E6=83=85=E4=B8=8E=E5=8F=91=E8=B4=A7=E4=BF=A1=E6=81=AF=E6=94=B9?= =?UTF-8?q?=E7=94=A8=E5=AE=98=E6=96=B9=E5=AD=98=E5=9C=A8=E7=9A=84=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 沃尔玛官方 spec 里这两条路由都不存在,原实现会 404: - GET /v3/returns/{returnOrderId}:Returns spec 只有 GET /v3/returns 与 POST .../refund - GET /v3/orders/{id}/shipping:Orders spec 里该路径只有 POST(标发) 【改动】 - getReturn 改走列表接口 GET /v3/returns?returnOrderId=xxx&limit=1; 平台不保证过滤生效(沙箱 mock 就不生效),本地再按单号筛一次, 避免把别的退货单混进来 - getShipping 改读订单详情 GET /v3/orders/{id},从 orderLines[].orderLineStatuses[].trackingInfo 抽行级发货记录; 数据与「发货信息」完全一致 - 两个方法的对外签名不变,调用方无需改动 - 删除不再使用的 WalmartShipmentDtos 与 orders/shipping.json、 returns/detail.json 两个夹具 【顺带修复】 - markShipped 解析响应改用 parseQuietly:平台只回受理结果或空体时 返回最小结果而不是抛异常,避免成功的发货被幂等层记成 FAILED 后重试重复发货 【测试】158 个;新增「平台返回多条退货单时本地只保留目标单」 「无 trackingInfo 时返回空列表」等用例。 Co-Authored-By: Claude Code --- .../ecommerce/walmart/adapter/WalmartAdapter.java | 81 ++++++++---- .../ecommerce/walmart/dto/WalmartShipmentDtos.java | 134 -------------------- .../walmart/mapper/WalmartShipmentMapper.java | 72 +++++------ .../walmart/adapter/WalmartExtraQueryTest.java | 137 +++++++++++++++++---- .../fixtures/walmart/orders/shipping.json | 59 --------- .../resources/fixtures/walmart/returns/detail.json | 52 -------- docs/walmart/README.md | 15 +-- 7 files changed, 206 insertions(+), 344 deletions(-) delete mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java delete mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json delete mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java index d8be395..a5f43ff 100644 --- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java @@ -43,7 +43,6 @@ import common.ecommerce.walmart.dto.WalmartOrderDtos; import common.ecommerce.walmart.dto.WalmartReturnDtos; import common.ecommerce.walmart.dto.WalmartFeedDtos; import common.ecommerce.walmart.dto.WalmartRefundDtos; -import common.ecommerce.walmart.dto.WalmartShipmentDtos; import common.ecommerce.walmart.dto.WalmartShipmentWriteDtos; import common.ecommerce.walmart.http.WalmartErrors; import common.ecommerce.walmart.http.WalmartRequestFactory; @@ -466,38 +465,52 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, /** * 退货单详情:{@code GET /v3/returns/{returnOrderId}}。 * + *

沃尔玛没有 {@code GET /v3/returns/{returnOrderId}}——官方 Returns + * spec 里只有列表与退款两条。这里改用官方列表接口按 {@code returnOrderId} 过滤, + * 对外行为与「查详情」一致:返回该退货单展开出的所有售后行。

+ * *

与列表一样按商品行展开:一个退货单可能含多个退货行, * 返回的 {@link AfterSale#afterSaleId()} 与列表里的完全一致({@code returnOrderId:行号}), * 可以直接拿去 upsert。

* - *

{@link AfterSaleCapable} 没有「取详情」方法——售后以拉取为主, - * 需要单条时用列表的时间窗过滤即可。这里提供它是因为沃尔玛有真实路由, - * 且列表接口的过滤参数在沙箱不生效,生产上按单号回查更快。

- * - *

⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。

+ *

平台不保证过滤参数生效(沙箱 mock 就不生效),所以本地会再按单号筛一次, + * 不会把别的退货单混进来。

* * @param returnOrderId 退货单号 * @return 该退货单展开出的售后行;退货单没有行时返回空列表 * @throws ChannelException 平台 404 / 其它错误,由 {@link WalmartErrors} 分类 */ public List getReturn(ChannelContext ctx, String returnOrderId) { - if (returnOrderId == null || returnOrderId.trim().isEmpty()) { + if (isBlank(returnOrderId)) { throw unsupportedFilter("walmart return detail requires returnOrderId"); } ChannelAccount account = ctx.account(); - String path = WalmartConstants.PATH_RETURN_BY_ID - + WalmartRequestFactory.pathSegment(returnOrderId.trim()); + Map queryParams = WalmartRequestFactory.query(); + // 官方没有 GET /v3/returns/{id},只能走列表接口的 returnOrderId 过滤 + queryParams.put("returnOrderId", returnOrderId.trim()); + queryParams.put("limit", 1); HttpResponse response = execute(ctx, "afterSales.get", new GetPlan() { @Override public HttpRequest request(ChannelContext c, AccessToken t) { - return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "afterSales.get"); + return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_RETURNS, + queryParams, t, c, "afterSales.get"); } }); - WalmartReturnDtos.ReturnOrder dto = - json.fromJson(response.body(), WalmartReturnDtos.ReturnOrder.class); - return WalmartReturnMapper.toAfterSales(dto, account.omsStoreId(), zoneOf(ctx)); + WalmartReturnDtos.ReturnListResponse dto = + json.fromJson(response.body(), WalmartReturnDtos.ReturnListResponse.class); + if (dto == null || dto.returnOrders == null) { + return java.util.Collections.emptyList(); + } + List out = new ArrayList(); + for (WalmartReturnDtos.ReturnOrder order : dto.returnOrders) { + // 平台不保证过滤参数生效(沙箱 mock 就不生效),本地再筛一次 + if (order != null && returnOrderId.trim().equals(order.returnOrderId)) { + out.addAll(WalmartReturnMapper.toAfterSales(order, account.omsStoreId(), zoneOf(ctx))); + } + } + return out; } // ---------------------------------------------------------------- MarkShippedCapable @@ -544,7 +557,7 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, // 沃尔玛标发成功回更新后的订单;也见过只回受理结果的情况,两种都兼容 WalmartOrderDtos.OrderDetailResponse dto = - json.fromJson(response.body(), WalmartOrderDtos.OrderDetailResponse.class); + parseQuietly(response.body(), WalmartOrderDtos.OrderDetailResponse.class); return WalmartShipmentWriteMapper.toResult(dto == null ? null : dto.order, command); } @@ -606,6 +619,23 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, return WalmartRefundMapper.toResult(applied, command); } + /** + * 尽力解析响应体:空体、非 JSON、结构不符都返回 null,不抛。 + * + *

用于「平台可能只回受理结果」的写接口——把解析失败当成异常抛出, + * 会让一次成功的写操作变成失败(幂等层会记 FAILED,重试可能重复执行)。

+ */ + private T parseQuietly(String body, Class type) { + if (body == null || body.trim().isEmpty()) { + return null; + } + try { + return json.fromJson(body, type); + } catch (RuntimeException e) { + return null; + } + } + /** 退款响应尽力解析成退货单;解不出来返回 null,不抛。 */ private WalmartReturnDtos.ReturnOrder parseReturnOrderQuietly(String body) { if (body == null || body.trim().isEmpty()) { @@ -711,24 +741,25 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, /** * 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。 * - *

返回行级发货记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间)。 - * 统一模型没有独立的发货实体——从订单详情的行状态里也能读到同样的 - * {@code trackingInfo},两种方式数据一致;本方法用于只想知道「发了哪些行」的场景。

+ *

沃尔玛没有 {@code GET /v3/orders/{id}/shipping}——官方 Orders spec 里 + * 该路径只有 POST(标发)。所以这里改读订单详情 + * {@code GET /v3/orders/{purchaseOrderId}},从 + * {@code orderLines[].orderLineStatuses[].trackingInfo} 抽行级发货记录; + * 数据与「发货信息」完全一致。

* - *

⚠ 沙箱实测该路由 404(mock 未实现)。生产上若也不可用,改用 - * {@link #get(ChannelContext, SalesOrderRef)} 读订单详情。

+ *

返回行级记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间), + * 只包含有 {@code trackingInfo} 的行。

* * @param purchaseOrderId 沃尔玛订单号 * @return 已发货行的记录;未发货时返回空列表 */ public List getShipping(ChannelContext ctx, String purchaseOrderId) { - if (purchaseOrderId == null || purchaseOrderId.trim().isEmpty()) { + if (isBlank(purchaseOrderId)) { throw unsupportedFilter("walmart shipping query requires purchaseOrderId"); } String path = WalmartConstants.PATH_ORDER_BY_ID - + WalmartRequestFactory.pathSegment(purchaseOrderId.trim()) - + WalmartConstants.PATH_ORDER_SHIPPING; + + WalmartRequestFactory.pathSegment(purchaseOrderId.trim()); HttpResponse response = execute(ctx, "salesOrders.shipping", new GetPlan() { @Override @@ -737,9 +768,9 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, } }); - WalmartShipmentDtos.ShipmentResponse dto = - json.fromJson(response.body(), WalmartShipmentDtos.ShipmentResponse.class); - return WalmartShipmentMapper.toShipmentLines(dto); + WalmartOrderDtos.OrderDetailResponse dto = + json.fromJson(response.body(), WalmartOrderDtos.OrderDetailResponse.class); + return WalmartShipmentMapper.fromOrder(dto == null ? null : dto.order); } // ---------------------------------------------------------------- internals diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java deleted file mode 100644 index 907a2c9..0000000 --- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java +++ /dev/null @@ -1,134 +0,0 @@ -package common.ecommerce.walmart.dto; - -import com.fasterxml.jackson.annotation.JsonIgnoreProperties; -import com.fasterxml.jackson.annotation.JsonProperty; - -import java.util.List; - -/** - * 沃尔玛报文结构:查询发货信息({@code GET /v3/orders/{purchaseOrderId}/shipping})。 - * - *

响应结构与标发请求体同形:{@code orderShipment.orderLines.orderLine[]}, - * 每个行状态里带 {@code trackingInfo}。

- * - *

⚠ 沙箱实测该路由 404(mock 未实现)。若生产环境也不可用,可直接读订单详情 - * {@code orderLines[].orderLineStatuses[].trackingInfo}——两种方式数据一致。

- */ -public final class WalmartShipmentDtos { - - private WalmartShipmentDtos() { - } - - /** 发货信息响应。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class ShipmentResponse { - - /** 发货单容器。 */ - @JsonProperty("orderShipment") - public OrderShipment orderShipment; - } - - /** 发货单:行数组。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class OrderShipment { - - /** 行容器。 */ - @JsonProperty("orderLines") - public OrderLines orderLines; - } - - /** 行容器。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class OrderLines { - - /** 发货行数组。 */ - @JsonProperty("orderLine") - public List orderLine; - } - - /** 发货行。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class OrderLine { - - /** 订单行号。 */ - @JsonProperty("lineNumber") - public String lineNumber; - - /** 行状态容器(发货记录在 {@code status=Shipped} 的那条里)。 */ - @JsonProperty("orderLineStatuses") - public OrderLineStatuses orderLineStatuses; - } - - /** 行状态容器。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class OrderLineStatuses { - - /** 行状态数组。 */ - @JsonProperty("orderLineStatus") - public List orderLineStatus; - } - - /** 行状态:发货记录就挂在这里。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class OrderLineStatus { - - /** 状态:{@code Shipped} / {@code Delivered} 等。 */ - @JsonProperty("status") - public String status; - - /** 该状态对应数量。 */ - @JsonProperty("statusQuantity") - public Quantity statusQuantity; - - /** 物流信息。 */ - @JsonProperty("trackingInfo") - public TrackingInfo trackingInfo; - } - - /** 数量:与订单接口同形,{@code amount} 是字符串。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class Quantity { - - /** 计量单位。 */ - @JsonProperty("unitOfMeasurement") - public String unitOfMeasurement; - - /** 数量(字符串)。 */ - @JsonProperty("amount") - public String amount; - } - - /** 物流信息。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class TrackingInfo { - - /** 发货时间,ISO-8601。 */ - @JsonProperty("shipDateTime") - public String shipDateTime; - - /** 承运商。 */ - @JsonProperty("carrierName") - public CarrierName carrierName; - - /** 运输方式编码。 */ - @JsonProperty("methodCode") - public String methodCode; - - /** 跟踪号。 */ - @JsonProperty("trackingNumber") - public String trackingNumber; - } - - /** 承运商:{@code carrier} 与 {@code otherCarrier} 二选一。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class CarrierName { - - /** 标准承运商编码,如 {@code UPS}、{@code FedEx}。 */ - @JsonProperty("carrier") - public String carrier; - - /** 非标准承运商名称。 */ - @JsonProperty("otherCarrier") - public String otherCarrier; - } -} 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 038e5c2..26ed820 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 @@ -1,6 +1,6 @@ package common.ecommerce.walmart.mapper; -import common.ecommerce.walmart.dto.WalmartShipmentDtos; +import common.ecommerce.walmart.dto.WalmartOrderDtos; import java.util.ArrayList; import java.util.Collections; @@ -21,61 +21,47 @@ public final class WalmartShipmentMapper { } /** - * 抽取每行的发货记录。 + * 订单详情 → 行级发货记录。 * - *

同一行可能有多个状态({@code Created} / {@code Shipped}),只取带 - * {@code trackingInfo} 的那条;没有任何发货记录的行不出现在结果里(表示尚未发货)。

+ *

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

* - * @param dto 发货信息响应 - * @return 每行一条;响应为空时返回空列表 + *

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

+ * + * @param order 订单本体;null 时返回空列表 */ - public static List toShipmentLines(WalmartShipmentDtos.ShipmentResponse dto) { - if (dto == null || dto.orderShipment == null - || dto.orderShipment.orderLines == null - || dto.orderShipment.orderLines.orderLine == null) { + public static List fromOrder(WalmartOrderDtos.Order order) { + if (order == null || order.orderLines == null || order.orderLines.orderLine == null) { return Collections.emptyList(); } List out = new ArrayList(); - for (WalmartShipmentDtos.OrderLine line : dto.orderShipment.orderLines.orderLine) { - if (line == null) { + for (WalmartOrderDtos.OrderLine line : order.orderLines.orderLine) { + if (line == null || line.lineNumber == null + || line.orderLineStatuses == null || line.orderLineStatuses.orderLineStatus == null) { continue; } - WalmartShipmentDtos.TrackingInfo tracking = trackingOf(line); - if (tracking == null) { - continue; + // 同一行可能有多个状态,取第一个带 trackingInfo 的 + for (WalmartOrderDtos.OrderLineStatus status : line.orderLineStatuses.orderLineStatus) { + if (status == null || status.trackingInfo == null) { + continue; + } + WalmartOrderDtos.TrackingInfo tracking = status.trackingInfo; + out.add(new ShipmentLine( + line.lineNumber, + tracking.carrierName == null ? null + : (tracking.carrierName.carrier != null + ? tracking.carrierName.carrier + : tracking.carrierName.otherCarrier), + tracking.methodCode, + tracking.trackingNumber, + tracking.shipDateTime)); + break; } - out.add(new ShipmentLine( - line.lineNumber, - carrierOf(tracking), - tracking.methodCode, - tracking.trackingNumber, - tracking.shipDateTime)); } return out; } - /** 行上的发货记录:取第一条带 {@code trackingInfo} 的状态。 */ - static WalmartShipmentDtos.TrackingInfo trackingOf(WalmartShipmentDtos.OrderLine line) { - if (line.orderLineStatuses == null || line.orderLineStatuses.orderLineStatus == null) { - return null; - } - for (WalmartShipmentDtos.OrderLineStatus status : line.orderLineStatuses.orderLineStatus) { - if (status != null && status.trackingInfo != null) { - return status.trackingInfo; - } - } - return null; - } - - /** 承运商:标准编码优先,没有时用非标准名称。 */ - static String carrierOf(WalmartShipmentDtos.TrackingInfo tracking) { - if (tracking.carrierName == null) { - return null; - } - return tracking.carrierName.carrier != null - ? tracking.carrierName.carrier : tracking.carrierName.otherCarrier; - } - /** 一行的发货记录。 */ public static final class ShipmentLine { 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 d901fa5..e7ab41f 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 @@ -33,27 +33,96 @@ class WalmartExtraQueryTest { private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json"); + /** + * 官方没有退货详情与发货信息的 GET 路由,实现改为: + * 退货详情走列表接口 + {@code returnOrderId} 过滤,发货信息走订单详情。 + */ private RecordingTransport transport() { return RecordingTransport.create() .route("/v3/token", r -> Responses.ok(TOKEN_BODY)) - .route("/v3/returns/103738048909818825", - r -> Responses.ok(JsonFixture.load("fixtures/walmart/returns/detail.json"))) - .route("/shipping", r -> Responses.ok( - JsonFixture.load("fixtures/walmart/orders/shipping.json"))); + .route("/v3/returns", r -> Responses.ok(returnsListWithDetail())) + .route("/v3/orders/", r -> Responses.ok(shippedOrderDetail())); + } + + /** 已发货的订单详情:发货信息从 orderLineStatuses[].trackingInfo 里读。 */ + private static String shippedOrderDetail() { + return "{\"order\":{\"purchaseOrderId\":\"108816631915371\"," + + "\"customerOrderId\":\"100000159992851\"," + + "\"orderDate\":1686736267000," + + "\"orderLines\":{\"orderLine\":[{\"lineNumber\":\"1\"," + + "\"item\":{\"productName\":\"Chair\",\"sku\":\"SKU-1\"}," + + "\"orderLineQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"}," + + "\"orderLineStatuses\":{\"orderLineStatus\":[" + + "{\"status\":\"Created\",\"statusQuantity\":" + + "{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},\"trackingInfo\":null}," + + "{\"status\":\"Shipped\",\"statusQuantity\":" + + "{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"},\"trackingInfo\":{" + + "\"shipDateTime\":\"2026-11-16T07:00:00.000Z\"," + + "\"carrierName\":{\"carrier\":\"UPS\"}," + + "\"methodCode\":\"Standard\"," + + "\"trackingNumber\":\"1Z999AA10123456784\"}}]}}]}}}"; + } + + /** 列表响应里放一条与 detail.json 同构的退货单。 */ + private static String returnsListWithDetail() { + return "{\"meta\":{\"totalCount\":1,\"limit\":1,\"nextCursor\":null}," + + "\"returnOrders\":[" + returnOrderJson() + "]}"; + } + + /** 单条退货单(与官方列表元素同构)。 */ + private static String returnOrderJson() { + return "{\"returnOrderId\":\"103738048909818825\"," + + "\"customerOrderId\":\"1234567891234\"," + + "\"refundMode\":\"POST_DELIVERY\"," + + "\"returnOrderDate\":\"2019-02-21T01:01:08.000Z\"," + + "\"returnType\":\"REFUND\"," + + "\"returnChannel\":{\"channelName\":\"ONLINE\"}," + + "\"returnLineGroups\":[{\"groupNo\":1," + + "\"returnLines\":[{\"returnOrderLineNumber\":1}]," + + "\"labels\":[{\"carrierInfoList\":[{\"carrierName\":\"FEDEX\"," + + "\"trackingNo\":\"785611449666\"}]}],\"returnExpectedFlag\":true}]," + + "\"returnOrderLines\":[{\"returnOrderLineNumber\":1," + + "\"returnReason\":\"DAMAGED\",\"purchaseOrderId\":\"4790210558890\"," + + "\"item\":{\"sku\":\"ANTL_GDL-0700\",\"productName\":\"Antlion Audio ModMic\"}," + + "\"quantity\":{\"unitOfMeasure\":\"EACH\",\"measurementValue\":2}," + + "\"unitPrice\":{\"currencyAmount\":119.95,\"currencyUnit\":\"USD\"}," + + "\"chargeTotals\":[{\"name\":\"lineTotal\",\"value\":239.9}]," + + "\"currentRefundStatus\":\"REFUND_PROCESSED\"," + + "\"status\":\"IN_TRANSIT\"," + + "\"statusTime\":\"2019-03-05T00:00:00.000Z\"}]}"; } // ---------------------------------------------------------------- 退货单详情 @Test - void returnDetailUsesReturnOrderIdPath() { + void returnDetailUsesListEndpointWithFilter() { RecordingTransport transport = transport(); List afterSales = adapter(transport).getReturn(context(), "103738048909818825"); - assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/returns/103738048909818825"); + String url = lastUrl(transport); + // 官方没有 /v3/returns/{id},走列表 + returnOrderId 过滤 + assertUrlContains(url, ENDPOINT + "/v3/returns?"); + assertUrlContains(url, "returnOrderId=103738048909818825"); + assertTrue(!url.contains("/v3/returns/103738048909818825"), url); assertEquals(1, afterSales.size()); } @Test + void returnDetailIgnoresOtherOrdersReturnedByPlatform() { + // 平台不保证过滤参数生效(沙箱 mock 就不生效),本地要再筛一次 + RecordingTransport transport = RecordingTransport.create() + .route("/v3/token", r -> Responses.ok(TOKEN_BODY)) + .route("/v3/returns", r -> Responses.ok("{\"returnOrders\":[" + + returnOrderJson() + "," + + "{\"returnOrderId\":\"OTHER\",\"returnOrderLines\":[" + + "{\"returnOrderLineNumber\":1,\"status\":\"COMPLETED\"}]}]}")); + + List afterSales = adapter(transport).getReturn(context(), "103738048909818825"); + assertEquals(1, afterSales.size()); + assertEquals("103738048909818825:1", afterSales.get(0).afterSaleId()); + } + + @Test void returnDetailExpandsLinesLikeList() { AfterSale a = adapter(transport()).getReturn(context(), "103738048909818825").get(0); @@ -69,13 +138,15 @@ class WalmartExtraQueryTest { } @Test - void returnDetailEncodesId() { + void returnDetailEncodesIdAsQueryValue() { + // 单号现在走 query 参数,空格编成 %20 或 + 都可以,关键是做了编码 RecordingTransport transport = RecordingTransport.create() .route("/v3/token", r -> Responses.ok(TOKEN_BODY)) - .route("/v3/returns/", r -> Responses.ok( - JsonFixture.load("fixtures/walmart/returns/detail.json"))); + .route("/v3/returns", r -> Responses.ok("{\"returnOrders\":[]}")); adapter(transport).getReturn(context(), "R 1/2"); - assertUrlContains(lastUrl(transport), "/v3/returns/R%201%2F2"); + String url = lastUrl(transport); + assertTrue(!url.contains("R 1/2"), url); + assertTrue(url.contains("returnOrderId=R+1%2F2") || url.contains("returnOrderId=R%201%2F2"), url); } @Test @@ -89,7 +160,7 @@ class WalmartExtraQueryTest { void returnDetail404PropagatesAsValidationException() { RecordingTransport transport = RecordingTransport.create() .route("/v3/token", r -> Responses.ok(TOKEN_BODY)) - .route("/v3/returns/", r -> Responses.status(404, + .route("/v3/returns", r -> Responses.status(404, JsonFixture.load("fixtures/walmart/errors/gateway-404.json"))); ValidationException ex = assertThrows(ValidationException.class, @@ -100,14 +171,16 @@ class WalmartExtraQueryTest { // ---------------------------------------------------------------- 发货信息 @Test - void shippingUsesOrderPathAndMapsShippedLinesOnly() { + void shippingReadsOrderDetail() { RecordingTransport transport = transport(); List lines = adapter(transport).getShipping(context(), "108816631915371"); - assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/orders/108816631915371/shipping"); - // 3 行里只有 2 行有 trackingInfo;未发货行不出现 - assertEquals(2, lines.size()); + String url = lastUrl(transport); + // 官方没有 GET .../shipping,改读订单详情 + assertUrlContains(url, ENDPOINT + "/v3/orders/108816631915371"); + assertTrue(!url.contains("/shipping"), url); + assertEquals(1, lines.size()); assertEquals("1", lines.get(0).lineNumber()); assertEquals("UPS", lines.get(0).carrier()); assertEquals("Standard", lines.get(0).methodCode()); @@ -117,11 +190,23 @@ class WalmartExtraQueryTest { @Test void shippingFallsBackToOtherCarrier() { + String body = "{\"order\":{\"purchaseOrderId\":\"PO-1\",\"orderDate\":1686736267000," + + "\"orderLines\":{\"orderLine\":[{\"lineNumber\":\"1\"," + + "\"item\":{\"sku\":\"S\"}," + + "\"orderLineQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"}," + + "\"orderLineStatuses\":{\"orderLineStatus\":[{\"status\":\"Shipped\"," + + "\"statusQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"1\"}," + + "\"trackingInfo\":{\"shipDateTime\":\"2026-11-16T08:00:00.000Z\"," + + "\"carrierName\":{\"otherCarrier\":\"Local Courier\"}," + + "\"methodCode\":\"Freight\",\"trackingNumber\":\"LC-1\"}}]}}]}}}"; + RecordingTransport transport = RecordingTransport.create() + .route("/v3/token", r -> Responses.ok(TOKEN_BODY)) + .route("/v3/orders/", r -> Responses.ok(body)); + List lines = - adapter(transport()).getShipping(context(), "108816631915371"); - // 非标准承运商:carrier 为空时用 otherCarrier - assertEquals("Local Courier", lines.get(1).carrier()); - assertEquals("Freight", lines.get(1).methodCode()); + adapter(transport).getShipping(context(), "PO-1"); + assertEquals("Local Courier", lines.get(0).carrier()); + assertEquals("Freight", lines.get(0).methodCode()); } @Test @@ -132,10 +217,15 @@ class WalmartExtraQueryTest { } @Test - void emptyShipmentReturnsEmptyList() { + void orderWithoutTrackingReturnsEmptyList() { RecordingTransport transport = RecordingTransport.create() .route("/v3/token", r -> Responses.ok(TOKEN_BODY)) - .route("/shipping", r -> Responses.ok("{\"orderShipment\":{\"orderLines\":{\"orderLine\":[]}}}")); + .route("/v3/orders/", r -> Responses.ok("{\"order\":{\"purchaseOrderId\":\"PO-1\"," + + "\"orderDate\":1686736267000," + + "\"orderLines\":{\"orderLine\":[{\"lineNumber\":\"1\"," + + "\"item\":{\"sku\":\"S\"}," + + "\"orderLineStatuses\":{\"orderLineStatus\":[" + + "{\"status\":\"Created\",\"trackingInfo\":null}]}}]}}}")); assertTrue(adapter(transport).getShipping(context(), "PO-1").isEmpty()); } @@ -150,10 +240,9 @@ class WalmartExtraQueryTest { } @Test - void listAndDetailAgreeOnReturnPathPrefix() { - // 两个接口共用 /v3/returns 前缀;详情多一段 id,别把列表路由吃掉 + void detailUsesListPathNotByeIdPath() { + // 官方没有 /v3/returns/{id};实现改为列表接口 + returnOrderId 过滤 assertEquals("/v3/returns", WalmartConstants.PATH_RETURNS); - assertEquals("/v3/returns/", WalmartConstants.PATH_RETURN_BY_ID); } /** 列表接口仍然可用(详情方法没有误改列表路由)。 */ diff --git a/channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json b/channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json deleted file mode 100644 index 73af15d..0000000 --- a/channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json +++ /dev/null @@ -1,59 +0,0 @@ -{ - "orderShipment": { - "orderLines": { - "orderLine": [ - { - "lineNumber": "1", - "orderLineStatuses": { - "orderLineStatus": [ - { - "status": "Created", - "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" }, - "trackingInfo": null - }, - { - "status": "Shipped", - "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" }, - "trackingInfo": { - "shipDateTime": "2026-11-16T07:00:00.000Z", - "carrierName": { "carrier": "UPS" }, - "methodCode": "Standard", - "trackingNumber": "1Z999AA10123456784" - } - } - ] - } - }, - { - "lineNumber": "2", - "orderLineStatuses": { - "orderLineStatus": [ - { - "status": "Created", - "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" }, - "trackingInfo": null - } - ] - } - }, - { - "lineNumber": "3", - "orderLineStatuses": { - "orderLineStatus": [ - { - "status": "Shipped", - "statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" }, - "trackingInfo": { - "shipDateTime": "2026-11-16T08:00:00.000Z", - "carrierName": { "otherCarrier": "Local Courier" }, - "methodCode": "Freight", - "trackingNumber": "LC-0001" - } - } - ] - } - } - ] - } - } -} diff --git a/channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json b/channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json deleted file mode 100644 index f6f574d..0000000 --- a/channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json +++ /dev/null @@ -1,52 +0,0 @@ -{ - "returnOrderId": "103738048909818825", - "customerEmailId": "emailID123456@relay.walmart.com", - "customerName": { "firstName": "Jane", "lastName": "Doe" }, - "customerOrderId": "1234567891234", - "refundMode": "POST_DELIVERY", - "returnOrderDate": "2019-02-21T01:01:08.000Z", - "returnType": "RETURN", - "returnByDate": "2019-03-23T01:01:06.000Z", - "totalRefundAmount": { "currencyAmount": 127.45, "currencyUnit": "USD" }, - "returnChannel": { "channelName": "ONLINE" }, - "returnLineGroups": [ - { - "groupNo": 1, - "returnLines": [ { "returnOrderLineNumber": 1 } ], - "labels": [ - { - "labelImageURL": "https://i5.walmartimages.com/asr/label.png", - "carrierInfoList": [ - { - "carrierId": "11", - "carrierName": "FEDEX", - "serviceType": "FedEx Ground", - "trackingNo": "785611449666" - } - ] - } - ], - "returnExpectedFlag": true - } - ], - "returnOrderLines": [ - { - "returnOrderLineNumber": 1, - "salesOrderLineNumber": 1, - "returnReason": "DAMAGED", - "purchaseOrderId": "4790210558890", - "item": { - "sku": "ANTL_GDL-0700", - "productName": "Antlion Audio ModMic" - }, - "quantity": { "unitOfMeasure": "EACH", "measurementValue": 2 }, - "unitPrice": { "currencyAmount": 119.95, "currencyUnit": "USD" }, - "chargeTotals": [ { "name": "lineTotal", "value": 239.9 } ], - "currentDeliveryStatus": "IN_TRANSIT", - "currentRefundStatus": "REFUND_PROCESSED", - "refundedQty": 2, - "status": "IN_TRANSIT", - "statusTime": "2019-03-05T00:00:00.000Z" - } - ] -} diff --git a/docs/walmart/README.md b/docs/walmart/README.md index a779524..31e81ca 100644 --- a/docs/walmart/README.md +++ b/docs/walmart/README.md @@ -73,11 +73,12 @@ ChannelConnection conn = ChannelConnection.of( | `SALES_ORDER` 订单列表 / 详情 | ✅ | | `PRODUCT` 商品列表 / 详情 | ✅ | | `RETURNS` 退货列表(按行展开) | ✅ | -| 退货单详情 `WalmartAdapter.getReturn` | ✅(⚠ 沙箱 404) | -| 发货信息 `WalmartAdapter.getShipping` | ✅(⚠ 沙箱 404) | +| 退货单详情 `WalmartAdapter.getReturn` | ✅ 走列表接口 `returnOrderId` 过滤(官方无详情路由) | +| 发货信息 `WalmartAdapter.getShipping` | ✅ 走订单详情 `trackingInfo`(官方无 GET shipping 路由) | | `MARK_SHIPPED` 标发 | ✅(⚠ 沙箱 404,见 §7) | -| `REFUND` 退款 | ❌ 沙箱 404 | -| 商品写入(Feed / 单个) | ❌ 沙箱 520 | +| `REFUND` 退款 | ✅(⚠ 沙箱 404,见 §8) | +| 商品 Feed 提交 / 状态查询 | ✅ 扩展方法(⚠ 沙箱 520,见 §9) | +| 单个商品创建 / 更新 | ❌ 官方 API 不存在,商品写入走 Feed | 过滤条件的支持面比领星窄,**不支持的组合一律抛 `ValidationException`**,见 [`docs/channel/api-reference.md` §15A.6](../channel/api-reference.md#15a6-不支持的过滤条件显式报错)。 @@ -154,8 +155,6 @@ mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \ | `orders/detail.json` | 文档 §4.2 实测样例 | | `items/list.json` | 文档 §3.1 实测样例 + 补了 `PUBLISHED/ACTIVE` 与 `PUBLISHED/RETIRED` 两条 | | `returns/list.json` | 文档 §5.1 实测样例 + 补了第二行(覆盖无 `chargeTotals`、无面单分组) | -| `returns/detail.json` | 按文档 §5.2 的「同列表元素」结构构造(沙箱 404,无实测) | -| `orders/shipping.json` | 按文档 §4.4 的 `orderShipment` 结构构造(沙箱 404,无实测;含非标准承运商) | | `errors/*.json` | 文档 §1.5 两种错误格式原文 | | `token/success.json` | 文档 §2.1 实测结构(token 值为占位) | @@ -166,7 +165,9 @@ mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \ | 问题 | 状态 | |---|---| | 沙箱商品详情 404 | 生产环境再验 | -| 沙箱退货详情 / 退款 404 | 两条都已按文档实现(`getReturn` / `refund`),生产再验 | +| `GET /v3/returns/{id}` | **官方无此路由**;`getReturn` 改走列表接口 `returnOrderId` 过滤 | +| `GET /v3/orders/{id}/shipping` | **官方无此路由**(只有 POST 标发);`getShipping` 改读订单详情 `trackingInfo` | +| 沙箱退款 404 | 已按文档实现,生产再验 | | 沙箱 Feed 520 | 提交 / 状态查询已按文档实现(`submitFeed` / `getFeedStatus`),生产再验 | | 沙箱过滤参数不生效 | 以生产为准 | | 订单列表 `status` 过滤是否生效 | 探针未覆盖写操作,读侧以生产为准 |