Browse Source

feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期)

通道 ChannelProvider.DIRECT + Platform.WALMART_SC,新增模块 channel-sdk-walmart。
一期只做只读:鉴权、订单、商品、售后。标发、退款、商品写入不在本期,
对应能力位也不声明——门面调用会显式抛 UnsupportedCapabilityException。

【core 模型增量】全部是可选字段,不影响领星现有行为:
- 新增 ShipToAddress(收件信息;toString 只输出城市/州/邮编,不输出街道与姓名)
- SalesOrder 增加 buyerEmail / shipToAddress
- OrderLine 增加 status(行状态原值)与 lineAmount(行金额,金额权威来源)
- OrderLine.unitPrice 明确为「单价」:行金额除以数量,除不尽时留 null
  而不是四舍五入倒推,否则 unitPrice × quantity 与原金额会差出分差

【适配器】
- POST /v3/token(Basic Auth + client_credentials),按 clientId 缓存,
  提前 120s 续期;401/403 时 forceRefresh 后重发一次
- GET /v3/orders、/v3/orders/{id}:updatedAfter/Before 映射到创建时间窗
  (沃尔玛没有更新时间过滤),跨度超 180 天本地拒绝
- GET /v3/items、/v3/items/{sku}:limit 上限 200;syncStrategy=FULL_PULL_DIFF,
  传更新时间窗直接报错而不是静默忽略
- GET /v3/returns:一个退货单按商品行展开成多个 AfterSale,
  nextCursor 是整段查询串,翻页时整串拼到路径后
- 扩展查询:getReturn(退货详情)、getShipping(发货信息),沙箱均 404

增量语义拆成两条车道:pull 走创建时间窗语义可预测,老单状态变化由
pullOpenOrders 按行状态对账,不混在一个方法里。

脏数据处理:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页,
也不用假值兜底写脏主键。运费不冒充商品单价,行金额除不尽时 unitPrice 留 null。

【测试】108 个:订单 22、商品 18、售后 13、脏数据 10、扩展查询 12、
状态映射 16、错误 11、门面 5、沙箱探针 1(默认跳过)。

【文档】仅新增 docs/walmart/README.md,以及 README / 操作手册.md 里
沃尔玛相关的两处能力表条目。

Co-Authored-By: Claude Code <noreply@anthropic.com>
lml 3 days ago
parent
commit
e716a2593e
  1. 2
      README.md
  2. 61
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java
  3. 46
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java
  4. 231
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java
  5. 113
      channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java
  6. 49
      channel-sdk-walmart/pom.xml
  7. 115
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java
  8. 642
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
  9. 63
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java
  10. 127
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java
  11. 113
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java
  12. 377
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java
  13. 396
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java
  14. 134
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java
  15. 33
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartTokenDtos.java
  16. 138
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartOrderStatus.java
  17. 103
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartPublishedStatus.java
  18. 60
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartReturnType.java
  19. 165
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartErrors.java
  20. 130
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartRequestFactory.java
  21. 422
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartOrderMapper.java
  22. 148
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartProductMapper.java
  23. 304
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartReturnMapper.java
  24. 133
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java
  25. 154
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/WalmartFacadeTest.java
  26. 209
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartDirtyDataTest.java
  27. 171
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java
  28. 346
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartOrderTest.java
  29. 233
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartProductTest.java
  30. 210
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartReturnTest.java
  31. 131
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/enums/WalmartStatusMappingTest.java
  32. 132
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/http/WalmartErrorsTest.java
  33. 319
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/probe/WalmartProbeTest.java
  34. 112
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/support/WalmartTestSupport.java
  35. 13
      channel-sdk-walmart/src/test/resources/fixtures/walmart/errors/gateway-404.json
  36. 6
      channel-sdk-walmart/src/test/resources/fixtures/walmart/errors/route-404.json
  37. 49
      channel-sdk-walmart/src/test/resources/fixtures/walmart/items/list.json
  38. 56
      channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/detail.json
  39. 330
      channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/list.json
  40. 59
      channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json
  41. 52
      channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json
  42. 82
      channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/list.json
  43. 5
      channel-sdk-walmart/src/test/resources/fixtures/walmart/token/success.json
  44. 186
      docs/walmart/README.md
  45. 6
      pom.xml
  46. 20
      操作手册.md

2
README.md

