Browse Source

fix(walmart): 退货详情与发货信息改用官方存在的接口

沃尔玛官方 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 <noreply@anthropic.com>
lml 1 day ago
parent
commit
e3a087dfc8
  1. 81
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
  2. 134
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java
  3. 60
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java
  4. 137
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java
  5. 59
      channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json
  6. 52
      channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json
  7. 15
      docs/walmart/README.md

81
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.WalmartReturnDtos;
import common.ecommerce.walmart.dto.WalmartFeedDtos; import common.ecommerce.walmart.dto.WalmartFeedDtos;
import common.ecommerce.walmart.dto.WalmartRefundDtos; import common.ecommerce.walmart.dto.WalmartRefundDtos;
import common.ecommerce.walmart.dto.WalmartShipmentDtos;
import common.ecommerce.walmart.dto.WalmartShipmentWriteDtos; import common.ecommerce.walmart.dto.WalmartShipmentWriteDtos;
import common.ecommerce.walmart.http.WalmartErrors; import common.ecommerce.walmart.http.WalmartErrors;
import common.ecommerce.walmart.http.WalmartRequestFactory; 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}}。
* *
* <p><b>沃尔玛没有 {@code GET /v3/returns/{returnOrderId}}</b>——官方 Returns
* spec 里只有列表与退款两条。这里改用官方列表接口按 {@code returnOrderId} 过滤,
* 对外行为与「查详情」一致:返回该退货单展开出的所有售后行。</p>
*
* <p>与列表一样<b>按商品行展开</b>:一个退货单可能含多个退货行, * <p>与列表一样<b>按商品行展开</b>:一个退货单可能含多个退货行,
* 返回的 {@link AfterSale#afterSaleId()} 与列表里的完全一致({@code returnOrderId:行号}), * 返回的 {@link AfterSale#afterSaleId()} 与列表里的完全一致({@code returnOrderId:行号}),
* 可以直接拿去 upsert。</p> * 可以直接拿去 upsert。</p>
* *
* <p>{@link AfterSaleCapable} 没有「取详情」方法——售后以拉取为主, * <p>平台不保证过滤参数生效(沙箱 mock 就不生效),所以本地会再按单号筛一次,
* 需要单条时用列表的时间窗过滤即可。这里提供它是因为沃尔玛有真实路由, * 不会把别的退货单混进来。</p>
* 且列表接口的过滤参数在沙箱不生效,生产上按单号回查更快。</p>
*
* <p>⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。</p>
* *
* @param returnOrderId 退货单号 * @param returnOrderId 退货单号
* @return 该退货单展开出的售后行;退货单没有行时返回空列表 * @return 该退货单展开出的售后行;退货单没有行时返回空列表
* @throws ChannelException 平台 404 / 其它错误,由 {@link WalmartErrors} 分类 * @throws ChannelException 平台 404 / 其它错误,由 {@link WalmartErrors} 分类
*/ */
public List<AfterSale> getReturn(ChannelContext ctx, String returnOrderId) { public List<AfterSale> getReturn(ChannelContext ctx, String returnOrderId) {
if (returnOrderId == null || returnOrderId.trim().isEmpty()) { if (isBlank(returnOrderId)) {
throw unsupportedFilter("walmart return detail requires returnOrderId"); throw unsupportedFilter("walmart return detail requires returnOrderId");
} }
ChannelAccount account = ctx.account(); ChannelAccount account = ctx.account();
String path = WalmartConstants.PATH_RETURN_BY_ID Map<String, Object> queryParams = WalmartRequestFactory.query();
+ WalmartRequestFactory.pathSegment(returnOrderId.trim()); // 官方没有 GET /v3/returns/{id},只能走列表接口的 returnOrderId 过滤
queryParams.put("returnOrderId", returnOrderId.trim());
queryParams.put("limit", 1);
HttpResponse response = execute(ctx, "afterSales.get", new GetPlan() { HttpResponse response = execute(ctx, "afterSales.get", new GetPlan() {
@Override @Override
public HttpRequest request(ChannelContext c, AccessToken t) { 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 = WalmartReturnDtos.ReturnListResponse dto =
json.fromJson(response.body(), WalmartReturnDtos.ReturnOrder.class); json.fromJson(response.body(), WalmartReturnDtos.ReturnListResponse.class);
return WalmartReturnMapper.toAfterSales(dto, account.omsStoreId(), zoneOf(ctx)); if (dto == null || dto.returnOrders == null) {
return java.util.Collections.emptyList();
}
List<AfterSale> out = new ArrayList<AfterSale>();
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 // ---------------------------------------------------------------- MarkShippedCapable
@ -544,7 +557,7 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
// 沃尔玛标发成功回更新后的订单;也见过只回受理结果的情况,两种都兼容 // 沃尔玛标发成功回更新后的订单;也见过只回受理结果的情况,两种都兼容
WalmartOrderDtos.OrderDetailResponse dto = 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); 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); return WalmartRefundMapper.toResult(applied, command);
} }
/**
* 尽力解析响应体:空体、非 JSON、结构不符都返回 null,不抛。
*
* <p>用于「平台可能只回受理结果」的写接口——把解析失败当成异常抛出,
* 会让一次成功的写操作变成失败(幂等层会记 FAILED,重试可能重复执行)。</p>
*/
private <T> T parseQuietly(String body, Class<T> type) {
if (body == null || body.trim().isEmpty()) {
return null;
}
try {
return json.fromJson(body, type);
} catch (RuntimeException e) {
return null;
}
}
/** 退款响应尽力解析成退货单;解不出来返回 null,不抛。 */ /** 退款响应尽力解析成退货单;解不出来返回 null,不抛。 */
private WalmartReturnDtos.ReturnOrder parseReturnOrderQuietly(String body) { private WalmartReturnDtos.ReturnOrder parseReturnOrderQuietly(String body) {
if (body == null || body.trim().isEmpty()) { if (body == null || body.trim().isEmpty()) {
@ -711,24 +741,25 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
/** /**
* 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。 * 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。
* *
* <p>返回<b>行级</b>发货记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间)。 * <p><b>沃尔玛没有 {@code GET /v3/orders/{id}/shipping}</b>——官方 Orders spec 里
* 统一模型没有独立的发货实体——从订单详情的行状态里也能读到同样的 * 该路径只有 POST(标发)。所以这里改读订单详情
* {@code trackingInfo},两种方式数据一致;本方法用于只想知道「发了哪些行」的场景。</p> * {@code GET /v3/orders/{purchaseOrderId}},从
* {@code orderLines[].orderLineStatuses[].trackingInfo} 抽行级发货记录;
* 数据与「发货信息」完全一致。</p>
* *
* <p>⚠ 沙箱实测该路由 404(mock 未实现)。生产上若也不可用,改用 * <p>返回行级记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间),
* {@link #get(ChannelContext, SalesOrderRef)} 读订单详情。</p> * 只包含有 {@code trackingInfo} 的行。</p>
* *
* @param purchaseOrderId 沃尔玛订单号 * @param purchaseOrderId 沃尔玛订单号
* @return 已发货行的记录;未发货时返回空列表 * @return 已发货行的记录;未发货时返回空列表
*/ */
public List<WalmartShipmentMapper.ShipmentLine> getShipping(ChannelContext ctx, public List<WalmartShipmentMapper.ShipmentLine> getShipping(ChannelContext ctx,
String purchaseOrderId) { String purchaseOrderId) {
if (purchaseOrderId == null || purchaseOrderId.trim().isEmpty()) { if (isBlank(purchaseOrderId)) {
throw unsupportedFilter("walmart shipping query requires purchaseOrderId"); throw unsupportedFilter("walmart shipping query requires purchaseOrderId");
} }
String path = WalmartConstants.PATH_ORDER_BY_ID String path = WalmartConstants.PATH_ORDER_BY_ID
+ WalmartRequestFactory.pathSegment(purchaseOrderId.trim()) + WalmartRequestFactory.pathSegment(purchaseOrderId.trim());
+ WalmartConstants.PATH_ORDER_SHIPPING;
HttpResponse response = execute(ctx, "salesOrders.shipping", new GetPlan() { HttpResponse response = execute(ctx, "salesOrders.shipping", new GetPlan() {
@Override @Override
@ -737,9 +768,9 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
} }
}); });
WalmartShipmentDtos.ShipmentResponse dto = WalmartOrderDtos.OrderDetailResponse dto =
json.fromJson(response.body(), WalmartShipmentDtos.ShipmentResponse.class); json.fromJson(response.body(), WalmartOrderDtos.OrderDetailResponse.class);
return WalmartShipmentMapper.toShipmentLines(dto); return WalmartShipmentMapper.fromOrder(dto == null ? null : dto.order);
} }
// ---------------------------------------------------------------- internals // ---------------------------------------------------------------- internals

134
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java

@ -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})。
*
* <p>响应结构与标发请求体同形:{@code orderShipment.orderLines.orderLine[]},
* 每个行状态里带 {@code trackingInfo}。</p>
*
* <p>⚠ 沙箱实测该路由 404(mock 未实现)。若生产环境也不可用,可直接读订单详情
* {@code orderLines[].orderLineStatuses[].trackingInfo}——两种方式数据一致。</p>
*/
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> 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> 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;
}
}

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

@ -1,6 +1,6 @@
package common.ecommerce.walmart.mapper; package common.ecommerce.walmart.mapper;
import common.ecommerce.walmart.dto.WalmartShipmentDtos; import common.ecommerce.walmart.dto.WalmartOrderDtos;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.Collections; import java.util.Collections;
@ -21,59 +21,45 @@ public final class WalmartShipmentMapper {
} }
/** /**
* 抽取每行的发货记录。 * 订单详情 → 行级发货记录。
* *
* <p>同一行可能有多个状态({@code Created} / {@code Shipped}),只取带 * <p>沃尔玛没有「查询发货信息」的 GET 路由,发货信息本来就在订单详情的
* {@code trackingInfo} 的那条;没有任何发货记录的行不出现在结果里(表示尚未发货)。</p> * {@code orderLines[].orderLineStatuses[].trackingInfo} 里。这个方法把订单体
* 转成与 {@link #toShipmentLines} 相同的结构,所以调用方不用关心数据来自哪条路由。</p>
* *
* @param dto 发货信息响应 * <p>只输出有 {@code trackingInfo} 的行;未发货的行不出现。</p>
* @return 每行一条;响应为空时返回空列表 *
* @param order 订单本体;null 时返回空列表
*/ */
public static List<ShipmentLine> toShipmentLines(WalmartShipmentDtos.ShipmentResponse dto) { public static List<ShipmentLine> fromOrder(WalmartOrderDtos.Order order) {
if (dto == null || dto.orderShipment == null if (order == null || order.orderLines == null || order.orderLines.orderLine == null) {
|| dto.orderShipment.orderLines == null
|| dto.orderShipment.orderLines.orderLine == null) {
return Collections.emptyList(); return Collections.emptyList();
} }
List<ShipmentLine> out = new ArrayList<ShipmentLine>(); List<ShipmentLine> out = new ArrayList<ShipmentLine>();
for (WalmartShipmentDtos.OrderLine line : dto.orderShipment.orderLines.orderLine) { for (WalmartOrderDtos.OrderLine line : order.orderLines.orderLine) {
if (line == null) { if (line == null || line.lineNumber == null
|| line.orderLineStatuses == null || line.orderLineStatuses.orderLineStatus == null) {
continue; continue;
} }
WalmartShipmentDtos.TrackingInfo tracking = trackingOf(line); // 同一行可能有多个状态,取第一个带 trackingInfo 的
if (tracking == null) { for (WalmartOrderDtos.OrderLineStatus status : line.orderLineStatuses.orderLineStatus) {
if (status == null || status.trackingInfo == null) {
continue; continue;
} }
WalmartOrderDtos.TrackingInfo tracking = status.trackingInfo;
out.add(new ShipmentLine( out.add(new ShipmentLine(
line.lineNumber, line.lineNumber,
carrierOf(tracking), tracking.carrierName == null ? null
: (tracking.carrierName.carrier != null
? tracking.carrierName.carrier
: tracking.carrierName.otherCarrier),
tracking.methodCode, tracking.methodCode,
tracking.trackingNumber, tracking.trackingNumber,
tracking.shipDateTime)); tracking.shipDateTime));
break;
} }
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 out;
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;
} }
/** 一行的发货记录。 */ /** 一行的发货记录。 */

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

@ -33,24 +33,93 @@ class WalmartExtraQueryTest {
private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json"); private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
/**
* 官方没有退货详情与发货信息的 GET 路由,实现改为:
* 退货详情走列表接口 + {@code returnOrderId} 过滤,发货信息走订单详情。
*/
private RecordingTransport transport() { private RecordingTransport transport() {
return RecordingTransport.create() return RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY)) .route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/returns/103738048909818825", .route("/v3/returns", r -> Responses.ok(returnsListWithDetail()))
r -> Responses.ok(JsonFixture.load("fixtures/walmart/returns/detail.json"))) .route("/v3/orders/", r -> Responses.ok(shippedOrderDetail()));
.route("/shipping", r -> Responses.ok( }
JsonFixture.load("fixtures/walmart/orders/shipping.json")));
/** 已发货的订单详情:发货信息从 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 @Test
void returnDetailUsesReturnOrderIdPath() { void returnDetailUsesListEndpointWithFilter() {
RecordingTransport transport = transport(); RecordingTransport transport = transport();
List<AfterSale> afterSales = adapter(transport).getReturn(context(), "103738048909818825"); List<AfterSale> 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<AfterSale> afterSales = adapter(transport).getReturn(context(), "103738048909818825");
assertEquals(1, afterSales.size()); assertEquals(1, afterSales.size());
assertEquals("103738048909818825:1", afterSales.get(0).afterSaleId());
} }
@Test @Test
@ -69,13 +138,15 @@ class WalmartExtraQueryTest {
} }
@Test @Test
void returnDetailEncodesId() { void returnDetailEncodesIdAsQueryValue() {
// 单号现在走 query 参数,空格编成 %20 或 + 都可以,关键是做了编码
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY)) .route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/returns/", r -> Responses.ok( .route("/v3/returns", r -> Responses.ok("{\"returnOrders\":[]}"));
JsonFixture.load("fixtures/walmart/returns/detail.json")));
adapter(transport).getReturn(context(), "R 1/2"); 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 @Test
@ -89,7 +160,7 @@ class WalmartExtraQueryTest {
void returnDetail404PropagatesAsValidationException() { void returnDetail404PropagatesAsValidationException() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY)) .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"))); JsonFixture.load("fixtures/walmart/errors/gateway-404.json")));
ValidationException ex = assertThrows(ValidationException.class, ValidationException ex = assertThrows(ValidationException.class,
@ -100,14 +171,16 @@ class WalmartExtraQueryTest {
// ---------------------------------------------------------------- 发货信息 // ---------------------------------------------------------------- 发货信息
@Test @Test
void shippingUsesOrderPathAndMapsShippedLinesOnly() { void shippingReadsOrderDetail() {
RecordingTransport transport = transport(); RecordingTransport transport = transport();
List<WalmartShipmentMapper.ShipmentLine> lines = List<WalmartShipmentMapper.ShipmentLine> lines =
adapter(transport).getShipping(context(), "108816631915371"); adapter(transport).getShipping(context(), "108816631915371");
assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/orders/108816631915371/shipping"); String url = lastUrl(transport);
// 3 行里只有 2 行有 trackingInfo;未发货行不出现 // 官方没有 GET .../shipping,改读订单详情
assertEquals(2, lines.size()); assertUrlContains(url, ENDPOINT + "/v3/orders/108816631915371");
assertTrue(!url.contains("/shipping"), url);
assertEquals(1, lines.size());
assertEquals("1", lines.get(0).lineNumber()); assertEquals("1", lines.get(0).lineNumber());
assertEquals("UPS", lines.get(0).carrier()); assertEquals("UPS", lines.get(0).carrier());
assertEquals("Standard", lines.get(0).methodCode()); assertEquals("Standard", lines.get(0).methodCode());
@ -117,11 +190,23 @@ class WalmartExtraQueryTest {
@Test @Test
void shippingFallsBackToOtherCarrier() { 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<WalmartShipmentMapper.ShipmentLine> lines = List<WalmartShipmentMapper.ShipmentLine> lines =
adapter(transport()).getShipping(context(), "108816631915371"); adapter(transport).getShipping(context(), "PO-1");
// 非标准承运商:carrier 为空时用 otherCarrier assertEquals("Local Courier", lines.get(0).carrier());
assertEquals("Local Courier", lines.get(1).carrier()); assertEquals("Freight", lines.get(0).methodCode());
assertEquals("Freight", lines.get(1).methodCode());
} }
@Test @Test
@ -132,10 +217,15 @@ class WalmartExtraQueryTest {
} }
@Test @Test
void emptyShipmentReturnsEmptyList() { void orderWithoutTrackingReturnsEmptyList() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY)) .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()); assertTrue(adapter(transport).getShipping(context(), "PO-1").isEmpty());
} }
@ -150,10 +240,9 @@ class WalmartExtraQueryTest {
} }
@Test @Test
void listAndDetailAgreeOnReturnPathPrefix() { void detailUsesListPathNotByeIdPath() {
// 两个接口共用 /v3/returns 前缀;详情多一段 id,别把列表路由吃掉 // 官方没有 /v3/returns/{id};实现改为列表接口 + returnOrderId 过滤
assertEquals("/v3/returns", WalmartConstants.PATH_RETURNS); assertEquals("/v3/returns", WalmartConstants.PATH_RETURNS);
assertEquals("/v3/returns/", WalmartConstants.PATH_RETURN_BY_ID);
} }
/** 列表接口仍然可用(详情方法没有误改列表路由)。 */ /** 列表接口仍然可用(详情方法没有误改列表路由)。 */

59
channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json

@ -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"
}
}
]
}
}
]
}
}
}

