diff --git a/README.md b/README.md
index 5379ba7..36c9e25 100644
--- a/README.md
+++ b/README.md
@@ -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 ──┐
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
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java
index 81d5e6a..145c1ee 100644
--- a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java
@@ -26,22 +26,51 @@ public final class OrderLine {
/** 购买数量;0 表示平台未给或解析失败,非 null。 */
private final int quantity;
- /** 商品单价;平台未给时为 null。币种通常与订单总额一致。 */
+ /**
+ * 商品单价,不是行总额;平台未给时为 null。
+ *
+ *
有些平台只给整行金额(沃尔玛 {@code ItemPrice.chargeAmount} 是「行金额」),
+ * 适配器必须除以 {@link #quantity()} 后再填这里;下游按
+ * {@code unitPrice × quantity} 汇总才不会被算重。
+ *
+ * 除不尽时留 null,不要四舍五入倒推——例如 3 件共 100.00 时
+ * {@code 33.3333 × 3 = 99.9999},会凭空产生分差。此时精确金额看
+ * {@link #lineAmount()}。
+ */
private final Money unitPrice;
+ /**
+ * 行金额(单价 × 数量),平台原值;平台没给时为 null。
+ *
+ * 与 {@link #unitPrice()} 的关系:平台给单价时由适配器相乘得到,或干脆不填;
+ * 平台给整行金额时直接放这里,不做除法——这是金额的权威来源,不丢精度。
+ */
+ private final Money lineAmount;
+
/** 行税额;平台未给时为 null。 */
private final Money tax;
/** 行优惠/折扣金额;平台未给时为 null。 */
private final Money discount;
+ /**
+ * 行状态原值;平台不提供时为 null。
+ *
+ * 沃尔玛取 {@code orderLineStatuses.orderLineStatus[].status}({@code Created} 等),
+ * 订单级状态由适配器按行状态聚合;领星订单接口不返回行状态。
+ * 保留原值不做枚举,避免平台加值就编译不过。
+ */
+ 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 {
return quantity;
}
- /** 商品单价;平台未给时为 null。 */
+ /** 商品单价(不是行总额);平台未给或除不尽时为 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 {
return discount;
}
+ /** 行状态原值;平台不返回时为 null。 */
+ public String status() {
+ return status;
+ }
+
public static final class Builder {
/** 行标识;可空,仅作展示。 */
@@ -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 {
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 {
return this;
}
+ /** 设置行状态原值;可空。 */
+ public Builder status(String status) {
+ this.status = status;
+ return this;
+ }
+
/** 构建明细行;缺 platformSku 时抛 {@link NullPointerException}。 */
public OrderLine build() {
return new OrderLine(this);
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java
index c123332..2d3315e 100644
--- a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java
@@ -35,9 +35,25 @@ public final class SalesOrder {
/** 买家姓名,平台字段原样;多数领星订单接口不返回,此时为 null。 */
private final String buyerName;
+ /**
+ * 买家邮箱,平台字段原样;平台只给中转邮箱时保留中转地址,可空。
+ *
+ * 沃尔玛取 {@code customerEmailId}(形如 {@code xxx@relay.walmart.com}),
+ * 领星订单接口不返回该字段。
+ */
+ private final String buyerEmail;
+
/** 收货国家代码(ISO 3166-1 alpha-2,如 US / DE);领星取 store_Country_code,可空。 */
private final String shipToCountryCode;
+ /**
+ * 收货地址;平台不返回地址时为 null。
+ *
+ * 沃尔玛取 {@code shippingInfo.postalAddress},领星订单接口不返回该字段。
+ * 只承载收件信息,不含发货仓与物流方式。
+ */
+ private final ShipToAddress shipToAddress;
+
/** 订单明细行;不可变列表。空列表可能表示该接口未返回商品行(如 FBM 列表),不代表订单无商品。 */
private final List lines;
@@ -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(b.lines));
this.totalAmount = b.totalAmount;
this.occurredAt = Objects.requireNonNull(b.occurredAt, "occurredAt");
@@ -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 lines() {
return lines;
@@ -135,9 +163,15 @@ public final class SalesOrder {
/** 买家姓名;可空。 */
private String buyerName;
+ /** 买家邮箱;可空。 */
+ private String buyerEmail;
+
/** 收货国家代码;可空。 */
private String shipToCountryCode;
+ /** 收货地址;可空。 */
+ private ShipToAddress shipToAddress;
+
/** 订单明细行;默认空列表,传入 null 按空列表处理。 */
private List lines = Collections.emptyList();
@@ -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 lines) {
this.lines = lines == null ? Collections.emptyList() : lines;
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java
new file mode 100644
index 0000000..c8aa3dd
--- /dev/null
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java
@@ -0,0 +1,231 @@
+package common.ecommerce.channel.model.order;
+
+import java.util.Objects;
+
+/**
+ * 订单收货地址。
+ *
+ * 各平台字段名不同、语义一致:沃尔玛 {@code shippingInfo.postalAddress}、
+ * 亚马逊 {@code ShippingAddress}、领星 {@code address_*}。统一收在这里,
+ * 平台原始值不再重复存放于 {@code SalesOrder}。
+ *
+ * 本类只承载收件信息,不含发货仓、物流方式等履约配置;
+ * 那些属于出库/面单域,由 {@code OutboundOrder} 等模型表达。
+ *
+ * 地址类型不做成枚举:沃尔玛给 {@code RESIDENTIAL} / {@code OFFICE},
+ * 其它平台可能给别的值,做成枚举后平台加值就会编译不过。原值放在
+ * {@link #addressType()},由宿主自行解释。
+ */
+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);
+ }
+ }
+}
diff --git a/channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java b/channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java
new file mode 100644
index 0000000..67874ca
--- /dev/null
+++ b/channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java
@@ -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);
+ }
+}
diff --git a/channel-sdk-walmart/pom.xml b/channel-sdk-walmart/pom.xml
new file mode 100644
index 0000000..fd2529f
--- /dev/null
+++ b/channel-sdk-walmart/pom.xml
@@ -0,0 +1,49 @@
+
+
+ 4.0.0
+
+
+ ecommerce
+ channel-sdk-parent
+ 1.0.0-SNAPSHOT
+
+
+ channel-sdk-walmart
+ 沃尔玛 Marketplace 直连适配器(订单 / 商品 / 售后)
+
+
+
+ ecommerce
+ sdk-common
+
+
+ ecommerce
+ channel-sdk-core
+
+
+ com.fasterxml.jackson.core
+ jackson-databind
+
+
+ com.squareup.okhttp3
+ okhttp
+
+
+ org.slf4j
+ slf4j-api
+
+
+
+ ecommerce
+ sdk-testkit
+ test
+
+
+ org.junit.jupiter
+ junit-jupiter
+ test
+
+
+
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java
new file mode 100644
index 0000000..707c6da
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java
@@ -0,0 +1,115 @@
+package common.ecommerce.walmart;
+
+/**
+ * 沃尔玛 Marketplace 协议常量。
+ *
+ * 端点与路径属于协议的一部分,写在代码里,不做成配置表。
+ * 运行时不使用 {@link #PRODUCTION_BASE_URL} / {@link #SANDBOX_BASE_URL}:
+ * 端点由调用方每次经 {@code ChannelConnection} 传入(沙箱还是生产由宿主决定,
+ * 账户上的 {@code ChannelAccount.sandbox()} 只是元数据)。
+ *
+ * 来源:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱
+ * {@code https://sandbox.walmartapis.com} 实测。
+ */
+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";
+
+ /** 访问令牌;业务接口用它,不用 Authorization。 */
+ 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";
+
+ // ---------------------------------------------------------------- 限制
+
+ /**
+ * 商品列表单页上限(官方值,超了本地截断)。
+ *
+ * 与领星不同,这里是平台硬上限:静默截断是安全的,因为调用方本来
+ * 就只能拿到这么多,且用 {@code nextCursor} 翻页。
+ */
+ public static final int MAX_ITEM_PAGE_SIZE = 200;
+
+ /** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */
+ public static final int DEFAULT_ORDER_PAGE_SIZE = 20;
+
+ /**
+ * 订单列表单页上限(📖 官方常见取值 200,与商品一致)。
+ *
+ * 文档没给订单的 {@code limit} 上限;这里与商品保持同一策略:超了本地截断,
+ * 而不是把大值原样发给平台(沙箱 mock 不校验,生产会被拒)。
+ */
+ public static final int MAX_ORDER_PAGE_SIZE = 200;
+
+ /** 退货列表默认单页条数;沃尔玛默认 10。 */
+ public static final int DEFAULT_RETURN_PAGE_SIZE = 10;
+
+ /**
+ * 订单创建时间窗的最大回溯天数(📖 官方常见取值,待 Developer Portal 核实)。
+ *
+ * 超过这个跨度在本地直接拒绝,不做静默截断——静默截断会让宿主以为拉全了。
+ */
+ public static final int MAX_ORDER_WINDOW_DAYS = 180;
+
+ /**
+ * 令牌提前续期秒数。
+ *
+ * {@code expires_in} 只有 900 秒,且沙箱响应头 {@code x-current-token-count}
+ * 已达 99(平台对并发有效 token 有上限),必须缓存复用、提前续期。
+ */
+ public static final long TOKEN_EARLY_REFRESH_SECONDS = 120L;
+
+ /** 异常里保留的原始响应最大长度;避免整页报文塞进日志。 */
+ public static final int RAW_RESPONSE_LIMIT = 1024;
+
+ private WalmartConstants() {
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
new file mode 100644
index 0000000..b66d5b3
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
@@ -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 直连适配器(只读)。
+ *
+ * 实现三个能力接口:
+ *
+ * - {@link SalesOrderCapable}:{@code GET /v3/orders}、{@code GET /v3/orders/{id}}
+ * - {@link ProductCapable}:{@code GET /v3/items}、{@code GET /v3/items/{sku}}
+ * - {@link AfterSaleCapable}:{@code GET /v3/returns}
+ *
+ *
+ * 写操作(标发 / 退款 / 商品写入)本期不实现,对应能力位也不声明——
+ * 门面调用会显式抛 {@code UnsupportedCapabilityException},不会静默成功。
+ *
+ * 增量语义
+ * 沃尔玛订单接口只有创建时间过滤({@code createdStartDate/createdEndDate}),
+ * 没有更新时间。因此 {@link SalesOrderQuery#updatedAfter()} 被解释为创建时间窗;
+ * 「老单状态变化」需要宿主用 {@link #pullOpenOrders} 单独对账,两者不混在一起,
+ * 免得 {@code pull} 的语义变得不可预测。
+ */
+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 platforms() {
+ return EnumSet.of(Platform.WALMART_SC);
+ }
+
+ @Override
+ public EnumSet capabilities() {
+ return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS);
+ }
+
+ // ---------------------------------------------------------------- SalesOrderCapable
+
+ /**
+ * 按创建时间窗拉订单(沃尔玛没有更新时间过滤)。
+ *
+ * 时间窗超过 {@link WalmartConstants#MAX_ORDER_WINDOW_DAYS} 天时本地拒绝,
+ * 不做静默截断——静默截断会让宿主以为拉全了。
+ */
+ @Override
+ public Page 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 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 orders = new ArrayList();
+ 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} 的订单。
+ *
+ * 沃尔玛订单接口只能按创建时间过滤,{@code pull} 拿不到「老单今天发货」这种变化。
+ * 宿主在同步任务里追加一次本方法即可补齐,无需改统一模型。
+ *
+ * @param statuses 行状态列表,如 {@code ["Created","Acknowledged"]};空则用这两个
+ * @param createdAfter 创建时间下界;null 表示不限制(平台默认行为)
+ * @param cursor 游标;首页传 null
+ */
+ public Page pullOpenOrders(ChannelContext ctx, List statuses,
+ Instant createdAfter, String cursor) {
+ ChannelAccount account = ctx.account();
+ Map queryParams = WalmartRequestFactory.query();
+ List 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 orders = new ArrayList();
+ 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 接口没有更新时间过滤,只能全量拉 + 差分。
+ *
+ * @see ProductSyncStrategy#FULL_PULL_DIFF
+ */
+ @Override
+ public ProductSyncStrategy syncStrategy() {
+ return ProductSyncStrategy.FULL_PULL_DIFF;
+ }
+
+ /**
+ * 拉商品。
+ *
+ * 时间窗在此适配器里不支持:传了 {@code updatedAfter/updatedBefore} 直接抛
+ * {@link ValidationException},而不是静默忽略——静默忽略会让宿主以为做了增量。
+ */
+ @Override
+ public Page 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 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 products = new ArrayList();
+ 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 取单品。
+ *
+ * ⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。
+ */
+ @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
+
+ /**
+ * 拉退货单,按商品行展开。
+ *
+ * 分页特殊:{@code meta.nextCursor} 本身是一段查询串
+ * (如 {@code "?sellerId=151&limit=10&offset=10"}),翻页时整串拼到 URL 后面。
+ *
+ * 时间窗只支持按退货单创建时间;{@code PURCHASE_TIME} / {@code UPDATE_TIME}
+ * 显式报错,不做「拿售后时间顶替」的静默降级。
+ */
+ @Override
+ public Page 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 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 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 afterSales = new ArrayList();
+ String nextCursor = null;
+ if (dto != null) {
+ if (dto.returnOrders != null) {
+ for (WalmartReturnDtos.ReturnOrder order : dto.returnOrders) {
+ List 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}}。
+ *
+ * 与列表一样按商品行展开:一个退货单可能含多个退货行,
+ * 返回的 {@link AfterSale#afterSaleId()} 与列表里的完全一致({@code returnOrderId:行号}),
+ * 可以直接拿去 upsert。
+ *
+ * {@link AfterSaleCapable} 没有「取详情」方法——售后以拉取为主,
+ * 需要单条时用列表的时间窗过滤即可。这里提供它是因为沃尔玛有真实路由,
+ * 且列表接口的过滤参数在沙箱不生效,生产上按单号回查更快。
+ *
+ * ⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。
+ *
+ * @param returnOrderId 退货单号
+ * @return 该退货单展开出的售后行;退货单没有行时返回空列表
+ * @throws ChannelException 平台 404 / 其它错误,由 {@link WalmartErrors} 分类
+ */
+ public List 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}。
+ *
+ * 返回行级发货记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间)。
+ * 统一模型没有独立的发货实体——从订单详情的行状态里也能读到同样的
+ * {@code trackingInfo},两种方式数据一致;本方法用于只想知道「发了哪些行」的场景。
+ *
+ * ⚠ 沙箱实测该路由 404(mock 未实现)。生产上若也不可用,改用
+ * {@link #get(ChannelContext, SalesOrderRef)} 读订单详情。
+ *
+ * @param purchaseOrderId 沃尔玛订单号
+ * @return 已发货行的记录;未发货时返回空列表
+ */
+ public List 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 重试一次。
+ *
+ * 为什么要重试:沃尔玛 token 的 {@code expires_in} 是 900 秒,但平台可以提前作废
+ * (后台重置 secret、并发令牌超限被踢)。缓存里的坏 token 在自然过期前会一直命中,
+ * 期间所有请求都 401。{@code TokenManager} 有 {@code forceRefresh},但门面层没有
+ * 自动重试——重试策略属于适配器,这里只在本模块内实现一次「换 token + 重发」。
+ *
+ * 重试只做一次,第二次失败原样抛出,交由宿主决定是否停用账户。
+ */
+ 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。
+ *
+ * 缓存维度是 {@code clientId}:一个 clientId 对应一个 seller,
+ * 同 seller 的多个店铺共用一个令牌,避免触碰平台并发令牌上限。
+ */
+ 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 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();
+ }
+
+ /**
+ * 平台给了一条缺必填字段的记录,映射层丢弃时留痕。
+ *
+ * 不抛异常:一条脏数据不该卡住整页同步;但也不能完全静默——宿主需要知道
+ * 「这次少了一条」以及少的是哪个单号。
+ */
+ 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));
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java
new file mode 100644
index 0000000..d7da96b
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java
@@ -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;
+
+/**
+ * 沃尔玛直连适配器工厂。
+ *
+ * 与领星、三方仓使用同一套注册机制:工厂只装配基础设施,
+ * 不持有端点与凭据——两者由调用方每次经 {@code ChannelConnection} 传入。
+ *
+ *
+ * ChannelSdk.builder()
+ * .accountRepository(repo)
+ * .register(new WalmartAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
+ * .build();
+ *
+ */
+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 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);
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java
new file mode 100644
index 0000000..24d4ad7
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java
@@ -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}。
+ *
+ * 请求:Basic Auth({@code clientId:clientSecret})+ form 体
+ * {@code grant_type=client_credentials}。
+ *
+ * 响应:{@code access_token} / {@code token_type=Bearer} / {@code expires_in=900}。
+ * 业务接口带 {@code WM_SEC.ACCESS_TOKEN} 头,不再带 Basic Auth(沙箱实测)。
+ *
+ * 令牌按 {@code clientId} 维度缓存:一个 clientId 对应一个 seller,
+ * 多店铺共用同一令牌,避免触碰平台的并发有效令牌上限
+ * (沙箱 {@code x-current-token-count} 已接近上限)。
+ */
+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);
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java
new file mode 100644
index 0000000..5d7096c
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java
@@ -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}})。
+ *
+ * 列表字段名是单数 {@code ItemResponse},没有外层包装对象,直接是数组。
+ *
+ * {@code shelf} 是JSON 字符串数组(例如 {@code "[\"Home Page\",\"Clothing\"]"}),
+ * 需要二次解析;{@code UNNAV} 表示未分配到可浏览类目。
+ */
+public final class WalmartItemDtos {
+
+ private WalmartItemDtos() {
+ }
+
+ /** 商品列表响应。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class ItemListResponse {
+
+ /** 商品数组;字段名就是单数 {@code ItemResponse}。 */
+ @JsonProperty("ItemResponse")
+ public List 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 reason;
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java
new file mode 100644
index 0000000..097a51f
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java
@@ -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}})。
+ *
+ * 层次陷阱:沃尔玛的 JSON 由旧版 XML Schema 转换而来,数组外层带单数包装对象:
+ * {@code orderLines.orderLine[]}、{@code orderLineStatuses.orderLineStatus[]}、
+ * {@code charges.charge[]}。字段名照抄,不要「优化」成复数。
+ *
+ * 类型陷阱:金额是 {@code {"currency","amount"}} 且 amount 是数字;
+ * 数量是 {@code {"unitOfMeasurement","amount"}} 且 amount 是字符串;
+ * 时间是 epoch 毫秒。三者在退货接口里又都不一样。
+ */
+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;
+ }
+
+ /**
+ * 订单详情响应:{@code {"order": {...}}}。
+ *
+ * 比列表多包一层,映射时两者共用 {@link Order}。
+ */
+ @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;
+
+ /** 下单时间,epoch 毫秒。 */
+ @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;
+ }
+
+ /** 订单行。 */
+ @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 是字符串。 */
+ @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;
+ }
+
+ /** 单条费用。 */
+ @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 是字符串。 */
+ @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;
+ }
+
+ /** 行状态。 */
+ @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;
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java
new file mode 100644
index 0000000..b3ef31e
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java
@@ -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}})。
+ *
+ * 与订单接口的差异(同一个字段三种写法):
+ *
+ * - 金额:订单是 {@code {"currency","amount"}},退货是 {@code {"currencyAmount","currencyUnit"}}
+ * - 数量:订单是 {@code {"unitOfMeasurement","amount"(字符串)}},
+ * 退货是 {@code {"unitOfMeasure","measurementValue"(数字)}}
+ * - 时间:订单是 epoch 毫秒,退货是 ISO-8601 字符串
+ *
+ *
+ * 分页陷阱:{@code meta.nextCursor} 的值本身是一段查询串
+ * ({@code "?sellerId=151&limit=10&offset=10"}),翻页时整串拼到 URL 后面,
+ * 不是普通游标。
+ */
+public final class WalmartReturnDtos {
+
+ private WalmartReturnDtos() {
+ }
+
+ /** 退货单列表响应。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class ReturnListResponse {
+
+ /** 分页元信息。 */
+ @JsonProperty("meta")
+ public Meta meta;
+
+ /** 退货单数组。 */
+ @JsonProperty("returnOrders")
+ public List 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 returnLineGroups;
+
+ /** 退货行数组。 */
+ @JsonProperty("returnOrderLines")
+ public List 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 returnLines;
+
+ /** 面单列表。 */
+ @JsonProperty("labels")
+ public List