@ -139,6 +139,7 @@ sequenceDiagram @@ -139,6 +139,7 @@ sequenceDiagram
| `sdk-testkit` | 渠道域测试替身:InMemory SPI、FakeDirectAdapter |
| `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter |
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `channel-sdk-walmart` | 沃尔玛 Marketplace **直连**适配器(`DIRECT` + `WALMART_SC`):token / 订单 / 商品 / 售后,只读 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货 / 订单附件 / 销毁 / 箱标) |
@ -149,6 +150,7 @@ channel-sdk-core ──┐ @@ -149,6 +150,7 @@ channel-sdk-core ──┐
sdk-testkit ───────┼──→ sdk-common
warehouse-sdk-core ┘
lingxing ───────────→ channel-sdk-core, sdk-common
channel-sdk-walmart ──→ channel-sdk-core, sdk-common
warehouse-sdk-yqn ──→ warehouse-sdk-core, sdk-common
warehouse-sdk-xincang ──→ warehouse-sdk-core, sdk-common
warehouse-sdk-hengjian ──→ warehouse-sdk-core, sdk-common

61
channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java

@ -26,22 +26,51 @@ public final class OrderLine { @@ -26,22 +26,51 @@ public final class OrderLine {
/** 购买数量;0 表示平台未给或解析失败,非 null。 */
private final int quantity;
/** 商品单价;平台未给时为 null。币种通常与订单总额一致。 */
/**
* 商品<b>单价</b>,不是行总额;平台未给时为 null。
*
* <p>有些平台只给整行金额(沃尔玛 {@code ItemPrice.chargeAmount} 是「行金额」),
* 适配器必须除以 {@link #quantity()} 后再填这里;下游按
* {@code unitPrice × quantity} 汇总才不会被算重。</p>
*
* <p><b>除不尽时留 null</b>,不要四舍五入倒推——例如 3 件共 100.00 时
* {@code 33.3333 × 3 = 99.9999},会凭空产生分差。此时精确金额看
* {@link #lineAmount()}。</p>
*/
private final Money unitPrice;
/**
* 行金额(单价 × 数量),平台原值;平台没给时为 null。
*
* <p>与 {@link #unitPrice()} 的关系:平台给单价时由适配器相乘得到,或干脆不填;
* 平台给整行金额时直接放这里,<b>不做除法</b>——这是金额的权威来源,不丢精度。</p>
*/
private final Money lineAmount;
/** 行税额;平台未给时为 null。 */
private final Money tax;
/** 行优惠/折扣金额;平台未给时为 null。 */
private final Money discount;
/**
* 行状态原值;平台不提供时为 null。
*
* <p>沃尔玛取 {@code orderLineStatuses.orderLineStatus[].status}({@code Created} 等),
* 订单级状态由适配器按行状态聚合;领星订单接口不返回行状态。
* 保留原值不做枚举,避免平台加值就编译不过。</p>
*/
private final String status;
private OrderLine(Builder b) {
this.lineId = b.lineId;
this.platformSku = Objects.requireNonNull(b.platformSku, "platformSku");
this.quantity = b.quantity;
this.unitPrice = b.unitPrice;
this.lineAmount = b.lineAmount;
this.tax = b.tax;
this.discount = b.discount;
this.status = b.status;
}
/** 创建 Builder。 */
@ -64,11 +93,16 @@ public final class OrderLine { @@ -64,11 +93,16 @@ public final class OrderLine {
return quantity;
}
/** 商品单价;平台未给时为 null。 */
/** 商品<b>单价</b>(不是行总额);平台未给或除不尽时为 null。 */
public Money unitPrice() {
return unitPrice;
}
/** 行金额(单价 × 数量),平台原值;平台没给时为 null。精确金额以它为准。 */
public Money lineAmount() {
return lineAmount;
}
/** 行税额;平台未给时为 null。 */
public Money tax() {
return tax;
@ -79,6 +113,11 @@ public final class OrderLine { @@ -79,6 +113,11 @@ public final class OrderLine {
return discount;
}
/** 行状态原值;平台不返回时为 null。 */
public String status() {
return status;
}
public static final class Builder {
/** 行标识;可空,仅作展示。 */
@ -93,12 +132,18 @@ public final class OrderLine { @@ -93,12 +132,18 @@ public final class OrderLine {
/** 商品单价;可空。 */
private Money unitPrice;
/** 行金额;可空。 */
private Money lineAmount;
/** 行税额;可空。 */
private Money tax;
/** 行优惠/折扣金额;可空。 */
private Money discount;
/** 行状态原值;可空。 */
private String status;
/** 设置行标识;可空。 */
public Builder lineId(String lineId) {
this.lineId = lineId;
@ -123,6 +168,12 @@ public final class OrderLine { @@ -123,6 +168,12 @@ public final class OrderLine {
return this;
}
/** 设置行金额(单价 × 数量);平台给整行金额时直接放这里,不做除法。 */
public Builder lineAmount(Money lineAmount) {
this.lineAmount = lineAmount;
return this;
}
/** 设置行税额;可空。 */
public Builder tax(Money tax) {
this.tax = tax;
@ -135,6 +186,12 @@ public final class OrderLine { @@ -135,6 +186,12 @@ public final class OrderLine {
return this;
}
/** 设置行状态原值;可空。 */
public Builder status(String status) {
this.status = status;
return this;
}
/** 构建明细行;缺 platformSku 时抛 {@link NullPointerException}。 */
public OrderLine build() {
return new OrderLine(this);

46
channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java

@ -35,9 +35,25 @@ public final class SalesOrder { @@ -35,9 +35,25 @@ public final class SalesOrder {
/** 买家姓名,平台字段原样;多数领星订单接口不返回,此时为 null。 */
private final String buyerName;
/**
* 买家邮箱,平台字段原样;平台只给中转邮箱时保留中转地址,可空。
*
* <p>沃尔玛取 {@code customerEmailId}(形如 {@code xxx@relay.walmart.com}),
* 领星订单接口不返回该字段。</p>
*/
private final String buyerEmail;
/** 收货国家代码(ISO 3166-1 alpha-2,如 US / DE);领星取 store_Country_code,可空。 */
private final String shipToCountryCode;
/**
* 收货地址;平台不返回地址时为 null。
*
* <p>沃尔玛取 {@code shippingInfo.postalAddress},领星订单接口不返回该字段。
* 只承载收件信息,不含发货仓与物流方式。</p>
*/
private final ShipToAddress shipToAddress;
/** 订单明细行;不可变列表。空列表可能表示该接口未返回商品行(如 FBM 列表),不代表订单无商品。 */
private final List<OrderLine> lines;
@ -58,7 +74,9 @@ public final class SalesOrder { @@ -58,7 +74,9 @@ public final class SalesOrder {
this.channelOrderId = Objects.requireNonNull(b.channelOrderId, "channelOrderId");
this.status = b.status;
this.buyerName = b.buyerName;
this.buyerEmail = b.buyerEmail;
this.shipToCountryCode = b.shipToCountryCode;
this.shipToAddress = b.shipToAddress;
this.lines = Collections.unmodifiableList(new ArrayList<OrderLine>(b.lines));
this.totalAmount = b.totalAmount;
this.occurredAt = Objects.requireNonNull(b.occurredAt, "occurredAt");
@ -91,11 +109,21 @@ public final class SalesOrder { @@ -91,11 +109,21 @@ public final class SalesOrder {
return buyerName;
}
/** 买家邮箱(可能是平台中转邮箱);可空。 */
public String buyerEmail() {
return buyerEmail;
}
/** 收货国家代码(ISO 3166-1 alpha-2);可空。 */
public String shipToCountryCode() {
return shipToCountryCode;
}
/** 收货地址;平台不返回时为 null。 */
public ShipToAddress shipToAddress() {
return shipToAddress;
}
/** 订单明细行;不可变,可能为空列表。 */
public List<OrderLine> lines() {
return lines;
@ -135,9 +163,15 @@ public final class SalesOrder { @@ -135,9 +163,15 @@ public final class SalesOrder {
/** 买家姓名;可空。 */
private String buyerName;
/** 买家邮箱;可空。 */
private String buyerEmail;
/** 收货国家代码;可空。 */
private String shipToCountryCode;
/** 收货地址;可空。 */
private ShipToAddress shipToAddress;
/** 订单明细行;默认空列表,传入 null 按空列表处理。 */
private List<OrderLine> lines = Collections.emptyList();
@ -177,12 +211,24 @@ public final class SalesOrder { @@ -177,12 +211,24 @@ public final class SalesOrder {
return this;
}
/** 设置买家邮箱;可空。 */
public Builder buyerEmail(String buyerEmail) {
this.buyerEmail = buyerEmail;
return this;
}
/** 设置收货国家代码;可空。 */
public Builder shipToCountryCode(String shipToCountryCode) {
this.shipToCountryCode = shipToCountryCode;
return this;
}
/** 设置收货地址;可空,平台不返回地址时不设置。 */
public Builder shipToAddress(ShipToAddress shipToAddress) {
this.shipToAddress = shipToAddress;
return this;
}
/** 设置订单明细行;传 null 等价于空列表。 */
public Builder lines(List<OrderLine> lines) {
this.lines = lines == null ? Collections.<OrderLine>emptyList() : lines;

231
channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java

@ -0,0 +1,231 @@ @@ -0,0 +1,231 @@
package common.ecommerce.channel.model.order;
import java.util.Objects;
/**
* 订单收货地址。
*
* <p>各平台字段名不同、语义一致:沃尔玛 {@code shippingInfo.postalAddress}、
* 亚马逊 {@code ShippingAddress}、领星 {@code address_*}。统一收在这里,
* 平台原始值不再重复存放于 {@code SalesOrder}。</p>
*
* <p>本类只承载<b>收件信息</b>,不含发货仓、物流方式等履约配置;
* 那些属于出库/面单域,由 {@code OutboundOrder} 等模型表达。</p>
*
* <p><b>地址类型不做成枚举</b>:沃尔玛给 {@code RESIDENTIAL} / {@code OFFICE},
* 其它平台可能给别的值,做成枚举后平台加值就会编译不过。原值放在
* {@link #addressType()},由宿主自行解释。</p>
*/
public final class ShipToAddress {
/** 收件人姓名;平台不提供时为 null。 */
private final String name;
/** 地址行 1(街道、门牌号);平台不提供时为 null。 */
private final String address1;
/** 地址行 2(单元、楼层等);多数订单为 null。 */
private final String address2;
/** 城市;平台不提供时为 null。 */
private final String city;
/** 州 / 省;平台原始编码(如沃尔玛的 {@code CO}),不做大小写归一。 */
private final String state;
/** 邮编;保留平台原值,不补零、不去零。 */
private final String postalCode;
/** 国家代码;ISO 3166-1 alpha-2({@code US})或平台原值(沃尔玛给 {@code USA}),可空。 */
private final String countryCode;
/** 地址类型原值,如 {@code RESIDENTIAL} / {@code OFFICE};平台不给时为 null。 */
private final String addressType;
/** 收件人电话;平台以中转号或虚拟号给出时保留原值。 */
private final String phone;
private ShipToAddress(Builder b) {
this.name = b.name;
this.address1 = b.address1;
this.address2 = b.address2;
this.city = b.city;
this.state = b.state;
this.postalCode = b.postalCode;
this.countryCode = b.countryCode;
this.addressType = b.addressType;
this.phone = b.phone;
}
/** 创建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 收件人姓名。 */
public String name() {
return name;
}
/** 地址行 1。 */
public String address1() {
return address1;
}
/** 地址行 2。 */
public String address2() {
return address2;
}
/** 城市。 */
public String city() {
return city;
}
/** 州 / 省。 */
public String state() {
return state;
}
/** 邮编。 */
public String postalCode() {
return postalCode;
}
/** 国家代码原值。 */
public String countryCode() {
return countryCode;
}
/** 地址类型原值。 */
public String addressType() {
return addressType;
}
/** 收件人电话。 */
public String phone() {
return phone;
}
/** 地址是否为空(全字段为 null);适配器可据此决定要不要挂到订单上。 */
public boolean isEmpty() {
return name == null && address1 == null && address2 == null && city == null
&& state == null && postalCode == null && countryCode == null
&& addressType == null && phone == null;
}
/** 各字段都相同才相等。 */
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (!(o instanceof ShipToAddress)) {
return false;
}
ShipToAddress that = (ShipToAddress) o;
return Objects.equals(name, that.name)
&& Objects.equals(address1, that.address1)
&& Objects.equals(address2, that.address2)
&& Objects.equals(city, that.city)
&& Objects.equals(state, that.state)
&& Objects.equals(postalCode, that.postalCode)
&& Objects.equals(countryCode, that.countryCode)
&& Objects.equals(addressType, that.addressType)
&& Objects.equals(phone, that.phone);
}
/** 与 {@link #equals(Object)} 一致。 */
@Override
public int hashCode() {
return Objects.hash(name, address1, address2, city, state, postalCode, countryCode, addressType, phone);
}
/** 调试输出;地址属于个人信息,这里只输出城市与州,不输出街道与收件人。 */
@Override
public String toString() {
return "ShipToAddress{" + city + ", " + state + " " + postalCode + " " + countryCode + '}';
}
/** 收货地址构建器;所有字段可选。 */
public static final class Builder {
/** 收件人姓名。 */
private String name;
/** 地址行 1。 */
private String address1;
/** 地址行 2。 */
private String address2;
/** 城市。 */
private String city;
/** 州 / 省。 */
private String state;
/** 邮编。 */
private String postalCode;
/** 国家代码原值。 */
private String countryCode;
/** 地址类型原值。 */
private String addressType;
/** 收件人电话。 */
private String phone;
/** 设置收件人姓名。 */
public Builder name(String name) {
this.name = name;
return this;
}
/** 设置地址行 1。 */
public Builder address1(String address1) {
this.address1 = address1;
return this;
}
/** 设置地址行 2。 */
public Builder address2(String address2) {
this.address2 = address2;
return this;
}
/** 设置城市。 */
public Builder city(String city) {
this.city = city;
return this;
}
/** 设置州 / 省。 */
public Builder state(String state) {
this.state = state;
return this;
}
/** 设置邮编。 */
public Builder postalCode(String postalCode) {
this.postalCode = postalCode;
return this;
}
/** 设置国家代码原值。 */
public Builder countryCode(String countryCode) {
this.countryCode = countryCode;
return this;
}
/** 设置地址类型原值。 */
public Builder addressType(String addressType) {
this.addressType = addressType;
return this;
}
/** 设置收件人电话。 */
public Builder phone(String phone) {
this.phone = phone;
return this;
}
/** 构建地址对象;不做必填校验,缺字段就是 null。 */
public ShipToAddress build() {
return new ShipToAddress(this);
}
}
}

113
channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java

@ -0,0 +1,113 @@ @@ -0,0 +1,113 @@
package common.ecommerce.channel.model.order;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.PlatformTime;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 订单模型的增量字段必须全是可选的:老适配器(领星)不传时行为不能变。
*/
class SalesOrderOptionalFieldsTest {
private static SalesOrder minimalOrder() {
return SalesOrder.builder()
.omsStoreId("oms-wm-001")
.channelOrderId("PO-1")
.occurredAt(PlatformTime.of(Instant.parse("2026-11-18T00:00:00Z"), "America/Chicago"))
.sourceProvider(ChannelProvider.LINGXING)
.build();
}
@Test
void addressAndEmailDefaultToNull() {
SalesOrder order = minimalOrder();
assertNull(order.buyerEmail());
assertNull(order.shipToAddress());
assertNull(order.buyerName());
assertNull(order.shipToCountryCode());
}
@Test
void lineStatusDefaultsToNull() {
OrderLine line = OrderLine.builder().platformSku("SKU-1").quantity(1).build();
assertNull(line.status());
assertNull(line.lineId());
}
@Test
void walmartStyleOrderKeepsAllNewFields() {
SalesOrder order = SalesOrder.builder()
.omsStoreId("oms-wm-001")
.channelOrderId("108816631915371")
.status("Created")
.buyerName("Astro Test")
.buyerEmail("buyer@relay.walmart.com")
.shipToCountryCode("USA")
.shipToAddress(ShipToAddress.builder()
.name("Astro Test")
.address1("5809 W 44th Ave")
.city("Lakeside")
.state("CO")
.postalCode("80212")
.countryCode("USA")
.addressType("OFFICE")
.phone("555-0100")
.build())
.lines(java.util.Collections.singletonList(OrderLine.builder()
.lineId("1")
.platformSku("SKU-1")
.quantity(1)
.unitPrice(Money.of("499.99", "USD"))
.status("Created")
.build()))
.occurredAt(PlatformTime.of(Instant.ofEpochMilli(1686736267000L), "America/Chicago"))
.sourceProvider(ChannelProvider.DIRECT)
.build();
assertEquals("buyer@relay.walmart.com", order.buyerEmail());
assertEquals("Lakeside", order.shipToAddress().city());
assertEquals("Created", order.lines().get(0).status());
assertEquals("499.99", order.lines().get(0).unitPrice().amount().toPlainString());
}
@Test
void addressIsEmptyOnlyWhenEveryFieldIsNull() {
assertTrue(ShipToAddress.builder().build().isEmpty());
assertFalse(ShipToAddress.builder().city("Lakeside").build().isEmpty());
}
@Test
void addressEqualityCoversEveryField() {
ShipToAddress a = ShipToAddress.builder().address1("1 Main St").city("Dallas").build();
ShipToAddress b = ShipToAddress.builder().address1("1 Main St").city("Dallas").build();
ShipToAddress c = ShipToAddress.builder().address1("1 Main St").city("Austin").build();
assertEquals(a, b);
assertEquals(a.hashCode(), b.hashCode());
assertFalse(a.equals(c));
}
@Test
void addressToStringHidesPersonalFields() {
ShipToAddress address = ShipToAddress.builder()
.name("Jane Doe")
.address1("1 Main St")
.city("Dallas")
.state("TX")
.postalCode("75201")
.countryCode("USA")
.build();
String text = address.toString();
assertFalse(text.contains("Jane Doe"), text);
assertFalse(text.contains("1 Main St"), text);
assertTrue(text.contains("Dallas"), text);
}
}

49
channel-sdk-walmart/pom.xml

@ -0,0 +1,49 @@ @@ -0,0 +1,49 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>ecommerce</groupId>
<artifactId>channel-sdk-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>channel-sdk-walmart</artifactId>
<description>沃尔玛 Marketplace 直连适配器(订单 / 商品 / 售后)</description>
<dependencies>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>sdk-common</artifactId>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>channel-sdk-core</artifactId>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>sdk-testkit</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
</project>

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

@ -0,0 +1,115 @@ @@ -0,0 +1,115 @@
package common.ecommerce.walmart;
/**
* 沃尔玛 Marketplace 协议常量。
*
* <p>端点与路径属于<b>协议的一部分</b>,写在代码里,不做成配置表。
* 运行时不使用 {@link #PRODUCTION_BASE_URL} / {@link #SANDBOX_BASE_URL}:
* 端点由调用方每次经 {@code ChannelConnection} 传入(沙箱还是生产由宿主决定,
* 账户上的 {@code ChannelAccount.sandbox()} 只是元数据)。</p>
*
* <p>来源:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱
* {@code https://sandbox.walmartapis.com} 实测。</p>
*/
public final class WalmartConstants {
/** 适配器标识;注册表与日志用。 */
public static final String ADAPTER_ID = "walmart-direct";
/** 生产端点。 */
public static final String PRODUCTION_BASE_URL = "https://marketplace.walmartapis.com";
/** 沙箱端点。 */
public static final String SANDBOX_BASE_URL = "https://sandbox.walmartapis.com";
// ---------------------------------------------------------------- 路径
/** 换取访问令牌;form-urlencoded + Basic Auth。 */
public static final String PATH_TOKEN = "/v3/token";
/** 商品列表;游标分页。 */
public static final String PATH_ITEMS = "/v3/items";
/** 商品详情;路径参数为 URL 编码后的 SKU。 */
public static final String PATH_ITEM_BY_SKU = "/v3/items/";
/** 订单列表;按创建时间窗 + 游标分页。 */
public static final String PATH_ORDERS = "/v3/orders";
/** 订单详情;路径参数为 purchaseOrderId。响应多包一层 {@code {"order": ...}}。 */
public static final String PATH_ORDER_BY_ID = "/v3/orders/";
/** 退货单列表;{@code meta.nextCursor} 本身是一段查询串,翻页时整串拼到路径后面。 */
public static final String PATH_RETURNS = "/v3/returns";
/** 退货单详情;路径参数为 returnOrderId。⚠ 沙箱实测 404。 */
public static final String PATH_RETURN_BY_ID = "/v3/returns/";
/** 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。⚠ 沙箱实测 404。 */
public static final String PATH_ORDER_SHIPPING = "/shipping";
// ---------------------------------------------------------------- 请求头
/** 服务名,固定值。 */
public static final String HEADER_SVC_NAME = "WM_SVC.NAME";
/** 服务名的固定取值。 */
public static final String SVC_NAME_VALUE = "Walmart Marketplace";
/** 调用链追踪 ID,每次请求生成一个新的;SDK 用 {@code ChannelContext.requestId()}。 */
public static final String HEADER_CORRELATION_ID = "WM_QOS.CORRELATION_ID";
/** 访问令牌;<b>业务接口用它,不用 Authorization</b>。 */
public static final String HEADER_ACCESS_TOKEN = "WM_SEC.ACCESS_TOKEN";
/** 表单类型,仅令牌接口使用。 */
public static final String CONTENT_TYPE_FORM = "application/x-www-form-urlencoded";
/** JSON 类型,业务接口使用。 */
public static final String CONTENT_TYPE_JSON = "application/json";
// ---------------------------------------------------------------- 限制
/**
* 商品列表单页上限(官方值,超了本地截断)。
*
* <p>与领星不同,这里是<b>平台硬上限</b>:静默截断是安全的,因为调用方本来
* 就只能拿到这么多,且用 {@code nextCursor} 翻页。</p>
*/
public static final int MAX_ITEM_PAGE_SIZE = 200;
/** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */
public static final int DEFAULT_ORDER_PAGE_SIZE = 20;
/**
* 订单列表单页上限(📖 官方常见取值 200,与商品一致)。
*
* <p>文档没给订单的 {@code limit} 上限;这里与商品保持同一策略:超了本地截断,
* 而不是把大值原样发给平台(沙箱 mock 不校验,生产会被拒)。</p>
*/
public static final int MAX_ORDER_PAGE_SIZE = 200;
/** 退货列表默认单页条数;沃尔玛默认 10。 */
public static final int DEFAULT_RETURN_PAGE_SIZE = 10;
/**
* 订单创建时间窗的最大回溯天数(📖 官方常见取值,待 Developer Portal 核实)。
*
* <p>超过这个跨度在本地直接拒绝,不做静默截断——静默截断会让宿主以为拉全了。</p>
*/
public static final int MAX_ORDER_WINDOW_DAYS = 180;
/**
* 令牌提前续期秒数。
*
* <p>{@code expires_in} 只有 900 秒,且沙箱响应头 {@code x-current-token-count}
* 已达 99(平台对并发有效 token 有上限),必须缓存复用、提前续期。</p>
*/
public static final long TOKEN_EARLY_REFRESH_SECONDS = 120L;
/** 异常里保留的原始响应最大长度;避免整页报文塞进日志。 */
public static final int RAW_RESPONSE_LIMIT = 1024;
private WalmartConstants() {
}
}

642
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java

@ -0,0 +1,642 @@ @@ -0,0 +1,642 @@
package common.ecommerce.walmart.adapter;
import common.ecommerce.channel.capability.AfterSaleCapable;
import common.ecommerce.channel.capability.PlatformAdapter;
import common.ecommerce.channel.capability.ProductCapable;
import common.ecommerce.channel.capability.SalesOrderCapable;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.model.aftersale.AfterSale;
import common.ecommerce.channel.model.aftersale.AfterSaleQuery;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.order.SalesOrderRef;
import common.ecommerce.channel.model.product.ProductListing;
import common.ecommerce.channel.model.product.ProductQuery;
import common.ecommerce.channel.model.product.ProductRef;
import common.ecommerce.channel.model.product.ProductSyncStrategy;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.shared.model.Capability;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.shared.support.Page;
import common.ecommerce.http.TokenManager;
import common.ecommerce.walmart.WalmartConstants;
import common.ecommerce.walmart.auth.WalmartTokenClient;
import common.ecommerce.walmart.dto.WalmartItemDtos;
import common.ecommerce.walmart.dto.WalmartOrderDtos;
import common.ecommerce.walmart.dto.WalmartReturnDtos;
import common.ecommerce.walmart.dto.WalmartShipmentDtos;
import common.ecommerce.walmart.http.WalmartErrors;
import common.ecommerce.walmart.http.WalmartRequestFactory;
import common.ecommerce.walmart.mapper.WalmartOrderMapper;
import common.ecommerce.walmart.mapper.WalmartProductMapper;
import common.ecommerce.walmart.mapper.WalmartReturnMapper;
import common.ecommerce.walmart.mapper.WalmartShipmentMapper;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.EnumSet;
import java.util.List;
import java.util.Map;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* 沃尔玛 Marketplace 直连适配器(只读)。
*
* <p>实现三个能力接口:</p>
* <ul>
* <li>{@link SalesOrderCapable}:{@code GET /v3/orders}、{@code GET /v3/orders/{id}}</li>
* <li>{@link ProductCapable}:{@code GET /v3/items}、{@code GET /v3/items/{sku}}</li>
* <li>{@link AfterSaleCapable}:{@code GET /v3/returns}</li>
* </ul>
*
* <p>写操作(标发 / 退款 / 商品写入)本期不实现,对应能力位也不声明——
* 门面调用会显式抛 {@code UnsupportedCapabilityException},不会静默成功。</p>
*
* <h2>增量语义</h2>
* <p>沃尔玛订单接口只有<b>创建时间</b>过滤({@code createdStartDate/createdEndDate}),
* 没有更新时间。因此 {@link SalesOrderQuery#updatedAfter()} 被解释为创建时间窗;
* 「老单状态变化」需要宿主用 {@link #pullOpenOrders} 单独对账,两者不混在一起,
* 免得 {@code pull} 的语义变得不可预测。</p>
*/
public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, AfterSaleCapable {
private static final Logger LOG = LoggerFactory.getLogger(WalmartAdapter.class);
/** 沃尔玛日期时间格式:ISO-8601,毫秒精度,UTC。 */
private static final DateTimeFormatter WALMART_TIME_FORMAT =
DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'").withZone(java.time.ZoneOffset.UTC);
private final HttpTransport transport;
private final JacksonJsonCodec json;
private final WalmartRequestFactory requestFactory;
private final WalmartErrors errors;
private final TokenManager tokenManager;
public WalmartAdapter(HttpTransport transport, JacksonJsonCodec json,
TokenStore tokenStore, LockProvider lockProvider, Clock clock) {
this.transport = transport;
this.json = json;
this.requestFactory = new WalmartRequestFactory();
this.errors = new WalmartErrors(json);
final WalmartTokenClient tokenClient = new WalmartTokenClient(transport, json, clock);
// 令牌有效期 900s,提前 120s 续期;沙箱有效令牌数接近上限,必须缓存复用
this.tokenManager = new TokenManager(tokenStore, lockProvider, clock,
WalmartConstants.TOKEN_EARLY_REFRESH_SECONDS) {
@Override
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) {
return tokenClient.fetch(secret.endpointBaseUrl(), secret.clientId(), secret.clientSecret());
}
};
}
// ---------------------------------------------------------------- PlatformAdapter
@Override
public String adapterId() {
return WalmartConstants.ADAPTER_ID;
}
@Override
public ChannelProvider provider() {
return ChannelProvider.DIRECT;
}
@Override
public java.util.Set<Platform> platforms() {
return EnumSet.of(Platform.WALMART_SC);
}
@Override
public EnumSet<Capability> capabilities() {
return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS);
}
// ---------------------------------------------------------------- SalesOrderCapable
/**
* 按<b>创建时间窗</b>拉订单(沃尔玛没有更新时间过滤)。
*
* <p>时间窗超过 {@link WalmartConstants#MAX_ORDER_WINDOW_DAYS} 天时本地拒绝,
* 不做静默截断——静默截断会让宿主以为拉全了。</p>
*/
@Override
public Page<SalesOrder> pull(ChannelContext ctx, SalesOrderQuery query) {
ChannelAccount account = ctx.account();
Instant from = query.updatedAfter();
Instant to = query.updatedBefore() != null ? query.updatedBefore() : Instant.now(ctx.clock());
validateWindow(from, to);
Map<String, Object> queryParams = WalmartRequestFactory.query();
queryParams.put("createdStartDate", WALMART_TIME_FORMAT.format(from));
queryParams.put("createdEndDate", WALMART_TIME_FORMAT.format(to));
queryParams.put("limit", orderPageSize(query.pageSize()));
queryParams.put("nextCursor", query.cursor());
HttpResponse response = execute(ctx, "salesOrders.pull", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_ORDERS,
queryParams, t, c, "salesOrders.pull");
}
});
WalmartOrderDtos.OrderListResponse dto =
json.fromJson(response.body(), WalmartOrderDtos.OrderListResponse.class);
List<SalesOrder> orders = new ArrayList<SalesOrder>();
String nextCursor = null;
if (dto != null && dto.list != null) {
if (dto.list.elements != null && dto.list.elements.order != null) {
for (WalmartOrderDtos.Order order : dto.list.elements.order) {
SalesOrder mapped = WalmartOrderMapper.toSalesOrder(order,
account.omsStoreId(), zoneOf(ctx));
if (mapped != null) {
orders.add(mapped);
} else {
warnSkipped(ctx, "order", order == null ? null : order.purchaseOrderId);
}
}
}
if (dto.list.meta != null) {
nextCursor = dto.list.meta.nextCursor;
}
}
return Page.of(orders, nextCursor);
}
/** 订单详情;响应比列表多一层 {@code {"order": ...}}。 */
@Override
public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) {
ChannelAccount account = ctx.account();
String path = WalmartConstants.PATH_ORDER_BY_ID
+ WalmartRequestFactory.pathSegment(ref.channelOrderId());
HttpResponse response = execute(ctx, "salesOrders.get", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "salesOrders.get");
}
});
WalmartOrderDtos.OrderDetailResponse dto =
json.fromJson(response.body(), WalmartOrderDtos.OrderDetailResponse.class);
SalesOrder order = dto == null ? null
: WalmartOrderMapper.toSalesOrder(dto.order, account.omsStoreId(), zoneOf(ctx));
if (order == null) {
throw new ValidationException(ChannelException.builder()
.message("walmart order not found or empty: " + ref.channelOrderId())
.operation("salesOrders.get")
.provider(provider().name())
.omsStoreId(ctx.omsStoreId())
.platform(ctx.platform())
.requestId(ctx.requestId())
.platformCode(ref.channelOrderId())
.retryable(false));
}
return order;
}
/**
* 开放单对账:按行状态拉 {@code Created} / {@code Acknowledged} 的订单。
*
* <p>沃尔玛订单接口只能按创建时间过滤,{@code pull} 拿不到「老单今天发货」这种变化。
* 宿主在同步任务里追加一次本方法即可补齐,无需改统一模型。</p>
*
* @param statuses 行状态列表,如 {@code ["Created","Acknowledged"]};空则用这两个
* @param createdAfter 创建时间下界;null 表示不限制(平台默认行为)
* @param cursor 游标;首页传 null
*/
public Page<SalesOrder> pullOpenOrders(ChannelContext ctx, List<String> statuses,
Instant createdAfter, String cursor) {
ChannelAccount account = ctx.account();
Map<String, Object> queryParams = WalmartRequestFactory.query();
List<String> effective = statuses == null || statuses.isEmpty()
? java.util.Arrays.asList("Created", "Acknowledged") : statuses;
queryParams.put("status", joinComma(effective));
if (createdAfter != null) {
queryParams.put("createdStartDate", WALMART_TIME_FORMAT.format(createdAfter));
}
queryParams.put("limit", WalmartConstants.DEFAULT_ORDER_PAGE_SIZE);
queryParams.put("nextCursor", cursor);
HttpResponse response = execute(ctx, "salesOrders.pullOpen", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_ORDERS,
queryParams, t, c, "salesOrders.pullOpen");
}
});
WalmartOrderDtos.OrderListResponse dto =
json.fromJson(response.body(), WalmartOrderDtos.OrderListResponse.class);
List<SalesOrder> orders = new ArrayList<SalesOrder>();
String nextCursor = null;
if (dto != null && dto.list != null) {
if (dto.list.elements != null && dto.list.elements.order != null) {
for (WalmartOrderDtos.Order order : dto.list.elements.order) {
SalesOrder mapped = WalmartOrderMapper.toSalesOrder(order,
account.omsStoreId(), zoneOf(ctx));
if (mapped != null) {
orders.add(mapped);
} else {
warnSkipped(ctx, "order", order == null ? null : order.purchaseOrderId);
}
}
}
if (dto.list.meta != null) {
nextCursor = dto.list.meta.nextCursor;
}
}
return Page.of(orders, nextCursor);
}
// ---------------------------------------------------------------- ProductCapable
/**
* 沃尔玛 items 接口<b>没有更新时间过滤</b>,只能全量拉 + 差分。
*
* @see ProductSyncStrategy#FULL_PULL_DIFF
*/
@Override
public ProductSyncStrategy syncStrategy() {
return ProductSyncStrategy.FULL_PULL_DIFF;
}
/**
* 拉商品。
*
* <p>时间窗在此适配器里<b>不支持</b>:传了 {@code updatedAfter/updatedBefore} 直接抛
* {@link ValidationException},而不是静默忽略——静默忽略会让宿主以为做了增量。</p>
*/
@Override
public Page<ProductListing> pull(ChannelContext ctx, ProductQuery query) {
if (query.updatedAfter() != null || query.updatedBefore() != null) {
throw unsupportedFilter("walmart /v3/items does not support update-time filtering; "
+ "use syncStrategy FULL_PULL_DIFF or search by SKU");
}
if (query.searchField() != null && !query.searchValues().isEmpty()) {
throw unsupportedFilter("walmart /v3/items supports one sku at a time, not multi-value search");
}
if (query.searchField() == common.ecommerce.channel.model.product.ProductSearchField.LOCAL_SKU) {
throw unsupportedFilter("walmart has no local-sku concept; search by PLATFORM_SKU");
}
ChannelAccount account = ctx.account();
Map<String, Object> queryParams = WalmartRequestFactory.query();
queryParams.put("limit", Math.min(
query.pageSize() <= 0 ? WalmartConstants.MAX_ITEM_PAGE_SIZE : query.pageSize(),
WalmartConstants.MAX_ITEM_PAGE_SIZE));
queryParams.put("nextCursor", query.cursor());
if (query.searchValue() != null) {
queryParams.put("sku", query.searchValue());
}
HttpResponse response = execute(ctx, "products.pull", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_ITEMS,
queryParams, t, c, "products.pull");
}
});
WalmartItemDtos.ItemListResponse dto =
json.fromJson(response.body(), WalmartItemDtos.ItemListResponse.class);
List<ProductListing> products = new ArrayList<ProductListing>();
String nextCursor = null;
if (dto != null) {
if (dto.itemResponse != null) {
for (WalmartItemDtos.ItemResponse item : dto.itemResponse) {
ProductListing mapped = WalmartProductMapper.toProductListing(item, account.omsStoreId());
if (mapped != null) {
products.add(mapped);
} else {
warnSkipped(ctx, "item", item == null ? null : item.sku);
}
}
}
nextCursor = dto.nextCursor;
}
return Page.of(products, nextCursor);
}
/**
* 按 SKU 取单品。
*
* <p>⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。</p>
*/
@Override
public ProductListing get(ChannelContext ctx, ProductRef ref) {
ChannelAccount account = ctx.account();
String path = WalmartConstants.PATH_ITEM_BY_SKU
+ WalmartRequestFactory.pathSegment(ref.platformSku());
HttpResponse response = execute(ctx, "products.get", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "products.get");
}
});
WalmartItemDtos.ItemResponse dto =
json.fromJson(response.body(), WalmartItemDtos.ItemResponse.class);
return WalmartProductMapper.toProductListing(dto, account.omsStoreId());
}
// ---------------------------------------------------------------- AfterSaleCapable
/**
* 拉退货单,<b>按商品行展开</b>。
*
* <p>分页特殊:{@code meta.nextCursor} 本身是一段查询串
* (如 {@code "?sellerId=151&limit=10&offset=10"}),翻页时整串拼到 URL 后面。</p>
*
* <p>时间窗只支持按退货单创建时间;{@code PURCHASE_TIME} / {@code UPDATE_TIME}
* 显式报错,不做「拿售后时间顶替」的静默降级。</p>
*/
@Override
public Page<AfterSale> pull(ChannelContext ctx, AfterSaleQuery query) {
ChannelAccount account = ctx.account();
if (query.dateType() != AfterSaleQuery.DateType.AFTER_SALE_TIME) {
throw unsupportedFilter("walmart /v3/returns only filters by return-created date, got "
+ query.dateType());
}
if (!query.channelOrderIds().isEmpty()) {
throw unsupportedFilter("walmart /v3/returns filters one customerOrderId at a time, not a list");
}
String cursor = query.cursor();
if (cursor != null && !cursor.trim().isEmpty()) {
// 平台给的游标本身就是完整查询串,直接拼,不再追加参数
return executeReturns(ctx, account, "afterSales.pull", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
return requestFactory.getWithRawQuery(c.endpointBaseUrl(),
WalmartConstants.PATH_RETURNS, cursor.trim(), t, c, "afterSales.pull");
}
});
}
Map<String, Object> queryParams = WalmartRequestFactory.query();
queryParams.put("createdStartDate", WALMART_TIME_FORMAT.format(
query.startDate().atStartOfDay(ZoneId.of("UTC")).toInstant()));
queryParams.put("createdEndDate", WALMART_TIME_FORMAT.format(
query.endDate().atStartOfDay(ZoneId.of("UTC")).toInstant()));
queryParams.put("limit", query.pageSize() <= 0
? WalmartConstants.DEFAULT_RETURN_PAGE_SIZE : query.pageSize());
queryParams.put("offset", 0);
return executeReturns(ctx, account, "afterSales.pull", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_RETURNS,
queryParams, t, c, "afterSales.pull");
}
});
}
private Page<AfterSale> executeReturns(ChannelContext ctx, ChannelAccount account,
String operation, GetPlan plan) {
HttpResponse response = execute(ctx, operation, plan);
WalmartReturnDtos.ReturnListResponse dto =
json.fromJson(response.body(), WalmartReturnDtos.ReturnListResponse.class);
List<AfterSale> afterSales = new ArrayList<AfterSale>();
String nextCursor = null;
if (dto != null) {
if (dto.returnOrders != null) {
for (WalmartReturnDtos.ReturnOrder order : dto.returnOrders) {
List<AfterSale> lines = WalmartReturnMapper.toAfterSales(order,
account.omsStoreId(), zoneOf(ctx));
if (lines.isEmpty()) {
warnSkipped(ctx, "return", order == null ? null : order.returnOrderId);
}
afterSales.addAll(lines);
}
}
if (dto.meta != null) {
nextCursor = dto.meta.nextCursor;
}
}
return Page.of(afterSales, nextCursor);
}
/**
* 退货单详情:{@code GET /v3/returns/{returnOrderId}}。
*
* <p>与列表一样<b>按商品行展开</b>:一个退货单可能含多个退货行,
* 返回的 {@link AfterSale#afterSaleId()} 与列表里的完全一致({@code returnOrderId:行号}),
* 可以直接拿去 upsert。</p>
*
* <p>{@link AfterSaleCapable} 没有「取详情」方法——售后以拉取为主,
* 需要单条时用列表的时间窗过滤即可。这里提供它是因为沃尔玛有真实路由,
* 且列表接口的过滤参数在沙箱不生效,生产上按单号回查更快。</p>
*
* <p>⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。</p>
*
* @param returnOrderId 退货单号
* @return 该退货单展开出的售后行;退货单没有行时返回空列表
* @throws ChannelException 平台 404 / 其它错误,由 {@link WalmartErrors} 分类
*/
public List<AfterSale> getReturn(ChannelContext ctx, String returnOrderId) {
if (returnOrderId == null || returnOrderId.trim().isEmpty()) {
throw unsupportedFilter("walmart return detail requires returnOrderId");
}
ChannelAccount account = ctx.account();
String path = WalmartConstants.PATH_RETURN_BY_ID
+ WalmartRequestFactory.pathSegment(returnOrderId.trim());
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");
}
});
WalmartReturnDtos.ReturnOrder dto =
json.fromJson(response.body(), WalmartReturnDtos.ReturnOrder.class);
return WalmartReturnMapper.toAfterSales(dto, account.omsStoreId(), zoneOf(ctx));
}
// ---------------------------------------------------------------- 发货信息(非能力接口)
/**
* 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。
*
* <p>返回<b>行级</b>发货记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间)。
* 统一模型没有独立的发货实体——从订单详情的行状态里也能读到同样的
* {@code trackingInfo},两种方式数据一致;本方法用于只想知道「发了哪些行」的场景。</p>
*
* <p>⚠ 沙箱实测该路由 404(mock 未实现)。生产上若也不可用,改用
* {@link #get(ChannelContext, SalesOrderRef)} 读订单详情。</p>
*
* @param purchaseOrderId 沃尔玛订单号
* @return 已发货行的记录;未发货时返回空列表
*/
public List<WalmartShipmentMapper.ShipmentLine> getShipping(ChannelContext ctx,
String purchaseOrderId) {
if (purchaseOrderId == null || purchaseOrderId.trim().isEmpty()) {
throw unsupportedFilter("walmart shipping query requires purchaseOrderId");
}
String path = WalmartConstants.PATH_ORDER_BY_ID
+ WalmartRequestFactory.pathSegment(purchaseOrderId.trim())
+ WalmartConstants.PATH_ORDER_SHIPPING;
HttpResponse response = execute(ctx, "salesOrders.shipping", new GetPlan() {
@Override
public HttpRequest request(ChannelContext c, AccessToken t) {
return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "salesOrders.shipping");
}
});
WalmartShipmentDtos.ShipmentResponse dto =
json.fromJson(response.body(), WalmartShipmentDtos.ShipmentResponse.class);
return WalmartShipmentMapper.toShipmentLines(dto);
}
// ---------------------------------------------------------------- internals
/**
* 执行一次业务请求,401/403 时强制换 token 重试一次。
*
* <p>为什么要重试:沃尔玛 token 的 {@code expires_in} 是 900 秒,但平台可以提前作废
* (后台重置 secret、并发令牌超限被踢)。缓存里的坏 token 在自然过期前会一直命中,
* 期间所有请求都 401。{@code TokenManager} 有 {@code forceRefresh},但门面层没有
* 自动重试——重试策略属于适配器,这里只在本模块内实现一次「换 token + 重发」。</p>
*
* <p>重试只做一次,第二次失败原样抛出,交由宿主决定是否停用账户。</p>
*/
private HttpResponse execute(ChannelContext ctx, String operation, GetPlan plan) {
AccessToken token = token(ctx);
HttpResponse response = transport.execute(plan.request(ctx, token));
if (!isAuthFailure(response)) {
errors.throwIfError(response, ctx, operation);
return response;
}
// 缓存里的 token 已失效:强制换新后重发一次
ChannelSecret secret = ctx.secret();
AccessToken refreshed = tokenManager.forceRefresh(tokenKey(secret), secret);
HttpResponse retried = transport.execute(plan.request(ctx, refreshed));
errors.throwIfError(retried, ctx, operation);
return retried;
}
/** 401/403 才值得换 token 重试;其它错误交给 {@link WalmartErrors}。 */
private static boolean isAuthFailure(HttpResponse response) {
return response.statusCode() == 401 || response.statusCode() == 403;
}
/** 用「当前 token」拼请求;重试时会用新 token 再调一次。 */
private interface GetPlan {
HttpRequest request(ChannelContext ctx, AccessToken token);
}
/**
* 取令牌并返回请求要用的 token。
*
* <p>缓存维度是 {@code clientId}:一个 clientId 对应一个 seller,
* 同 seller 的多个店铺共用一个令牌,避免触碰平台并发令牌上限。</p>
*/
private AccessToken token(ChannelContext ctx) {
ChannelSecret secret = ctx.secret();
if (isBlank(secret.clientId()) || isBlank(secret.clientSecret())) {
throw new ValidationException(ChannelException.builder()
.message("walmart requires ChannelSecret.clientId and clientSecret")
.operation("token")
.provider(provider().name())
.omsStoreId(ctx.omsStoreId())
.platform(ctx.platform())
.requestId(ctx.requestId())
.retryable(false));
}
return tokenManager.getOrRefresh(tokenKey(secret), secret);
}
/** 令牌缓存键;按 clientId 聚合,同一 seller 的店铺共用。 */
static String tokenKey(ChannelSecret secret) {
return "walmart:" + secret.clientId();
}
/** 市场时区:账户没配时按沃尔玛总部所在时区兜底(美国中部)。 */
private static ZoneId zoneOf(ChannelContext ctx) {
ChannelAccount account = ctx.account();
String zone = account == null ? null : account.marketplaceZone();
return zone == null || zone.trim().isEmpty() ? ZoneId.of("America/Chicago") : ZoneId.of(zone);
}
/** 时间窗校验:起点必填、终点必须晚于起点、跨度不超过平台上限。 */
private static void validateWindow(Instant from, Instant to) {
if (from == null) {
throw unsupportedFilter("walmart /v3/orders requires updatedAfter (mapped to createdStartDate)");
}
if (!to.isAfter(from)) {
throw unsupportedFilter("walmart /v3/orders requires updatedBefore after updatedAfter");
}
long days = Duration.between(from, to).toDays();
if (days > WalmartConstants.MAX_ORDER_WINDOW_DAYS) {
throw unsupportedFilter("walmart /v3/orders window is " + days + " days, max "
+ WalmartConstants.MAX_ORDER_WINDOW_DAYS + "; split the window instead of truncating");
}
}
/** 订单单页条数:0 或负数用默认值,超出上限本地截断(与商品同一策略)。 */
private static int orderPageSize(int requested) {
if (requested <= 0) {
return WalmartConstants.DEFAULT_ORDER_PAGE_SIZE;
}
return Math.min(requested, WalmartConstants.MAX_ORDER_PAGE_SIZE);
}
private static String joinComma(List<String> values) {
StringBuilder sb = new StringBuilder();
for (String v : values) {
if (v == null || v.trim().isEmpty()) {
continue;
}
if (sb.length() > 0) {
sb.append(',');
}
sb.append(v.trim());
}
return sb.toString();
}
/**
* 平台给了一条缺必填字段的记录,映射层丢弃时留痕。
*
* <p>不抛异常:一条脏数据不该卡住整页同步;但也不能完全静默——宿主需要知道
* 「这次少了一条」以及少的是哪个单号。</p>
*/
private static void warnSkipped(ChannelContext ctx, String kind, String id) {
LOG.warn("walmart {} skipped: missing required field, id={} store={} requestId={}",
kind, id, ctx.omsStoreId(), ctx.requestId());
}
private static boolean isBlank(String v) {
return v == null || v.trim().isEmpty();
}
/** 适配器不支持某过滤条件时的统一异常。 */
private static ValidationException unsupportedFilter(String message) {
return new ValidationException(ChannelException.builder()
.message(message)
.operation("walmart.filter")
.provider(ChannelProvider.DIRECT.name())
.platform(Platform.WALMART_SC)
.retryable(false));
}
}

63
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java

@ -0,0 +1,63 @@ @@ -0,0 +1,63 @@
package common.ecommerce.walmart.adapter;
import common.ecommerce.channel.capability.PlatformAdapter;
import common.ecommerce.channel.sdk.AdapterFactory;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.walmart.WalmartConstants;
import java.time.Clock;
import java.util.EnumSet;
/**
* 沃尔玛直连适配器工厂。
*
* <p>与领星、三方仓使用同一套注册机制:工厂只装配基础设施,
* <b>不持有端点与凭据</b>——两者由调用方每次经 {@code ChannelConnection} 传入。</p>
*
* <pre>
* ChannelSdk.builder()
* .accountRepository(repo)
* .register(new WalmartAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
* .build();
* </pre>
*/
public final class WalmartAdapterFactory implements AdapterFactory {
private final TokenStore tokenStore;
private final LockProvider lockProvider;
private final Clock clock;
public WalmartAdapterFactory(TokenStore tokenStore, LockProvider lockProvider, Clock clock) {
this.tokenStore = tokenStore;
this.lockProvider = lockProvider;
this.clock = clock;
}
@Override
public String adapterId() {
return WalmartConstants.ADAPTER_ID;
}
@Override
public ChannelProvider provider() {
return ChannelProvider.DIRECT;
}
@Override
public EnumSet<Platform> platforms() {
return EnumSet.of(Platform.WALMART_SC);
}
@Override
public PlatformAdapter create(AdapterConfig config) {
return new WalmartAdapter(
new OkHttpTransport("common-ecommerce/1.0.0 (walmart)"),
new JacksonJsonCodec(),
tokenStore, lockProvider, clock);
}
}

127
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java

@ -0,0 +1,127 @@ @@ -0,0 +1,127 @@
package common.ecommerce.walmart.auth;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.Responses;
import common.ecommerce.shared.error.AuthException;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.walmart.WalmartConstants;
import common.ecommerce.walmart.dto.WalmartTokenDtos;
import java.nio.charset.StandardCharsets;
import java.time.Clock;
import java.time.Instant;
import java.util.Base64;
/**
* 沃尔玛令牌接口:{@code POST /v3/token}。
*
* <p>请求:Basic Auth({@code clientId:clientSecret})+ form 体
* {@code grant_type=client_credentials}。</p>
*
* <p>响应:{@code access_token} / {@code token_type=Bearer} / {@code expires_in=900}。
* 业务接口带 {@code WM_SEC.ACCESS_TOKEN} 头,<b>不再</b>带 Basic Auth(沙箱实测)。</p>
*
* <p>令牌按 {@code clientId} 维度缓存:一个 clientId 对应一个 seller,
* 多店铺共用同一令牌,避免触碰平台的并发有效令牌上限
* (沙箱 {@code x-current-token-count} 已接近上限)。</p>
*/
public final class WalmartTokenClient {
private static final String OP_FETCH = "token.fetch";
/** 平台未返回 expires_in 时的兜底有效期(秒):官方值为 900。 */
static final long DEFAULT_EXPIRES_IN_SECONDS = 900L;
private final HttpTransport transport;
private final JacksonJsonCodec json;
private final Clock clock;
public WalmartTokenClient(HttpTransport transport, JacksonJsonCodec json, Clock clock) {
this.transport = transport;
this.json = json;
this.clock = clock;
}
/**
* 用 clientId + clientSecret 换新令牌。
*
* @param baseUrl 端点基址(沙箱或生产),由调用方每次传入
* @param clientId 沃尔玛 Client ID
* @param clientSecret 沃尔玛 Client Secret
* @throws AuthException clientId / clientSecret 为空,或平台返回 401 / 403
*/
public AccessToken fetch(String baseUrl, String clientId, String clientSecret) {
if (isBlank(clientId) || isBlank(clientSecret)) {
throw new AuthException(ChannelException.builder()
.message("walmart token requires clientId and clientSecret")
.operation(OP_FETCH)
.provider(WalmartConstants.ADAPTER_ID)
.retryable(false));
}
HttpRequest request = HttpRequest.builder()
.method("POST")
.url(baseUrl + WalmartConstants.PATH_TOKEN)
.contentType(WalmartConstants.CONTENT_TYPE_FORM)
.header("Authorization", basicAuth(clientId, clientSecret))
.header(WalmartConstants.HEADER_SVC_NAME, WalmartConstants.SVC_NAME_VALUE)
.header("Accept", WalmartConstants.CONTENT_TYPE_JSON)
.body("grant_type=client_credentials")
.operation(OP_FETCH)
.build();
HttpResponse response = transport.execute(request);
Responses.throwIfNotSuccess(response, OP_FETCH);
WalmartTokenDtos.TokenResponse dto;
try {
dto = json.fromJson(response.body(), WalmartTokenDtos.TokenResponse.class);
} catch (IllegalArgumentException e) {
throw new AuthException(ChannelException.builder()
.message("walmart token response is not valid json")
.operation(OP_FETCH)
.provider(WalmartConstants.ADAPTER_ID)
.retryable(false)
.rawResponse(truncate(response.body())),
e);
}
if (dto == null || isBlank(dto.accessToken)) {
throw new AuthException(ChannelException.builder()
.message("walmart token response has no access_token")
.operation(OP_FETCH)
.provider(WalmartConstants.ADAPTER_ID)
.retryable(false)
.rawResponse(truncate(response.body())));
}
long expiresIn = dto.expiresIn == null || dto.expiresIn <= 0
? DEFAULT_EXPIRES_IN_SECONDS : dto.expiresIn.longValue();
return AccessToken.builder()
.value(dto.accessToken)
.tokenType(isBlank(dto.tokenType) ? "Bearer" : dto.tokenType)
.expiresAt(Instant.now(clock).plusSeconds(expiresIn))
.build();
}
/** Base64(clientId:clientSecret),UTF-8。 */
static String basicAuth(String clientId, String clientSecret) {
String raw = clientId + ":" + clientSecret;
return "Basic " + Base64.getEncoder().encodeToString(raw.getBytes(StandardCharsets.UTF_8));
}
private static boolean isBlank(String v) {
return v == null || v.trim().isEmpty();
}
private static String truncate(String body) {
if (body == null) {
return null;
}
return body.length() <= WalmartConstants.RAW_RESPONSE_LIMIT
? body : body.substring(0, WalmartConstants.RAW_RESPONSE_LIMIT);
}
}

113
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java

@ -0,0 +1,113 @@ @@ -0,0 +1,113 @@
package common.ecommerce.walmart.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.math.BigDecimal;
import java.util.List;
/**
* 沃尔玛报文结构:商品 Listing({@code GET /v3/items}、{@code GET /v3/items/{sku}})。
*
* <p>列表字段名是单数 {@code ItemResponse},没有外层包装对象,直接是数组。</p>
*
* <p>{@code shelf} 是<b>JSON 字符串数组</b>(例如 {@code "[\"Home Page\",\"Clothing\"]"}),
* 需要二次解析;{@code UNNAV} 表示未分配到可浏览类目。</p>
*/
public final class WalmartItemDtos {
private WalmartItemDtos() {
}
/** 商品列表响应。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ItemListResponse {
/** 商品数组;字段名就是单数 {@code ItemResponse}。 */
@JsonProperty("ItemResponse")
public List<ItemResponse> itemResponse;
/** 商品总数。 */
@JsonProperty("totalItems")
public Integer totalItems;
/** 下一页游标;无更多时为 null。 */
@JsonProperty("nextCursor")
public String nextCursor;
}
/** 商品。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ItemResponse {
/** 站点:{@code WALMART_US} / {@code WALMART_CA} / {@code WALMART_MX}。 */
@JsonProperty("mart")
public String mart;
/** 卖家 SKU。 */
@JsonProperty("sku")
public String sku;
/** 沃尔玛商品 ID(Walmart Product ID)。 */
@JsonProperty("wpid")
public String wpid;
/** UPC 编码。 */
@JsonProperty("upc")
public String upc;
/** GTIN 编码(14 位,含前导 0)。 */
@JsonProperty("gtin")
public String gtin;
/** 商品名称。 */
@JsonProperty("productName")
public String productName;
/** 前台类目:JSON 字符串数组,如 {@code "[\"Home Page\",\"Clothing\"]"}。 */
@JsonProperty("shelf")
public String shelf;
/** 商品类型 / 类目模板名,如 {@code T-Shirts};{@code default} 表示默认模板。 */
@JsonProperty("productType")
public String productType;
/** 价格。 */
@JsonProperty("price")
public Price price;
/** 发布状态:{@code PUBLISHED} / {@code UNPUBLISHED} / {@code SYSTEM_PROBLEM} 等。 */
@JsonProperty("publishedStatus")
public String publishedStatus;
/** 未发布原因。 */
@JsonProperty("unpublishedReasons")
public UnpublishedReasons unpublishedReasons;
/** 生命周期状态:{@code ACTIVE} / {@code ARCHIVED} / {@code RETIRED}。 */
@JsonProperty("lifecycleStatus")
public String lifecycleStatus;
}
/** 价格。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Price {
/** 币种:{@code USD} / {@code CAD} / {@code MXN}。 */
@JsonProperty("currency")
public String currency;
/** 售价;用 BigDecimal 接。 */
@JsonProperty("amount")
public BigDecimal amount;
}
/** 未发布原因容器。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class UnpublishedReasons {
/** 原因列表(英文描述)。 */
@JsonProperty("reason")
public List<String> reason;
}
}

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

@ -0,0 +1,377 @@ @@ -0,0 +1,377 @@
package common.ecommerce.walmart.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.math.BigDecimal;
import java.util.List;
/**
* 沃尔玛报文结构:订单({@code GET /v3/orders}、{@code GET /v3/orders/{id}})。
*
* <p><b>层次陷阱</b>:沃尔玛的 JSON 由旧版 XML Schema 转换而来,数组外层带单数包装对象:
* {@code orderLines.orderLine[]}、{@code orderLineStatuses.orderLineStatus[]}、
* {@code charges.charge[]}。字段名照抄,不要「优化」成复数。</p>
*
* <p><b>类型陷阱</b>:金额是 {@code {"currency","amount"}} 且 amount 是数字;
* 数量是 {@code {"unitOfMeasurement","amount"}} 且 amount 是<b>字符串</b>;
* 时间是 epoch 毫秒。三者在退货接口里又都不一样。</p>
*/
public final class WalmartOrderDtos {
private WalmartOrderDtos() {
}
/** 订单列表响应:{@code list.meta} + {@code list.elements.order[]}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderListResponse {
/** 列表容器;平台未返回时为 null。 */
@JsonProperty("list")
public ListWrapper list;
}
/** 列表容器。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ListWrapper {
/** 分页元信息。 */
@JsonProperty("meta")
public Meta meta;
/** 订单数组容器。 */
@JsonProperty("elements")
public Elements elements;
}
/** 分页元信息。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Meta {
/** 总订单数。 */
@JsonProperty("totalCount")
public Integer totalCount;
/** 当前每页条数。 */
@JsonProperty("limit")
public Integer limit;
/** 下一页游标;无更多为 null。 */
@JsonProperty("nextCursor")
public String nextCursor;
}
/** 订单数组的包装层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Elements {
/** 订单数组;字段名就是单数 {@code order}。 */
@JsonProperty("order")
public List<Order> order;
}
/**
* 订单详情响应:{@code {"order": {...}}}。
*
* <p>比列表多包一层,映射时两者共用 {@link Order}。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderDetailResponse {
/** 订单本体。 */
@JsonProperty("order")
public Order order;
}
/** 订单本体。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Order {
/** 沃尔玛订单号;标发接口的路径参数。 */
@JsonProperty("purchaseOrderId")
public String purchaseOrderId;
/** 平台客户订单号;买家侧看到的是它。 */
@JsonProperty("customerOrderId")
public String customerOrderId;
/** 客户邮箱;通常是沃尔玛中转地址({@code @relay.walmart.com})。 */
@JsonProperty("customerEmailId")
public String customerEmailId;
/** 下单时间,<b>epoch 毫秒</b>。 */
@JsonProperty("orderDate")
public Long orderDate;
/** 配送与收货信息。 */
@JsonProperty("shippingInfo")
public ShippingInfo shippingInfo;
/** 订单行容器。 */
@JsonProperty("orderLines")
public OrderLines orderLines;
/** 发货节点类型({@code SellerFulfilled} / {@code WalmartFulfilled})。 */
@JsonProperty("shipNode")
public ShipNode shipNode;
}
/** 配送与收货信息。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ShippingInfo {
/** 收件人电话。 */
@JsonProperty("phone")
public String phone;
/** 预计发货时间,epoch 毫秒。 */
@JsonProperty("estimatedShipDate")
public Long estimatedShipDate;
/** 预计送达时间,epoch 毫秒。 */
@JsonProperty("estimatedDeliveryDate")
public Long estimatedDeliveryDate;
/** 订单配送方式({@code Value} / {@code Standard} / {@code TwoDay} 等)。 */
@JsonProperty("methodCode")
public String methodCode;
/** 收货地址。 */
@JsonProperty("postalAddress")
public PostalAddress postalAddress;
}
/** 收货地址。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class PostalAddress {
/** 收件人姓名。 */
@JsonProperty("name")
public String name;
/** 地址行 1。 */
@JsonProperty("address1")
public String address1;
/** 地址行 2;可为 null。 */
@JsonProperty("address2")
public String address2;
/** 城市。 */
@JsonProperty("city")
public String city;
/** 州。 */
@JsonProperty("state")
public String state;
/** 邮编。 */
@JsonProperty("postalCode")
public String postalCode;
/** 国家,如 {@code USA}。 */
@JsonProperty("country")
public String country;
/** 地址类型:{@code RESIDENTIAL} / {@code OFFICE}。 */
@JsonProperty("addressType")
public String addressType;
}
/** 订单行容器。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderLines {
/** 订单行数组。 */
@JsonProperty("orderLine")
public List<OrderLine> orderLine;
}
/** 订单行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderLine {
/** 行号;标发报文里对应 {@code orderLine.lineNumber}。 */
@JsonProperty("lineNumber")
public String lineNumber;
/** 商品信息。 */
@JsonProperty("item")
public Item item;
/** 费用明细容器。 */
@JsonProperty("charges")
public Charges charges;
/** 数量,amount 是<b>字符串</b>。 */
@JsonProperty("orderLineQuantity")
public Quantity orderLineQuantity;
/** 行状态容器。 */
@JsonProperty("orderLineStatuses")
public OrderLineStatuses orderLineStatuses;
/** 状态时间,epoch 毫秒。 */
@JsonProperty("statusDate")
public Long statusDate;
/** 履约信息;结构未在沙箱覆盖,保留原始节点不映射。 */
@JsonProperty("fulfillment")
public Object fulfillment;
}
/** 订单行商品。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Item {
/** 商品名称。 */
@JsonProperty("productName")
public String productName;
/** 卖家 SKU。 */
@JsonProperty("sku")
public String sku;
}
/** 费用明细容器。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Charges {
/** 费用数组。 */
@JsonProperty("charge")
public List<Charge> charge;
}
/** 单条费用。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Charge {
/** 费用类型:{@code PRODUCT} / {@code FEE} / {@code SHIPPING}。 */
@JsonProperty("chargeType")
public String chargeType;
/** 费用名称,如 {@code ItemPrice}、{@code Shipping}。 */
@JsonProperty("chargeName")
public String chargeName;
/** 费用金额。 */
@JsonProperty("chargeAmount")
public Amount chargeAmount;
/** 税。 */
@JsonProperty("tax")
public Tax tax;
}
/** 金额:{@code {"currency","amount"}},amount 是数字。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Amount {
/** 币种,如 {@code USD}。 */
@JsonProperty("currency")
public String currency;
/** 金额;用 BigDecimal 接,避免 double 精度问题。 */
@JsonProperty("amount")
public BigDecimal amount;
}
/** 税。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Tax {
/** 税名。 */
@JsonProperty("taxName")
public String taxName;
/** 税额。 */
@JsonProperty("taxAmount")
public Amount taxAmount;
}
/** 数量:{@code {"unitOfMeasurement","amount"}},amount 是<b>字符串</b>。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Quantity {
/** 计量单位,如 {@code EACH}。 */
@JsonProperty("unitOfMeasurement")
public String unitOfMeasurement;
/** 数量,字符串(沙箱样例 {@code "1"})。 */
@JsonProperty("amount")
public String amount;
}
/** 行状态容器。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderLineStatuses {
/** 行状态数组。 */
@JsonProperty("orderLineStatus")
public List<OrderLineStatus> orderLineStatus;
}
/** 行状态。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderLineStatus {
/** 状态:{@code Created} / {@code Acknowledged} / {@code Shipped} / {@code Delivered} / {@code Cancelled}。 */
@JsonProperty("status")
public String status;
/** 该状态对应的数量。 */
@JsonProperty("statusQuantity")
public Quantity statusQuantity;
/** 取消原因,仅取消时有值。 */
@JsonProperty("cancellationReason")
public String cancellationReason;
/** 物流跟踪信息;未发货时为 null。 */
@JsonProperty("trackingInfo")
public TrackingInfo trackingInfo;
}
/** 物流跟踪信息。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TrackingInfo {
/** 发货时间,ISO-8601 字符串(与订单其它时间是 epoch 毫秒不同)。 */
@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;
}
/** 发货节点。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ShipNode {
/** 发货节点类型:{@code SellerFulfilled} / {@code WalmartFulfilled}。 */
@JsonProperty("type")
public String type;
}
}

396
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java

@ -0,0 +1,396 @@ @@ -0,0 +1,396 @@
package common.ecommerce.walmart.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.math.BigDecimal;
import java.util.List;
/**
* 沃尔玛报文结构:售后退货({@code GET /v3/returns}、{@code GET /v3/returns/{id}})。
*
* <p><b>与订单接口的差异(同一个字段三种写法)</b>:</p>
* <ul>
* <li>金额:订单是 {@code {"currency","amount"}},退货是 {@code {"currencyAmount","currencyUnit"}}</li>
* <li>数量:订单是 {@code {"unitOfMeasurement","amount"(字符串)}},
* 退货是 {@code {"unitOfMeasure","measurementValue"(数字)}}</li>
* <li>时间:订单是 epoch 毫秒,退货是 ISO-8601 字符串</li>
* </ul>
*
* <p><b>分页陷阱</b>:{@code meta.nextCursor} 的值本身是一段查询串
* ({@code "?sellerId=151&limit=10&offset=10"}),翻页时整串拼到 URL 后面,
* 不是普通游标。</p>
*/
public final class WalmartReturnDtos {
private WalmartReturnDtos() {
}
/** 退货单列表响应。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ReturnListResponse {
/** 分页元信息。 */
@JsonProperty("meta")
public Meta meta;
/** 退货单数组。 */
@JsonProperty("returnOrders")
public List<ReturnOrder> returnOrders;
}
/** 分页元信息。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Meta {
/** 退货单总数。 */
@JsonProperty("totalCount")
public Integer totalCount;
/** 当前每页条数。 */
@JsonProperty("limit")
public Integer limit;
/** 下一页查询串;无更多时为 null。 */
@JsonProperty("nextCursor")
public String nextCursor;
}
/** 退货单(一个退货单可含多个退货行)。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ReturnOrder {
/** 退货单号。 */
@JsonProperty("returnOrderId")
public String returnOrderId;
/** 客户邮箱(沃尔玛中转邮箱)。 */
@JsonProperty("customerEmailId")
public String customerEmailId;
/** 客户姓名。 */
@JsonProperty("customerName")
public CustomerName customerName;
/** 平台客户订单号。 */
@JsonProperty("customerOrderId")
public String customerOrderId;
/** 退款模式:{@code PRE_DELIVERY} / {@code POST_DELIVERY}。 */
@JsonProperty("refundMode")
public String refundMode;
/** 退货单创建时间,ISO-8601 字符串。 */
@JsonProperty("returnOrderDate")
public String returnOrderDate;
/** 退货类型:{@code RETURN} / {@code REPLACEMENT}。 */
@JsonProperty("returnType")
public String returnType;
/** 换货生成的客户订单号;换货时有值。 */
@JsonProperty("replacementCustomerOrderId")
public String replacementCustomerOrderId;
/** 最晚退货时间,ISO-8601。 */
@JsonProperty("returnByDate")
public String returnByDate;
/** 应退总金额。 */
@JsonProperty("totalRefundAmount")
public CurrencyAmount totalRefundAmount;
/** 退货渠道。 */
@JsonProperty("returnChannel")
public ReturnChannel returnChannel;
/** 退货包裹 / 面单分组。 */
@JsonProperty("returnLineGroups")
public List<ReturnLineGroup> returnLineGroups;
/** 退货行数组。 */
@JsonProperty("returnOrderLines")
public List<ReturnOrderLine> returnOrderLines;
}
/** 客户姓名。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CustomerName {
/** 名。 */
@JsonProperty("firstName")
public String firstName;
/** 姓。 */
@JsonProperty("lastName")
public String lastName;
}
/** 退货金额:{@code {"currencyAmount","currencyUnit"}};currencyAmount 是数字。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CurrencyAmount {
/** 金额;用 BigDecimal 接。 */
@JsonProperty("currencyAmount")
public BigDecimal currencyAmount;
/** 币种,如 {@code USD}。 */
@JsonProperty("currencyUnit")
public String currencyUnit;
}
/** 退货渠道。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ReturnChannel {
/** 渠道名:{@code IN_STORE}(到店) / {@code ONLINE}(线上)。 */
@JsonProperty("channelName")
public String channelName;
}
/** 退货包裹 / 面单分组。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ReturnLineGroup {
/** 分组号。 */
@JsonProperty("groupNo")
public Integer groupNo;
/** 组内退货行。 */
@JsonProperty("returnLines")
public List<GroupReturnLine> returnLines;
/** 面单列表。 */
@JsonProperty("labels")
public List<Label> labels;
/** 是否预期退回商品。 */
@JsonProperty("returnExpectedFlag")
public Boolean returnExpectedFlag;
}
/** 组内退货行:这里只有行号,明细在 {@code returnOrderLines}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class GroupReturnLine {
/** 退货行号。 */
@JsonProperty("returnOrderLineNumber")
public Integer returnOrderLineNumber;
}
/** 退货面单。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Label {
/** 面单图片 URL。 */
@JsonProperty("labelImageURL")
public String labelImageURL;
/** 承运商信息列表。 */
@JsonProperty("carrierInfoList")
public List<CarrierInfo> carrierInfoList;
}
/** 退货承运商信息。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CarrierInfo {
/** 承运商 ID。 */
@JsonProperty("carrierId")
public String carrierId;
/** 承运商名称,如 {@code FEDEX}。 */
@JsonProperty("carrierName")
public String carrierName;
/** 服务类型,如 {@code FedEx Ground}。 */
@JsonProperty("serviceType")
public String serviceType;
/** 退货物流跟踪号。 */
@JsonProperty("trackingNo")
public String trackingNo;
}
/** 退货行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ReturnOrderLine {
/** 退货行号;售后单拆分的唯一锚点。 */
@JsonProperty("returnOrderLineNumber")
public Integer returnOrderLineNumber;
/** 原销售订单行号。 */
@JsonProperty("salesOrderLineNumber")
public Integer salesOrderLineNumber;
/** 退货原因,如 {@code ARRIVED_LATE}。 */
@JsonProperty("returnReason")
public String returnReason;
/** 原沃尔玛订单号。 */
@JsonProperty("purchaseOrderId")
public String purchaseOrderId;
/** 卖家订单号。 */
@JsonProperty("sellerOrderId")
public String sellerOrderId;
/** 原订单行号。 */
@JsonProperty("purchaseOrderLineNumber")
public Integer purchaseOrderLineNumber;
/** 商品。 */
@JsonProperty("item")
public Item item;
/** 退货数量;{@code measurementValue} 是数字。 */
@JsonProperty("quantity")
public Measure quantity;
/** 单价。 */
@JsonProperty("unitPrice")
public CurrencyAmount unitPrice;
/** 费用明细。 */
@JsonProperty("charges")
public List<Charge> charges;
/** 行金额汇总({@code name} + {@code value})。 */
@JsonProperty("chargeTotals")
public List<ChargeTotal> chargeTotals;
/** 当前物流状态。 */
@JsonProperty("currentDeliveryStatus")
public String currentDeliveryStatus;
/** 当前退款状态。 */
@JsonProperty("currentRefundStatus")
public String currentRefundStatus;
/** 退款渠道。 */
@JsonProperty("refundChannel")
public String refundChannel;
/** 退款渠道明细。 */
@JsonProperty("refundChannels")
public List<RefundChannel> refundChannels;
/** 已退数量。 */
@JsonProperty("refundedQty")
public BigDecimal refundedQty;
/** 可取消数量。 */
@JsonProperty("cancellableQty")
public BigDecimal cancellableQty;
/** 可再次扣费数量。 */
@JsonProperty("rechargeableQty")
public BigDecimal rechargeableQty;
/** 是否预期退回。 */
@JsonProperty("returnExpectedFlag")
public Boolean returnExpectedFlag;
/** 是否「keep it」售后(客户留货、无需寄回)。 */
@JsonProperty("isKeepIt")
public Boolean isKeepIt;
/** 是否快速换货。 */
@JsonProperty("isFastReplacement")
public Boolean isFastReplacement;
/** 是否该订单最后一个商品。 */
@JsonProperty("lastItem")
public Boolean lastItem;
/** 退货行状态:{@code COMPLETED} / {@code INITIATED} 等。 */
@JsonProperty("status")
public String status;
/** 状态时间,ISO-8601。 */
@JsonProperty("statusTime")
public String statusTime;
}
/** 退货行商品。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Item {
/** 卖家 SKU。 */
@JsonProperty("sku")
public String sku;
/** 商品名称。 */
@JsonProperty("productName")
public String productName;
/** 商品重量;{@code unitOfMeasure} + {@code measurementValue}。 */
@JsonProperty("itemWeight")
public Measure itemWeight;
}
/** 数量 / 重量:{@code {"unitOfMeasure","measurementValue"}};值与订单接口不同。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Measure {
/** 计量单位,如 {@code EACH}、{@code POUND}。 */
@JsonProperty("unitOfMeasure")
public String unitOfMeasure;
/** 数值;退货接口是数字,不是字符串。 */
@JsonProperty("measurementValue")
public BigDecimal measurementValue;
}
/** 退货行费用明细。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Charge {
/** 费用类别,如 {@code PRODUCT}。 */
@JsonProperty("chargeCategory")
public String chargeCategory;
/** 费用名称,如 {@code ItemPrice}。 */
@JsonProperty("chargeName")
public String chargeName;
/** 单价金额。 */
@JsonProperty("chargePerUnit")
public CurrencyAmount chargePerUnit;
/** 是否折扣。 */
@JsonProperty("isDiscount")
public Boolean isDiscount;
/** 是否计费。 */
@JsonProperty("isBillable")
public Boolean isBillable;
}
/** 行金额汇总项;{@code name} 如 {@code lineTotal}、{@code lineProductTaxes}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ChargeTotal {
/** 汇总项名称。 */
@JsonProperty("name")
public String name;
/** 金额;结构随接口版本变化,按数字接,解析失败由映射层兜底。 */
@JsonProperty("value")
public BigDecimal value;
}
/** 退款渠道明细。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class RefundChannel {
/** 退款渠道名,如 {@code SELLER_MANUAL_REFUND}、{@code InstantRefund}。 */
@JsonProperty("refundChannelName")
public String refundChannelName;
/** 数量。 */
@JsonProperty("quantity")
public BigDecimal quantity;
}
}

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

@ -0,0 +1,134 @@ @@ -0,0 +1,134 @@
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;
}
}

33
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartTokenDtos.java

@ -0,0 +1,33 @@ @@ -0,0 +1,33 @@
package common.ecommerce.walmart.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 沃尔玛报文结构:获取令牌({@code POST /v3/token})。
*
* <p>请求体是 form-urlencoded(只有 {@code grant_type}),不需要在这里建模;
* 这里只描述响应。</p>
*/
public final class WalmartTokenDtos {
private WalmartTokenDtos() {
}
/** 令牌响应;{@code access_token} 是 JWT,实测约 841 字符。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TokenResponse {
/** 访问令牌。 */
@JsonProperty("access_token")
public String accessToken;
/** 令牌类型,固定 {@code Bearer}。 */
@JsonProperty("token_type")
public String tokenType;
/** 有效期,单位秒,实测固定 900(15 分钟)。 */
@JsonProperty("expires_in")
public Integer expiresIn;
}
}

138
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartOrderStatus.java

@ -0,0 +1,138 @@ @@ -0,0 +1,138 @@
package common.ecommerce.walmart.enums;
/**
* 沃尔玛订单 / 订单行状态。
*
* <p>沃尔玛<b>没有订单级状态字段</b>:文档 §4.1 的 {@code status} 只出现在
* {@code orderLineStatuses.orderLineStatus[]} 上。适配器必须自己聚合出订单级状态,
* 见 {@link #aggregate(Iterable)}。</p>
*
* <p>聚合规则(写死,不猜):</p>
* <ul>
* <li>所有行都 {@code Cancelled} → {@link #CANCELLED}</li>
* <li>所有行都 {@code Delivered} → {@link #DELIVERED}</li>
* <li>所有行都已终结({@code Shipped} / {@code Delivered} / {@code Cancelled} 混合)
* 且至少有一行发过货 → {@link #SHIPPED}</li>
* <li>还有 {@code Created} 行(部分发货时也会命中这一条)→ {@link #CREATED}:
* 仍有未发货的行,调用方要发货;逐行差异看 {@code OrderLine.status()}</li>
* <li>有 {@code Acknowledged} 且无 {@code Created} → {@link #ACKNOWLEDGED}</li>
* <li>识别不了 → {@link #UNKNOWN},原值保留在行上</li>
* </ul>
*
* <p>「部分发货」不单独表达:统一模型的状态是字符串原值,没有 PARTIALLY_SHIPPED 这个平台值,
* 凭空造一个会让下游按平台原值匹配的地方全部失效。需要精确判断时逐行读状态。</p>
*/
public enum WalmartOrderStatus {
/** 新订单,待处理 / 待发货。 */
CREATED("Created"),
/** 已确认,待发货。 */
ACKNOWLEDGED("Acknowledged"),
/** 已发货。 */
SHIPPED("Shipped"),
/** 已送达。 */
DELIVERED("Delivered"),
/** 已取消。 */
CANCELLED("Cancelled"),
/** 无法识别。 */
UNKNOWN(null);
/** 平台原始值;{@link #UNKNOWN} 为 null。 */
private final String raw;
WalmartOrderStatus(String raw) {
this.raw = raw;
}
/** 平台原始状态值;{@link #UNKNOWN} 返回 null。 */
public String raw() {
return raw;
}
/**
* 精确匹配平台原值;不做 {@code contains} 或大小写模糊匹配
* ({@code Cancelled} 里含 {@code Cancel},模糊匹配容易把取消的单判成别的)。
*
* @param raw 平台原值,可空
* @return 对应枚举;无法识别或空返回 {@link #UNKNOWN}
*/
public static WalmartOrderStatus fromRaw(String raw) {
if (raw == null) {
return UNKNOWN;
}
for (WalmartOrderStatus s : values()) {
if (s.raw != null && s.raw.equals(raw)) {
return s;
}
}
return UNKNOWN;
}
/**
* 按订单行状态聚合出订单级状态。
*
* @param lineStatuses 各行状态原值(可含 null)
* @return 聚合后的订单状态;没有任何可识别状态时返回 {@link #UNKNOWN}
*/
public static WalmartOrderStatus aggregate(Iterable<String> lineStatuses) {
if (lineStatuses == null) {
return UNKNOWN;
}
int total = 0;
int created = 0;
int acknowledged = 0;
int shipped = 0;
int delivered = 0;
int cancelled = 0;
int recognized = 0;
for (String raw : lineStatuses) {
total++;
WalmartOrderStatus s = fromRaw(raw);
switch (s) {
case CREATED:
created++;
recognized++;
break;
case ACKNOWLEDGED:
acknowledged++;
recognized++;
break;
case SHIPPED:
shipped++;
recognized++;
break;
case DELIVERED:
delivered++;
recognized++;
break;
case CANCELLED:
cancelled++;
recognized++;
break;
default:
break;
}
}
if (total == 0 || recognized == 0) {
return UNKNOWN;
}
if (cancelled == total) {
return CANCELLED;
}
if (delivered == total) {
return DELIVERED;
}
if (shipped + delivered + cancelled == total && shipped + delivered > 0) {
// 全部行都已终结:已发货 / 已送达 / 已取消混合时以「已发货」表达,
// 逐行差异看 OrderLine.status(),不做进一步细分以免猜错
return SHIPPED;
}
if (created > 0) {
return CREATED;
}
if (acknowledged > 0) {
return ACKNOWLEDGED;
}
return UNKNOWN;
}
}

103
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartPublishedStatus.java

@ -0,0 +1,103 @@ @@ -0,0 +1,103 @@
package common.ecommerce.walmart.enums;
import common.ecommerce.channel.model.product.ProductStatus;
/**
* 沃尔玛商品状态:{@code publishedStatus} + {@code lifecycleStatus} 的组合。
*
* <p>沃尔玛没有单一的「商品状态」字段,要两个维度一起看:</p>
* <ul>
* <li>{@code publishedStatus}:是否发布了,未发布时原因在 {@code unpublishedReasons}</li>
* <li>{@code lifecycleStatus}:是否还在生命周期内(归档 / 停售后不再销售)</li>
* </ul>
*
* <p>映射到统一 {@link ProductStatus} 的规则:</p>
* <table>
* <tr><th>published</th><th>lifecycle</th><th>ProductStatus</th></tr>
* <tr><td>PUBLISHED</td><td>ACTIVE</td><td>ACTIVE</td></tr>
* <tr><td>PUBLISHED</td><td>ARCHIVED / RETIRED</td><td>INACTIVE</td></tr>
* <tr><td>UNPUBLISHED / STAGE / IN_PROGRESS / SYSTEM_PROBLEM</td><td>任意</td><td>INACTIVE</td></tr>
* <tr><td>其它</td><td>任意</td><td>UNKNOWN</td></tr>
* </table>
*
* <p>统一模型没有「已删除」语义:沃尔玛也不提供删除接口,归档沿用 {@code INACTIVE}。</p>
*/
public enum WalmartPublishedStatus {
/** 已发布,前台可售。 */
PUBLISHED("PUBLISHED"),
/** 未发布,具体原因见 {@code unpublishedReasons}。 */
UNPUBLISHED("UNPUBLISHED"),
/** 沃尔玛系统侧异常导致未能正常发布。 */
SYSTEM_PROBLEM("SYSTEM_PROBLEM"),
/** 发布处理中。 */
IN_PROGRESS("IN_PROGRESS"),
/** 暂存 / 待发布。 */
STAGE("STAGE"),
/** 无法识别。 */
UNKNOWN(null);
/** 平台原始值;{@link #UNKNOWN} 为 null。 */
private final String raw;
WalmartPublishedStatus(String raw) {
this.raw = raw;
}
/** 平台原始值;{@link #UNKNOWN} 返回 null。 */
public String raw() {
return raw;
}
/** 精确匹配平台原值。 */
public static WalmartPublishedStatus fromRaw(String raw) {
if (raw == null) {
return UNKNOWN;
}
for (WalmartPublishedStatus s : values()) {
if (s.raw != null && s.raw.equals(raw)) {
return s;
}
}
return UNKNOWN;
}
/** 生命周期是否表示「不再销售」。 */
static boolean isRetiredLifecycle(String lifecycleStatus) {
return "ARCHIVED".equals(lifecycleStatus) || "RETIRED".equals(lifecycleStatus);
}
/**
* 把两个维度归一成统一状态。
*
* @param publishedStatus 平台 {@code publishedStatus}
* @param lifecycleStatus 平台 {@code lifecycleStatus}
* @return 统一商品状态,不会为 null
*/
public static ProductStatus toProductStatus(String publishedStatus, String lifecycleStatus) {
WalmartPublishedStatus published = fromRaw(publishedStatus);
switch (published) {
case PUBLISHED:
return isRetiredLifecycle(lifecycleStatus) ? ProductStatus.INACTIVE : ProductStatus.ACTIVE;
case UNPUBLISHED:
case STAGE:
case IN_PROGRESS:
case SYSTEM_PROBLEM:
return ProductStatus.INACTIVE;
default:
return ProductStatus.UNKNOWN;
}
}
/**
* 拼一个稳定的原始状态串,供 {@code ProductListing.rawStatus()} 使用,
* 例如 {@code "UNPUBLISHED/ACTIVE"}。
*
* @param publishedStatus 平台 {@code publishedStatus}
* @param lifecycleStatus 平台 {@code lifecycleStatus}
*/
public static String rawStatus(String publishedStatus, String lifecycleStatus) {
return (publishedStatus == null ? "UNKNOWN" : publishedStatus)
+ "/" + (lifecycleStatus == null ? "UNKNOWN" : lifecycleStatus);
}
}

60
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartReturnType.java

@ -0,0 +1,60 @@ @@ -0,0 +1,60 @@
package common.ecommerce.walmart.enums;
import common.ecommerce.channel.model.aftersale.AfterSaleType;
/**
* 沃尔玛退货类型 {@code returnType} → 统一 {@link AfterSaleType}。
*
* <p>沃尔玛只有两种:{@link #RETURN}(退货退款)和 {@link #REPLACEMENT}(换货)。
* 换货在统一模型里叫 {@link AfterSaleType#EXCHANGE}。</p>
*
* <p>注意 {@code REPLACEMENT} 也会出现在 {@code refundMode} 等其它字段的枚举里,
* 这里只用于 {@code returnType}。</p>
*/
public enum WalmartReturnType {
/** 退货(退款)。 */
RETURN("RETURN", AfterSaleType.RETURN),
/** 换货 / 补发。 */
REPLACEMENT("REPLACEMENT", AfterSaleType.EXCHANGE),
/** 无法识别。 */
UNKNOWN(null, AfterSaleType.UNKNOWN);
/** 平台原始值。 */
private final String raw;
/** 统一类型。 */
private final AfterSaleType core;
WalmartReturnType(String raw, AfterSaleType core) {
this.raw = raw;
this.core = core;
}
/** 平台原始值;{@link #UNKNOWN} 返回 null。 */
public String raw() {
return raw;
}
/** 统一售后类型。 */
public AfterSaleType toCore() {
return core;
}
/** 精确匹配平台原值;空或无法识别返回 {@link #UNKNOWN}。 */
public static WalmartReturnType fromRaw(String raw) {
if (raw == null) {
return UNKNOWN;
}
for (WalmartReturnType t : values()) {
if (t.raw != null && t.raw.equals(raw)) {
return t;
}
}
return UNKNOWN;
}
/** 便捷方法:直接取统一类型。 */
public static AfterSaleType toCore(String raw) {
return fromRaw(raw).toCore();
}
}

165
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartErrors.java

@ -0,0 +1,165 @@ @@ -0,0 +1,165 @@
package common.ecommerce.walmart.http;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.error.AuthException;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.error.RateLimitException;
import common.ecommerce.shared.error.TransientException;
import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.walmart.WalmartConstants;
import com.fasterxml.jackson.databind.JsonNode;
/**
* 沃尔玛错误解析。
*
* <p>沙箱观察到两种错误格式,必须都认:</p>
* <ol>
* <li><b>业务网关错误</b>:{@code {"error":[{"code":"CONTENT_NOT_FOUND.GMP_GATEWAY_API",
* "description":"...","info":"...","severity":"INFO","category":"APPLICATION"}]}}</li>
* <li><b>路由级错误</b>:{@code {"timestamp":"...","status":404,"error":"Request Not Found...","path":"..."}}</li>
* </ol>
*
* <p>不用 {@code Responses.throwIfNotSuccess}:它只看状态码,拿不到 body 里的
* {@code code} / {@code description},排障时只能看到 {@code http 400 on xxx}。</p>
*/
public final class WalmartErrors {
private final JacksonJsonCodec json;
public WalmartErrors(JacksonJsonCodec json) {
this.json = json;
}
/**
* 非 2xx 时抛对应异常,2xx 直接返回。
*
* <p>分类:</p>
* <ul>
* <li>401 / 403 → {@link AuthException}(调用方刷新后重试一次)</li>
* <li>429 → {@link RateLimitException},遵守 {@code Retry-After}</li>
* <li>5xx → {@link TransientException},{@code retryable=true}</li>
* <li>其它 4xx → {@link ValidationException},不重试</li>
* </ul>
*
* <p>沃尔玛业务错误码里的 {@code SYSTEM_ERROR.GMP_*} 也按可重试处理,
* 即便 HTTP 是 4xx——这类是平台侧数据状态问题,原样重跑常能成功。</p>
*/
public void throwIfError(HttpResponse response, ChannelContext ctx, String operation) {
if (response.isSuccess()) {
return;
}
String code = null;
String description = null;
String severity = null;
JsonNode root = parse(response.body());
if (root != null) {
JsonNode errors = root.get("error");
if (errors != null && errors.isArray() && errors.size() > 0) {
JsonNode first = errors.get(0);
code = text(first, "code");
description = text(first, "description");
severity = text(first, "severity");
String info = text(first, "info");
if (description == null) {
description = info;
}
} else {
// 格式二:路由级错误,没有 error 数组
description = text(root, "error");
}
}
ChannelException.Builder b = ChannelException.builder()
.message(buildMessage(response, operation, code, description, severity))
.operation(operation)
.platform(ctx.platform())
.provider(ctx.providerName())
.omsStoreId(ctx.omsStoreId())
.requestId(ctx.requestId())
.platformCode(code != null ? code : String.valueOf(response.statusCode()))
.rawResponse(truncate(response.body()));
int status = response.statusCode();
if (response.isAuthFailure()) {
throw new AuthException(b);
}
if (response.isRateLimited()) {
throw new RateLimitException(b, parseRetryAfterMillis(response.header("Retry-After")));
}
if (response.isServerError()) {
throw new TransientException(b.retryable(true), null);
}
if (isSystemError(code)) {
throw new TransientException(b.retryable(true), null);
}
// 其余 4xx 一律按「数据/参数错误,重跑也不会成功」处理。
// 不猜 {@code INVALID_STATE} / {@code CONFLICT} 这类前缀:文档实测只给了
// CONTENT_NOT_FOUND.* 与 SYSTEM_ERROR.*,凭前缀分类会把可重试错误判成终态。
throw new ValidationException(b);
}
/** 沃尔玛的 {@code SYSTEM_ERROR.*} 是平台侧问题,可重试。 */
static boolean isSystemError(String code) {
return code != null && code.startsWith("SYSTEM_ERROR");
}
/** 拼接一条既能定位又能看懂的异常消息。 */
private static String buildMessage(HttpResponse response, String operation,
String code, String description, String severity) {
StringBuilder sb = new StringBuilder("walmart http ").append(response.statusCode())
.append(" on ").append(operation);
if (code != null) {
sb.append(" [").append(code).append(']');
}
if (description != null) {
sb.append(": ").append(description);
}
if (severity != null && !"ERROR".equalsIgnoreCase(severity)) {
sb.append(" (severity=").append(severity).append(')');
}
return sb.toString();
}
/** Retry-After 只支持秒数;解析失败给 1s 默认值,避免 0 导致无退避重试。 */
static long parseRetryAfterMillis(String raw) {
if (raw == null || raw.trim().isEmpty()) {
return 1_000L;
}
try {
return Math.max(0L, Long.parseLong(raw.trim()) * 1000L);
} catch (NumberFormatException e) {
return 1_000L;
}
}
/** 原始报文截断,避免整页 JSON 进日志/异常。 */
static String truncate(String body) {
if (body == null) {
return null;
}
return body.length() <= WalmartConstants.RAW_RESPONSE_LIMIT
? body : body.substring(0, WalmartConstants.RAW_RESPONSE_LIMIT);
}
private JsonNode parse(String body) {
if (body == null || body.trim().isEmpty()) {
return null;
}
try {
return json.mapper().readTree(body);
} catch (Exception e) {
return null;
}
}
private static String text(JsonNode node, String field) {
if (node == null) {
return null;
}
JsonNode value = node.get(field);
return value == null || value.isNull() ? null : value.asText();
}
}

130
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartRequestFactory.java

@ -0,0 +1,130 @@ @@ -0,0 +1,130 @@
package common.ecommerce.walmart.http;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.walmart.WalmartConstants;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* 构造沃尔玛请求:公共头 + 令牌头 + 链路 ID。
*
* <p>沃尔玛不需要签名,鉴权只靠 {@code WM_SEC.ACCESS_TOKEN} 头;
* 业务接口<b>不再</b>带 Basic Auth(沙箱实测确认)。</p>
*
* <p>query 参数按插入顺序拼接,null 值跳过;游标类参数由调用方决定是否编码,
* 因为退货接口的 {@code nextCursor} 本身就是一段带 {@code ?} 的查询串。</p>
*/
public final class WalmartRequestFactory {
/** 无状态;请求体序列化由各 DTO 与 JacksonJsonCodec 承担,本类只管 URL 与请求头。 */
public WalmartRequestFactory() {
}
/** GET 业务请求;{@code query} 为 null 或空时不拼 {@code ?}。 */
public HttpRequest get(String baseUrl, String path, Map<String, Object> query,
AccessToken token, ChannelContext ctx, String operation) {
return HttpRequest.builder()
.method("GET")
.url(baseUrl + path + queryString(query))
.header(WalmartConstants.HEADER_SVC_NAME, WalmartConstants.SVC_NAME_VALUE)
.header(WalmartConstants.HEADER_CORRELATION_ID, ctx.requestId())
.header(WalmartConstants.HEADER_ACCESS_TOKEN, token.value())
.header("Accept", WalmartConstants.CONTENT_TYPE_JSON)
.operation(operation)
.build();
}
/**
* 用一段<b>已拼好的查询串</b>发 GET。
*
* <p>退货列表的 {@code meta.nextCursor} 形如 {@code ?sellerId=151&limit=10&offset=10},
* 翻页时整串拼到路径后面,不能再做 URL 编码,也不能重复加 {@code ?}。</p>
*
* @param rawQuery 查询串,可带或不带开头的 {@code ?};null / 空表示无。
* 以 {@code &} 开头的串会被归一成 {@code ?} + 余下部分——
* 直接拼 {@code path + "&k=v"} 会生成没有 {@code ?} 的非法 URL。
*/
public HttpRequest getWithRawQuery(String baseUrl, String path, String rawQuery,
AccessToken token, ChannelContext ctx, String operation) {
String query = normalizeRawQuery(rawQuery);
return HttpRequest.builder()
.method("GET")
.url(baseUrl + path + (query == null ? "" : query))
.header(WalmartConstants.HEADER_SVC_NAME, WalmartConstants.SVC_NAME_VALUE)
.header(WalmartConstants.HEADER_CORRELATION_ID, ctx.requestId())
.header(WalmartConstants.HEADER_ACCESS_TOKEN, token.value())
.header("Accept", WalmartConstants.CONTENT_TYPE_JSON)
.operation(operation)
.build();
}
/**
* 归一原始查询串:空串 → null;不以 {@code ?} 开头时补上;开头的 {@code &} 去掉。
*
* @param rawQuery 平台的 {@code nextCursor} 或调用方拼的查询串
*/
static String normalizeRawQuery(String rawQuery) {
if (rawQuery == null) {
return null;
}
String query = rawQuery.trim();
if (query.isEmpty()) {
return null;
}
if (query.charAt(0) == '&') {
// "&a=1&b=2" → "?a=1&b=2"
return "?" + query.substring(1);
}
return query.charAt(0) == '?' ? query : "?" + query;
}
/** 把查询参数拼成 {@code ?k=v&k2=v2};空 Map 返回空串。 */
public static String queryString(Map<String, Object> query) {
if (query == null || query.isEmpty()) {
return "";
}
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, Object> e : query.entrySet()) {
if (e.getValue() == null) {
continue;
}
sb.append(sb.length() == 0 ? '?' : '&')
.append(urlEncode(e.getKey()))
.append('=')
.append(urlEncode(String.valueOf(e.getValue())));
}
return sb.toString();
}
/** 新建有序 query 容器;便于测试断言参数顺序。 */
public static Map<String, Object> query() {
return new LinkedHashMap<String, Object>();
}
/** UTF-8 URL 编码;{@link URLEncoder} 把空格编成 {@code +},对 query 而言是合法的。 */
public static String urlEncode(String value) {
if (value == null) {
return "";
}
try {
return URLEncoder.encode(value, "UTF-8");
} catch (UnsupportedEncodingException e) {
// UTF-8 一定存在
throw new IllegalStateException("UTF-8 not supported", e);
}
}
/** 路径段编码:{@link #urlEncode(String)} 但把 {@code +} 还原成 {@code %20}。
*
* <p>路径里的 {@code +} 是字面量加号,不是空格;SKU / 订单号里带空格时
* 用 query 编码会拼出错误的路径。</p>
*/
public static String pathSegment(String value) {
return urlEncode(value).replace("+", "%20");
}
}

422
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartOrderMapper.java

@ -0,0 +1,422 @@ @@ -0,0 +1,422 @@
package common.ecommerce.walmart.mapper;
import common.ecommerce.channel.model.order.OrderLine;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.ShipToAddress;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.PlatformTime;
import common.ecommerce.walmart.dto.WalmartOrderDtos;
import java.math.BigDecimal;
import java.time.Instant;
import java.time.ZoneId;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 沃尔玛订单 → 统一 {@link SalesOrder}。
*
* <p>只做字段搬运与必要的单位/格式转换,不做业务判断:</p>
* <ul>
* <li>时间:订单接口是 epoch 毫秒,统一转 {@link PlatformTime}</li>
* <li>数量:{@code orderLineQuantity.amount} 是字符串,解析失败记 0 而不是抛异常,
* 避免一行脏数据卡住整页同步</li>
* <li>单价:沃尔玛的 {@code ItemPrice.chargeAmount} 是<b>整行金额</b>,
* 必须除以行数量才是 {@link OrderLine#unitPrice()};数量为 0 时无法拆分,
* 保留整行金额(此时它等于单价,因为只有 1 件)</li>
* <li>行税额:取该行所有 charge 上 {@code tax.taxAmount} 的合计</li>
* <li>订单总额:按行合计(商品金额 + 税),币种取第一个非空币种</li>
* </ul>
*/
public final class WalmartOrderMapper {
private WalmartOrderMapper() {
}
/**
* 映射一个订单。
*
* <p><b>不完整的订单返回 null</b>,由调用方跳过并记一条 WARN:
* {@code purchaseOrderId} 与 {@code orderDate} 在统一模型里是必填
* (前者进 canonicalKey,后者进 {@code occurredAt}),平台漏给时硬造一个值
* 会把脏数据写进主键。宁可少一条,也不能写错一条。</p>
*
* @param dto 平台订单
* @param omsStoreId 宿主店铺 ID
* @param marketplaceZone 市场时区,用于 {@link PlatformTime}
* @return 统一订单;{@code dto} 为 null、缺订单号或缺下单时间时返回 null
*/
public static SalesOrder toSalesOrder(WalmartOrderDtos.Order dto, String omsStoreId,
ZoneId marketplaceZone) {
if (dto == null || isBlank(dto.purchaseOrderId) || dto.orderDate == null) {
return null;
}
List<OrderLine> lines = toOrderLines(dto);
return SalesOrder.builder()
.omsStoreId(omsStoreId)
.channelOrderId(dto.purchaseOrderId)
.status(statusOf(dto))
.buyerName(dto.shippingInfo == null || dto.shippingInfo.postalAddress == null
? null : dto.shippingInfo.postalAddress.name)
.buyerEmail(dto.customerEmailId)
.shipToCountryCode(countryCodeOf(dto))
.shipToAddress(toShipToAddress(dto))
.lines(lines)
.totalAmount(totalOf(dto))
.occurredAt(toPlatformTime(dto.orderDate, marketplaceZone))
.sourceProvider(ChannelProvider.DIRECT)
.sourceAccountId(null)
.build();
}
/** 平台必填字段缺失时的判定;只 trim,不做其它归一。 */
private static boolean isBlank(String value) {
return value == null || value.trim().isEmpty();
}
/**
* 订单级状态:沃尔玛没有这个字段,按行状态聚合。
*
* <p>一行的 {@code orderLineStatus[]} 不是纯历史:部分发货时
* {@code Created(3)} 与 {@code Shipped(1)} 会同时存在,数量各不相同。所以先按数量
* 把每行<b>归一</b>成一个当前状态(见 {@link #resolveLineStatus}),再交给
* {@link common.ecommerce.walmart.enums.WalmartOrderStatus#aggregate}。</p>
*
* @see common.ecommerce.walmart.enums.WalmartOrderStatus#aggregate(Iterable)
*/
static String statusOf(WalmartOrderDtos.Order dto) {
if (dto.orderLines == null || dto.orderLines.orderLine == null) {
return null;
}
List<String> statuses = new ArrayList<String>();
for (WalmartOrderDtos.OrderLine line : dto.orderLines.orderLine) {
if (line == null) {
continue;
}
String resolved = resolveLineStatus(line);
if (resolved != null) {
statuses.add(resolved);
}
}
return common.ecommerce.walmart.enums.WalmartOrderStatus.aggregate(statuses).raw();
}
/**
* 按订单行数量把行状态归一成一个「当前」状态。
*
* <p>规则(数量缺失时退化为「取状态列表最后一条」):</p>
* <ol>
* <li>取消数量 ≥ 订量 → {@code Cancelled}</li>
* <li>发货数量({@code Shipped} + {@code Delivered})≥ 订量 - 取消数量:
* 全部 {@code Delivered} 时给 {@code Delivered},否则 {@code Shipped}</li>
* <li>还有没发的余量 → {@code Created}(订单层面仍需发货动作)</li>
* <li>什么都不匹配 → 状态列表最后一条的原值</li>
* </ol>
*
* <p>{@code OrderLine.status()} 保留的是<b>平台原值</b>(状态列表最后一条),
* 需要判断「这一行还差多少没发」时以 {@link #resolveLineStatus} 的结果为准。</p>
*/
static String resolveLineStatus(WalmartOrderDtos.OrderLine line) {
int ordered = parseQuantity(line.orderLineQuantity);
if (ordered <= 0 || line.orderLineStatuses == null
|| line.orderLineStatuses.orderLineStatus == null) {
return currentLineStatus(line);
}
int shipped = 0;
int delivered = 0;
int cancelled = 0;
boolean anyQuantity = false;
for (WalmartOrderDtos.OrderLineStatus s : line.orderLineStatuses.orderLineStatus) {
if (s == null || s.status == null) {
continue;
}
int qty = parseQuantity(s.statusQuantity);
if (qty > 0) {
anyQuantity = true;
}
if ("Shipped".equals(s.status)) {
shipped += qty;
} else if ("Delivered".equals(s.status)) {
delivered += qty;
} else if ("Cancelled".equals(s.status)) {
cancelled += qty;
}
}
if (!anyQuantity) {
return currentLineStatus(line);
}
if (cancelled >= ordered) {
return "Cancelled";
}
int fulfilled = shipped + delivered;
int expected = ordered - cancelled;
if (fulfilled >= expected) {
return delivered >= expected ? "Delivered" : "Shipped";
}
return "Created";
}
/** 收货地址;平台未返回地址时返回 null(全空对象不挂到订单上)。 */
static ShipToAddress toShipToAddress(WalmartOrderDtos.Order dto) {
if (dto.shippingInfo == null || dto.shippingInfo.postalAddress == null) {
return null;
}
WalmartOrderDtos.PostalAddress a = dto.shippingInfo.postalAddress;
ShipToAddress address = ShipToAddress.builder()
.name(a.name)
.address1(a.address1)
.address2(a.address2)
.city(a.city)
.state(a.state)
.postalCode(a.postalCode)
.countryCode(a.country)
.addressType(a.addressType)
.phone(dto.shippingInfo.phone)
.build();
return address.isEmpty() ? null : address;
}
/** 收货国家:优先地址里的国家;没有地址时返回 null。 */
static String countryCodeOf(WalmartOrderDtos.Order dto) {
return dto.shippingInfo == null || dto.shippingInfo.postalAddress == null
? null : dto.shippingInfo.postalAddress.country;
}
/**
* 订单总额:逐行商品金额 + 税合计;一行都算不出来时返回 null。
*
* <p><b>币种不一致时返回 null</b>:沃尔玛一个订单只有一个币种,
* 出现两个说明数据有问题;把不同币种直接相加会得到一个无意义的数。</p>
*/
static Money totalOf(WalmartOrderDtos.Order dto) {
if (dto.orderLines == null || dto.orderLines.orderLine == null) {
return null;
}
BigDecimal total = BigDecimal.ZERO;
String currency = null;
boolean any = false;
for (WalmartOrderDtos.OrderLine line : dto.orderLines.orderLine) {
if (line == null || line.charges == null || line.charges.charge == null) {
continue;
}
for (WalmartOrderDtos.Charge charge : line.charges.charge) {
if (charge == null || charge.chargeAmount == null || charge.chargeAmount.amount == null) {
continue;
}
if (charge.chargeAmount.currency == null) {
continue;
}
if (currency == null) {
currency = charge.chargeAmount.currency;
} else if (!currency.equals(charge.chargeAmount.currency)) {
// 同单多币种:数据异常,宁可不给总额,也不给一个加错的数
return null;
}
total = total.add(charge.chargeAmount.amount);
any = true;
if (charge.tax != null && charge.tax.taxAmount != null
&& charge.tax.taxAmount.amount != null) {
total = total.add(charge.tax.taxAmount.amount);
}
}
}
if (!any) {
return null;
}
try {
return Money.of(total, currency);
} catch (IllegalArgumentException e) {
// 平台给了非法币种代码:不阻断整页,按「金额不可用」处理
return null;
}
}
/** 订单行。 */
static List<OrderLine> toOrderLines(WalmartOrderDtos.Order dto) {
if (dto.orderLines == null || dto.orderLines.orderLine == null) {
return Collections.emptyList();
}
List<OrderLine> out = new ArrayList<OrderLine>(dto.orderLines.orderLine.size());
for (WalmartOrderDtos.OrderLine line : dto.orderLines.orderLine) {
if (line == null) {
continue;
}
int quantity = parseQuantity(line.orderLineQuantity);
out.add(OrderLine.builder()
.lineId(line.lineNumber)
.platformSku(line.item == null || line.item.sku == null ? "" : line.item.sku)
.quantity(quantity)
.lineAmount(lineAmountOf(line))
.unitPrice(unitPriceOf(line, quantity))
.tax(taxOf(line))
.status(currentLineStatus(line))
.build());
}
return out;
}
/** 行当前状态:取状态列表里最后一条。 */
static String currentLineStatus(WalmartOrderDtos.OrderLine line) {
if (line.orderLineStatuses == null || line.orderLineStatuses.orderLineStatus == null
|| line.orderLineStatuses.orderLineStatus.isEmpty()) {
return null;
}
List<WalmartOrderDtos.OrderLineStatus> list = line.orderLineStatuses.orderLineStatus;
for (int i = list.size() - 1; i >= 0; i--) {
WalmartOrderDtos.OrderLineStatus s = list.get(i);
if (s != null && s.status != null) {
return s.status;
}
}
return null;
}
/**
* 行<b>金额</b>:{@code ItemPrice.chargeAmount} 原值,不做任何除法。
*
* <p>这是金额的权威来源;{@link #unitPriceOf} 由它派生,除不尽时会给 null。</p>
*/
static Money lineAmountOf(WalmartOrderDtos.OrderLine line) {
BigDecimal amount = itemPriceTotalOf(line);
String currency = itemPriceCurrencyOf(line);
if (amount == null || currency == null) {
return null;
}
try {
return Money.of(amount, currency);
} catch (IllegalArgumentException e) {
return null;
}
}
/**
* 商品<b>单价</b>:由行金额除以数量得到,<b>除不尽时为 null</b>。
*
* <p>示例:2 件共 99.98 → 单价 49.99,可精确表示;3 件共 100.00 → 33.3333…,
* 除不尽,返回 null——用 33.3333 会让人误以为 {@code ×3} 等于原金额,
* 实际差 0.0001。需要行金额时用 {@link OrderLine#lineAmount()}。</p>
*
* <p>数量缺失或为 0 时不拆:只有 1 件(或数量未知)时行金额即单价。</p>
*/
static Money unitPriceOf(WalmartOrderDtos.OrderLine line, int quantity) {
Money amount = lineAmountOf(line);
if (amount == null) {
return null;
}
if (quantity <= 1) {
return amount;
}
BigDecimal divisor = BigDecimal.valueOf(quantity);
// 先按 4 位小数试除,再回乘校验:只有 unitPrice × quantity 精确等于行金额才认可
BigDecimal unit = amount.amount().divide(divisor, 4, java.math.RoundingMode.HALF_UP);
if (unit.multiply(divisor).compareTo(amount.amount()) != 0) {
// 除不尽:不四舍五入倒推,避免单价 × 数量 ≠ 行金额
return null;
}
return Money.of(unit.stripTrailingZeros(), amount.currencyCode());
}
/** {@code ItemPrice} 的整行金额;没有则该行第一条带金额的 charge。 */
static BigDecimal itemPriceTotalOf(WalmartOrderDtos.OrderLine line) {
WalmartOrderDtos.Charge charge = itemPriceChargeOf(line);
return charge == null || charge.chargeAmount == null ? null : charge.chargeAmount.amount;
}
/** 与 {@link #itemPriceTotalOf} 同一条 charge 上的币种。 */
static String itemPriceCurrencyOf(WalmartOrderDtos.OrderLine line) {
WalmartOrderDtos.Charge charge = itemPriceChargeOf(line);
return charge == null || charge.chargeAmount == null ? null : charge.chargeAmount.currency;
}
/**
* 行金额对应的 charge:优先 {@code ItemPrice},其次<b>同类型商品费</b>。
*
* <p><b>不把运费 / 手续费当商品价</b>:只有 {@code chargeType=PRODUCT} 的 charge
* 才能退而求其次;一条商品费都没有时返回 null,让单价保持 null,
* 而不是把 {@code Shipping} 的金额除以数量冒充单价。</p>
*/
static WalmartOrderDtos.Charge itemPriceChargeOf(WalmartOrderDtos.OrderLine line) {
if (line.charges == null || line.charges.charge == null) {
return null;
}
WalmartOrderDtos.Charge productFallback = null;
for (WalmartOrderDtos.Charge charge : line.charges.charge) {
if (charge == null || charge.chargeAmount == null || charge.chargeAmount.amount == null) {
continue;
}
if ("ItemPrice".equals(charge.chargeName)) {
return charge;
}
if (productFallback == null && "PRODUCT".equals(charge.chargeType)) {
productFallback = charge;
}
}
return productFallback;
}
/** 行税额:取所有 charge 上 tax 的合计;一条都没有时为 null。 */
static Money taxOf(WalmartOrderDtos.OrderLine line) {
if (line.charges == null || line.charges.charge == null) {
return null;
}
BigDecimal total = BigDecimal.ZERO;
String currency = null;
boolean any = false;
for (WalmartOrderDtos.Charge charge : line.charges.charge) {
if (charge == null || charge.tax == null || charge.tax.taxAmount == null
|| charge.tax.taxAmount.amount == null) {
continue;
}
total = total.add(charge.tax.taxAmount.amount);
if (currency == null) {
currency = charge.tax.taxAmount.currency;
}
any = true;
}
if (!any || currency == null) {
return null;
}
try {
return Money.of(total, currency);
} catch (IllegalArgumentException e) {
return null;
}
}
/**
* 数量解析:沃尔玛把数量放在字符串里({@code "1"}),也见过数字形式。
*
* <p>非法值记 0,与「0 表示平台未给」的约定一致,不因一行脏数据卡住整页。</p>
*/
static int parseQuantity(WalmartOrderDtos.Quantity quantity) {
if (quantity == null || quantity.amount == null || quantity.amount.trim().isEmpty()) {
return 0;
}
try {
return new BigDecimal(quantity.amount.trim()).intValue();
} catch (NumberFormatException e) {
return 0;
}
}
/** epoch 毫秒 → 三轴时间;null 时返回当前时钟(订单下单时间不该为空,兜底不抛)。 */
static PlatformTime toPlatformTime(Long epochMillis, ZoneId zone) {
if (epochMillis == null) {
return null;
}
return PlatformTime.of(Instant.ofEpochMilli(epochMillis.longValue()), zone);
}
private static Money money(WalmartOrderDtos.Amount amount) {
if (amount == null || amount.amount == null || amount.currency == null) {
return null;
}
try {
return Money.of(amount.amount, amount.currency);
} catch (IllegalArgumentException e) {
return null;
}
}
}

148
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartProductMapper.java

@ -0,0 +1,148 @@ @@ -0,0 +1,148 @@
package common.ecommerce.walmart.mapper;
import common.ecommerce.channel.model.product.ProductListing;
import common.ecommerce.channel.model.product.ProductStatus;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.support.Money;
import common.ecommerce.walmart.dto.WalmartItemDtos;
import common.ecommerce.walmart.enums.WalmartPublishedStatus;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 沃尔玛商品 → 统一 {@link ProductListing}。
*
* <p>字段对应:</p>
* <ul>
* <li>{@code platformSku} ← {@code sku},{@code listingId} ← {@code wpid}</li>
* <li>{@code gtin} ← {@code gtin},缺失回落 {@code upc}</li>
* <li>{@code status} ← {@code publishedStatus} + {@code lifecycleStatus} 组合,
* 见 {@link WalmartPublishedStatus}</li>
* <li>{@code rawStatus} ← {@code "UNPUBLISHED/ACTIVE"} 这样的组合串,便于排查</li>
* <li>{@code attributes} ← 未标准化的 {@code mart} / {@code shelf} / {@code productType} /
* {@code unpublishedReasons} / {@code upc}</li>
* </ul>
*
* <p>{@code shelf} 是 JSON 字符串数组,这里二次解析成 {@code List<String>};
* 解析失败时按原串放进 attributes,不让一行脏数据卡住整页。</p>
*/
public final class WalmartProductMapper {
/** 解析 {@code shelf} 用;只在解析字符串数组,不做路径查询。 */
private static final ObjectMapper SHELF_PARSER = new ObjectMapper();
private WalmartProductMapper() {
}
/**
* 映射一个商品。
*
* @param dto 平台商品
* @param omsStoreId 宿主店铺 ID
* @return 统一商品;{@code dto} 为 null 或缺少 SKU 时返回 null
*/
public static ProductListing toProductListing(WalmartItemDtos.ItemResponse dto, String omsStoreId) {
if (dto == null || dto.sku == null || dto.sku.trim().isEmpty()) {
// SKU 是 canonicalKey 的一部分,没有它就没有可落库的对象
return null;
}
ProductStatus status = WalmartPublishedStatus.toProductStatus(
dto.publishedStatus, dto.lifecycleStatus);
return ProductListing.builder()
.platform(Platform.WALMART_SC)
.omsStoreId(omsStoreId)
.platformSku(dto.sku)
.listingId(dto.wpid)
.gtin(dto.gtin != null ? dto.gtin : dto.upc)
.title(dto.productName)
.price(priceOf(dto))
.currency(dto.price == null ? null : dto.price.currency)
.status(status)
.rawStatus(WalmartPublishedStatus.rawStatus(dto.publishedStatus, dto.lifecycleStatus))
.attributes(attributesOf(dto))
.sourceProvider(ChannelProvider.DIRECT)
.build();
}
/** 价格;金额或币种缺失时为 null(不猜币种)。 */
static Money priceOf(WalmartItemDtos.ItemResponse dto) {
if (dto.price == null || dto.price.amount == null || dto.price.currency == null) {
return null;
}
try {
return Money.of(dto.price.amount, dto.price.currency);
} catch (IllegalArgumentException e) {
return null;
}
}
/**
* 未标准化字段。键名与沃尔玛一致,宿主可以直接读。
*
* <p>值为 null 的字段不放进 Map,避免上游拿到一堆 null 分不清「没有」和「空」。</p>
*/
static Map<String, Object> attributesOf(WalmartItemDtos.ItemResponse dto) {
Map<String, Object> attributes = new LinkedHashMap<String, Object>();
putIfNotNull(attributes, "mart", dto.mart);
putIfNotNull(attributes, "productType", dto.productType);
putIfNotNull(attributes, "upc", dto.upc);
putIfNotNull(attributes, "lifecycleStatus", dto.lifecycleStatus);
putIfNotNull(attributes, "publishedStatus", dto.publishedStatus);
if (dto.shelf != null) {
attributes.put("shelf", parseShelf(dto.shelf));
attributes.put("shelfRaw", dto.shelf);
}
if (dto.unpublishedReasons != null && dto.unpublishedReasons.reason != null
&& !dto.unpublishedReasons.reason.isEmpty()) {
attributes.put("unpublishedReasons",
new ArrayList<String>(dto.unpublishedReasons.reason));
}
return attributes;
}
/**
* 解析 {@code shelf}。
*
* @param raw 形如 {@code "[\"UNNAV\"]"} 的 JSON 字符串
* @return 解析成功返回字符串列表;不是合法 JSON 数组时返回只含原串的单元素列表
*/
static List<String> parseShelf(String raw) {
List<String> out = new ArrayList<String>();
if (raw == null) {
return out;
}
try {
JsonNode node = SHELF_PARSER.readTree(raw);
if (node != null && node.isArray()) {
for (JsonNode item : node) {
if (item != null && !item.isNull()) {
out.add(item.asText());
}
}
return out;
}
// 不是数组:可能是单个裸字符串(如 "UNNAV"),也照收
if (node != null && node.isTextual()) {
out.add(node.asText());
return out;
}
} catch (Exception e) {
// 落回原文,不阻断同步
}
out.add(raw);
return out;
}
private static void putIfNotNull(Map<String, Object> map, String key, Object value) {
if (value != null) {
map.put(key, value);
}
}
}

304
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartReturnMapper.java

@ -0,0 +1,304 @@ @@ -0,0 +1,304 @@
package common.ecommerce.walmart.mapper;
import common.ecommerce.channel.model.aftersale.AfterSale;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.PlatformTime;
import common.ecommerce.walmart.dto.WalmartReturnDtos;
import common.ecommerce.walmart.enums.WalmartReturnType;
import java.math.BigDecimal;
import java.time.Instant;
import java.time.ZoneId;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 沃尔玛退货单 → 统一 {@link AfterSale}(<b>按商品行展开</b>)。
*
* <p>沃尔玛一个 {@code returnOrder} 里带多个 {@code returnOrderLines},而统一模型
* 一行 = 一个售后商品行,所以这里是 1 → N 展开。</p>
*
* <p>{@code afterSaleId} 用 {@code returnOrderId:returnOrderLineNumber}:
* 两个字段都是平台侧稳定值,重复同步可幂等 upsert。</p>
*
* <p>退货行本身不带物流信息:承运商 / 跟踪号在
* {@code returnLineGroups[].labels[].carrierInfoList[]} 上,按
* {@code returnLineGroups[].returnLines[].returnOrderLineNumber} 关联到行。</p>
*/
public final class WalmartReturnMapper {
private WalmartReturnMapper() {
}
/**
* 把一个退货单展开成多个售后行。
*
* <p><b>{@code returnOrderId} 缺失时整单丢弃</b>:它进 {@code afterSaleId}
* (upsert 主键),漏了会拼出 {@code "null:1"} 这种键,脏数据会静默落库。
* 部分行缺行号仍可映射(行号退化为 0),因为单号还在。</p>
*
* @param dto 平台退货单
* @param omsStoreId 宿主店铺 ID
* @param marketplaceZone 市场时区
* @return 售后行列表;{@code dto} 为 null、缺退货单号、或没有退货行时返回空列表
*/
public static List<AfterSale> toAfterSales(WalmartReturnDtos.ReturnOrder dto, String omsStoreId,
ZoneId marketplaceZone) {
if (dto == null || isBlank(dto.returnOrderId)
|| dto.returnOrderLines == null || dto.returnOrderLines.isEmpty()) {
return Collections.emptyList();
}
Map<Integer, WalmartReturnDtos.CarrierInfo> carrierByLine = carrierIndex(dto);
Map<Integer, Boolean> expectedByLine = expectedIndex(dto);
List<AfterSale> out = new ArrayList<AfterSale>(dto.returnOrderLines.size());
for (WalmartReturnDtos.ReturnOrderLine line : dto.returnOrderLines) {
if (line == null) {
continue;
}
AfterSale afterSale = toAfterSale(dto, line, omsStoreId, marketplaceZone,
carrierByLine.get(line.returnOrderLineNumber),
expectedByLine.get(line.returnOrderLineNumber));
if (afterSale != null) {
out.add(afterSale);
}
}
return out;
}
/** 单行映射。 */
static AfterSale toAfterSale(WalmartReturnDtos.ReturnOrder dto, WalmartReturnDtos.ReturnOrderLine line,
String omsStoreId, ZoneId marketplaceZone,
WalmartReturnDtos.CarrierInfo carrier, Boolean returnExpected) {
return AfterSale.builder()
.platform(Platform.WALMART_SC)
.omsStoreId(omsStoreId)
.afterSaleId(afterSaleId(dto.returnOrderId, line.returnOrderLineNumber))
.channelOrderId(line.purchaseOrderId != null ? line.purchaseOrderId : dto.customerOrderId)
.type(WalmartReturnType.toCore(dto.returnType))
.rawType(dto.returnType)
.status(line.status)
.reason(line.returnReason)
.quantity(line.quantity == null || line.quantity.measurementValue == null
? 0 : line.quantity.measurementValue.intValue())
.platformSku(line.item == null ? null : line.item.sku)
.refundAmount(refundAmountOf(line))
.afterSaleTime(toPlatformTime(dto.returnOrderDate, marketplaceZone))
.updatedAt(toPlatformTime(line.statusTime, marketplaceZone))
.carrier(carrier == null ? null : carrier.carrierName)
.trackingNumber(carrier == null ? null : carrier.trackingNo)
.exchangeOrderId(dto.replacementCustomerOrderId)
.attributes(attributesOf(dto, line, returnExpected))
.sourceProvider(ChannelProvider.DIRECT)
.build();
}
/** {@code returnOrderId:returnOrderLineNumber};行号缺失时退化为退货单号。 */
static String afterSaleId(String returnOrderId, Integer returnOrderLineNumber) {
return returnOrderId + ":" + (returnOrderLineNumber == null ? "0" : returnOrderLineNumber);
}
/**
* 本行<b>应退</b>金额(按退货数量计,不是「已退」金额)。
*
* <p>取 {@code chargeTotals} 里 {@code name=lineTotal} 的值——它是<b>退货行</b>的合计,
* 等于「退货数量 × 单价」,不是原订单整行金额。没有时用 {@code unitPrice × quantity} 兜底。</p>
*
* <p>「已退多少」看行上的 {@code refundedQty}(可能小于退货数量,部分退款场景),
* 换算成金额后放在 {@code attributes.refundedAmount},不覆盖本字段——
* 两个语义混在一起会让下游算错超退。</p>
*
* <p>币种只从 {@code unitPrice.currencyUnit} 取,拿不到币种时整体为 null——
* 不猜币种,也不拿订单总额硬摊。</p>
*/
static Money refundAmountOf(WalmartReturnDtos.ReturnOrderLine line) {
String currency = line.unitPrice == null ? null : line.unitPrice.currencyUnit;
BigDecimal amount = lineTotalOf(line);
if (amount == null) {
amount = unitPriceTimesQuantity(line);
}
if (amount == null) {
amount = line.unitPrice == null ? null : line.unitPrice.currencyAmount;
}
if (amount == null || currency == null) {
return null;
}
try {
return Money.of(amount, currency);
} catch (IllegalArgumentException e) {
return null;
}
}
/** 已退金额 = {@code refundedQty × unitPrice};任一缺失返回 null。 */
static Money refundedAmountOf(WalmartReturnDtos.ReturnOrderLine line) {
if (line.refundedQty == null || line.unitPrice == null
|| line.unitPrice.currencyAmount == null || line.unitPrice.currencyUnit == null) {
return null;
}
try {
return Money.of(line.refundedQty.multiply(line.unitPrice.currencyAmount),
line.unitPrice.currencyUnit);
} catch (IllegalArgumentException e) {
return null;
}
}
/** {@code chargeTotals} 里 {@code lineTotal} 的值;没有返回 null。 */
static BigDecimal lineTotalOf(WalmartReturnDtos.ReturnOrderLine line) {
if (line.chargeTotals == null) {
return null;
}
for (WalmartReturnDtos.ChargeTotal total : line.chargeTotals) {
if (total != null && "lineTotal".equals(total.name)) {
return total.value;
}
}
return null;
}
/** 单价 × 数量;任一缺失返回 null。 */
static BigDecimal unitPriceTimesQuantity(WalmartReturnDtos.ReturnOrderLine line) {
if (line.unitPrice == null || line.unitPrice.currencyAmount == null
|| line.quantity == null || line.quantity.measurementValue == null) {
return null;
}
return line.unitPrice.currencyAmount.multiply(line.quantity.measurementValue);
}
/**
* 原始字段。沃尔玛售后的细分状态(退款状态、物流状态、keep-it 等)统一模型没有
* 对应字段,全部原样保留在这里;键名与平台一致。
*/
static Map<String, Object> attributesOf(WalmartReturnDtos.ReturnOrder dto,
WalmartReturnDtos.ReturnOrderLine line,
Boolean returnExpected) {
Map<String, Object> attributes = new LinkedHashMap<String, Object>();
putIfNotNull(attributes, "returnOrderId", dto.returnOrderId);
putIfNotNull(attributes, "customerOrderId", dto.customerOrderId);
putIfNotNull(attributes, "customerEmailId", dto.customerEmailId);
putIfNotNull(attributes, "refundMode", dto.refundMode);
putIfNotNull(attributes, "returnByDate", dto.returnByDate);
putIfNotNull(attributes, "returnChannel",
dto.returnChannel == null ? null : dto.returnChannel.channelName);
putIfNotNull(attributes, "totalRefundAmount", currencyAmount(dto.totalRefundAmount));
putIfNotNull(attributes, "salesOrderLineNumber", line.salesOrderLineNumber);
putIfNotNull(attributes, "purchaseOrderLineNumber", line.purchaseOrderLineNumber);
putIfNotNull(attributes, "sellerOrderId", line.sellerOrderId);
putIfNotNull(attributes, "currentDeliveryStatus", line.currentDeliveryStatus);
putIfNotNull(attributes, "currentRefundStatus", line.currentRefundStatus);
putIfNotNull(attributes, "refundChannel", line.refundChannel);
putIfNotNull(attributes, "refundedQty", line.refundedQty);
Money refunded = refundedAmountOf(line);
putIfNotNull(attributes, "refundedAmount", refunded == null ? null : refunded.toString());
putIfNotNull(attributes, "cancellableQty", line.cancellableQty);
putIfNotNull(attributes, "rechargeableQty", line.rechargeableQty);
putIfNotNull(attributes, "isKeepIt", line.isKeepIt);
putIfNotNull(attributes, "isFastReplacement", line.isFastReplacement);
putIfNotNull(attributes, "lastItem", line.lastItem);
putIfNotNull(attributes, "unitOfMeasure",
line.quantity == null ? null : line.quantity.unitOfMeasure);
if (returnExpected != null) {
attributes.put("returnExpectedFlag", returnExpected);
}
return attributes;
}
/** 按 {@code returnOrderLineNumber} 建承运商索引;一个行可能有多个面单,取第一个非空。 */
static Map<Integer, WalmartReturnDtos.CarrierInfo> carrierIndex(WalmartReturnDtos.ReturnOrder dto) {
Map<Integer, WalmartReturnDtos.CarrierInfo> index =
new LinkedHashMap<Integer, WalmartReturnDtos.CarrierInfo>();
if (dto.returnLineGroups == null) {
return index;
}
for (WalmartReturnDtos.ReturnLineGroup group : dto.returnLineGroups) {
if (group == null) {
continue;
}
WalmartReturnDtos.CarrierInfo carrier = firstCarrier(group);
if (carrier == null || group.returnLines == null) {
continue;
}
for (WalmartReturnDtos.GroupReturnLine gl : group.returnLines) {
if (gl != null && gl.returnOrderLineNumber != null
&& !index.containsKey(gl.returnOrderLineNumber)) {
index.put(gl.returnOrderLineNumber, carrier);
}
}
}
return index;
}
/** 按 {@code returnOrderLineNumber} 建「是否预期退回」索引。 */
static Map<Integer, Boolean> expectedIndex(WalmartReturnDtos.ReturnOrder dto) {
Map<Integer, Boolean> index = new LinkedHashMap<Integer, Boolean>();
if (dto.returnLineGroups == null) {
return index;
}
for (WalmartReturnDtos.ReturnLineGroup group : dto.returnLineGroups) {
if (group == null || group.returnExpectedFlag == null || group.returnLines == null) {
continue;
}
for (WalmartReturnDtos.GroupReturnLine gl : group.returnLines) {
if (gl != null && gl.returnOrderLineNumber != null
&& !index.containsKey(gl.returnOrderLineNumber)) {
index.put(gl.returnOrderLineNumber, group.returnExpectedFlag);
}
}
}
return index;
}
private static WalmartReturnDtos.CarrierInfo firstCarrier(WalmartReturnDtos.ReturnLineGroup group) {
if (group.labels == null) {
return null;
}
for (WalmartReturnDtos.Label label : group.labels) {
if (label == null || label.carrierInfoList == null) {
continue;
}
for (WalmartReturnDtos.CarrierInfo info : label.carrierInfoList) {
if (info != null) {
return info;
}
}
}
return null;
}
/** {@code {currencyAmount, currencyUnit}} → {@code "127.45 USD"};用于 attributes。 */
private static String currencyAmount(WalmartReturnDtos.CurrencyAmount amount) {
if (amount == null || amount.currencyAmount == null) {
return null;
}
return amount.currencyAmount.toPlainString() + " " + amount.currencyUnit;
}
/** ISO-8601 字符串 → 三轴时间;解析失败返回 null,不让脏时间卡住整页。 */
static PlatformTime toPlatformTime(String iso, ZoneId zone) {
if (iso == null || iso.trim().isEmpty()) {
return null;
}
try {
return PlatformTime.of(Instant.parse(iso.trim()), zone);
} catch (Exception e) {
return null;
}
}
/** 平台必填字段缺失判定。 */
private static boolean isBlank(String value) {
return value == null || value.trim().isEmpty();
}
private static void putIfNotNull(Map<String, Object> map, String key, Object value) {
if (value != null) {
map.put(key, value);
}
}
}

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

@ -0,0 +1,133 @@ @@ -0,0 +1,133 @@
package common.ecommerce.walmart.mapper;
import common.ecommerce.walmart.dto.WalmartShipmentDtos;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 发货信息({@code GET /v3/orders/{id}/shipping})→ 行级发货记录。
*
* <p>统一模型没有独立的「发货记录」实体:同样的 {@code trackingInfo} 也挂在订单详情的
* 行状态上,两种方式数据一致。本类只给「单独查发货信息」的场景用。</p>
*
* <p><b>不扩展 {@code OrderLine}</b>:跟踪号、承运商属于履约域,统一订单模型只保留交易信息;
* 要发货信息请走 {@code WalmartAdapter.getShipping},不要在 {@code OrderLine} 上找。</p>
*/
public final class WalmartShipmentMapper {
private WalmartShipmentMapper() {
}
/**
* 抽取每行的发货记录。
*
* <p>同一行可能有多个状态({@code Created} / {@code Shipped}),只取带
* {@code trackingInfo} 的那条;没有任何发货记录的行不出现在结果里(表示尚未发货)。</p>
*
* @param dto 发货信息响应
* @return 每行一条;响应为空时返回空列表
*/
public static List<ShipmentLine> toShipmentLines(WalmartShipmentDtos.ShipmentResponse dto) {
if (dto == null || dto.orderShipment == null
|| dto.orderShipment.orderLines == null
|| dto.orderShipment.orderLines.orderLine == null) {
return Collections.emptyList();
}
List<ShipmentLine> out = new ArrayList<ShipmentLine>();
for (WalmartShipmentDtos.OrderLine line : dto.orderShipment.orderLines.orderLine) {
if (line == null) {
continue;
}
WalmartShipmentDtos.TrackingInfo tracking = trackingOf(line);
if (tracking == null) {
continue;
}
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 {
/** 订单行号。 */
private final String lineNumber;
/** 承运商编码;非标准承运商时为 {@code otherCarrier} 名称。 */
private final String carrier;
/** 运输方式编码。 */
private final String methodCode;
/** 跟踪号。 */
private final String trackingNumber;
/** 发货时间,ISO-8601 原值。 */
private final String shipDateTime;
ShipmentLine(String lineNumber, String carrier, String methodCode,
String trackingNumber, String shipDateTime) {
this.lineNumber = lineNumber;
this.carrier = carrier;
this.methodCode = methodCode;
this.trackingNumber = trackingNumber;
this.shipDateTime = shipDateTime;
}
/** 订单行号。 */
public String lineNumber() {
return lineNumber;
}
/** 承运商编码 / 非标准承运商名称。 */
public String carrier() {
return carrier;
}
/** 运输方式编码。 */
public String methodCode() {
return methodCode;
}
/** 跟踪号。 */
public String trackingNumber() {
return trackingNumber;
}
/** 发货时间(ISO-8601 原值)。 */
public String shipDateTime() {
return shipDateTime;
}
/** 调试输出;不含收货人信息。 */
@Override
public String toString() {
return "ShipmentLine{" + lineNumber + ", " + carrier + ", " + trackingNumber + '}';
}
}
}

154
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/WalmartFacadeTest.java

@ -0,0 +1,154 @@ @@ -0,0 +1,154 @@
package common.ecommerce.walmart;
import common.ecommerce.channel.capability.CapabilityReport;
import common.ecommerce.channel.capability.PlatformAdapter;
import common.ecommerce.channel.model.account.AccountKey;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.model.aftersale.AfterSale;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.product.ProductListing;
import common.ecommerce.channel.model.product.ProductQuery;
import common.ecommerce.channel.sdk.AdapterFactory;
import common.ecommerce.channel.sdk.ChannelSdk;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.model.Capability;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.InMemoryAccounts;
import common.ecommerce.shared.testkit.InMemoryLockProvider;
import common.ecommerce.shared.testkit.InMemoryTokenStore;
import common.ecommerce.shared.testkit.JsonFixture;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.walmart.adapter.WalmartAdapterFactory;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import java.time.LocalDate;
import java.util.EnumSet;
import static common.ecommerce.walmart.support.WalmartTestSupport.CLIENT_ID;
import static common.ecommerce.walmart.support.WalmartTestSupport.CLIENT_SECRET;
import static common.ecommerce.walmart.support.WalmartTestSupport.CLOCK;
import static common.ecommerce.walmart.support.WalmartTestSupport.ENDPOINT;
import static common.ecommerce.walmart.support.WalmartTestSupport.account;
import static common.ecommerce.walmart.support.WalmartTestSupport.adapter;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 门面集成:沃尔玛适配器注册后,{@code ChannelSdk} 按 DIRECT + WALMART_SC 路由,
* 能力矩阵与领星账户互不干扰。
*/
class WalmartFacadeTest {
private static final AccountKey WM =
AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001");
private static final common.ecommerce.channel.sdk.ChannelConnection CONNECTION =
common.ecommerce.channel.sdk.ChannelConnection.of(ENDPOINT,
ChannelSecret.builder().clientId(CLIENT_ID).clientSecret(CLIENT_SECRET).build());
private RecordingTransport transport() {
return RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(JsonFixture.load("fixtures/walmart/token/success.json")))
.route("/v3/orders", r -> Responses.ok(JsonFixture.load("fixtures/walmart/orders/list.json")))
.route("/v3/items", r -> Responses.ok(JsonFixture.load("fixtures/walmart/items/list.json")))
.route("/v3/returns", r -> Responses.ok(JsonFixture.load("fixtures/walmart/returns/list.json")));
}
/**
* 用录制传输层装配门面。
*
* <p>工厂 {@code create()} 装配的是真实 OkHttp 传输层(生产路径),测试里直接
* 注册适配器实例,才能把网络关掉。工厂本身另由
* {@link #factoryRegistersDirectWalmart()} 覆盖。</p>
*/
private ChannelSdk sdkWithRecording(RecordingTransport transport, InMemoryAccounts accounts) {
return ChannelSdk.builder()
.accountRepository(accounts)
.register(adapter(transport))
.build();
}
private static InMemoryAccounts accounts() {
return new InMemoryAccounts().put(account());
}
@Test
void factoryRegistersDirectWalmart() {
AdapterFactory factory = new WalmartAdapterFactory(
new InMemoryTokenStore(), new InMemoryLockProvider(), CLOCK);
assertEquals(ChannelProvider.DIRECT, factory.provider());
assertEquals(EnumSet.of(Platform.WALMART_SC), factory.platforms());
PlatformAdapter adapter = factory.create(AdapterFactory.AdapterConfig.NONE);
assertEquals(ChannelProvider.DIRECT, adapter.provider());
assertEquals(EnumSet.of(Platform.WALMART_SC), adapter.platforms());
}
@Test
void capabilityReportIsExactlyReadOnlyThree() {
ChannelSdk sdk = sdkWithRecording(transport(), accounts());
CapabilityReport report = sdk.capabilities(WM);
assertEquals(EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS),
report.supported());
assertFalse(report.supports(Capability.MARK_SHIPPED));
assertFalse(report.supports(Capability.BILLING));
}
@Test
void pullsThroughFacade() {
ChannelSdk sdk = sdkWithRecording(transport(), accounts());
Page<SalesOrder> orders = sdk.salesOrders(WM, CONNECTION).pull(SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-11-01T00:00:00Z"))
.updatedBefore(Instant.parse("2026-11-02T00:00:00Z"))
.build());
assertEquals(5, orders.size());
Page<ProductListing> products = sdk.products(WM, CONNECTION)
.pull(ProductQuery.builder().build());
assertEquals(3, products.size());
Page<AfterSale> afterSales = sdk.afterSales(WM, CONNECTION).pull(
common.ecommerce.channel.model.aftersale.AfterSaleQuery.builder()
.startDate(LocalDate.of(2026, 11, 1))
.endDate(LocalDate.of(2026, 11, 18))
.build());
assertEquals(2, afterSales.size());
}
@Test
void writeOperationsAreRejectedNotSilentlyIgnored() {
ChannelSdk sdk = sdkWithRecording(transport(), accounts());
ChannelException.UnsupportedCapabilityException ex = assertThrows(
ChannelException.UnsupportedCapabilityException.class,
() -> sdk.outbounds(WM, CONNECTION).submit(java.util.Collections.emptyList()));
assertEquals(Capability.MARK_SHIPPED, ex.capability());
}
@Test
void unregisteredPlatformIsNotRouted() {
// 账户存在但没有任何适配器覆盖 AMAZON_SC:报「没有适配器」而不是「账户未配置」
InMemoryAccounts accounts = accounts().put(ChannelAccount.builder()
.key(AccountKey.of(ChannelProvider.DIRECT, Platform.AMAZON_SC, "oms-amz-001"))
.externalStoreId("amz-seller-01")
.credentialRef("kms://test/amazon")
.marketplaceZone("America/Los_Angeles")
.currency("USD")
.build());
ChannelSdk sdk = sdkWithRecording(transport(), accounts);
AccountKey amazon = AccountKey.of(ChannelProvider.DIRECT, Platform.AMAZON_SC, "oms-amz-001");
IllegalStateException ex = assertThrows(IllegalStateException.class,
() -> sdk.capabilities(amazon));
assertTrue(ex.getMessage().contains("no adapter registered"), ex.getMessage());
}
}

209
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartDirtyDataTest.java

@ -0,0 +1,209 @@ @@ -0,0 +1,209 @@
package common.ecommerce.walmart.adapter;
import common.ecommerce.channel.model.aftersale.AfterSaleQuery;
import common.ecommerce.channel.model.order.OrderLine;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.JsonFixture;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import java.time.LocalDate;
import static common.ecommerce.walmart.support.WalmartTestSupport.adapter;
import static common.ecommerce.walmart.support.WalmartTestSupport.context;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 脏数据韧性:平台给了缺字段 / 非预期费用的记录时,
* 适配器要「丢一条 + 不崩页」,而不是抛 NPE 或写脏主键。
*/
class WalmartDirtyDataTest {
private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
private static RecordingTransport transport(String path, String body) {
return RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(JsonFixture.load("fixtures/walmart/token/success.json")))
.route(path, r -> Responses.ok(body));
}
private static SalesOrderQuery orderQuery() {
return SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-11-01T00:00:00Z"))
.updatedBefore(Instant.parse("2026-11-02T00:00:00Z")).build();
}
/** 取一条正常订单,按需删字段 / 改费用。 */
private static ObjectNode sampleOrder() throws Exception {
ObjectNode root = (ObjectNode) JSON.mapper().readTree(
JsonFixture.load("fixtures/walmart/orders/list.json"));
return (ObjectNode) root.at("/list/elements/order/0");
}
private static String orderBody(ObjectNode order) {
ObjectNode root = JSON.mapper().createObjectNode();
ObjectNode list = root.putObject("list");
ArrayNode orders = list.putObject("elements").putArray("order");
orders.add(order);
return JSON.toJson(root);
}
private static String wrapOrders(String... orderJson) {
StringBuilder sb = new StringBuilder("{\"list\":{\"elements\":{\"order\":[");
for (int i = 0; i < orderJson.length; i++) {
if (i > 0) {
sb.append(',');
}
sb.append(orderJson[i]);
}
return sb.append("]}}}").toString();
}
// ---------------------------------------------------------------- 订单
@Test
void orderWithoutPurchaseOrderIdIsSkippedNotFatal() throws Exception {
ObjectNode missing = sampleOrder();
missing.remove("purchaseOrderId");
Page<SalesOrder> page = adapter(transport("/v3/orders",
wrapOrders(missing.toString(), sampleOrder().toString())))
.pull(context(), orderQuery());
// 坏的那条丢掉,好的那条照常返回
assertEquals(1, page.size());
assertEquals("108816631915371", page.items().get(0).channelOrderId());
}
@Test
void orderWithoutOrderDateIsSkippedNotFatal() throws Exception {
ObjectNode missing = sampleOrder();
missing.remove("orderDate");
Page<SalesOrder> page = adapter(transport("/v3/orders",
wrapOrders(missing.toString(), sampleOrder().toString())))
.pull(context(), orderQuery());
assertEquals(1, page.size());
}
@Test
void blankPurchaseOrderIdIsSkipped() throws Exception {
ObjectNode blank = sampleOrder();
blank.put("purchaseOrderId", " ");
Page<SalesOrder> page = adapter(transport("/v3/orders", orderBody(blank)))
.pull(context(), orderQuery());
assertTrue(page.items().isEmpty());
}
// ---------------------------------------------------------------- 单价与行金额
@Test
void lineAmountIsAuthoritativeAndUnitPriceDerived() throws Exception {
OrderLine line = singleLine(sampleOrder());
// 1 件 499.99:行金额与单价相同
assertEquals("499.99", line.lineAmount().amount().toPlainString());
assertEquals("499.99", line.unitPrice().amount().toPlainString());
}
@Test
void unitPriceIsNullWhenNotExactlyDivisible() throws Exception {
OrderLine line = singleLine(twoUnitsOf("100.00", 3));
// 3 件共 100:除不尽,不给四舍五入后的 33.3333
assertNull(line.unitPrice());
assertEquals("100", line.lineAmount().amount().stripTrailingZeros().toPlainString());
}
@Test
void unitPriceIsPresentWhenExactlyDivisible() throws Exception {
OrderLine line = singleLine(twoUnitsOf("99.98", 2));
assertEquals("49.99", line.unitPrice().amount().toPlainString());
assertEquals("99.98", line.lineAmount().amount().toPlainString());
}
@Test
void shippingChargeIsNotTreatedAsUnitPrice() throws Exception {
ObjectNode order = sampleOrder();
ObjectNode line = (ObjectNode) order.at("/orderLines/orderLine/0");
// 去掉商品费,只剩运费
ObjectNode charges = (ObjectNode) line.at("/charges");
ArrayNode chargeArray = charges.putArray("charge");
ObjectNode shipping = chargeArray.addObject();
shipping.put("chargeType", "SHIPPING");
shipping.put("chargeName", "Shipping");
shipping.putObject("chargeAmount").put("currency", "USD").put("amount", 9.99);
OrderLine mapped = singleLine(order);
// 运费不是商品价:单价与行金额都不给,但订单总额仍能算出来
assertNull(mapped.unitPrice());
assertNull(mapped.lineAmount());
}
@Test
void totalIsNullWhenCurrenciesDiffer() throws Exception {
ObjectNode order = sampleOrder();
ObjectNode line = (ObjectNode) order.at("/orderLines/orderLine/0");
ArrayNode chargeArray = (ArrayNode) line.at("/charges/charge");
ObjectNode other = chargeArray.addObject();
other.put("chargeType", "FEE");
other.put("chargeName", "Fee");
other.putObject("chargeAmount").put("currency", "CAD").put("amount", 5.0);
Page<SalesOrder> page = adapter(transport("/v3/orders", orderBody(order)))
.pull(context(), orderQuery());
// 同单两个币种属于数据异常:宁可不给总额
assertNull(page.items().get(0).totalAmount());
}
// ---------------------------------------------------------------- 售后
@Test
void returnWithoutReturnOrderIdIsDropped() {
String body = "{\"returnOrders\":[{\"returnOrderLines\":[{\"returnOrderLineNumber\":1}]}]}";
Page<common.ecommerce.channel.model.aftersale.AfterSale> page =
adapter(transport("/v3/returns", body)).pull(context(), AfterSaleQuery.builder()
.startDate(LocalDate.of(2026, 11, 1))
.endDate(LocalDate.of(2026, 11, 18)).build());
// 不能拼出 "null:1" 这种主键
assertTrue(page.items().isEmpty());
}
@Test
void returnLineWithoutLineNumberStillUsesReturnOrderId() {
String body = "{\"returnOrders\":[{\"returnOrderId\":\"R-9\",\"returnOrderLines\":[{\"status\":\"INITIATED\"}]}]}";
Page<common.ecommerce.channel.model.aftersale.AfterSale> page =
adapter(transport("/v3/returns", body)).pull(context(), AfterSaleQuery.builder()
.startDate(LocalDate.of(2026, 11, 1))
.endDate(LocalDate.of(2026, 11, 18)).build());
assertEquals("R-9:0", page.items().get(0).afterSaleId());
}
// ---------------------------------------------------------------- helpers
private static OrderLine singleLine(ObjectNode order) throws Exception {
Page<SalesOrder> page = adapter(transport("/v3/orders", orderBody(order)))
.pull(context(), orderQuery());
return page.items().get(0).lines().get(0);
}
/** 把样例订单改成「quantity 件共 amount」。 */
private static ObjectNode twoUnitsOf(String amount, int quantity) throws Exception {
ObjectNode order = sampleOrder();
ObjectNode line = (ObjectNode) order.at("/orderLines/orderLine/0");
ObjectNode charge = (ObjectNode) line.at("/charges/charge/0");
charge.putObject("chargeAmount").put("currency", "USD").put("amount", new java.math.BigDecimal(amount));
((ObjectNode) charge.at("/tax/taxAmount")).put("amount", 0);
((ObjectNode) line.at("/orderLineQuantity")).put("amount", String.valueOf(quantity));
return order;
}
}

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

@ -0,0 +1,171 @@ @@ -0,0 +1,171 @@
package common.ecommerce.walmart.adapter;
import common.ecommerce.channel.model.aftersale.AfterSale;
import common.ecommerce.channel.model.aftersale.AfterSaleQuery;
import common.ecommerce.channel.model.aftersale.AfterSaleType;
import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.shared.testkit.JsonFixture;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.walmart.WalmartConstants;
import common.ecommerce.walmart.mapper.WalmartShipmentMapper;
import org.junit.jupiter.api.Test;
import java.time.LocalDate;
import java.util.List;
import static common.ecommerce.walmart.support.WalmartTestSupport.ENDPOINT;
import static common.ecommerce.walmart.support.WalmartTestSupport.adapter;
import static common.ecommerce.walmart.support.WalmartTestSupport.assertUrlContains;
import static common.ecommerce.walmart.support.WalmartTestSupport.context;
import static common.ecommerce.walmart.support.WalmartTestSupport.lastUrl;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 两个「有路由但不在能力接口里」的查询:退货单详情、发货信息。
*
* <p>两者沙箱都 404,所以这里用契约测试锁住请求构造与响应映射;
* 真实可用性由沙箱探针在生产环境补齐。</p>
*/
class WalmartExtraQueryTest {
private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
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")));
}
// ---------------------------------------------------------------- 退货单详情
@Test
void returnDetailUsesReturnOrderIdPath() {
RecordingTransport transport = transport();
List<AfterSale> afterSales = adapter(transport).getReturn(context(), "103738048909818825");
assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/returns/103738048909818825");
assertEquals(1, afterSales.size());
}
@Test
void returnDetailExpandsLinesLikeList() {
AfterSale a = adapter(transport()).getReturn(context(), "103738048909818825").get(0);
// 与列表接口相同的 id 规则,可直接 upsert
assertEquals("103738048909818825:1", a.afterSaleId());
assertEquals(AfterSaleType.RETURN, a.type());
assertEquals("IN_TRANSIT", a.status());
assertEquals(2, a.quantity());
assertEquals("239.9", a.refundAmount().amount().toPlainString());
assertEquals("FEDEX", a.carrier());
assertEquals("785611449666", a.trackingNumber());
assertEquals("ONLINE", a.attributes().get("returnChannel"));
}
@Test
void returnDetailEncodesId() {
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")));
adapter(transport).getReturn(context(), "R 1/2");
assertUrlContains(lastUrl(transport), "/v3/returns/R%201%2F2");
}
@Test
void blankReturnOrderIdIsRejectedBeforeAnyRequest() {
RecordingTransport transport = transport();
assertThrows(ValidationException.class, () -> adapter(transport).getReturn(context(), " "));
assertEquals(0, transport.recorded().size());
}
@Test
void returnDetail404PropagatesAsValidationException() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/returns/", r -> Responses.status(404,
JsonFixture.load("fixtures/walmart/errors/gateway-404.json")));
ValidationException ex = assertThrows(ValidationException.class,
() -> adapter(transport).getReturn(context(), "SOMETHING"));
assertEquals("CONTENT_NOT_FOUND.GMP_GATEWAY_API", ex.platformCode());
}
// ---------------------------------------------------------------- 发货信息
@Test
void shippingUsesOrderPathAndMapsShippedLinesOnly() {
RecordingTransport transport = transport();
List<WalmartShipmentMapper.ShipmentLine> lines =
adapter(transport).getShipping(context(), "108816631915371");
assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/orders/108816631915371/shipping");
// 3 行里只有 2 行有 trackingInfo;未发货行不出现
assertEquals(2, lines.size());
assertEquals("1", lines.get(0).lineNumber());
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());
}
@Test
void shippingFallsBackToOtherCarrier() {
List<WalmartShipmentMapper.ShipmentLine> lines =
adapter(transport()).getShipping(context(), "108816631915371");
// 非标准承运商:carrier 为空时用 otherCarrier
assertEquals("Local Courier", lines.get(1).carrier());
assertEquals("Freight", lines.get(1).methodCode());
}
@Test
void blankOrderIdIsRejectedBeforeAnyRequest() {
RecordingTransport transport = transport();
assertThrows(ValidationException.class, () -> adapter(transport).getShipping(context(), ""));
assertEquals(0, transport.recorded().size());
}
@Test
void emptyShipmentReturnsEmptyList() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/shipping", r -> Responses.ok("{\"orderShipment\":{\"orderLines\":{\"orderLine\":[]}}}"));
assertTrue(adapter(transport).getShipping(context(), "PO-1").isEmpty());
}
@Test
void shipmentLineCarriesTrackingButNoRecipientInfo() {
WalmartShipmentMapper.ShipmentLine line =
adapter(transport()).getShipping(context(), "108816631915371").get(0);
// 发货记录只含履约字段,不含收件人 / 地址
assertEquals("1Z999AA10123456784", line.trackingNumber());
assertTrue(line.toString().contains("1Z999AA10123456784"), line.toString());
assertTrue(!line.toString().contains("@"), line.toString());
}
@Test
void listAndDetailAgreeOnReturnPathPrefix() {
// 两个接口共用 /v3/returns 前缀;详情多一段 id,别把列表路由吃掉
assertEquals("/v3/returns", WalmartConstants.PATH_RETURNS);
assertEquals("/v3/returns/", WalmartConstants.PATH_RETURN_BY_ID);
}
/** 列表接口仍然可用(详情方法没有误改列表路由)。 */
@Test
void listStillWorks() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/returns", r -> Responses.ok(JsonFixture.load("fixtures/walmart/returns/list.json")));
int size = adapter(transport).pull(context(), AfterSaleQuery.builder()
.startDate(LocalDate.of(2026, 11, 1))
.endDate(LocalDate.of(2026, 11, 18))
.build()).size();
assertEquals(2, size);
}
}

346
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartOrderTest.java

@ -0,0 +1,346 @@ @@ -0,0 +1,346 @@
package common.ecommerce.walmart.adapter;
import common.ecommerce.channel.model.order.OrderLine;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.shared.model.Capability;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.InMemoryTokenStore;
import common.ecommerce.shared.testkit.JsonFixture;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.walmart.WalmartConstants;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import java.util.EnumSet;
import java.util.List;
import static common.ecommerce.walmart.support.WalmartTestSupport.ENDPOINT;
import static common.ecommerce.walmart.support.WalmartTestSupport.adapter;
import static common.ecommerce.walmart.support.WalmartTestSupport.assertUrlContains;
import static common.ecommerce.walmart.support.WalmartTestSupport.context;
import static common.ecommerce.walmart.support.WalmartTestSupport.lastUrl;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** 沃尔玛订单:请求构造 + 响应映射 + 增量语义。 */
class WalmartOrderTest {
private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
private RecordingTransport transport() {
return RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/orders/108816631915371",
r -> Responses.ok(JsonFixture.load("fixtures/walmart/orders/detail.json")))
.route("/v3/orders", r -> Responses.ok(JsonFixture.load("fixtures/walmart/orders/list.json")));
}
// ---------------------------------------------------------------- 请求
@Test
void pullSendsAuthHeadersAndCreatedWindow() {
RecordingTransport transport = transport();
adapter(transport).pull(context(), query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z"));
String url = lastUrl(transport);
assertUrlContains(url, ENDPOINT + WalmartConstants.PATH_ORDERS);
assertUrlContains(url, "createdStartDate=2026-11-01T00%3A00%3A00.000Z");
assertUrlContains(url, "createdEndDate=2026-11-02T00%3A00%3A00.000Z");
common.ecommerce.http.HttpRequest request = transport.recorded().get(transport.recorded().size() - 1);
assertEquals("Walmart Marketplace", request.headers().get(WalmartConstants.HEADER_SVC_NAME));
assertEquals("req-1", request.headers().get(WalmartConstants.HEADER_CORRELATION_ID));
// 业务请求带的是 WM_SEC.ACCESS_TOKEN,不是 Authorization
assertNotNull(request.headers().get(WalmartConstants.HEADER_ACCESS_TOKEN));
assertNull(request.headers().get("Authorization"));
}
@Test
void tokenRequestUsesBasicAuthAndFormBody() {
RecordingTransport transport = transport();
adapter(transport).pull(context(), query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z"));
common.ecommerce.http.HttpRequest token = transport.recorded().get(0);
assertEquals(ENDPOINT + WalmartConstants.PATH_TOKEN, token.url());
assertEquals("POST", token.method());
assertEquals("application/x-www-form-urlencoded", token.contentType());
assertEquals("grant_type=client_credentials", token.body());
assertTrue(token.headers().get("Authorization").startsWith("Basic "),
token.headers().get("Authorization"));
}
@Test
void tokenIsCachedAcrossCalls() {
RecordingTransport transport = transport();
InMemoryTokenStore tokens = new InMemoryTokenStore();
common.ecommerce.walmart.adapter.WalmartAdapter walmart = adapter(transport, tokens,
new common.ecommerce.shared.testkit.InMemoryLockProvider());
walmart.pull(context(), query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z"));
walmart.pull(context(), query("2026-11-03T00:00:00Z", "2026-11-04T00:00:00Z"));
// 只换一次 token:沙箱有效令牌数接近上限,必须复用
assertEquals(1, tokens.saveCount());
assertEquals(1, countTokenRequests(transport));
}
@Test
void cursorIsPassedThrough() {
RecordingTransport transport = transport();
adapter(transport).pull(context(), SalesOrderQuery.builder()
.updatedAfter(Instant.parse("2026-11-01T00:00:00Z"))
.updatedBefore(Instant.parse("2026-11-02T00:00:00Z"))
.pageSize(50)
.cursor("FGluY2x1ZGQ==")
.build());
String url = lastUrl(transport);
assertUrlContains(url, "limit=50");
assertUrlContains(url, "nextCursor=FGluY2x1ZGQ%3D%3D");
}
// ---------------------------------------------------------------- 校验
@Test
void windowOver180DaysIsRejected() {
RecordingTransport transport = transport();
ValidationException ex = assertThrows(ValidationException.class,
() -> adapter(transport).pull(context(),
query("2026-01-01T00:00:00Z", "2026-11-02T00:00:00Z")));
assertTrue(ex.getMessage().contains("max 180"), ex.getMessage());
// 本地拒绝,不发出业务请求
assertEquals(0, transport.dataRequests().size());
}
@Test
void invertedWindowIsRejected() {
RecordingTransport transport = transport();
assertThrows(ValidationException.class,
() -> adapter(transport).pull(context(),
query("2026-11-02T00:00:00Z", "2026-11-01T00:00:00Z")));
}
// ---------------------------------------------------------------- 映射
@Test
void mapsOrderFields() {
Page<SalesOrder> page = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z"));
assertEquals(5, page.size());
SalesOrder order = page.items().get(0);
assertEquals("oms-wm-001", order.omsStoreId());
assertEquals("108816631915371", order.channelOrderId());
assertEquals("Created", order.status());
assertEquals("Astro Test", order.buyerName());
assertEquals("emailID123456@relay.walmart.com", order.buyerEmail());
assertEquals("USA", order.shipToCountryCode());
assertEquals(ChannelProvider.DIRECT, order.sourceProvider());
// orderDate 是 epoch 毫秒
assertEquals(Instant.ofEpochMilli(1686736267000L), order.occurredAt().utc());
assertNull(page.nextCursor());
}
@Test
void mapsShippingAddress() {
SalesOrder order = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items().get(0);
assertNotNull(order.shipToAddress());
assertEquals("5809 W 44th Ave", order.shipToAddress().address1());
assertEquals("Lakeside", order.shipToAddress().city());
assertEquals("CO", order.shipToAddress().state());
assertEquals("80212", order.shipToAddress().postalCode());
assertEquals("USA", order.shipToAddress().countryCode());
assertEquals("OFFICE", order.shipToAddress().addressType());
assertEquals("555-0100", order.shipToAddress().phone());
}
@Test
void mapsLinesWithStringQuantityAndCharges() {
SalesOrder order = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items().get(0);
assertEquals(1, order.lines().size());
OrderLine line = order.lines().get(0);
assertEquals("1", line.lineId());
assertEquals("67022229561Test5_skuUpdate", line.platformSku());
// 订单接口的 amount 是字符串
assertEquals(1, line.quantity());
assertEquals("499.99", line.unitPrice().amount().toPlainString());
assertEquals("USD", line.unitPrice().currencyCode());
assertEquals("29.72", line.tax().amount().toPlainString());
assertEquals("Created", line.status());
}
@Test
void unitPriceIsLineTotalDividedByQuantity() {
// 2 件共 99.98:ItemPrice.chargeAmount 是整行金额,unitPrice 必须是 49.99
SalesOrder multi = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items().get(4);
assertEquals(2, multi.lines().get(0).quantity());
assertEquals("49.99", multi.lines().get(0).unitPrice().amount().toPlainString());
// 总额仍是行金额 + 税,与单价拆分互不影响
assertEquals("105.92", multi.totalAmount().amount().toPlainString());
}
@Test
void singleQuantityKeepsChargeAmountAsUnitPrice() {
SalesOrder single = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items().get(0);
assertEquals(1, single.lines().get(0).quantity());
assertEquals("499.99", single.lines().get(0).unitPrice().amount().toPlainString());
}
@Test
void authFailureRetriesOnceWithFreshToken() {
final int[] attempts = new int[2];
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/orders", r -> {
attempts[0]++;
return attempts[0] == 1
? Responses.status(401, "{\"error\":[{\"code\":\"UNAUTHORIZED\"}]}")
: Responses.ok(JsonFixture.load("fixtures/walmart/orders/list.json"));
});
Page<SalesOrder> page = adapter(transport).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z"));
// 第一次 401 → 强制换 token → 第二次成功
assertEquals(5, page.size());
assertEquals(2, attempts[0]);
assertEquals(2, countTokenRequests(transport));
}
@Test
void authFailureOnRetryIsNotSwallowed() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/orders", r -> Responses.status(401,
"{\"error\":[{\"code\":\"UNAUTHORIZED\"}]}"));
assertThrows(common.ecommerce.shared.error.AuthException.class,
() -> adapter(transport).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")));
// 只重试一次,不能无限刷 token
assertEquals(2, countTokenRequests(transport));
}
@Test
void privacySafeAddressToString() {
// ShipToAddress.toString 只输出城市/州/邮编/国家,不输出街道与收件人
SalesOrder order = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items().get(0);
String text = order.shipToAddress().toString();
org.junit.jupiter.api.Assertions.assertFalse(text.contains("5809 W 44th Ave"), text);
org.junit.jupiter.api.Assertions.assertFalse(text.contains("Astro Test"), text);
}
@Test
void totalIsSumOfChargesAndTax() {
SalesOrder order = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items().get(0);
// ItemPrice 499.99 + tax 29.72 + Shipping 0.00 + tax 0.00
assertEquals("529.71", order.totalAmount().amount().toPlainString());
assertEquals("USD", order.totalAmount().currencyCode());
}
@Test
void shippedOrderHasShippedStatus() {
SalesOrder order = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items().get(1);
assertEquals("Shipped", order.status());
assertEquals("Shipped", order.lines().get(0).status());
}
@Test
void partialShipmentKeepsOrderCreatedAndRecordsRealLineStatus() {
// Created(2) + Shipped(1) of 3:还差 2 件没发,订单级别仍是 Created
List<SalesOrder> orders = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items();
SalesOrder partial = orders.get(2);
assertEquals("108816631915373", partial.channelOrderId());
assertEquals("Created", partial.status());
// 行上是平台原值:状态列表最后一条
assertEquals("Shipped", partial.lines().get(0).status());
}
@Test
void fullyShippedHistoryResolvesToShippedNotCreated() {
// Created(0) + Shipped(3) of 3:历史里残留 Created,但整行已发完
SalesOrder full = adapter(transport()).pull(context(),
query("2026-11-01T00:00:00Z", "2026-11-02T00:00:00Z")).items().get(3);
assertEquals("108816631915374", full.channelOrderId());
assertEquals("Shipped", full.status());
}
@Test
void getUnwrapsOrderEnvelope() {
RecordingTransport transport = transport();
SalesOrder order = adapter(transport).get(context(),
common.ecommerce.channel.model.order.SalesOrderRef.of("108816631915371"));
assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/orders/108816631915371");
assertEquals("108816631915371", order.channelOrderId());
assertEquals("Astro Test", order.shipToAddress().name());
}
@Test
void getUrlEncodesOrderId() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/orders/", r -> Responses.ok(JsonFixture.load("fixtures/walmart/orders/detail.json")));
adapter(transport).get(context(),
common.ecommerce.channel.model.order.SalesOrderRef.of("PO 1/2"));
// 路径里的空格编成 %20,不是 +(+ 在路径里是字面量加号)
assertUrlContains(lastUrl(transport), "/v3/orders/PO%201%2F2");
}
// ---------------------------------------------------------------- 能力
@Test
void declaresOnlyReadCapabilities() {
assertEquals(EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS),
adapter(transport()).capabilities());
assertEquals(ChannelProvider.DIRECT, adapter(transport()).provider());
assertEquals(EnumSet.of(Platform.WALMART_SC), adapter(transport()).platforms());
}
@Test
void openOrderReconciliationFiltersByStatus() {
RecordingTransport transport = transport();
Page<SalesOrder> page = adapter(transport).pullOpenOrders(context(), null, null, null);
String url = lastUrl(transport);
assertUrlContains(url, "status=Created%2CAcknowledged");
assertEquals(5, page.size());
}
// ---------------------------------------------------------------- helpers
private static SalesOrderQuery query(String from, String to) {
return SalesOrderQuery.builder()
.updatedAfter(Instant.parse(from))
.updatedBefore(Instant.parse(to))
.build();
}
private static int countTokenRequests(RecordingTransport transport) {
int count = 0;
for (common.ecommerce.http.HttpRequest request : transport.recorded()) {
if (request.url().contains(WalmartConstants.PATH_TOKEN)) {
count++;
}
}
return count;
}
}

233
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartProductTest.java

@ -0,0 +1,233 @@ @@ -0,0 +1,233 @@
package common.ecommerce.walmart.adapter;
import common.ecommerce.channel.model.product.ProductListing;
import common.ecommerce.channel.model.product.ProductQuery;
import common.ecommerce.channel.model.product.ProductSearchField;
import common.ecommerce.channel.model.product.ProductStatus;
import common.ecommerce.channel.model.product.ProductSyncStrategy;
import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.JsonFixture;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.walmart.WalmartConstants;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import static common.ecommerce.walmart.support.WalmartTestSupport.ENDPOINT;
import static common.ecommerce.walmart.support.WalmartTestSupport.adapter;
import static common.ecommerce.walmart.support.WalmartTestSupport.assertUrlContains;
import static common.ecommerce.walmart.support.WalmartTestSupport.context;
import static common.ecommerce.walmart.support.WalmartTestSupport.lastUrl;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** 沃尔玛商品:请求构造 + 响应映射 + 不支持的过滤条件必须显式报错。 */
class WalmartProductTest {
private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
private RecordingTransport transport() {
return RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/items/", r -> Responses.ok(
"{\"sku\":\"5212572\",\"productName\":\"Detail Item\",\"publishedStatus\":\"PUBLISHED\","
+ "\"lifecycleStatus\":\"ACTIVE\",\"price\":{\"currency\":\"USD\",\"amount\":1.5}}"))
.route("/v3/items", r -> Responses.ok(JsonFixture.load("fixtures/walmart/items/list.json")));
}
// ---------------------------------------------------------------- 请求
@Test
void pullSendsLimitAndCursor() {
RecordingTransport transport = transport();
adapter(transport).pull(context(), ProductQuery.builder().pageSize(50).cursor("CUR").build());
String url = lastUrl(transport);
assertUrlContains(url, ENDPOINT + WalmartConstants.PATH_ITEMS);
assertUrlContains(url, "limit=50");
assertUrlContains(url, "nextCursor=CUR");
}
@Test
void limitIsCappedAtPlatformMaximum() {
RecordingTransport transport = transport();
adapter(transport).pull(context(), ProductQuery.builder().pageSize(5_000).build());
assertUrlContains(lastUrl(transport), "limit=" + WalmartConstants.MAX_ITEM_PAGE_SIZE);
}
@Test
void skuSearchBecomesQueryParameter() {
RecordingTransport transport = transport();
adapter(transport).pull(context(), ProductQuery.builder()
.searchField(ProductSearchField.PLATFORM_SKU)
.searchValue("ABC-1")
.build());
assertUrlContains(lastUrl(transport), "sku=ABC-1");
}
// ---------------------------------------------------------------- 不支持的过滤
@Test
void timeWindowIsRejectedInsteadOfSilentlyIgnored() {
RecordingTransport transport = transport();
ValidationException ex = assertThrows(ValidationException.class,
() -> adapter(transport).pull(context(), ProductQuery.builder()
.updatedAfter(Instant.parse("2026-11-01T00:00:00Z"))
.build()));
assertTrue(ex.getMessage().contains("update-time filtering"), ex.getMessage());
// 本地拒绝:连 token 都不换
assertEquals(0, transport.recorded().size());
}
@Test
void multiValueSearchIsRejected() {
RecordingTransport transport = transport();
assertThrows(ValidationException.class,
() -> adapter(transport).pull(context(), ProductQuery.builder()
.searchField(ProductSearchField.PLATFORM_SKU)
.searchValues(Arrays.asList("A", "B"))
.build()));
}
@Test
void localSkuSearchIsRejected() {
RecordingTransport transport = transport();
ValidationException ex = assertThrows(ValidationException.class,
() -> adapter(transport).pull(context(), ProductQuery.builder()
.searchField(ProductSearchField.LOCAL_SKU)
.searchValue("LOCAL-1")
.build()));
assertTrue(ex.getMessage().contains("no local-sku"), ex.getMessage());
}
@Test
void syncStrategyIsFullPullDiff() {
assertEquals(ProductSyncStrategy.FULL_PULL_DIFF, adapter(transport()).syncStrategy());
}
// ---------------------------------------------------------------- 映射
@Test
void mapsUnpublishedItem() {
ProductListing p = adapter(transport()).pull(context(), ProductQuery.builder().build())
.items().get(0);
assertEquals("5212572", p.platformSku());
assertEquals("1YKTCEME6DEH", p.listingId());
assertEquals("00888555387476", p.gtin());
assertEquals("Obermeyer Kid's Ultra Gear Bottom", p.title());
assertEquals("USD", p.currency());
assertEquals("34.5", p.price().amount().toPlainString());
// 未发布即不可售,即使生命周期仍是 ACTIVE
assertEquals(ProductStatus.INACTIVE, p.status());
assertEquals("UNPUBLISHED/ACTIVE", p.rawStatus());
}
@Test
void mapsPublishedActiveItem() {
ProductListing p = adapter(transport()).pull(context(), ProductQuery.builder().build())
.items().get(1);
assertEquals(ProductStatus.ACTIVE, p.status());
assertEquals("PUBLISHED/ACTIVE", p.rawStatus());
}
@Test
void archivedLifecycleMapsToInactiveEvenIfPublished() {
ProductListing p = adapter(transport()).pull(context(), ProductQuery.builder().build())
.items().get(2);
assertEquals(ProductStatus.INACTIVE, p.status());
assertEquals("PUBLISHED/RETIRED", p.rawStatus());
// 没有 gtin 时回落 upc
assertEquals("888555387490", p.gtin());
}
@Test
void parsesShelfJsonString() {
List<ProductListing> items = adapter(transport()).pull(context(), ProductQuery.builder().build())
.items();
assertEquals(Collections.singletonList("UNNAV"), items.get(0).attributes().get("shelf"));
assertEquals(Arrays.asList("Home Page", "Clothing"), items.get(1).attributes().get("shelf"));
// 原文也保留一份,便于对照平台
assertEquals("[\"UNNAV\"]", items.get(0).attributes().get("shelfRaw"));
}
@Test
void keepsUnpublishedReasonsInAttributes() {
ProductListing p = adapter(transport()).pull(context(), ProductQuery.builder().build())
.items().get(0);
Object reasons = p.attributes().get("unpublishedReasons");
assertTrue(reasons instanceof List, String.valueOf(reasons));
assertEquals(2, ((List<?>) reasons).size());
}
@Test
void malformedShelfFallsBackToRawString() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/items", r -> Responses.ok(
"{\"ItemResponse\":[{\"sku\":\"S1\",\"shelf\":\"NOT_JSON\","
+ "\"publishedStatus\":\"PUBLISHED\",\"lifecycleStatus\":\"ACTIVE\"}]}"));
ProductListing p = adapter(transport).pull(context(), ProductQuery.builder().build())
.items().get(0);
assertEquals(Collections.singletonList("NOT_JSON"), p.attributes().get("shelf"));
}
@Test
void itemWithoutSkuIsSkipped() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/items", r -> Responses.ok(
"{\"ItemResponse\":[{\"productName\":\"no sku\"},{\"sku\":\"S2\"}]}"));
Page<ProductListing> page = adapter(transport).pull(context(), ProductQuery.builder().build());
assertEquals(1, page.size());
assertEquals("S2", page.items().get(0).platformSku());
}
@Test
void nextCursorIsReturned() {
Page<ProductListing> page = adapter(transport()).pull(context(), ProductQuery.builder().build());
assertEquals("FGluY2x1ZGQ==", page.nextCursor());
}
@Test
void getUsesSkuPath() {
RecordingTransport transport = transport();
ProductListing item = adapter(transport).get(context(),
common.ecommerce.channel.model.product.ProductRef.of("5212572"));
assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/items/5212572");
assertEquals("Detail Item", item.title());
}
@Test
void unknownStatusMapsToUnknown() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/items", r -> Responses.ok(
"{\"ItemResponse\":[{\"sku\":\"S3\",\"publishedStatus\":\"WHATEVER\"}]}"));
ProductListing p = adapter(transport).pull(context(), ProductQuery.builder().build())
.items().get(0);
assertEquals(ProductStatus.UNKNOWN, p.status());
assertEquals("WHATEVER/UNKNOWN", p.rawStatus());
}
@Test
void itemWithoutPriceHasNullPrice() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/items", r -> Responses.ok(
"{\"ItemResponse\":[{\"sku\":\"S4\",\"publishedStatus\":\"PUBLISHED\","
+ "\"lifecycleStatus\":\"ACTIVE\"}]}"));
ProductListing p = adapter(transport).pull(context(), ProductQuery.builder().build())
.items().get(0);
assertNull(p.price());
assertNull(p.currency());
}
}

210
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartReturnTest.java

@ -0,0 +1,210 @@ @@ -0,0 +1,210 @@
package common.ecommerce.walmart.adapter;
import common.ecommerce.channel.model.aftersale.AfterSale;
import common.ecommerce.channel.model.aftersale.AfterSaleQuery;
import common.ecommerce.channel.model.aftersale.AfterSaleType;
import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.JsonFixture;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.walmart.WalmartConstants;
import org.junit.jupiter.api.Test;
import java.time.LocalDate;
import java.util.Collections;
import java.util.List;
import static common.ecommerce.walmart.support.WalmartTestSupport.ENDPOINT;
import static common.ecommerce.walmart.support.WalmartTestSupport.adapter;
import static common.ecommerce.walmart.support.WalmartTestSupport.assertUrlContains;
import static common.ecommerce.walmart.support.WalmartTestSupport.context;
import static common.ecommerce.walmart.support.WalmartTestSupport.lastUrl;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** 沃尔玛售后:1 个退货单拆 N 个售后行 + 查询串型游标。 */
class WalmartReturnTest {
private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
private RecordingTransport transport() {
return RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/returns", r -> Responses.ok(JsonFixture.load("fixtures/walmart/returns/list.json")));
}
private static AfterSaleQuery query() {
return AfterSaleQuery.builder()
.startDate(LocalDate.of(2026, 11, 1))
.endDate(LocalDate.of(2026, 11, 18))
.build();
}
// ---------------------------------------------------------------- 请求
@Test
void pullSendsCreatedWindowAndLimit() {
RecordingTransport transport = transport();
adapter(transport).pull(context(), query());
String url = lastUrl(transport);
assertUrlContains(url, ENDPOINT + WalmartConstants.PATH_RETURNS);
assertUrlContains(url, "createdStartDate=2026-11-01T00%3A00%3A00.000Z");
assertUrlContains(url, "createdEndDate=2026-11-18T00%3A00%3A00.000Z");
assertUrlContains(url, "limit=100");
assertUrlContains(url, "offset=0");
}
@Test
void cursorIsASingleQueryStringAppendedAsIs() {
RecordingTransport transport = transport();
adapter(transport).pull(context(), query().toBuilder()
.cursor("?sellerId=151&limit=10&offset=10")
.build());
String url = lastUrl(transport);
// 游标整串追加,不再二次编码,也不重复加 ?
assertUrlContains(url, ENDPOINT + WalmartConstants.PATH_RETURNS
+ "?sellerId=151&limit=10&offset=10");
assertEquals(1, countOccurrences(url, '?'), url);
}
@Test
void nonSaleTimeDateTypeIsRejected() {
RecordingTransport transport = transport();
ValidationException ex = assertThrows(ValidationException.class,
() -> adapter(transport).pull(context(), query().toBuilder()
.dateType(AfterSaleQuery.DateType.UPDATE_TIME)
.build()));
assertTrue(ex.getMessage().contains("return-created date"), ex.getMessage());
assertEquals(0, transport.recorded().size());
}
@Test
void orderIdFilterIsRejected() {
RecordingTransport transport = transport();
assertThrows(ValidationException.class,
() -> adapter(transport).pull(context(), query().toBuilder()
.channelOrderIds(Collections.singletonList("123"))
.build()));
}
// ---------------------------------------------------------------- 映射
@Test
void oneReturnOrderExpandsToAllLines() {
Page<AfterSale> page = adapter(transport()).pull(context(), query());
// 一个退货单里两个退货行
assertEquals(2, page.size());
}
@Test
void mapsFirstLine() {
AfterSale a = adapter(transport()).pull(context(), query()).items().get(0);
assertEquals("103738048909818825:1", a.afterSaleId());
assertEquals("4790210558890", a.channelOrderId());
// REPLACEMENT → EXCHANGE
assertEquals(AfterSaleType.EXCHANGE, a.type());
assertEquals("REPLACEMENT", a.rawType());
assertEquals("COMPLETED", a.status());
assertEquals("ARRIVED_LATE", a.reason());
// 退货接口的数量是数字,不是字符串
assertEquals(3, a.quantity());
assertEquals("ANTL_GDL-0700", a.platformSku());
// 应退金额:chargeTotals 里的 lineTotal(退货行合计)优先
assertEquals("359.85", a.refundAmount().amount().toPlainString());
// 已退金额:refundedQty(1) × unitPrice(119.95),与应退分开
assertEquals("119.95 USD", a.attributes().get("refundedAmount"));
assertEquals("USD", a.refundAmount().currencyCode());
assertEquals("FEDEX", a.carrier());
assertEquals("785611449666", a.trackingNumber());
assertEquals("1234567891234", a.exchangeOrderId());
assertNotNull(a.afterSaleTime());
assertEquals("2019-02-21T01:01:08Z", a.afterSaleTime().utc().toString());
assertEquals("2019-03-02T05:45:45Z", a.updatedAt().utc().toString());
}
@Test
void refundFallsBackToUnitPriceTimesQuantity() {
AfterSale a = adapter(transport()).pull(context(), query()).items().get(1);
// 第二行没有 chargeTotals:79.5 × 1 = 79.5(不做额外舍入)
assertEquals("79.5", a.refundAmount().amount().toPlainString());
// 第二行没有分组面单,承运商为空
assertNull(a.carrier());
assertNull(a.trackingNumber());
}
@Test
void keepsRefundDetailInAttributes() {
AfterSale a = adapter(transport()).pull(context(), query()).items().get(0);
assertEquals("POST_DELIVERY", a.attributes().get("refundMode"));
assertEquals("IN_STORE", a.attributes().get("returnChannel"));
assertEquals("REFUND_INITIATED", a.attributes().get("currentRefundStatus"));
assertEquals("NOT_SHIPPED", a.attributes().get("currentDeliveryStatus"));
assertEquals(Boolean.TRUE, a.attributes().get("returnExpectedFlag"));
assertEquals("127.45 USD", a.attributes().get("totalRefundAmount"));
}
@Test
void lineStatusTimeIsUsedForUpdateTime() {
AfterSale a = adapter(transport()).pull(context(), query()).items().get(1);
assertEquals("IN_TRANSIT", a.status());
assertEquals("2019-03-01T00:00:00Z", a.updatedAt().utc().toString());
}
@Test
void nextCursorIsTheRawQueryString() {
assertEquals("?sellerId=151&limit=10&offset=10",
adapter(transport()).pull(context(), query()).nextCursor());
}
@Test
void returnWithoutLinesIsDropped() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/returns", r -> Responses.ok(
"{\"meta\":{\"totalCount\":0},\"returnOrders\":[{\"returnOrderId\":\"R1\"}]}"));
List<AfterSale> items = adapter(transport).pull(context(), query()).items();
assertTrue(items.isEmpty());
}
@Test
void unknownReturnTypeMapsToUnknown() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/returns", r -> Responses.ok(
"{\"returnOrders\":[{\"returnOrderId\":\"R2\",\"returnType\":\"SOMETHING\","
+ "\"returnOrderLines\":[{\"returnOrderLineNumber\":1,\"status\":\"INITIATED\"}]}]}"));
AfterSale a = adapter(transport).pull(context(), query()).items().get(0);
assertEquals(AfterSaleType.UNKNOWN, a.type());
assertEquals("SOMETHING", a.rawType());
}
@Test
void badStatusTimeDoesNotBreakThePage() {
RecordingTransport transport = RecordingTransport.create()
.route("/v3/token", r -> Responses.ok(TOKEN_BODY))
.route("/v3/returns", r -> Responses.ok(
"{\"returnOrders\":[{\"returnOrderId\":\"R3\",\"returnOrderDate\":\"not-a-date\","
+ "\"returnOrderLines\":[{\"returnOrderLineNumber\":1,"
+ "\"statusTime\":\"2026-13-45\"}]}]}"));
AfterSale a = adapter(transport).pull(context(), query()).items().get(0);
assertNull(a.afterSaleTime());
assertNull(a.updatedAt());
}
private static int countOccurrences(String text, char c) {
int count = 0;
for (int i = 0; i < text.length(); i++) {
if (text.charAt(i) == c) {
count++;
}
}
return count;
}
}

131
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/enums/WalmartStatusMappingTest.java

@ -0,0 +1,131 @@ @@ -0,0 +1,131 @@
package common.ecommerce.walmart.enums;
import common.ecommerce.channel.model.aftersale.AfterSaleType;
import common.ecommerce.channel.model.product.ProductStatus;
import org.junit.jupiter.api.Test;
import java.util.Arrays;
import java.util.Collections;
import static org.junit.jupiter.api.Assertions.assertEquals;
/** 状态映射的边界值:精确匹配、未知值、空值。 */
class WalmartStatusMappingTest {
// ---------------------------------------------------------------- 订单状态聚合
@Test
void singleCreatedLineIsCreated() {
assertEquals(WalmartOrderStatus.CREATED,
WalmartOrderStatus.aggregate(Collections.singletonList("Created")));
}
@Test
void acknowledgedOnlyIsAcknowledged() {
assertEquals(WalmartOrderStatus.ACKNOWLEDGED,
WalmartOrderStatus.aggregate(Collections.singletonList("Acknowledged")));
}
@Test
void allCancelledIsCancelled() {
assertEquals(WalmartOrderStatus.CANCELLED,
WalmartOrderStatus.aggregate(Arrays.asList("Cancelled", "Cancelled")));
}
@Test
void allDeliveredIsDelivered() {
assertEquals(WalmartOrderStatus.DELIVERED,
WalmartOrderStatus.aggregate(Arrays.asList("Delivered", "Delivered")));
}
@Test
void partiallyShippedStaysCreatedBecauseLinesRemain() {
// 还有未发货的行:订单仍需发货动作,逐行状态看 OrderLine.status()
assertEquals(WalmartOrderStatus.CREATED,
WalmartOrderStatus.aggregate(Arrays.asList("Created", "Shipped")));
}
@Test
void shippedAndCancelledMixIsShipped() {
assertEquals(WalmartOrderStatus.SHIPPED,
WalmartOrderStatus.aggregate(Arrays.asList("Shipped", "Cancelled")));
}
@Test
void createdWinsOverAcknowledged() {
assertEquals(WalmartOrderStatus.CREATED,
WalmartOrderStatus.aggregate(Arrays.asList("Acknowledged", "Created")));
}
@Test
void unknownValueIsIgnoredButDoesNotPoison() {
assertEquals(WalmartOrderStatus.CREATED,
WalmartOrderStatus.aggregate(Arrays.asList("Created", "Bogus")));
}
@Test
void allUnknownIsUnknown() {
assertEquals(WalmartOrderStatus.UNKNOWN,
WalmartOrderStatus.aggregate(Arrays.asList("Bogus", null)));
assertEquals(WalmartOrderStatus.UNKNOWN, WalmartOrderStatus.aggregate(Collections.<String>emptyList()));
assertEquals(WalmartOrderStatus.UNKNOWN, WalmartOrderStatus.aggregate(null));
}
@Test
void matchingIsExactNotContains() {
// 模糊匹配会把 "NotCreated" 判成 Created
assertEquals(WalmartOrderStatus.UNKNOWN, WalmartOrderStatus.fromRaw("NotCreated"));
assertEquals(WalmartOrderStatus.UNKNOWN, WalmartOrderStatus.fromRaw("created"));
assertEquals(WalmartOrderStatus.CREATED, WalmartOrderStatus.fromRaw("Created"));
}
// ---------------------------------------------------------------- 商品状态
@Test
void publishedActiveIsActive() {
assertEquals(ProductStatus.ACTIVE,
WalmartPublishedStatus.toProductStatus("PUBLISHED", "ACTIVE"));
}
@Test
void publishedArchivedIsInactive() {
assertEquals(ProductStatus.INACTIVE,
WalmartPublishedStatus.toProductStatus("PUBLISHED", "ARCHIVED"));
assertEquals(ProductStatus.INACTIVE,
WalmartPublishedStatus.toProductStatus("PUBLISHED", "RETIRED"));
}
@Test
void unpublishedAnythingIsInactive() {
assertEquals(ProductStatus.INACTIVE,
WalmartPublishedStatus.toProductStatus("UNPUBLISHED", "ACTIVE"));
assertEquals(ProductStatus.INACTIVE,
WalmartPublishedStatus.toProductStatus("STAGE", "ACTIVE"));
assertEquals(ProductStatus.INACTIVE,
WalmartPublishedStatus.toProductStatus("IN_PROGRESS", null));
assertEquals(ProductStatus.INACTIVE,
WalmartPublishedStatus.toProductStatus("SYSTEM_PROBLEM", null));
}
@Test
void unknownPublishedStatusIsUnknown() {
assertEquals(ProductStatus.UNKNOWN, WalmartPublishedStatus.toProductStatus(null, "ACTIVE"));
assertEquals(ProductStatus.UNKNOWN, WalmartPublishedStatus.toProductStatus("BOGUS", "ACTIVE"));
}
@Test
void rawStatusCombinesBothDimensions() {
assertEquals("UNPUBLISHED/ACTIVE", WalmartPublishedStatus.rawStatus("UNPUBLISHED", "ACTIVE"));
assertEquals("UNKNOWN/UNKNOWN", WalmartPublishedStatus.rawStatus(null, null));
}
// ---------------------------------------------------------------- 售后类型
@Test
void returnTypeMapping() {
assertEquals(AfterSaleType.RETURN, WalmartReturnType.toCore("RETURN"));
assertEquals(AfterSaleType.EXCHANGE, WalmartReturnType.toCore("REPLACEMENT"));
assertEquals(AfterSaleType.UNKNOWN, WalmartReturnType.toCore("SOMETHING"));
assertEquals(AfterSaleType.UNKNOWN, WalmartReturnType.toCore(null));
}
}

132
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/http/WalmartErrorsTest.java

@ -0,0 +1,132 @@ @@ -0,0 +1,132 @@
package common.ecommerce.walmart.http;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.error.AuthException;
import common.ecommerce.shared.error.RateLimitException;
import common.ecommerce.shared.error.TransientException;
import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.shared.testkit.JsonFixture;
import common.ecommerce.shared.testkit.Responses;
import org.junit.jupiter.api.Test;
import java.util.Collections;
import static common.ecommerce.walmart.support.WalmartTestSupport.context;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/** 两种错误格式的解析与异常分类。 */
class WalmartErrorsTest {
private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
private final WalmartErrors errors = new WalmartErrors(JSON);
private final ChannelContext ctx = context();
@Test
void gatewayErrorFormatCarriesCodeAndDescription() {
HttpResponse response = Responses.withHeaders(400,
Collections.<String, String>emptyMap(),
JsonFixture.load("fixtures/walmart/errors/gateway-404.json"));
ValidationException ex = assertThrows(ValidationException.class,
() -> errors.throwIfError(response, ctx, "afterSales.pull"));
assertEquals("CONTENT_NOT_FOUND.GMP_GATEWAY_API", ex.platformCode());
assertTrue(ex.getMessage().contains("CONTENT_NOT_FOUND.GMP_GATEWAY_API"), ex.getMessage());
assertTrue(ex.getMessage().contains("No static resource"), ex.getMessage());
assertEquals("req-1", ex.requestId());
}
@Test
void routeLevelErrorFormatFallsBackToStatusAndMessage() {
HttpResponse response = Responses.status(404,
JsonFixture.load("fixtures/walmart/errors/route-404.json"));
ValidationException ex = assertThrows(ValidationException.class,
() -> errors.throwIfError(response, ctx, "salesOrders.get"));
// 没有业务码时用 HTTP 状态码兜底,消息里带平台原文
assertEquals("404", ex.platformCode());
assertTrue(ex.getMessage().contains("Request Not Found"), ex.getMessage());
}
@Test
void authFailureIsAuthException() {
HttpResponse response = Responses.status(401, "{\"error\":[{\"code\":\"UNAUTHORIZED\"}]}");
assertThrows(AuthException.class, () -> errors.throwIfError(response, ctx, "salesOrders.pull"));
}
@Test
void rateLimitHonoursRetryAfter() {
RateLimitException ex = assertThrows(RateLimitException.class,
() -> errors.throwIfError(Responses.rateLimited("7"), ctx, "products.pull"));
assertEquals(7_000L, ex.retryAfterMillis());
}
@Test
void rateLimitWithoutHeaderUsesOneSecond() {
RateLimitException ex = assertThrows(RateLimitException.class,
() -> errors.throwIfError(Responses.status(429, ""), ctx, "products.pull"));
assertEquals(1_000L, ex.retryAfterMillis());
}
@Test
void serverErrorIsRetryable() {
TransientException ex = assertThrows(TransientException.class,
() -> errors.throwIfError(Responses.status(520, "{\"error\":\"boom\"}"), ctx, "products.pull"));
assertTrue(ex.retryable());
}
@Test
void systemErrorCodeOn4xxIsAlsoRetryable() {
// 平台侧数据状态问题:HTTP 是 4xx,但重跑常能成功
HttpResponse response = Responses.status(400,
"{\"error\":[{\"code\":\"SYSTEM_ERROR.GMP_DATA_STATUS_API\",\"description\":\"try later\"}]}");
TransientException ex = assertThrows(TransientException.class,
() -> errors.throwIfError(response, ctx, "salesOrders.pull"));
assertTrue(ex.retryable());
assertEquals("SYSTEM_ERROR.GMP_DATA_STATUS_API", ex.platformCode());
}
@Test
void unknown4xxCodeIsNotGuessedAsRetryable() {
// 文档实测只有 CONTENT_NOT_FOUND.* 与 SYSTEM_ERROR.*;其余 4xx 按数据错误处理,
// 不做前缀猜测——猜错会把可重试错误判成终态
HttpResponse response = Responses.status(400,
"{\"error\":[{\"code\":\"SOME_UNKNOWN.CODE\",\"description\":\"nope\"}]}");
ValidationException ex = assertThrows(ValidationException.class,
() -> errors.throwIfError(response, ctx, "salesOrders.pull"));
assertEquals("SOME_UNKNOWN.CODE", ex.platformCode());
assertFalse(ex.retryable());
}
@Test
void successPassesThrough() {
errors.throwIfError(Responses.ok("{}"), ctx, "salesOrders.pull");
}
@Test
void emptyBodyStillThrowsByStatus() {
ValidationException ex = assertThrows(ValidationException.class,
() -> errors.throwIfError(Responses.status(400, ""), ctx, "products.get"));
assertEquals("400", ex.platformCode());
}
@Test
void rawResponseIsTruncated() {
StringBuilder big = new StringBuilder("{\"error\":[{\"description\":\"");
for (int i = 0; i < 5_000; i++) {
big.append('x');
}
big.append("\"}]}");
ValidationException ex = assertThrows(ValidationException.class,
() -> errors.throwIfError(Responses.status(400, big.toString()), ctx, "products.get"));
assertEquals(common.ecommerce.walmart.WalmartConstants.RAW_RESPONSE_LIMIT,
ex.rawResponse().length());
}
}

319
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/probe/WalmartProbeTest.java

@ -0,0 +1,319 @@ @@ -0,0 +1,319 @@
package common.ecommerce.walmart.probe;
import common.ecommerce.channel.model.aftersale.AfterSale;
import common.ecommerce.channel.model.aftersale.AfterSaleQuery;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.product.ProductListing;
import common.ecommerce.channel.model.product.ProductQuery;
import common.ecommerce.channel.model.product.ProductSearchField;
import common.ecommerce.channel.sdk.ChannelConnection;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.InMemoryLockProvider;
import common.ecommerce.shared.testkit.InMemoryTokenStore;
import common.ecommerce.walmart.adapter.WalmartAdapter;
import common.ecommerce.walmart.support.WalmartTestSupport;
import org.junit.jupiter.api.MethodOrderer;
import org.junit.jupiter.api.Order;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestInstance;
import org.junit.jupiter.api.TestMethodOrder;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
import java.time.Clock;
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneOffset;
import java.util.ArrayList;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 沃尔玛沙箱探针(<b>只读</b>)。
*
* <p>默认跳过,用 {@code -Dwalmart.probe=true} 显式开启;凭据走系统属性,
* <b>真实凭据不入库</b>:</p>
*
* <pre>
* mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
* -Dwalmart.probe=true \
* -Dwalmart.probe.clientId=你的clientId \
* -Dwalmart.probe.clientSecret=你的clientSecret \
* -Dtest=WalmartProbeTest test
* </pre>
*
* <p>可选:{@code -Dwalmart.probe.baseUrl=https://marketplace.walmartapis.com} 打生产环境
* (<b>只跑读接口</b>),{@code -Dwalmart.probe.sku=SKU} 单独查一个商品。</p>
*
* <h2>沙箱已知限制(2026-11-16 实测)</h2>
* <table>
* <tr><th>接口</th><th>沙箱行为</th></tr>
* <tr><td>GET /v3/items</td><td>固定 20 条,limit / sku / nextCursor 过滤不生效</td></tr>
* <tr><td>GET /v3/items/{sku}</td><td>404,mock 未实现</td></tr>
* <tr><td>GET /v3/orders</td><td>固定 12 条,过滤参数是否生效以生产为准</td></tr>
* <tr><td>GET /v3/returns</td><td>固定 10 条 totalCount=30,过滤参数不生效</td></tr>
* </table>
*
* <p>因此探针<b>不把 404 / 固定条数当失败</b>,只打印原始报文,方便逐条核对字段;
* 唯一硬断言是 token 能换到。</p>
*/
@EnabledIfSystemProperty(named = "walmart.probe", matches = "true")
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class WalmartProbeTest {
// 真实凭据不入库:本地跑探针时用 -D 传入
private static final String CLIENT_ID = System.getProperty("walmart.probe.clientId", "");
private static final String CLIENT_SECRET = System.getProperty("walmart.probe.clientSecret", "");
private static final String BASE_URL = System.getProperty("walmart.probe.baseUrl",
common.ecommerce.walmart.WalmartConstants.SANDBOX_BASE_URL);
private static final String SKU = System.getProperty("walmart.probe.sku", "");
private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
/** 打印用;真实 token 不打印,只打印前 12 位指纹。 */
private final LoggingTransport transport = new LoggingTransport(
new OkHttpTransport("common-ecommerce-walmart-probe"));
private final WalmartAdapter adapter = new WalmartAdapter(transport, JSON,
new InMemoryTokenStore(), new InMemoryLockProvider(), Clock.systemUTC());
/** 最近一次拉到的售后行;详情探针按它取一个 returnOrderId。 */
private List<AfterSale> lastAfterSales = new ArrayList<AfterSale>();
private final ChannelContext ctx = ChannelContext.of(
WalmartTestSupport.account("probe-store"),
ChannelConnection.of(BASE_URL, ChannelSecret.builder()
.clientId(CLIENT_ID).clientSecret(CLIENT_SECRET).build()),
"probe-1", Clock.systemUTC());
@Test
@Order(1)
void probeOrderList() {
requireCredentials();
section("GET /v3/orders createdStartDate=[now-7d, now]");
Instant to = Instant.now();
Instant from = to.minusSeconds(7 * 24 * 3600L);
probe(() -> {
Page<SalesOrder> page = adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(from).updatedBefore(to).pageSize(5).build());
System.out.println("orders=" + page.size() + " nextCursor=" + page.nextCursor());
for (SalesOrder order : page.items()) {
System.out.println(" " + order.channelOrderId()
+ " status=" + order.status()
+ " buyer=" + order.buyerName()
+ " addr=" + order.shipToAddress()
+ " lines=" + order.lines().size()
+ " total=" + order.totalAmount()
+ " at=" + order.occurredAt());
order.lines().forEach(line -> System.out.println(" line " + line.lineId()
+ " sku=" + line.platformSku()
+ " qty=" + line.quantity()
+ " status=" + line.status()
+ " unitPrice=" + line.unitPrice()
+ " tax=" + line.tax()));
}
});
}
@Test
@Order(2)
void probeOrderDetail() {
requireCredentials();
List<SalesOrder> orders = ordersOfLastWindow();
if (orders.isEmpty()) {
System.out.println("skip detail: no order in last 7 days");
return;
}
String id = orders.get(0).channelOrderId();
section("GET /v3/orders/" + id);
probe(() -> {
SalesOrder order = adapter.get(ctx,
common.ecommerce.channel.model.order.SalesOrderRef.of(id));
System.out.println("status=" + order.status() + " addr=" + order.shipToAddress());
});
}
@Test
@Order(3)
void probeItemList() {
requireCredentials();
section("GET /v3/items?limit=20");
probe(() -> {
Page<ProductListing> page = adapter.pull(ctx, ProductQuery.builder().pageSize(20).build());
System.out.println("items=" + page.size() + " nextCursor=" + page.nextCursor());
for (ProductListing item : page.items()) {
System.out.println(" " + item.platformSku()
+ " status=" + item.status() + "/" + item.rawStatus()
+ " price=" + item.price()
+ " shelf=" + item.attributes().get("shelf")
+ " reasons=" + item.attributes().get("unpublishedReasons"));
}
});
}
@Test
@Order(4)
void probeItemSearchAndDetail() {
requireCredentials();
String sku = SKU.isEmpty() ? "5212572" : SKU;
section("GET /v3/items?sku=" + sku + "(沙箱可能忽略该过滤)");
probe(() -> {
Page<ProductListing> page = adapter.pull(ctx, ProductQuery.builder()
.searchField(ProductSearchField.PLATFORM_SKU).searchValue(sku).build());
System.out.println("items=" + page.size() + " (沙箱固定 20 条属正常)");
});
section("GET /v3/items/" + sku + "(沙箱 404 属正常)");
probe(() -> System.out.println("detail=" + adapter.get(ctx,
common.ecommerce.channel.model.product.ProductRef.of(sku))));
}
@Test
@Order(5)
void probeReturns() {
requireCredentials();
LocalDate today = LocalDate.now(ZoneOffset.UTC);
section("GET /v3/returns createdStartDate=[" + today.minusDays(7) + ", " + today + "]");
probe(() -> {
Page<AfterSale> page = adapter.pull(ctx, AfterSaleQuery.builder()
.startDate(today.minusDays(7)).endDate(today).pageSize(10).build());
lastAfterSales = page.items();
System.out.println("afterSales=" + page.size() + " nextCursor=" + page.nextCursor());
for (AfterSale a : page.items()) {
System.out.println(" " + a.afterSaleId()
+ " type=" + a.type() + "/" + a.rawType()
+ " status=" + a.status()
+ " qty=" + a.quantity()
+ " refund=" + a.refundAmount()
+ " carrier=" + a.carrier()
+ " tracking=" + a.trackingNumber()
+ " refundStatus=" + a.attributes().get("currentRefundStatus"));
}
});
}
@Test
@Order(6)
void probeReturnDetail() {
requireCredentials();
List<AfterSale> page = lastAfterSales;
if (page.isEmpty()) {
System.out.println("skip return detail: no return in last 7 days (sandbox mock is fixed data)");
return;
}
String id = String.valueOf(page.get(0).attributes().get("returnOrderId"));
section("GET /v3/returns/" + id + "(沙箱 404 属正常)");
probe(() -> {
List<AfterSale> lines = adapter.getReturn(ctx, id);
System.out.println("detail afterSales=" + lines.size());
for (AfterSale a : lines) {
System.out.println(" " + a.afterSaleId() + " status=" + a.status()
+ " refund=" + a.refundAmount());
}
});
}
@Test
@Order(7)
void probeOrderShipping() {
requireCredentials();
List<SalesOrder> orders = ordersOfLastWindow();
if (orders.isEmpty()) {
System.out.println("skip shipping: no order in last 7 days");
return;
}
String id = orders.get(0).channelOrderId();
section("GET /v3/orders/" + id + "/shipping(沙箱 404 属正常)");
probe(() -> {
List<common.ecommerce.walmart.mapper.WalmartShipmentMapper.ShipmentLine> lines =
adapter.getShipping(ctx, id);
System.out.println("shipped lines=" + lines.size());
for (common.ecommerce.walmart.mapper.WalmartShipmentMapper.ShipmentLine line : lines) {
System.out.println(" " + line);
}
});
}
// ---------------------------------------------------------------- internals
/** 探针不因平台 404 / 固定条数失败:打印异常后继续跑下一段。 */
private static void probe(Runnable action) {
try {
action.run();
} catch (ChannelException e) {
System.out.println(" !! " + e.getClass().getSimpleName()
+ " code=" + e.platformCode() + " : " + e.getMessage());
} catch (RuntimeException e) {
System.out.println(" !! " + e.getClass().getSimpleName() + " : " + e.getMessage());
}
}
private List<SalesOrder> ordersOfLastWindow() {
List<SalesOrder> out = new ArrayList<SalesOrder>();
try {
Instant to = Instant.now();
out.addAll(adapter.pull(ctx, SalesOrderQuery.builder()
.updatedAfter(to.minusSeconds(7 * 24 * 3600L)).updatedBefore(to).build()).items());
} catch (RuntimeException e) {
System.out.println(" order window unavailable: " + e.getMessage());
}
return out;
}
private static void requireCredentials() {
assertTrue(!CLIENT_ID.isEmpty() && !CLIENT_SECRET.isEmpty(),
"set -Dwalmart.probe.clientId=... -Dwalmart.probe.clientSecret=... "
+ "(或用环境变量注入后转成系统属性)");
}
private static void section(String title) {
System.out.println("\n========== " + title + " ==========");
}
/** 打印请求与响应摘要;token 头只打印前缀。 */
private static final class LoggingTransport implements HttpTransport {
private final HttpTransport delegate;
private LoggingTransport(HttpTransport delegate) {
this.delegate = delegate;
}
@Override
public HttpResponse execute(HttpRequest request) {
System.out.println("-> " + request.method() + " " + request.url());
System.out.println(" corr=" + request.headers().get("WM_QOS.CORRELATION_ID")
+ " token=" + mask(request.headers().get("WM_SEC.ACCESS_TOKEN"))
+ " count=" + request.headers().get("x-current-token-count"));
HttpResponse response = delegate.execute(request);
System.out.println("<- " + response.statusCode()
+ " tokenCount=" + response.header("x-current-token-count")
+ " body=" + shorten(response.body()));
return response;
}
private static String mask(String token) {
if (token == null) {
return "null";
}
return token.length() <= 12 ? "***" : token.substring(0, 12) + "...";
}
private static String shorten(String body) {
if (body == null) {
return "null";
}
return body.length() <= 1_200 ? body : body.substring(0, 1_200) + "...(" + body.length() + " chars)";
}
}
}

112
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/support/WalmartTestSupport.java

@ -0,0 +1,112 @@ @@ -0,0 +1,112 @@
package common.ecommerce.walmart.support;
import common.ecommerce.channel.model.account.AccountKey;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.sdk.ChannelConnection;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.shared.model.ChannelProvider;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.shared.testkit.InMemoryLockProvider;
import common.ecommerce.shared.testkit.InMemoryTokenStore;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.walmart.WalmartConstants;
import common.ecommerce.walmart.adapter.WalmartAdapter;
import common.ecommerce.http.JacksonJsonCodec;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
/**
* 沃尔玛测试的公共样板:固定时钟、固定账户、组装适配器。
*
* <p>各契约测试只关心「请求怎么拼」和「响应怎么映射」,
* token、缓存、错误映射的装配都在这里完成。</p>
*/
public final class WalmartTestSupport {
/** 认的 clientId / secret;测试里不出现真实凭据。 */
public static final String CLIENT_ID = "test-client-id";
public static final String CLIENT_SECRET = "test-client-secret";
/** 沙箱端点,与线上地址格式一致。 */
public static final String ENDPOINT = WalmartConstants.SANDBOX_BASE_URL;
/** 固定时钟:2026-11-18T00:00:00Z,测试里的「现在」。 */
public static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-18T00:00:00Z"), ZoneOffset.UTC);
public static final JacksonJsonCodec JSON = new JacksonJsonCodec();
private WalmartTestSupport() {
}
/** 沃尔玛直连账户。 */
public static ChannelAccount account() {
return account("oms-wm-001");
}
/** 指定 OMS 店铺 ID 的账户。 */
public static ChannelAccount account(String omsStoreId) {
return ChannelAccount.builder()
.key(AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, omsStoreId))
.externalStoreId("wm-seller-01")
.credentialRef("kms://test/walmart")
.marketplaceZone("America/Chicago")
.currency("USD")
.build();
}
/** 连接:端点 + 凭据。 */
public static ChannelConnection connection() {
return ChannelConnection.of(ENDPOINT, ChannelSecret.builder()
.clientId(CLIENT_ID)
.clientSecret(CLIENT_SECRET)
.build());
}
/** 一次调用的上下文。 */
public static ChannelContext context() {
return ChannelContext.of(account(), connection(), "req-1", CLOCK);
}
/** 带指定账户与链路 ID 的上下文。 */
public static ChannelContext context(ChannelAccount account, String requestId) {
return ChannelContext.of(account, connection(), requestId, CLOCK);
}
/** 装配一个使用内存令牌存储与锁的适配器。 */
public static WalmartAdapter adapter(RecordingTransport transport) {
return adapter(transport, new InMemoryTokenStore(), new InMemoryLockProvider());
}
public static WalmartAdapter adapter(RecordingTransport transport, TokenStore tokens, LockProvider locks) {
return new WalmartAdapter(transport, JSON, tokens, locks, CLOCK);
}
/** 业务请求(排除令牌请求)。 */
public static List<HttpRequest> dataRequests(RecordingTransport transport) {
return transport.dataRequests();
}
/** 最后一个请求的 URL。 */
public static String lastUrl(RecordingTransport transport) {
List<HttpRequest> requests = transport.recorded();
if (requests.isEmpty()) {
throw new IllegalStateException("no request recorded");
}
return requests.get(requests.size() - 1).url();
}
/** 断言 URL 含某段;失败时打印完整 URL 便于定位。 */
public static void assertUrlContains(String url, String expected) {
if (url == null || !url.contains(expected)) {
throw new AssertionError("expected url to contain <" + expected + "> but was <" + url + ">");
}
}
}

13
channel-sdk-walmart/src/test/resources/fixtures/walmart/errors/gateway-404.json

@ -0,0 +1,13 @@ @@ -0,0 +1,13 @@
{
"error": [
{
"code": "CONTENT_NOT_FOUND.GMP_GATEWAY_API",
"description": "No static resource v3/returns/103738048909818825.",
"info": "Requested content could not be found.",
"severity": "INFO",
"category": "APPLICATION",
"causes": [],
"errorIdentifiers": {}
}
]
}

6
channel-sdk-walmart/src/test/resources/fixtures/walmart/errors/route-404.json

@ -0,0 +1,6 @@ @@ -0,0 +1,6 @@
{
"timestamp": "2026-11-16T07:23:08Z",
"status": 404,
"error": "Request Not Found, Please correct the request!",
"path": "/v3/orders/INVALID-PO-999/shipping"
}

49
channel-sdk-walmart/src/test/resources/fixtures/walmart/items/list.json

@ -0,0 +1,49 @@ @@ -0,0 +1,49 @@
{
"ItemResponse": [
{
"mart": "WALMART_US",
"sku": "5212572",
"wpid": "1YKTCEME6DEH",
"upc": "888555387476",
"gtin": "00888555387476",
"productName": "Obermeyer Kid's Ultra Gear Bottom",
"shelf": "[\"UNNAV\"]",
"productType": "T-Shirts",
"price": { "currency": "USD", "amount": 34.5 },
"publishedStatus": "UNPUBLISHED",
"unpublishedReasons": {
"reason": [
"No shipping information was set up.",
"There is no primary image for your item."
]
},
"lifecycleStatus": "ACTIVE"
},
{
"mart": "WALMART_US",
"sku": "5212573",
"wpid": "1YKTCEME6DEJ",
"gtin": "00888555387483",
"productName": "Published Item",
"shelf": "[\"Home Page\",\"Clothing\"]",
"productType": "Pants",
"price": { "currency": "USD", "amount": 19.99 },
"publishedStatus": "PUBLISHED",
"lifecycleStatus": "ACTIVE"
},
{
"mart": "WALMART_US",
"sku": "5212574",
"wpid": "1YKTCEME6DEK",
"upc": "888555387490",
"productName": "Retired Item",
"shelf": "[\"UNNAV\"]",
"productType": "Pants",
"price": { "currency": "USD", "amount": 9.5 },
"publishedStatus": "PUBLISHED",
"lifecycleStatus": "RETIRED"
}
],
"totalItems": 20,
"nextCursor": "FGluY2x1ZGQ=="
}

56
channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/detail.json

@ -0,0 +1,56 @@ @@ -0,0 +1,56 @@
{
"order": {
"purchaseOrderId": "108816631915371",
"customerOrderId": "100000159992851",
"customerEmailId": "emailID123456@relay.walmart.com",
"orderDate": 1686736267000,
"shippingInfo": {
"phone": "555-0100",
"methodCode": "Value",
"postalAddress": {
"name": "Astro Test",
"address1": "5809 W 44th Ave",
"city": "Lakeside",
"state": "CO",
"postalCode": "80212",
"country": "USA",
"addressType": "OFFICE"
}
},
"orderLines": {
"orderLine": [
{
"lineNumber": "1",
"item": {
"productName": "Delta Children Disney Mickey Mouse Upholstered Toddler Chair with Side Pockets",
"sku": "67022229561Test5_skuUpdate"
},
"charges": {
"charge": [
{
"chargeType": "PRODUCT",
"chargeName": "ItemPrice",
"chargeAmount": { "currency": "USD", "amount": 499.99 },
"tax": {
"taxName": "Tax1",
"taxAmount": { "currency": "USD", "amount": 29.72 }
}
}
]
},
"orderLineQuantity": { "unitOfMeasurement": "EACH", "amount": "1" },
"orderLineStatuses": {
"orderLineStatus": [
{
"status": "Created",
"statusQuantity": { "unitOfMeasurement": "EACH", "amount": "1" },
"trackingInfo": null
}
]
}
}
]
},
"shipNode": { "type": "SellerFulfilled" }
}
}

330
channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/list.json

@ -0,0 +1,330 @@ @@ -0,0 +1,330 @@
{
"list": {
"meta": {
"totalCount": 12,
"limit": 5,
"nextCursor": null
},
"elements": {
"order": [
{
"purchaseOrderId": "108816631915371",
"customerOrderId": "100000159992851",
"customerEmailId": "emailID123456@relay.walmart.com",
"orderDate": 1686736267000,
"shippingInfo": {
"phone": "555-0100",
"estimatedShipDate": 1686822667000,
"estimatedDeliveryDate": 1686995467000,
"methodCode": "Value",
"postalAddress": {
"name": "Astro Test",
"address1": "5809 W 44th Ave",
"address2": null,
"city": "Lakeside",
"state": "CO",
"postalCode": "80212",
"country": "USA",
"addressType": "OFFICE"
}
},
"orderLines": {
"orderLine": [
{
"lineNumber": "1",
"item": {
"productName": "Delta Children Disney Mickey Mouse Upholstered Toddler Chair",
"sku": "67022229561Test5_skuUpdate"
},
"charges": {
"charge": [
{
"chargeType": "PRODUCT",
"chargeName": "ItemPrice",
"chargeAmount": {
"currency": "USD",
"amount": 499.99
},
"tax": {
"taxName": "Tax1",
"taxAmount": {
"currency": "USD",
"amount": 29.72
}
}
},
{
"chargeType": "SHIPPING",
"chargeName": "Shipping",
"chargeAmount": {
"currency": "USD",
"amount": 0.0
},
"tax": {
"taxName": "Tax1",
"taxAmount": {
"currency": "USD",
"amount": 0.0
}
}
}
]
},
"orderLineQuantity": {
"unitOfMeasurement": "EACH",
"amount": "1"
},
"statusDate": 1686736267000,
"orderLineStatuses": {
"orderLineStatus": [
{
"status": "Created",
"statusQuantity": {
"unitOfMeasurement": "EACH",
"amount": "1"
},
"trackingInfo": null
}
]
}
}
]
},
"shipNode": {
"type": "SellerFulfilled"
}
},
{
"purchaseOrderId": "108816631915372",
"customerOrderId": "100000159992852",
"orderDate": 1686736300000,
"shippingInfo": {
"methodCode": "Standard",
"postalAddress": {
"name": "Second Buyer",
"address1": "1 Main St",
"city": "Dallas",
"state": "TX",
"postalCode": "75201",
"country": "USA",
"addressType": "RESIDENTIAL"
}
},
"orderLines": {
"orderLine": [
{
"lineNumber": "1",
"item": {
"productName": "Chair",
"sku": "SKU-1"
},
"orderLineQuantity": {
"unitOfMeasurement": "EACH",
"amount": "1"
},
"orderLineStatuses": {
"orderLineStatus": [
{
"status": "Shipped",
"statusQuantity": {
"unitOfMeasurement": "EACH",
"amount": "1"
},
"trackingInfo": {
"shipDateTime": "2026-11-16T07:00:00.000Z",
"carrierName": {
"carrier": "UPS"
},
"methodCode": "Standard",
"trackingNumber": "1Z999AA10123456784"
}
}
]
}
}
]
},
"shipNode": {
"type": "SellerFulfilled"
}
},
{
"purchaseOrderId": "108816631915373",
"customerOrderId": "C-108816631915373",
"orderDate": 1686736400000,
"shippingInfo": {
"methodCode": "Value",
"postalAddress": {
"name": "History Buyer",
"address1": "9 Elm St",
"city": "Austin",
"state": "TX",
"postalCode": "73301",
"country": "USA",
"addressType": "RESIDENTIAL"
}
},
"orderLines": {
"orderLine": [
{
"lineNumber": "1",
"item": {
"productName": "Partially Shipped Chair",
"sku": "SKU-PARTIAL"
},
"orderLineQuantity": {
"unitOfMeasurement": "EACH",
"amount": "3"
},
"orderLineStatuses": {
"orderLineStatus": [
{
"status": "Created",
"statusQuantity": {
"unitOfMeasurement": "EACH",
"amount": "2"
},
"trackingInfo": null
},
{
"status": "Shipped",
"statusQuantity": {
"unitOfMeasurement": "EACH",
"amount": "1"
},
"trackingInfo": null
}
]
}
}
]
},
"shipNode": {
"type": "SellerFulfilled"
}
},
{
"purchaseOrderId": "108816631915374",
"customerOrderId": "C-108816631915374",
"orderDate": 1686736400000,
"shippingInfo": {
"methodCode": "Value",
"postalAddress": {
"name": "History Buyer",
"address1": "9 Elm St",
"city": "Austin",
"state": "TX",
"postalCode": "73301",
"country": "USA",
"addressType": "RESIDENTIAL"
}
},
"orderLines": {
"orderLine": [
{
"lineNumber": "1",
"item": {
"productName": "Fully Shipped Chair",
"sku": "SKU-FULL"
},
"orderLineQuantity": {
"unitOfMeasurement": "EACH",
"amount": "3"
},
"orderLineStatuses": {
"orderLineStatus": [
{
"status": "Created",
"statusQuantity": {
"unitOfMeasurement": "EACH",
"amount": "0"
},
"trackingInfo": null
},
{
"status": "Shipped",
"statusQuantity": {
"unitOfMeasurement": "EACH",
"amount": "3"
},
"trackingInfo": null
}
]
}
}
]
},
"shipNode": {
"type": "SellerFulfilled"
}
},
{
"purchaseOrderId": "108816631915375",
"customerOrderId": "C-108816631915375",
"orderDate": 1686736500000,
"shippingInfo": {
"methodCode": "Value",
"postalAddress": {
"name": "Multi Qty Buyer",
"address1": "1 Two St",
"city": "Denver",
"state": "CO",
"postalCode": "80202",
"country": "USA",
"addressType": "RESIDENTIAL"
}
},
"orderLines": {
"orderLine": [
{
"lineNumber": "1",
"item": {
"productName": "Two Pack",
"sku": "SKU-MULTI"
},
"charges": {
"charge": [
{
"chargeType": "PRODUCT",
"chargeName": "ItemPrice",
"chargeAmount": {
"currency": "USD",
"amount": 99.98
},
"tax": {
"taxName": "Tax1",
"taxAmount": {
"currency": "USD",
"amount": 5.94
}
}
}
]
},
"orderLineQuantity": {
"unitOfMeasurement": "EACH",
"amount": "2"
},
"orderLineStatuses": {
"orderLineStatus": [
{
"status": "Created",
"statusQuantity": {
"unitOfMeasurement": "EACH",
"amount": "2"
},
"trackingInfo": null
}
]
}
}
]
},
"shipNode": {
"type": "SellerFulfilled"
}
}
]
}
}
}

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

@ -0,0 +1,59 @@ @@ -0,0 +1,59 @@
{
"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

@ -0,0 +1,52 @@ @@ -0,0 +1,52 @@
{
"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"
}
]
}

82
channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/list.json

@ -0,0 +1,82 @@ @@ -0,0 +1,82 @@
{
"meta": { "totalCount": 30, "limit": 10, "nextCursor": "?sellerId=151&limit=10&offset=10" },
"returnOrders": [
{
"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": "REPLACEMENT",
"replacementCustomerOrderId": "1234567891234",
"returnByDate": "2019-03-23T01:01:06.000Z",
"totalRefundAmount": { "currencyAmount": 127.45, "currencyUnit": "USD" },
"returnChannel": { "channelName": "IN_STORE" },
"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": "ARRIVED_LATE",
"purchaseOrderId": "4790210558890",
"sellerOrderId": "123",
"purchaseOrderLineNumber": 1,
"item": {
"sku": "ANTL_GDL-0700",
"productName": "Antlion Audio ModMic",
"itemWeight": { "unitOfMeasure": "POUND", "measurementValue": 0.5 }
},
"quantity": { "unitOfMeasure": "EACH", "measurementValue": 3 },
"unitPrice": { "currencyAmount": 119.95, "currencyUnit": "USD" },
"chargeTotals": [
{ "name": "lineUnitPrice", "value": 119.95 },
{ "name": "lineTotal", "value": 359.85 }
],
"currentDeliveryStatus": "NOT_SHIPPED",
"currentRefundStatus": "REFUND_INITIATED",
"refundedQty": 1,
"cancellableQty": 0,
"rechargeableQty": 2,
"status": "COMPLETED",
"statusTime": "2019-03-02T05:45:45.000Z"
},
{
"returnOrderLineNumber": 2,
"salesOrderLineNumber": 2,
"returnReason": "DAMAGED",
"purchaseOrderId": "4790210558890",
"item": {
"sku": "ANTL_GDL-0701",
"productName": "Antlion Audio ModMic USB"
},
"quantity": { "unitOfMeasure": "EACH", "measurementValue": 1 },
"unitPrice": { "currencyAmount": 79.5, "currencyUnit": "USD" },
"currentDeliveryStatus": "SHIPPED",
"currentRefundStatus": "NO_REFUND",
"status": "IN_TRANSIT",
"statusTime": "2019-03-01T00:00:00.000Z"
}
]
}
]
}

5
channel-sdk-walmart/src/test/resources/fixtures/walmart/token/success.json

@ -0,0 +1,5 @@ @@ -0,0 +1,5 @@
{
"access_token": "eyJraWQiOiI1ZTI5N2Q4Yi05MWZjLTRiNDctYTliMS02NmJhZmU0ZjE4Y2EiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ3YWxtYXJ0In0.c2lnbmF0dXJl",
"token_type": "Bearer",
"expires_in": 900
}

186
docs/walmart/README.md

@ -0,0 +1,186 @@ @@ -0,0 +1,186 @@
# 沃尔玛直连接入(channel-sdk-walmart)
> 模块:`channel-sdk-walmart` 通道:`ChannelProvider.DIRECT` 平台:`Platform.WALMART_SC`
> 协议依据:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱 `https://sandbox.walmartapis.com`
只读三件套:**订单 / 商品 / 售后**。标发、退款、商品写入、`WALMART_1P`、结算、Webhook 不在本期。
---
## 1. 目录结构
```
channel-sdk-walmart/
├── src/main/java/common/ecommerce/walmart/
│ ├── WalmartConstants.java 沙箱/生产端点、路径、请求头名、分页上限、时间窗上限
│ ├── adapter/
│ │ ├── WalmartAdapter.java SalesOrderCapable + ProductCapable + AfterSaleCapable
│ │ └── WalmartAdapterFactory.java DIRECT + WALMART_SC
│ ├── auth/WalmartTokenClient.java POST /v3/token(Basic Auth + form)
│ ├── http/
│ │ ├── WalmartRequestFactory.java 公共头 + token 头 + query 拼接
│ │ └── WalmartErrors.java 两种错误格式 → Auth/Transient/RateLimit/Validation
│ ├── mapper/
│ │ ├── WalmartOrderMapper.java 订单 → SalesOrder(行状态聚合、金额汇总、单价折分)
│ │ ├── WalmartProductMapper.java ItemResponse → ProductListing(shelf 二次解析)
│ │ ├── WalmartReturnMapper.java returnOrder → List<AfterSale>(1 → N)
│ │ └── WalmartShipmentMapper.java shipping 响应 → 行级发货记录
│ ├── enums/
│ │ ├── WalmartOrderStatus.java 行状态 → 订单级状态聚合
│ │ ├── WalmartPublishedStatus.java publishedStatus + lifecycleStatus → ProductStatus
│ │ └── WalmartReturnType.java returnType → AfterSaleType
│ └── dto/ 一个接口一个文件,字段名照抄沃尔玛
└── src/test/
├── java/.../adapter/ 订单 / 商品 / 售后契约测试
├── java/.../http/ 错误解析
├── java/.../enums/ 状态映射边界
├── java/.../WalmartFacadeTest 门面集成
├── java/.../probe/ 沙箱探针(默认跳过)
└── resources/fixtures/walmart/ 夹具,来源见 §5
```
---
## 2. 接入
```java
ChannelSdk sdk = ChannelSdk.builder()
.accountRepository(repo)
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
.register(new WalmartAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
.build();
AccountKey key = AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001");
ChannelConnection conn = ChannelConnection.of(
"https://sandbox.walmartapis.com",
ChannelSecret.builder()
.clientId("...")
.clientSecret("...")
.build());
```
`ChannelAccount` 上只需要 `marketplaceZone`(订单时间用)、`currency`;`platformCode` 对直连没有意义,
落库用 `ChannelProvider.NO_PLATFORM_CODE`。
---
## 3. 能力与限制
| 能力 | 状态 |
|---|---|
| `SALES_ORDER` 订单列表 / 详情 | ✅ |
| `PRODUCT` 商品列表 / 详情 | ✅ |
| `RETURNS` 退货列表(按行展开) | ✅ |
| 退货单详情 `WalmartAdapter.getReturn` | ✅(⚠ 沙箱 404) |
| 发货信息 `WalmartAdapter.getShipping` | ✅(⚠ 沙箱 404) |
| `MARK_SHIPPED` 标发 | ❌ 下一期 |
| `REFUND` 退款 | ❌ 沙箱 404 |
| 商品写入(Feed / 单个) | ❌ 沙箱 520 |
过滤条件的支持面比领星窄,**不支持的组合一律抛 `ValidationException`**,见
[`docs/channel/api-reference.md` §15A.6](../channel/api-reference.md#15a6-不支持的过滤条件显式报错)。
---
## 4. 增量同步
沃尔玛订单只有**创建时间**过滤,没有更新时间。SDK 给了两条明确的路,不混用:
| 场景 | 调用 |
|---|---|
| 拉新单(水位线增量) | `sdk.salesOrders(key, conn).pull(query)`,`updatedAfter/updatedBefore` 即创建时间窗 |
| 老单状态对账 | `WalmartAdapter.pullOpenOrders(ctx, statuses, createdAfter, cursor)`,按 `Created`/`Acknowledged` 拉开放单 |
`SyncEngine` 目前只支持 `syncSalesOrders`;商品的 `FULL_PULL_DIFF` 由宿主自己比对
(`ProductCapable.syncStrategy()` 已声明)。
时间窗上限 180 天(📖 待官方核实),超了本地拒绝,不静默截断。
---
## 5. 测试与探针
### 5.1 契约测试(无网络)
```bash
mvn -pl channel-sdk-walmart -am test
```
| 测试 | 覆盖 |
|---|---|
| `WalmartOrderTest` | 请求头、创建时间窗、游标、token 缓存与 401 重试、行状态聚合、金额汇总、地址映射 |
| `WalmartDirtyDataTest` | 缺单号/下单时间的单被跳过、除不尽时 `unitPrice` 为 null、运费不冒充单价、多币种不给总额、退货缺单号整单丢弃 |
| `WalmartProductTest` | limit 上限、sku 搜索、三种不支持过滤的报错、shelf 解析、状态组合 |
| `WalmartReturnTest` | 1 单拆 N 行、查询串型游标、退款金额回落、脏时间不卡页 |
| `WalmartErrorsTest` | 两种错误格式、401/429/5xx/`SYSTEM_ERROR` 分类、报文截断 |
| `WalmartStatusMappingTest` | 精确匹配(不做 contains)、未知值、空值 |
| `WalmartExtraQueryTest` | 退货详情、发货信息两个扩展查询 |
| `WalmartFacadeTest` | 门面路由、能力矩阵、写能力被拒、未注册平台报错 |
### 5.2 沙箱探针(只读,默认跳过)
```bash
mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
-Dwalmart.probe=true \
-Dwalmart.probe.clientId=你的clientId \
-Dwalmart.probe.clientSecret=你的clientSecret \
-Dtest=WalmartProbeTest test
```
可选参数:`-Dwalmart.probe.baseUrl=...`(打生产,**只读**)、`-Dwalmart.probe.sku=...`。
探针打印每一条请求/响应(token 只打前 12 位),对已知的 404 / 固定条数**不断言失败**,
唯一硬断言是 token 能换到。
探针跑完请核对这几件事,四项都确认后可以把 `WalmartConstants` 里的「📖 待核实」注释去掉:
1. `x-current-token-count` 的实际值(确认缓存复用是否必要)
2. `createdStartDate` 的真实最大回溯窗口
3. `charges` 的真实结构(沙箱样例有 `ItemPrice` + `Shipping` 两条)
4. 退货 `nextCursor` 的形态是否始终是查询串
### 5.3 夹具来源
`src/test/resources/fixtures/walmart/`:
| 文件 | 来源 |
|---|---|
| `orders/list.json` | 文档 §4.1 实测样例(2 条)+ 补了 3 条:部分发货、已发完仍残留 `Created`、多件(整行金额折单价) |
| `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 值为占位) |
---
## 6. 已知问题
| 问题 | 状态 |
|---|---|
| 沙箱商品详情 404 | 生产环境再验 |
| 沙箱退货详情 / 退款 404 | 详情已按文档实现(`getReturn`),退款未实现 |
| 沙箱 Feed 520 | 未实现 |
| 沙箱过滤参数不生效 | 以生产为准 |
| 订单列表 `status` 过滤是否生效 | 探针未覆盖写操作,读侧以生产为准 |
| `pullOpenOrders` 的 `status=Created,Acknowledged` 多值是否成立 | **未验证**,文档只给了单值示例;探针跑通后确认 |
| 订单翻页时是否仍需带时间窗 | **未验证**,退货游标是完整查询串,暗示游标已蕴含条件 |
| `createdStartDate` 最大回溯窗口 | 代码按 180 天硬校验,待探针核实 |
| `x-current-token-count` 实际值 | 待探针核实 |
| 标发 | 下一期:新增 `MarkShippedCapable` + `SalesOrders.markShipped(...)` |
---
## 7. 下一期(标发)
设计已定,实现待排:
- core 新增 `MarkShippedCapable`:`ShipmentConfirmation confirm(ChannelContext, ShipmentCommand)`
- 模型:行号 + 数量 + 承运商 + `methodCode` + 跟踪号 + 发货时间(ISO-8601)
- 门面:`sdk.salesOrders(key, conn).markShipped(...)`,写操作由调用方包在 `sdk.writes()` 里
- 幂等键:`action=markShipped`,`businessRef=purchaseOrderId:lineNumber:quantity`
(**不带金额**,符合 `WriteScope` 约定)
- 部分发货:同一行可多次调用,`statusQuantity.amount` 累计;调用前先 `get` 确认行状态与数量

6
pom.xml

@ -30,6 +30,7 @@ @@ -30,6 +30,7 @@
<module>channel-sdk-core</module>
<module>sdk-testkit</module>
<module>lingxing</module>
<module>channel-sdk-walmart</module>
<module>warehouse-sdk-core</module>
<module>warehouse-sdk-testkit</module>
<module>warehouse-sdk-yqn</module>
@ -52,6 +53,11 @@ @@ -52,6 +53,11 @@
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>channel-sdk-walmart</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>sdk-testkit</artifactId>
<version>${project.version}</version>
</dependency>

20
操作手册.md

@ -138,7 +138,7 @@ ChannelConnection conn = ChannelConnection.of( @@ -138,7 +138,7 @@ ChannelConnection conn = ChannelConnection.of(
|:---|:---|
| 领星 | `appKey`(= AppID)、`appSecret` |
| 亚马逊直连 | `clientId`、`clientSecret`、`refreshToken` |
| 沃尔玛 | `clientId`、`clientSecret` |
| 沃尔玛(领星 / 直连) | `clientId`、`clientSecret` |
**安全要求**:
@ -534,16 +534,20 @@ try { @@ -534,16 +534,20 @@ try {
## 附录:当前实现状态
| 能力 | 亚马逊 SC | 亚马逊 VC | 沃尔玛 | Temu / SHEIN / eBay / TikTok / Target / AliExpress 等 | Direct |
| 能力 | 亚马逊 SC | 亚马逊 VC | 沃尔玛(领星) | 其他平台(领星) | 沃尔玛直连 |
|:---|:---:|:---:|:---:|:---:|:---:|
| 订单列表 | ✅ | ✅ | ✅ | ✅(多平台统一订单) | ❌ |
| 订单详情 | ✅(含 FBM) | ✅ | ❌ | ❌ | ❌ |
| 商品 / Listing | ✅ | ✅ | ✅ | ✅(8 个平台) | ❌ |
| 店铺列表 | ✅ | ✅ | ✅ | ✅ | — |
| 订单列表 | ✅ | ✅ | ✅ | ✅(多平台统一订单) | ✅ |
| 订单详情 | ✅(含 FBM) | ✅ | ❌ | ❌ | ✅ |
| 商品 / Listing | ✅ | ✅ | ✅ | ✅(8 个平台) | ✅ |
| 商品详情 | ❌ | ❌ | ❌ | ❌ | ✅(生产;沙箱 404) |
| 店铺列表 | ✅ | ✅ | ✅ | ✅ | —(直连无此概念) |
| 账单 / 结算 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 售后(只读) | ✅ | ❌ | ❌ | ❌ | ❌ |
| 快速出库(写) | ✅ | ✅ | ✅ | ✅ | ❌ |
| 售后(只读) | ✅ | ❌ | ❌ | ❌ | ✅ |
| 快速出库(写) | ✅ | ✅ | ✅ | ✅ | ❌(下一期标发) |
| 出库单 / 面单 / 审核发货 | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ |
| 订单编辑(写) | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ |
> 「沃尔玛直连」= `ChannelProvider.DIRECT` + `Platform.WALMART_SC`,模块 `channel-sdk-walmart`,
> 详见 [docs/walmart/README.md](docs/walmart/README.md)。
写接口没有测试环境,联调时**只跑查询**。

Loading…
Cancel
Save