52
channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json

@ -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"
}
]
}

15
docs/walmart/README.md

@ -73,11 +73,12 @@ ChannelConnection conn = ChannelConnection.of(
| `SALES_ORDER` 订单列表 / 详情 | ✅ | | `SALES_ORDER` 订单列表 / 详情 | ✅ |
| `PRODUCT` 商品列表 / 详情 | ✅ | | `PRODUCT` 商品列表 / 详情 | ✅ |
| `RETURNS` 退货列表(按行展开) | ✅ | | `RETURNS` 退货列表(按行展开) | ✅ |
| 退货单详情 `WalmartAdapter.getReturn` | ✅(⚠ 沙箱 404) | | 退货单详情 `WalmartAdapter.getReturn` | ✅ 走列表接口 `returnOrderId` 过滤(官方无详情路由) |
| 发货信息 `WalmartAdapter.getShipping` | ✅(⚠ 沙箱 404) | | 发货信息 `WalmartAdapter.getShipping` | ✅ 走订单详情 `trackingInfo`(官方无 GET shipping 路由) |
| `MARK_SHIPPED` 标发 | ✅(⚠ 沙箱 404,见 §7) | | `MARK_SHIPPED` 标发 | ✅(⚠ 沙箱 404,见 §7) |
| `REFUND` 退款 | ❌ 沙箱 404 | | `REFUND` 退款 | ✅(⚠ 沙箱 404,见 §8) |
| 商品写入(Feed / 单个) | ❌ 沙箱 520 | | 商品 Feed 提交 / 状态查询 | ✅ 扩展方法(⚠ 沙箱 520,见 §9) |
| 单个商品创建 / 更新 | ❌ 官方 API 不存在,商品写入走 Feed |
过滤条件的支持面比领星窄,**不支持的组合一律抛 `ValidationException`**,见 过滤条件的支持面比领星窄,**不支持的组合一律抛 `ValidationException`**,见
[`docs/channel/api-reference.md` §15A.6](../channel/api-reference.md#15a6-不支持的过滤条件显式报错)。 [`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 实测样例 | | `orders/detail.json` | 文档 §4.2 实测样例 |
| `items/list.json` | 文档 §3.1 实测样例 + 补了 `PUBLISHED/ACTIVE` 与 `PUBLISHED/RETIRED` 两条 | | `items/list.json` | 文档 §3.1 实测样例 + 补了 `PUBLISHED/ACTIVE` 与 `PUBLISHED/RETIRED` 两条 |
| `returns/list.json` | 文档 §5.1 实测样例 + 补了第二行(覆盖无 `chargeTotals`、无面单分组) | | `returns/list.json` | 文档 §5.1 实测样例 + 补了第二行(覆盖无 `chargeTotals`、无面单分组) |
| `returns/detail.json` | 按文档 §5.2 的「同列表元素」结构构造(沙箱 404,无实测) |
| `orders/shipping.json` | 按文档 §4.4 的 `orderShipment` 结构构造(沙箱 404,无实测;含非标准承运商) |
| `errors/*.json` | 文档 §1.5 两种错误格式原文 | | `errors/*.json` | 文档 §1.5 两种错误格式原文 |
| `token/success.json` | 文档 §2.1 实测结构(token 值为占位) | | `token/success.json` | 文档 §2.1 实测结构(token 值为占位) |
@ -166,7 +165,9 @@ mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
| 问题 | 状态 | | 问题 | 状态 |
|---|---| |---|---|
| 沙箱商品详情 404 | 生产环境再验 | | 沙箱商品详情 404 | 生产环境再验 |
| 沙箱退货详情 / 退款 404 | 两条都已按文档实现(`getReturn` / `refund`),生产再验 | | `GET /v3/returns/{id}` | **官方无此路由**;`getReturn` 改走列表接口 `returnOrderId` 过滤 |
| `GET /v3/orders/{id}/shipping` | **官方无此路由**(只有 POST 标发);`getShipping` 改读订单详情 `trackingInfo` |
| 沙箱退款 404 | 已按文档实现,生产再验 |
| 沙箱 Feed 520 | 提交 / 状态查询已按文档实现(`submitFeed` / `getFeedStatus`),生产再验 | | 沙箱 Feed 520 | 提交 / 状态查询已按文档实现(`submitFeed` / `getFeedStatus`),生产再验 |
| 沙箱过滤参数不生效 | 以生产为准 | | 沙箱过滤参数不生效 | 以生产为准 |
| 订单列表 `status` 过滤是否生效 | 探针未覆盖写操作,读侧以生产为准 | | 订单列表 `status` 过滤是否生效 | 探针未覆盖写操作,读侧以生产为准 |

Loading…
Cancel
Save