From a3c5931c5cbe799acfc0cf9efa0c38e9af8973d9 Mon Sep 17 00:00:00 2001
From: lml <1297555865@qq.com>
Date: Thu, 19 Nov 2026 16:18:37 +0800
Subject: [PATCH] =?UTF-8?q?feat(walmart):=20=E6=A0=87=E5=8F=91=20/=20?=
=?UTF-8?q?=E9=80=80=E6=AC=BE=20/=20=E5=95=86=E5=93=81=20Feed=20=E6=8E=A5?=
=?UTF-8?q?=E5=85=A5=EF=BC=8C=E5=B9=B6=E6=8C=89=E5=AE=98=E6=96=B9=20schema?=
=?UTF-8?q?=20=E4=BF=AE=E6=AD=A3=E5=8F=82=E6=95=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
【新增写操作】
- MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货;
幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号)
- RefundCapable + AfterSales.refund:按退货行 × 费用项退款
- WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法,
不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形)
【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】
标发 POST /v3/orders/{id}/shipping:
- shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64)
- 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断)
- 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空)
- OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE)
退货 GET /v3/returns:
- 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate
- DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate;
PURCHASE_TIME 无对应参数,本地报错
- 去掉官方不存在的 offset 参数
- returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据
- limit 加上限 200
商品 GET /v3/items:
- limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值)
- 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor
商品 Feed POST /v3/feeds:
- feedType 按官方 13 个枚举值本地校验,非法值直接拒绝
- 成功响应是 200 而非 202
【校验与容错】
- 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页
- 行金额除不尽时 unitPrice 留 null,不四舍五入倒推
- 运费不冒充商品单价;同单多币种时 totalAmount 为 null
- 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误
【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、
状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。
Co-Authored-By: Claude Code
---
.../ecommerce/channel/capability/AfterSales.java | 28 ++
.../channel/capability/MarkShippedCapable.java | 39 +++
.../channel/capability/RefundCapable.java | 35 +++
.../ecommerce/channel/capability/SalesOrders.java | 27 ++
.../channel/model/aftersale/RefundCommand.java | 275 ++++++++++++++++
.../channel/model/aftersale/RefundResult.java | 134 ++++++++
.../channel/model/fulfillment/ShipmentCommand.java | 345 +++++++++++++++++++++
.../channel/model/fulfillment/ShipmentResult.java | 142 +++++++++
.../common/ecommerce/walmart/WalmartConstants.java | 45 ++-
.../ecommerce/walmart/adapter/WalmartAdapter.java | 261 +++++++++++++++-
.../ecommerce/walmart/dto/WalmartFeedDtos.java | 209 +++++++++++++
.../ecommerce/walmart/dto/WalmartRefundDtos.java | 82 +++++
.../walmart/dto/WalmartShipmentWriteDtos.java | 194 ++++++++++++
.../ecommerce/walmart/enums/WalmartReturnType.java | 28 +-
.../walmart/http/WalmartRequestFactory.java | 22 ++
.../walmart/mapper/WalmartFeedMapper.java | 105 +++++++
.../walmart/mapper/WalmartRefundMapper.java | 103 ++++++
.../walmart/mapper/WalmartShipmentWriteMapper.java | 203 ++++++++++++
.../walmart/model/WalmartFeedCommand.java | 170 ++++++++++
.../ecommerce/walmart/model/WalmartFeedStatus.java | 248 +++++++++++++++
.../ecommerce/walmart/WalmartFacadeTest.java | 13 +-
.../ecommerce/walmart/adapter/WalmartFeedTest.java | 230 ++++++++++++++
.../walmart/adapter/WalmartMarkShippedTest.java | 304 ++++++++++++++++++
.../walmart/adapter/WalmartOrderTest.java | 5 +-
.../walmart/adapter/WalmartProductTest.java | 22 +-
.../walmart/adapter/WalmartRefundTest.java | 209 +++++++++++++
.../walmart/adapter/WalmartReturnTest.java | 32 +-
.../walmart/enums/WalmartStatusMappingTest.java | 21 +-
.../ecommerce/walmart/probe/WalmartProbeTest.java | 42 +++
docs/walmart/README.md | 155 ++++++++-
30 files changed, 3670 insertions(+), 58 deletions(-)
create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java
create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java
create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java
create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundResult.java
create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentCommand.java
create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentResult.java
create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartFeedDtos.java
create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartRefundDtos.java
create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentWriteDtos.java
create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartFeedMapper.java
create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java
create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java
create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedCommand.java
create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedStatus.java
create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartFeedTest.java
create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java
create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartRefundTest.java
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java
index 6a1a634..83c2a72 100644
--- a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java
@@ -6,6 +6,8 @@ import common.ecommerce.shared.model.Capability;
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.aftersale.RefundCommand;
+import common.ecommerce.channel.model.aftersale.RefundResult;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.audit.CallSupport;
import common.ecommerce.channel.sdk.ChannelContext;
@@ -72,6 +74,32 @@ public final class AfterSales {
});
}
+ /**
+ * 发起退款(写操作,调用方需包在 {@code sdk.writes()} 里)。
+ *
+ * 推荐幂等键:{@code action=refund}、
+ * {@code businessRef=退货单号:行号,行号}(行号排序);不含金额——
+ * 金额修正不应被当成重复退款。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 未声明 REFUND 或未实现 RefundCapable
+ */
+ public RefundResult refund(final RefundCommand command) {
+ return CallSupport.observe(observer, ctx, "afterSales.refund",
+ CallSupport.params(
+ "afterSaleId", command == null ? null : command.afterSaleId(),
+ "lineCount", command == null ? 0 : command.lines().size(),
+ "amount", command == null || command.totalAmount() == null
+ ? null : command.totalAmount().toString()),
+ result -> 1,
+ () -> {
+ if (!adapter.supports(account, Capability.REFUND)
+ || !(adapter instanceof RefundCapable)) {
+ throw new ChannelException.UnsupportedCapabilityException(Capability.REFUND);
+ }
+ return ((RefundCapable) adapter).refund(ctx, command);
+ });
+ }
+
/** 能力双检:账户级能力声明 + 接口实现,缺一即拒绝。 */
private void requireAfterSaleCapable() {
if (!adapter.supports(account, Capability.RETURNS) || !(adapter instanceof AfterSaleCapable)) {
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java
new file mode 100644
index 0000000..6b45e50
--- /dev/null
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java
@@ -0,0 +1,39 @@
+package common.ecommerce.channel.capability;
+
+import common.ecommerce.channel.model.fulfillment.ShipmentCommand;
+import common.ecommerce.channel.model.fulfillment.ShipmentResult;
+import common.ecommerce.channel.sdk.ChannelContext;
+
+/**
+ * 3P 标发能力:把订单行标记为已发货并回传物流信息。
+ *
+ * 这是一次真实的外部动作(买家会看到物流),写操作,必须经
+ * {@code IdempotencyGuard} 执行 。推荐幂等键:
+ * {@code action=markShipped}、{@code businessRef=订单号:行号:数量}
+ * ——不带金额,金额变化不应产生新的业务动作。
+ *
+ * 与 {@link OutboundCapable} 的区别:快速出库是「提交出库任务、异步回查结果」;
+ * 标发是同步确认订单行的发货状态,一次调用对应一个平台订单。
+ *
+ * 支持部分发货的平台(如沃尔玛),同一行可以分多次调用,
+ * 每次只给本次实发数量;不支持部分发货的平台在数量不一致时应抛业务异常,
+ * 不能静默按整行发货。
+ *
+ * 能力位 {@link common.ecommerce.shared.model.Capability#MARK_SHIPPED}。
+ */
+public interface MarkShippedCapable extends PlatformAdapter {
+
+ /**
+ * 标发一个订单。
+ *
+ * 平台按订单返回结果;部分发货时结果里的行数量是累计已发 数量。
+ * 订单状态已不允许发货(如已取消)时应抛
+ * {@link common.ecommerce.shared.error.PlatformBusinessException},
+ * 不要返回一个「看起来成功」的空结果。
+ *
+ * @param ctx 调用上下文
+ * @param command 发货命令,一个命令对应一个平台订单
+ * @return 平台确认后的发货结果
+ */
+ ShipmentResult markShipped(ChannelContext ctx, ShipmentCommand command);
+}
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java
new file mode 100644
index 0000000..75ad922
--- /dev/null
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java
@@ -0,0 +1,35 @@
+package common.ecommerce.channel.capability;
+
+import common.ecommerce.channel.model.aftersale.RefundCommand;
+import common.ecommerce.channel.model.aftersale.RefundResult;
+import common.ecommerce.channel.sdk.ChannelContext;
+
+/**
+ * 退款能力:按平台退货单发起退款。
+ *
+ * 写操作,涉及资金,必须经 {@code IdempotencyGuard} 执行 。
+ * 推荐幂等键:{@code action=refund}、
+ * {@code businessRef=退货单号:行号,行号}——不带金额与费用项;
+ * 金额修正属于另一个动作,不应被当成「新的退款」重复执行。
+ *
+ * 能力位 {@link Capability#REFUND},与只读的 {@link AfterSaleCapable} 分开声明:
+ * 有些平台只能查售后、不能发起退款。
+ *
+ * 调用前应先查售后详情核对可退数量 / 可退金额,避免超退。
+ * 适配器只做报文校验,余额校验由平台负责。
+ */
+public interface RefundCapable extends PlatformAdapter {
+
+ /**
+ * 发起一次退款。
+ *
+ * 部分平台退货单里含多行,可以只退其中几行或几项费用;
+ * 命令里给什么就退什么,适配器不做补全。
+ *
+ * @param ctx 调用上下文
+ * @param command 退款命令
+ * @return 平台确认结果
+ * @throws common.ecommerce.shared.error.PlatformBusinessException 平台拒绝(如已退过、超过可退金额)
+ */
+ RefundResult refund(ChannelContext ctx, RefundCommand command);
+}
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java
index e770aca..47df885 100644
--- a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java
@@ -7,6 +7,8 @@ import common.ecommerce.shared.model.Capability;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.model.fulfillment.OrderEditRequest;
import common.ecommerce.channel.model.fulfillment.OrderEditResult;
+import common.ecommerce.channel.model.fulfillment.ShipmentCommand;
+import common.ecommerce.channel.model.fulfillment.ShipmentResult;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.order.SalesOrderRef;
@@ -126,6 +128,31 @@ public final class SalesOrders {
});
}
+ /**
+ * 标发一个订单(写操作,调用方需包在 {@code sdk.writes()} 里)。
+ *
+ * 推荐幂等键:{@code action=markShipped}、
+ * {@code businessRef=订单号:行号:数量};同一行分多次部分发货时,
+ * 数量不同即视为不同业务动作。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 MARK_SHIPPED 或未实现 MarkShippedCapable
+ */
+ public ShipmentResult markShipped(final ShipmentCommand command) {
+ return CallSupport.observe(observer, ctx, "salesOrders.markShipped",
+ CallSupport.params(
+ "channelOrderId", command == null ? null : command.channelOrderId(),
+ "lineCount", command == null ? 0 : command.lines().size(),
+ "quantity", command == null ? 0 : command.totalQuantity()),
+ result -> 1,
+ () -> {
+ if (!adapter.supports(account, Capability.MARK_SHIPPED)
+ || !(adapter instanceof MarkShippedCapable)) {
+ throw new ChannelException.UnsupportedCapabilityException(Capability.MARK_SHIPPED);
+ }
+ return ((MarkShippedCapable) adapter).markShipped(ctx, command);
+ });
+ }
+
/** 把批量编辑结果映射成成功 / 部分成功 / 失败摘要。 */
private static CallSupport.ResultSummary editSummary(OrderEditResult result) {
if (result == null) {
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java
new file mode 100644
index 0000000..d4813e2
--- /dev/null
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java
@@ -0,0 +1,275 @@
+package common.ecommerce.channel.model.aftersale;
+
+import common.ecommerce.shared.support.Money;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 退款命令。
+ *
+ * 按平台退货单发起退款。平台侧的退款通常细到退货行 × 费用项
+ * (沃尔玛 {@code refundLines[].refundCharges[]}),所以这里不是「退多少钱」,
+ * 而是逐行逐费用给金额。
+ *
+ * 调用前应先查售后详情核对 {@code refundedQty} / {@code cancellableQty},
+ * 避免超退——各平台超额规则不同,适配器只做格式校验,不做余额校验。
+ */
+public final class RefundCommand {
+
+ /** 平台退货单号;必填。 */
+ private final String afterSaleId;
+
+ /** 退款行;不可变,至少一行。 */
+ private final List lines;
+
+ private RefundCommand(Builder b) {
+ if (isBlank(b.afterSaleId)) {
+ throw new IllegalArgumentException("afterSaleId must not be blank");
+ }
+ if (b.lines.isEmpty()) {
+ throw new IllegalArgumentException("refund requires at least one line");
+ }
+ this.afterSaleId = b.afterSaleId.trim();
+ this.lines = Collections.unmodifiableList(new ArrayList(b.lines));
+ }
+
+ /** 新建构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 平台退货单号。 */
+ public String afterSaleId() {
+ return afterSaleId;
+ }
+
+ /** 退款行;不可变,至少一行。 */
+ public List lines() {
+ return lines;
+ }
+
+ /** 退款总额;币种不一致时抛 {@link IllegalArgumentException},为空行返回 null。 */
+ public Money totalAmount() {
+ Money total = null;
+ for (Line line : lines) {
+ for (Charge charge : line.charges()) {
+ total = total == null ? charge.amount() : total.add(charge.amount());
+ }
+ }
+ return total;
+ }
+
+ /**
+ * 一条退款行:对应平台的一个退货商品行。
+ *
+ * {@code lineId} 是平台退货行号 (沃尔玛 {@code returnOrderLineNumber}),
+ * 不是统一模型的 {@code afterSaleId()};后者是「退货单号:行号」的拼接。
+ */
+ public static final class Line {
+
+ /** 平台退货行号;必填。 */
+ private final String lineId;
+
+ /** 费用明细;不可变,至少一条。 */
+ private final List charges;
+
+ private Line(Builder b) {
+ if (isBlank(b.lineId)) {
+ throw new IllegalArgumentException("refund lineId must not be blank");
+ }
+ if (b.charges.isEmpty()) {
+ throw new IllegalArgumentException("refund line requires at least one charge");
+ }
+ this.lineId = b.lineId.trim();
+ this.charges = Collections.unmodifiableList(new ArrayList(b.charges));
+ }
+
+ /** 新建构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 平台退货行号。 */
+ public String lineId() {
+ return lineId;
+ }
+
+ /** 费用明细。 */
+ public List charges() {
+ return charges;
+ }
+
+ /** 退款行构建器。 */
+ public static final class Builder {
+
+ /** 平台退货行号。 */
+ private String lineId;
+ /** 费用明细。 */
+ private final List charges = new ArrayList();
+
+ /** 设置平台退货行号;必填。 */
+ public Builder lineId(String lineId) {
+ this.lineId = lineId;
+ return this;
+ }
+
+ /** 追加一条费用明细。 */
+ public Builder charge(Charge charge) {
+ if (charge != null) {
+ this.charges.add(charge);
+ }
+ return this;
+ }
+
+ /** 批量追加费用明细;null 视为不加。 */
+ public Builder charges(List charges) {
+ if (charges != null) {
+ for (Charge charge : charges) {
+ charge(charge);
+ }
+ }
+ return this;
+ }
+
+ /** 构建退款行;缺行号或没有费用项时抛 {@link IllegalArgumentException}。 */
+ public Line build() {
+ return new Line(this);
+ }
+ }
+ }
+
+ /**
+ * 一条退款费用项。
+ *
+ * 沃尔玛要求 {@code chargeName}(如 {@code ItemPrice})、
+ * {@code chargeType}({@code PRODUCT} / {@code FEE} / {@code SHIPPING})与金额三者都给;
+ * 费用名要与退货详情 {@code chargeTotals[].name} 对得上。
+ */
+ public static final class Charge {
+
+ /** 费用名称;必填。 */
+ private final String chargeName;
+
+ /** 费用类型;必填。 */
+ private final String chargeType;
+
+ /** 退款金额;必填,不能为负。 */
+ private final Money amount;
+
+ private Charge(Builder b) {
+ if (isBlank(b.chargeName)) {
+ throw new IllegalArgumentException("chargeName must not be blank");
+ }
+ if (isBlank(b.chargeType)) {
+ throw new IllegalArgumentException("chargeType must not be blank");
+ }
+ if (b.amount == null) {
+ throw new IllegalArgumentException("refund amount must not be null");
+ }
+ if (b.amount.isNegative()) {
+ throw new IllegalArgumentException("refund amount must not be negative");
+ }
+ this.chargeName = b.chargeName.trim();
+ this.chargeType = b.chargeType.trim();
+ this.amount = b.amount;
+ }
+
+ /** 新建构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 费用名称。 */
+ public String chargeName() {
+ return chargeName;
+ }
+
+ /** 费用类型。 */
+ public String chargeType() {
+ return chargeType;
+ }
+
+ /** 退款金额。 */
+ public Money amount() {
+ return amount;
+ }
+
+ /** 费用项构建器。 */
+ public static final class Builder {
+
+ /** 费用名称。 */
+ private String chargeName;
+ /** 费用类型。 */
+ private String chargeType;
+ /** 退款金额。 */
+ private Money amount;
+
+ /** 设置费用名称;必填。 */
+ public Builder chargeName(String chargeName) {
+ this.chargeName = chargeName;
+ return this;
+ }
+
+ /** 设置费用类型;必填。 */
+ public Builder chargeType(String chargeType) {
+ this.chargeType = chargeType;
+ return this;
+ }
+
+ /** 设置退款金额;必填且不能为负。 */
+ public Builder amount(Money amount) {
+ this.amount = amount;
+ return this;
+ }
+
+ /** 构建费用项;缺字段或金额为负时抛 {@link IllegalArgumentException}。 */
+ public Charge build() {
+ return new Charge(this);
+ }
+ }
+ }
+
+ /** 退款命令构建器。 */
+ public static final class Builder {
+
+ /** 平台退货单号。 */
+ private String afterSaleId;
+ /** 退款行。 */
+ private final List lines = new ArrayList();
+
+ /** 设置平台退货单号;必填。 */
+ public Builder afterSaleId(String afterSaleId) {
+ this.afterSaleId = afterSaleId;
+ return this;
+ }
+
+ /** 追加一条退款行。 */
+ public Builder line(Line line) {
+ if (line != null) {
+ this.lines.add(line);
+ }
+ return this;
+ }
+
+ /** 批量追加退款行;null 视为不加。 */
+ public Builder lines(List lines) {
+ if (lines != null) {
+ for (Line line : lines) {
+ line(line);
+ }
+ }
+ return this;
+ }
+
+ /** 构建命令;缺单号或没有退款行时抛 {@link IllegalArgumentException}。 */
+ public RefundCommand build() {
+ return new RefundCommand(this);
+ }
+ }
+
+ private static boolean isBlank(String value) {
+ return value == null || value.trim().isEmpty();
+ }
+}
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundResult.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundResult.java
new file mode 100644
index 0000000..0afba6d
--- /dev/null
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundResult.java
@@ -0,0 +1,134 @@
+package common.ecommerce.channel.model.aftersale;
+
+import common.ecommerce.shared.support.Money;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 退款结果。
+ *
+ * 各平台对退款接口的响应差异很大:有的返回更新后的退货单,有的只返回受理状态,
+ * 有的什么都不回。所以这里只收敛三样调用方一定关心的东西:
+ * 哪个退货单、退款是否被受理、平台回传的金额(如果有)。
+ *
+ * 平台若返回了完整退货单,行级状态放在 {@link #lines()};
+ * 原值始终可通过 {@link #rawStatus()} 取到,便于排查。
+ */
+public final class RefundResult {
+
+ /** 平台退货单号;非 null。 */
+ private final String afterSaleId;
+
+ /** 平台返回的退款状态原值;平台不回时为 null。 */
+ private final String rawStatus;
+
+ /** 平台回传的退款金额;平台不回或没有币种时为 null(不猜)。 */
+ private final Money refundedAmount;
+
+ /** 行级退款结果;不可变,永不为 null,可能为空。 */
+ private final List lines;
+
+ private RefundResult(Builder b) {
+ this.afterSaleId = b.afterSaleId;
+ this.rawStatus = b.rawStatus;
+ this.refundedAmount = b.refundedAmount;
+ this.lines = Collections.unmodifiableList(new ArrayList(b.lines));
+ }
+
+ /** 新建构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 平台退货单号。 */
+ public String afterSaleId() {
+ return afterSaleId;
+ }
+
+ /** 平台返回的退款状态原值;可空。 */
+ public String rawStatus() {
+ return rawStatus;
+ }
+
+ /** 平台回传的退款金额;可空。 */
+ public Money refundedAmount() {
+ return refundedAmount;
+ }
+
+ /** 行级结果;可能为空。 */
+ public List lines() {
+ return lines;
+ }
+
+ /** 单行的退款结果。 */
+ public static final class LineResult {
+
+ /** 平台退货行号。 */
+ private final String lineId;
+
+ /** 平台该行的退款状态原值。 */
+ private final String status;
+
+ /** 构造单行结果;两个字段都可空。 */
+ public LineResult(String lineId, String status) {
+ this.lineId = lineId;
+ this.status = status;
+ }
+
+ /** 平台退货行号。 */
+ public String lineId() {
+ return lineId;
+ }
+
+ /** 平台退款状态原值。 */
+ public String status() {
+ return status;
+ }
+ }
+
+ /** 退款结果构建器。 */
+ public static final class Builder {
+
+ /** 平台退货单号。 */
+ private String afterSaleId;
+ /** 平台状态原值。 */
+ private String rawStatus;
+ /** 平台回传金额。 */
+ private Money refundedAmount;
+ /** 行级结果。 */
+ private final List lines = new ArrayList();
+
+ /** 设置平台退货单号。 */
+ public Builder afterSaleId(String afterSaleId) {
+ this.afterSaleId = afterSaleId;
+ return this;
+ }
+
+ /** 设置平台状态原值。 */
+ public Builder rawStatus(String rawStatus) {
+ this.rawStatus = rawStatus;
+ return this;
+ }
+
+ /** 设置平台回传的退款金额。 */
+ public Builder refundedAmount(Money refundedAmount) {
+ this.refundedAmount = refundedAmount;
+ return this;
+ }
+
+ /** 追加一条行级结果。 */
+ public Builder line(LineResult line) {
+ if (line != null) {
+ this.lines.add(line);
+ }
+ return this;
+ }
+
+ /** 构建结果。 */
+ public RefundResult build() {
+ return new RefundResult(this);
+ }
+ }
+}
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentCommand.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentCommand.java
new file mode 100644
index 0000000..145108f
--- /dev/null
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentCommand.java
@@ -0,0 +1,345 @@
+package common.ecommerce.channel.model.fulfillment;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 标发(订单发货)命令。
+ *
+ * 一个命令对应一个平台订单 。沃尔玛没有批量标发接口,多订单要循环调用;
+ * 其它平台若支持批量,由适配器自行拆成多次调用,门面层保持「一命令一订单」的语义。
+ *
+ * 支持部分发货:同一订单行可以分多次提交,每次给本次实发数量。
+ * 是否允许部分发货由平台决定,适配器在平台拒绝时抛业务异常。
+ */
+public final class ShipmentCommand {
+
+ /** 平台订单号;必填。 */
+ private final String channelOrderId;
+
+ /** 发货行;不可变,至少一行。 */
+ private final List lines;
+
+ private ShipmentCommand(Builder b) {
+ if (b.channelOrderId == null || b.channelOrderId.trim().isEmpty()) {
+ throw new IllegalArgumentException("channelOrderId must not be blank");
+ }
+ if (b.lines.isEmpty()) {
+ throw new IllegalArgumentException("shipment requires at least one line");
+ }
+ this.channelOrderId = b.channelOrderId.trim();
+ this.lines = Collections.unmodifiableList(new ArrayList(b.lines));
+ }
+
+ /** 新建构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 平台订单号。 */
+ public String channelOrderId() {
+ return channelOrderId;
+ }
+
+ /** 发货行;不可变,至少一行。 */
+ public List lines() {
+ return lines;
+ }
+
+ /**
+ * 幂等业务键:{@code 订单号:行号:数量, 行号:数量...}。
+ *
+ * 行号排序后拼接,保证同一组行无论顺序如何都得到同一个键。
+ * 不含金额与跟踪号 :重发同一批货不该因为换了跟踪号而变成新动作;
+ * 换了跟踪号属于「修正」,由宿主决定是否先作废原动作。
+ */
+ public String businessRef() {
+ List parts = new ArrayList(lines.size());
+ for (Line line : lines) {
+ parts.add(line.lineNumber() + ":" + line.quantity());
+ }
+ java.util.Collections.sort(parts);
+ StringBuilder sb = new StringBuilder(channelOrderId).append('|');
+ for (int i = 0; i < parts.size(); i++) {
+ if (i > 0) {
+ sb.append(',');
+ }
+ sb.append(parts.get(i));
+ }
+ return sb.toString();
+ }
+
+ /** 本次发货的总件数,便于埋点与幂等键构造。 */
+ public int totalQuantity() {
+ int total = 0;
+ for (Line line : lines) {
+ total += line.quantity();
+ }
+ return total;
+ }
+
+ /**
+ * 一条发货行:订单行 + 本次实发数量 + 物流信息。
+ *
+ * 沃尔玛要求 {@code lineNumber} 必须与订单详情里的一致,否则整单被拒。
+ */
+ public static final class Line {
+
+ /** 平台订单行号;必填。 */
+ private final String lineNumber;
+
+ /** 本次实发数量;必须大于 0。 */
+ private final int quantity;
+
+ /** 承运商编码,如 {@code UPS} / {@code FedEx};与 {@link #carrierName} 二选一。 */
+ private final String carrier;
+
+ /** 非标准承运商名称;与 {@link #carrier} 二选一。 */
+ private final String carrierName;
+
+ /** 运输方式编码;平台要求与承运商匹配(如沃尔玛的 {@code Standard})。 */
+ private final String methodCode;
+
+ /** 物流跟踪号;必填。 */
+ private final String trackingNumber;
+
+ /**
+ * 承运商跟踪页 URL;可空。
+ *
+ * 部分平台在用非标准承运商时要求它,沃尔玛的官方 schema 未强制。
+ */
+ private final String trackingUrl;
+
+ /**
+ * 卖家自定义订单号;可空,平台有长度限制(沃尔玛 ≤30 字符)。
+ *
+ * 沃尔玛会把它印在退货面单上,通常填 customerOrderId。
+ */
+ private final String sellerOrderId;
+
+ /**
+ * 客户已申请取消但卖家仍要发货时的确认标记;默认 false。
+ *
+ * 只有平台明确要求时才有意义(沃尔玛 {@code intentToCancelOverride})。
+ */
+ private final boolean intentToCancelOverride;
+
+ /** 发货时间;null 表示由适配器取当前时钟。 */
+ private final Instant shippedAt;
+
+ private Line(Builder b) {
+ if (b.lineNumber == null || b.lineNumber.trim().isEmpty()) {
+ throw new IllegalArgumentException("lineNumber must not be blank");
+ }
+ if (b.quantity <= 0) {
+ throw new IllegalArgumentException("quantity must be positive");
+ }
+ if (b.trackingNumber == null || b.trackingNumber.trim().isEmpty()) {
+ throw new IllegalArgumentException("trackingNumber must not be blank");
+ }
+ if (isBlank(b.carrier) && isBlank(b.carrierName)) {
+ throw new IllegalArgumentException("carrier or carrierName is required");
+ }
+ this.lineNumber = b.lineNumber.trim();
+ this.quantity = b.quantity;
+ this.carrier = b.carrier;
+ this.carrierName = b.carrierName;
+ this.methodCode = b.methodCode;
+ this.trackingNumber = b.trackingNumber.trim();
+ this.trackingUrl = b.trackingUrl;
+ this.sellerOrderId = b.sellerOrderId;
+ this.intentToCancelOverride = b.intentToCancelOverride;
+ this.shippedAt = b.shippedAt;
+ }
+
+ /** 平台订单行号。 */
+ public String lineNumber() {
+ return lineNumber;
+ }
+
+ /** 本次实发数量。 */
+ public int quantity() {
+ return quantity;
+ }
+
+ /** 标准承运商编码;可空。 */
+ public String carrier() {
+ return carrier;
+ }
+
+ /** 非标准承运商名称;可空。 */
+ public String carrierName() {
+ return carrierName;
+ }
+
+ /** 运输方式编码;可空。 */
+ public String methodCode() {
+ return methodCode;
+ }
+
+ /** 物流跟踪号。 */
+ public String trackingNumber() {
+ return trackingNumber;
+ }
+
+ /** 承运商跟踪页 URL;可空。 */
+ public String trackingUrl() {
+ return trackingUrl;
+ }
+
+ /** 卖家自定义订单号;可空。 */
+ public String sellerOrderId() {
+ return sellerOrderId;
+ }
+
+ /** 客户已申请取消仍要发货时的确认标记。 */
+ public boolean intentToCancelOverride() {
+ return intentToCancelOverride;
+ }
+
+ /** 发货时间;null 表示由适配器取当前时钟。 */
+ public Instant shippedAt() {
+ return shippedAt;
+ }
+
+ /** 新建发货行构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 发货行构建器。 */
+ public static final class Builder {
+
+ /** 平台订单行号;必填。 */
+ private String lineNumber;
+ /** 本次实发数量。 */
+ private int quantity;
+ /** 标准承运商编码。 */
+ private String carrier;
+ /** 非标准承运商名称。 */
+ private String carrierName;
+ /** 运输方式编码。 */
+ private String methodCode;
+ /** 物流跟踪号。 */
+ private String trackingNumber;
+ /** 承运商跟踪页 URL;可空。 */
+ private String trackingUrl;
+ /** 卖家自定义订单号;可空。 */
+ private String sellerOrderId;
+ /** 客户已申请取消仍要发货时的确认标记;默认 false。 */
+ private boolean intentToCancelOverride;
+ /** 发货时间;null 由适配器取当前时钟。 */
+ private Instant shippedAt;
+
+ /** 设置行号;必填。 */
+ public Builder lineNumber(String lineNumber) {
+ this.lineNumber = lineNumber;
+ return this;
+ }
+
+ /** 设置本次实发数量;必须大于 0。 */
+ public Builder quantity(int quantity) {
+ this.quantity = quantity;
+ return this;
+ }
+
+ /** 设置标准承运商编码。 */
+ public Builder carrier(String carrier) {
+ this.carrier = carrier;
+ return this;
+ }
+
+ /** 设置非标准承运商名称。 */
+ public Builder carrierName(String carrierName) {
+ this.carrierName = carrierName;
+ return this;
+ }
+
+ /** 设置运输方式编码。 */
+ public Builder methodCode(String methodCode) {
+ this.methodCode = methodCode;
+ return this;
+ }
+
+ /** 设置物流跟踪号;必填。 */
+ public Builder trackingNumber(String trackingNumber) {
+ this.trackingNumber = trackingNumber;
+ return this;
+ }
+
+ /** 设置承运商跟踪页 URL;可空。 */
+ public Builder trackingUrl(String trackingUrl) {
+ this.trackingUrl = trackingUrl;
+ return this;
+ }
+
+ /** 设置卖家自定义订单号;可空,平台长度上限见各适配器。 */
+ public Builder sellerOrderId(String sellerOrderId) {
+ this.sellerOrderId = sellerOrderId;
+ return this;
+ }
+
+ /** 设置「客户已申请取消但仍要发货」的确认标记。 */
+ public Builder intentToCancelOverride(boolean intentToCancelOverride) {
+ this.intentToCancelOverride = intentToCancelOverride;
+ return this;
+ }
+
+ /** 设置发货时间;不设置时由适配器取当前时钟。 */
+ public Builder shippedAt(Instant shippedAt) {
+ this.shippedAt = shippedAt;
+ return this;
+ }
+
+ /** 构建发货行;缺必填字段时抛 {@link IllegalArgumentException}。 */
+ public Line build() {
+ return new Line(this);
+ }
+ }
+ }
+
+ /** 发货命令构建器。 */
+ public static final class Builder {
+
+ /** 平台订单号;必填。 */
+ private String channelOrderId;
+
+ /** 发货行。 */
+ private final List lines = new ArrayList();
+
+ /** 设置平台订单号。 */
+ public Builder channelOrderId(String channelOrderId) {
+ this.channelOrderId = channelOrderId;
+ return this;
+ }
+
+ /** 追加一条发货行。 */
+ public Builder line(Line line) {
+ if (line != null) {
+ this.lines.add(line);
+ }
+ return this;
+ }
+
+ /** 批量追加发货行;null 视为不加。 */
+ public Builder lines(List lines) {
+ if (lines != null) {
+ for (Line line : lines) {
+ line(line);
+ }
+ }
+ return this;
+ }
+
+ /** 构建命令;订单号为空或没有发货行时抛 {@link IllegalArgumentException}。 */
+ public ShipmentCommand build() {
+ return new ShipmentCommand(this);
+ }
+ }
+
+ private static boolean isBlank(String value) {
+ return value == null || value.trim().isEmpty();
+ }
+}
diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentResult.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentResult.java
new file mode 100644
index 0000000..24470aa
--- /dev/null
+++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentResult.java
@@ -0,0 +1,142 @@
+package common.ecommerce.channel.model.fulfillment;
+
+import java.time.Instant;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * 标发结果。
+ *
+ * 标发是「一订单一次调用」,所以结果以订单为单位:成功时带平台确认的
+ * 发货时间与(可能的)新状态;平台只回订单对象时,这里只保留关键字段,
+ * 完整订单由调用方按需重新查询。
+ */
+public final class ShipmentResult {
+
+ /** 平台订单号;非 null。 */
+ private final String channelOrderId;
+
+ /** 平台确认的发货时间;平台不回时为 null。 */
+ private final Instant shippedAt;
+
+ /** 平台侧记录的跟踪号;平台不回时为 null。 */
+ private final String trackingNumber;
+
+ /** 行级发货记录;不可变,永远不为 null,可能为空(平台只回整体状态时)。 */
+ private final Map lines;
+
+ private ShipmentResult(Builder b) {
+ this.channelOrderId = b.channelOrderId;
+ this.shippedAt = b.shippedAt;
+ this.trackingNumber = b.trackingNumber;
+ this.lines = Collections.unmodifiableMap(new LinkedHashMap(b.lines));
+ }
+
+ /** 新建构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 平台订单号。 */
+ public String channelOrderId() {
+ return channelOrderId;
+ }
+
+ /** 平台确认的发货时间;可空。 */
+ public Instant shippedAt() {
+ return shippedAt;
+ }
+
+ /** 平台记录的跟踪号;可空。 */
+ public String trackingNumber() {
+ return trackingNumber;
+ }
+
+ /** 行级发货记录,键为平台订单行号;可能为空 Map。 */
+ public Map lines() {
+ return lines;
+ }
+
+ /**
+ * 单行的发货状态。
+ *
+ * 平台可能只回「部分发货」:同一行的 {@link #quantity()} 是累计已发数量,
+ * 不是本次实发数量。
+ */
+ public static final class LineShipment {
+
+ /** 平台订单行号。 */
+ private final String lineNumber;
+ /** 平台侧该行累计已发数量。 */
+ private final int quantity;
+ /** 行状态原值,如 {@code Shipped}、{@code Created}。 */
+ private final String status;
+
+ /** 构造单行发货状态。 */
+ public LineShipment(String lineNumber, int quantity, String status) {
+ this.lineNumber = lineNumber;
+ this.quantity = quantity;
+ this.status = status;
+ }
+
+ /** 平台订单行号。 */
+ public String lineNumber() {
+ return lineNumber;
+ }
+
+ /** 该行累计已发数量。 */
+ public int quantity() {
+ return quantity;
+ }
+
+ /** 行状态原值。 */
+ public String status() {
+ return status;
+ }
+ }
+
+ /** 标发结果构建器。 */
+ public static final class Builder {
+
+ /** 平台订单号。 */
+ private String channelOrderId;
+ /** 平台确认的发货时间。 */
+ private Instant shippedAt;
+ /** 跟踪号。 */
+ private String trackingNumber;
+ /** 行级记录。 */
+ private final Map lines = new LinkedHashMap();
+
+ /** 设置平台订单号。 */
+ public Builder channelOrderId(String channelOrderId) {
+ this.channelOrderId = channelOrderId;
+ return this;
+ }
+
+ /** 设置平台确认的发货时间。 */
+ public Builder shippedAt(Instant shippedAt) {
+ this.shippedAt = shippedAt;
+ return this;
+ }
+
+ /** 设置平台记录的跟踪号。 */
+ public Builder trackingNumber(String trackingNumber) {
+ this.trackingNumber = trackingNumber;
+ return this;
+ }
+
+ /** 追加一条行级记录。 */
+ public Builder line(LineShipment line) {
+ if (line != null && line.lineNumber() != null) {
+ this.lines.put(line.lineNumber(), line);
+ }
+ return this;
+ }
+
+ /** 构建结果。 */
+ public ShipmentResult build() {
+ return new ShipmentResult(this);
+ }
+ }
+}
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
index 707c6da..2c6a081 100644
--- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java
@@ -8,8 +8,10 @@ package common.ecommerce.walmart;
* 端点由调用方每次经 {@code ChannelConnection} 传入(沙箱还是生产由宿主决定,
* 账户上的 {@code ChannelAccount.sandbox()} 只是元数据)。
*
- * 来源:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱
- * {@code https://sandbox.walmartapis.com} 实测。
+ * 来源:Walmart Developer Portal 官方 reference(2026-11 核对):
+ * {@code /us-marketplace/reference/} 下的 {@code shippingupdates}、{@code getallorders}、
+ * {@code getreturns}、{@code getallitems}、{@code itembulkuploads}、{@code getallfeedstatuses}。
+ * 与《沃尔玛沙箱接口说明》v1.0 冲突时以官方 schema 为准 。
*/
public final class WalmartConstants {
@@ -48,6 +50,17 @@ public final class WalmartConstants {
/** 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。⚠ 沙箱实测 404。 */
public static final String PATH_ORDER_SHIPPING = "/shipping";
+ /** 发起退款:{@code POST /v3/returns/{returnOrderId}/refund}。⚠ 沙箱实测 404。 */
+ public static final String PATH_RETURN_REFUND = "/refund";
+
+ /**
+ * Feed 提交({@code POST /v3/feeds?feedType=...})与状态查询({@code GET /v3/feeds/{feedId}})。
+ *
+ * ⚠ 沙箱实测两条路由都 520(mock 未实现);本期只做常量与 DTO,
+ * 没有对外方法——沃尔玛的商品写入是 Feed 的载体,等商品写接入时一起开放。
+ */
+ public static final String PATH_FEEDS = "/v3/feeds";
+
// ---------------------------------------------------------------- 请求头
/** 服务名,固定值。 */
@@ -71,27 +84,41 @@ public final class WalmartConstants {
// ---------------------------------------------------------------- 限制
/**
- * 商品列表单页上限(官方值,超了本地截断)。
+ * 商品列表单页上限。
*
- * 与领星不同,这里是平台硬上限 :静默截断是安全的,因为调用方本来
- * 就只能拿到这么多,且用 {@code nextCursor} 翻页。
+ * 官方原文:{@code cannot be more than 1000 entities per request},默认 20。
+ * 注意 {@code nextCursor} 描述里的「more than 200 items」是建议改用游标的阈值 ,
+ * 不是 limit 上限——两者容易混。
*/
- public static final int MAX_ITEM_PAGE_SIZE = 200;
+ public static final int MAX_ITEM_PAGE_SIZE = 1000;
+
+ /**
+ * 商品列表 {@code nextCursor} 的初始值。
+ *
+ * 官方 schema 的 {@code default} 与 {@code example} 都是 {@code *}。
+ * 不过首页不传也能用平台默认,适配器选择不显式传 ,避免平台版本差异导致 400。
+ */
+ public static final String ITEM_CURSOR_INITIAL = "*";
+
+ /** 商品游标有效期(秒);过期平台返回 400 Invalid Cursor。 */
+ public static final int ITEM_CURSOR_TTL_SECONDS = 120;
/** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */
public static final int DEFAULT_ORDER_PAGE_SIZE = 20;
/**
- * 订单列表单页上限(📖 官方常见取值 200,与商品一致)。
+ * 订单列表单页上限。
*
- * 文档没给订单的 {@code limit} 上限;这里与商品保持同一策略:超了本地截断,
- * 而不是把大值原样发给平台(沙箱 mock 不校验,生产会被拒)。
+ * 官方原文:{@code Cannot be larger than 200.}
*/
public static final int MAX_ORDER_PAGE_SIZE = 200;
/** 退货列表默认单页条数;沃尔玛默认 10。 */
public static final int DEFAULT_RETURN_PAGE_SIZE = 10;
+ /** 退货列表单页上限;官方原文 {@code Cannot be larger than 200.} */
+ public static final int MAX_RETURN_PAGE_SIZE = 200;
+
/**
* 订单创建时间窗的最大回溯天数(📖 官方常见取值,待 Developer Portal 核实)。
*
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
index b66d5b3..d8be395 100644
--- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
@@ -1,12 +1,16 @@
package common.ecommerce.walmart.adapter;
import common.ecommerce.channel.capability.AfterSaleCapable;
+import common.ecommerce.channel.capability.MarkShippedCapable;
+import common.ecommerce.channel.capability.RefundCapable;
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.aftersale.RefundCommand;
+import common.ecommerce.channel.model.aftersale.RefundResult;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.order.SalesOrderRef;
@@ -14,6 +18,8 @@ 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.model.fulfillment.ShipmentCommand;
+import common.ecommerce.channel.model.fulfillment.ShipmentResult;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
@@ -35,13 +41,21 @@ 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.WalmartFeedDtos;
+import common.ecommerce.walmart.dto.WalmartRefundDtos;
import common.ecommerce.walmart.dto.WalmartShipmentDtos;
+import common.ecommerce.walmart.dto.WalmartShipmentWriteDtos;
import common.ecommerce.walmart.http.WalmartErrors;
import common.ecommerce.walmart.http.WalmartRequestFactory;
+import common.ecommerce.walmart.model.WalmartFeedCommand;
+import common.ecommerce.walmart.model.WalmartFeedStatus;
import common.ecommerce.walmart.mapper.WalmartOrderMapper;
import common.ecommerce.walmart.mapper.WalmartProductMapper;
import common.ecommerce.walmart.mapper.WalmartReturnMapper;
+import common.ecommerce.walmart.mapper.WalmartFeedMapper;
+import common.ecommerce.walmart.mapper.WalmartRefundMapper;
import common.ecommerce.walmart.mapper.WalmartShipmentMapper;
+import common.ecommerce.walmart.mapper.WalmartShipmentWriteMapper;
import java.time.Clock;
import java.time.Duration;
@@ -75,7 +89,8 @@ import org.slf4j.LoggerFactory;
* 「老单状态变化」需要宿主用 {@link #pullOpenOrders} 单独对账,两者不混在一起,
* 免得 {@code pull} 的语义变得不可预测。
*/
-public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, AfterSaleCapable {
+public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, AfterSaleCapable,
+ MarkShippedCapable, RefundCapable {
private static final Logger LOG = LoggerFactory.getLogger(WalmartAdapter.class);
@@ -125,7 +140,8 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
@Override
public EnumSet capabilities() {
- return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS);
+ return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS,
+ Capability.MARK_SHIPPED, Capability.REFUND);
}
// ---------------------------------------------------------------- SalesOrderCapable
@@ -364,15 +380,18 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
* 分页特殊:{@code meta.nextCursor} 本身是一段查询串
* (如 {@code "?sellerId=151&limit=10&offset=10"}),翻页时整串拼到 URL 后面。
*
- * 时间窗只支持按退货单创建时间;{@code PURCHASE_TIME} / {@code UPDATE_TIME}
- * 显式报错,不做「拿售后时间顶替」的静默降级。
+ * 时间窗映射:{@link AfterSaleQuery.DateType#AFTER_SALE_TIME} 用
+ * {@code returnCreationStartDate/EndDate},
+ * {@link AfterSaleQuery.DateType#UPDATE_TIME} 用
+ * {@code returnLastModifiedStartDate/EndDate}(官方两套参数都有)。
+ * {@code PURCHASE_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.dateType() == AfterSaleQuery.DateType.PURCHASE_TIME) {
+ throw unsupportedFilter("walmart /v3/returns has no purchase-time filter; "
+ + "use AFTER_SALE_TIME or UPDATE_TIME");
}
if (!query.channelOrderIds().isEmpty()) {
throw unsupportedFilter("walmart /v3/returns filters one customerOrderId at a time, not a list");
@@ -391,13 +410,23 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
}
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()));
+ // 官方参数名是 returnCreationStartDate/EndDate 与 returnLastModifiedStartDate/EndDate
+ // (不是 createdStartDate);传错名字平台会忽略过滤条件、返回全量数据
+ String from = WALMART_TIME_FORMAT.format(
+ query.startDate().atStartOfDay(ZoneId.of("UTC")).toInstant());
+ String to = WALMART_TIME_FORMAT.format(
+ query.endDate().atStartOfDay(ZoneId.of("UTC")).toInstant());
+ if (query.dateType() == AfterSaleQuery.DateType.UPDATE_TIME) {
+ queryParams.put("returnLastModifiedStartDate", from);
+ queryParams.put("returnLastModifiedEndDate", to);
+ } else {
+ queryParams.put("returnCreationStartDate", from);
+ queryParams.put("returnCreationEndDate", to);
+ }
queryParams.put("limit", query.pageSize() <= 0
- ? WalmartConstants.DEFAULT_RETURN_PAGE_SIZE : query.pageSize());
- queryParams.put("offset", 0);
+ ? WalmartConstants.DEFAULT_RETURN_PAGE_SIZE
+ : Math.min(query.pageSize(), WalmartConstants.MAX_RETURN_PAGE_SIZE));
+ // 官方退货接口没有 offset 参数,翻页只靠 meta.nextCursor
return executeReturns(ctx, account, "afterSales.pull", new GetPlan() {
@Override
@@ -471,6 +500,212 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
return WalmartReturnMapper.toAfterSales(dto, account.omsStoreId(), zoneOf(ctx));
}
+ // ---------------------------------------------------------------- MarkShippedCapable
+
+ /**
+ * 标发:{@code POST /v3/orders/{purchaseOrderId}/shipping}。
+ *
+ * 沃尔玛没有批量标发接口 ,一次一个订单。支持部分发货:同一行可以
+ * 多次调用,{@code statusQuantity.amount} 累计;剩余数量标完后行状态才变
+ * {@code Shipped}。
+ *
+ * 幂等由调用方经 {@code sdk.writes()} 保证,推荐业务键
+ * {@link ShipmentCommand#businessRef()}:订单号 + 行号 + 数量。
+ *
+ * ⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。
+ *
+ * @throws common.ecommerce.shared.error.ValidationException 命令不完整
+ * @throws common.ecommerce.shared.error.PlatformBusinessException 平台拒绝(如订单已取消)
+ */
+ @Override
+ public ShipmentResult markShipped(ChannelContext ctx, ShipmentCommand command) {
+ if (command == null) {
+ throw new ValidationException(ChannelException.builder()
+ .message("walmart markShipped requires a shipment command")
+ .operation("salesOrders.markShipped")
+ .provider(provider().name())
+ .platform(Platform.WALMART_SC)
+ .retryable(false));
+ }
+ String path = WalmartConstants.PATH_ORDER_BY_ID
+ + WalmartRequestFactory.pathSegment(command.channelOrderId())
+ + WalmartConstants.PATH_ORDER_SHIPPING;
+
+ WalmartShipmentWriteDtos.ShipmentRequest body =
+ WalmartShipmentWriteMapper.toRequest(command, ctx.clock());
+
+ HttpResponse response = execute(ctx, "salesOrders.markShipped", new GetPlan() {
+ @Override
+ public HttpRequest request(ChannelContext c, AccessToken t) {
+ return requestFactory.write("POST", c.endpointBaseUrl(), path, null, body, json, t, c,
+ "salesOrders.markShipped");
+ }
+ });
+
+ // 沃尔玛标发成功回更新后的订单;也见过只回受理结果的情况,两种都兼容
+ WalmartOrderDtos.OrderDetailResponse dto =
+ json.fromJson(response.body(), WalmartOrderDtos.OrderDetailResponse.class);
+ return WalmartShipmentWriteMapper.toResult(dto == null ? null : dto.order, command);
+ }
+
+ // ---------------------------------------------------------------- RefundCapable
+
+ /**
+ * 发起退款:{@code POST /v3/returns/{returnOrderId}/refund}。
+ *
+ * 沃尔玛退款细到退货行 × 费用项 :每个退货行可只退部分费用
+ * (商品价 / 运费 / 税)。命令里给什么就退什么,适配器不补全。
+ *
+ * 业务规则(文档 §5.3):部分售后由平台自动退款,只有
+ * {@code currentRefundStatus} 需要卖家处理时才需调用;调用前应查详情核对
+ * {@code refundedQty} / {@code cancellableQty},避免超退。
+ *
+ * 幂等由调用方经 {@code sdk.writes()} 保证。
+ *
+ * ⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。
+ *
+ * @throws ValidationException 退货行号不是整数(沃尔玛要求 integer)
+ * @throws common.ecommerce.shared.error.PlatformBusinessException 平台拒绝(已退过 / 超退)
+ */
+ @Override
+ public RefundResult refund(ChannelContext ctx, RefundCommand command) {
+ if (command == null) {
+ throw new ValidationException(ChannelException.builder()
+ .message("walmart refund requires a refund command")
+ .operation("afterSales.refund")
+ .provider(provider().name())
+ .platform(Platform.WALMART_SC)
+ .retryable(false));
+ }
+ final WalmartRefundDtos.RefundRequest body;
+ try {
+ body = WalmartRefundMapper.toRequest(command, command.afterSaleId());
+ } catch (IllegalArgumentException e) {
+ throw new ValidationException(ChannelException.builder()
+ .message(e.getMessage())
+ .operation("afterSales.refund")
+ .provider(provider().name())
+ .platform(Platform.WALMART_SC)
+ .retryable(false));
+ }
+
+ String path = WalmartConstants.PATH_RETURN_BY_ID
+ + WalmartRequestFactory.pathSegment(command.afterSaleId())
+ + WalmartConstants.PATH_RETURN_REFUND;
+
+ HttpResponse response = execute(ctx, "afterSales.refund", new GetPlan() {
+ @Override
+ public HttpRequest request(ChannelContext c, AccessToken t) {
+ return requestFactory.write("POST", c.endpointBaseUrl(), path, null, body, json, t, c,
+ "afterSales.refund");
+ }
+ });
+
+ // 响应结构未实测:能解成退货单就取行级状态,否则只保留单号
+ WalmartReturnDtos.ReturnOrder applied = parseReturnOrderQuietly(response.body());
+ return WalmartRefundMapper.toResult(applied, command);
+ }
+
+ /** 退款响应尽力解析成退货单;解不出来返回 null,不抛。 */
+ private WalmartReturnDtos.ReturnOrder parseReturnOrderQuietly(String body) {
+ if (body == null || body.trim().isEmpty()) {
+ return null;
+ }
+ try {
+ return json.fromJson(body, WalmartReturnDtos.ReturnOrder.class);
+ } catch (RuntimeException e) {
+ return null;
+ }
+ }
+
+ // ---------------------------------------------------------------- Feed(非能力接口)
+
+ /**
+ * 提交商品 Feed:{@code POST /v3/feeds?feedType=MP_ITEM}。
+ *
+ * 沃尔玛的商品写入是异步批量 :提交只回一个 {@code feedId},
+ * 真正的成败要用 {@link #getFeedStatus} 轮询。成功响应是 HTTP 200
+ * 且 body 带 {@code feedId}(官方 schema 只声明了 200,没有 202)。
+ *
+ * 商品报文字段原样透传({@code MPItem[]} 每个元素的结构由调用方按
+ * Walmart《Item Spec》给),本适配器只补报文头。
+ *
+ * ⚠ 沙箱实测返回 520(mock 未实现),只能在生产环境验证。
+ *
+ * @param command Feed 命令
+ * @return 批次 ID
+ * @throws common.ecommerce.shared.error.TransientException 平台 5xx(可重试)
+ */
+ public String submitFeed(ChannelContext ctx, WalmartFeedCommand command) {
+ if (command == null) {
+ throw unsupportedFilter("walmart feed submit requires a command");
+ }
+ if (!WalmartFeedDtos.isSupportedFeedType(command.feedType())) {
+ throw unsupportedFilter("walmart feedType is not supported: " + command.feedType()
+ + "; valid values: " + WalmartFeedDtos.FEED_TYPES);
+ }
+ Map queryParams = WalmartRequestFactory.query();
+ queryParams.put("feedType", command.feedType());
+ WalmartFeedDtos.FeedRequest body = WalmartFeedMapper.toRequest(command);
+
+ HttpResponse response = execute(ctx, "feeds.submit", new GetPlan() {
+ @Override
+ public HttpRequest request(ChannelContext c, AccessToken t) {
+ return requestFactory.write("POST", c.endpointBaseUrl(), WalmartConstants.PATH_FEEDS,
+ queryParams, body, json, t, c, "feeds.submit");
+ }
+ });
+
+ WalmartFeedDtos.FeedSubmitResponse dto =
+ json.fromJson(response.body(), WalmartFeedDtos.FeedSubmitResponse.class);
+ if (dto == null || isBlank(dto.feedId)) {
+ throw new ValidationException(ChannelException.builder()
+ .message("walmart feed submit returned no feedId")
+ .operation("feeds.submit")
+ .provider(provider().name())
+ .omsStoreId(ctx.omsStoreId())
+ .platform(ctx.platform())
+ .requestId(ctx.requestId())
+ .rawResponse(response.body())
+ .retryable(false));
+ }
+ return dto.feedId;
+ }
+
+ /**
+ * 查询 Feed 处理状态:{@code GET /v3/feeds/{feedId}}。
+ *
+ * 典型轮询:{@code RECEIVED} → {@code INPROGRESS} → {@code PROCESSED} / {@code ERROR}。
+ * {@code PROCESSED} 也可能有部分失败,看 {@code itemsFailed()} 与
+ * {@code items()} 里的逐条 {@code DATA_ERROR}。
+ *
+ * @param feedId submitFeed 返回的批次 ID
+ * @param includeDetails 是否要逐商品明细
+ * @return 处理状态
+ */
+ public WalmartFeedStatus getFeedStatus(ChannelContext ctx, String feedId, boolean includeDetails) {
+ if (isBlank(feedId)) {
+ throw unsupportedFilter("walmart feed status requires feedId");
+ }
+ String path = WalmartConstants.PATH_FEEDS
+ + "/" + WalmartRequestFactory.pathSegment(feedId.trim());
+ Map queryParams = WalmartRequestFactory.query();
+ if (includeDetails) {
+ queryParams.put("includeDetails", true);
+ }
+
+ HttpResponse response = execute(ctx, "feeds.status", new GetPlan() {
+ @Override
+ public HttpRequest request(ChannelContext c, AccessToken t) {
+ return requestFactory.get(c.endpointBaseUrl(), path, queryParams, t, c, "feeds.status");
+ }
+ });
+
+ WalmartFeedDtos.FeedStatusResponse dto =
+ json.fromJson(response.body(), WalmartFeedDtos.FeedStatusResponse.class);
+ return WalmartFeedMapper.toStatus(dto);
+ }
+
// ---------------------------------------------------------------- 发货信息(非能力接口)
/**
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartFeedDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartFeedDtos.java
new file mode 100644
index 0000000..66e2065
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartFeedDtos.java
@@ -0,0 +1,209 @@
+package common.ecommerce.walmart.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+/**
+ * 沃尔玛报文结构:商品 Feed。
+ *
+ *
+ * 提交:{@code POST /v3/feeds?feedType=MP_ITEM},返回 {@code feedId}
+ * 查询:{@code GET /v3/feeds/{feedId}},返回处理进度与逐商品明细
+ *
+ *
+ * 在本模块里的实际用法 :商品写入走 {@code POST /v3/feeds}(Bulk Item Setup),
+ * 该接口在官方 reference 的 {@code itembulkuploads} 里,官方 {@code feedType} 枚举见
+ * {@link #FEED_TYPES}; 提交成功返回 HTTP 200 且带 {@code feedId},不是 202。
+ *
+ * ⚠ 沙箱实测两条路由都不可用(提交 520、查询 520),只能在生产环境验证。
+ */
+public final class WalmartFeedDtos {
+
+ /**
+ * 官方 {@code feedType} 全量枚举({@code reference/itembulkuploads})。
+ *
+ * 注意《沃尔玛沙箱接口说明》里列的 {@code INVENTORY} / {@code PRICE} /
+ * {@code PROMO} / {@code LAG_TIME} 不在 这个接口的枚举里——库存、价格、
+ * 备货时效各有独立接口。
+ */
+ public static final java.util.Set FEED_TYPES = java.util.Collections.unmodifiableSet(
+ new java.util.LinkedHashSet(java.util.Arrays.asList(
+ "RETIRE_ITEM", "MP_ITEM", "MP_WFS_ITEM", "MP_ITEM_MATCH", "MP_MAINTENANCE",
+ "SKU_TEMPLATE_MAP", "SHIPPING_OVERRIDES", "OMNI_WFS", "FITMENT_ACES",
+ "FITMENT_PIES", "SPLIT_AND_MERGE", "DELETE_ITEM", "MP_VIRTUAL_PACK_BUNDLE")));
+
+ /** 校验 feedType 是否在官方枚举内;不在时由适配器本地拒绝。 */
+ public static boolean isSupportedFeedType(String feedType) {
+ return feedType != null && FEED_TYPES.contains(feedType.trim());
+ }
+
+ private WalmartFeedDtos() {
+ }
+
+ // ---------------------------------------------------------------- 提交
+
+ /**
+ * Feed 提交请求体({@code MP_ITEM} 类型)。
+ *
+ * 字段名与沃尔玛一致;{@code MPItem} 里每个元素的完整结构由
+ * Walmart《Item Spec》决定,随 {@code productType} 不同而不同,
+ * 因此这里用 {@code Object} 承载,由调用方给完整报文。
+ */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class FeedRequest {
+
+ /** 报文头;必填。 */
+ @JsonProperty("MPItemFeedHeader")
+ public FeedHeader header;
+
+ /** 商品数组;必填。每个元素结构见 Item Spec。 */
+ @JsonProperty("MPItem")
+ public List items;
+ }
+
+ /** Feed 报文头。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class FeedHeader {
+
+ /** Item Spec 版本,如 {@code 4.2} / {@code 4.3},需与后台开通版本一致。 */
+ @JsonProperty("version")
+ public String version;
+
+ /** 语言,通常 {@code en}。 */
+ @JsonProperty("locale")
+ public String locale;
+
+ /** 站点,如 {@code WALMART_US}。 */
+ @JsonProperty("businessUnit")
+ public String businessUnit;
+
+ /** 子类目,如 {@code OTHER};可选。 */
+ @JsonProperty("subCategory")
+ public String subCategory;
+ }
+
+ /** Feed 提交响应:只回一个批次 ID。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class FeedSubmitResponse {
+
+ /** Feed 批次 ID,用于查询处理状态。 */
+ @JsonProperty("feedId")
+ public String feedId;
+ }
+
+ // ---------------------------------------------------------------- 查询
+
+ /** Feed 状态响应。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class FeedStatusResponse {
+
+ /** Feed 批次 ID。 */
+ @JsonProperty("feedId")
+ public String feedId;
+
+ /** Feed 类型,如 {@code MP_ITEM}。 */
+ @JsonProperty("feedType")
+ public String feedType;
+
+ /** 处理状态:{@code RECEIVED} / {@code INPROGRESS} / {@code PROCESSED} / {@code ERROR}。 */
+ @JsonProperty("feedStatus")
+ public String feedStatus;
+
+ /** 接收商品数。 */
+ @JsonProperty("itemsReceived")
+ public Integer itemsReceived;
+
+ /** 处理中数量。 */
+ @JsonProperty("itemsProcessing")
+ public Integer itemsProcessing;
+
+ /** 成功数量。 */
+ @JsonProperty("itemsSucceeded")
+ public Integer itemsSucceeded;
+
+ /** 失败数量。 */
+ @JsonProperty("itemsFailed")
+ public Integer itemsFailed;
+
+ /** 提交时间,ISO-8601。 */
+ @JsonProperty("feedSubmissionDate")
+ public String feedSubmissionDate;
+
+ /** 开始处理时间,ISO-8601。 */
+ @JsonProperty("ingestedDate")
+ public String ingestedDate;
+
+ /** 逐商品明细;{@code includeDetails=true} 时才有。 */
+ @JsonProperty("itemDetails")
+ public ItemDetails itemDetails;
+ }
+
+ /** 明细容器。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class ItemDetails {
+
+ /** 明细数组。 */
+ @JsonProperty("itemIngestionStatus")
+ public List itemIngestionStatus;
+ }
+
+ /** 单个商品的处理结果。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class ItemIngestionStatus {
+
+ /** 平台商品 ID(成功时返回)。 */
+ @JsonProperty("wpid")
+ public String wpid;
+
+ /** 卖家 SKU。 */
+ @JsonProperty("sku")
+ public String sku;
+
+ /** 索引(对应提交时报文的顺序)。 */
+ @JsonProperty("index")
+ public Integer index;
+
+ /** 处理状态:{@code SUCCESS} / {@code DATA_ERROR} / {@code SYSTEM_ERROR}。 */
+ @JsonProperty("ingestionStatus")
+ public String ingestionStatus;
+
+ /** 错误原因。 */
+ @JsonProperty("ingestionErrors")
+ public IngestionErrors ingestionErrors;
+ }
+
+ /** 错误明细。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class IngestionErrors {
+
+ /** 错误数组。 */
+ @JsonProperty("ingestionError")
+ public List ingestionError;
+ }
+
+ /** 单条错误。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class IngestionError {
+
+ /** 错误码。 */
+ @JsonProperty("code")
+ public String code;
+
+ /** 错误字段。 */
+ @JsonProperty("field")
+ public String field;
+
+ /** 错误描述。 */
+ @JsonProperty("description")
+ public String description;
+
+ /** 错误类型:{@code DATA_ERROR} / {@code SYSTEM_ERROR}。 */
+ @JsonProperty("type")
+ public String type;
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartRefundDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartRefundDtos.java
new file mode 100644
index 0000000..4b8a6e3
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartRefundDtos.java
@@ -0,0 +1,82 @@
+package common.ecommerce.walmart.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.math.BigDecimal;
+import java.util.List;
+
+/**
+ * 沃尔玛报文结构:发起退款({@code POST /v3/returns/{returnOrderId}/refund})。
+ *
+ * ⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。
+ *
+ * 金额结构是退货接口那一套({@code currencyUnit} + {@code currencyAmount}),
+ * 与订单接口的 {@code {"currency","amount"}} 不同。
+ */
+public final class WalmartRefundDtos {
+
+ private WalmartRefundDtos() {
+ }
+
+ /** 退款请求体。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class RefundRequest {
+
+ /** 退货单号;与路径参数一致。 */
+ @JsonProperty("returnOrderId")
+ public String returnOrderId;
+
+ /** 退款行;必填。 */
+ @JsonProperty("refundLines")
+ public List refundLines;
+ }
+
+ /** 一条退款行。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class RefundLine {
+
+ /** 退货行号,对应退货详情 {@code returnOrderLines[].returnOrderLineNumber}。 */
+ @JsonProperty("returnOrderLineNumber")
+ public Integer returnOrderLineNumber;
+
+ /** 退款费用明细;必填。 */
+ @JsonProperty("refundCharges")
+ public List refundCharges;
+ }
+
+ /** 一条退款费用项。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class RefundCharge {
+
+ /** 费用名称,如 {@code ItemPrice}、{@code Shipping}。 */
+ @JsonProperty("chargeName")
+ public String chargeName;
+
+ /** 费用类型:{@code PRODUCT} / {@code FEE} / {@code SHIPPING}。 */
+ @JsonProperty("chargeType")
+ public String chargeType;
+
+ /** 退款金额。 */
+ @JsonProperty("refundAmount")
+ public CurrencyAmount refundAmount;
+ }
+
+ /** 金额:{@code {"currencyUnit","currencyAmount"}},与退货接口一致。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class CurrencyAmount {
+
+ /** 币种,如 {@code USD}。 */
+ @JsonProperty("currencyUnit")
+ public String currencyUnit;
+
+ /** 金额;用 BigDecimal 避免精度问题。 */
+ @JsonProperty("currencyAmount")
+ public BigDecimal currencyAmount;
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentWriteDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentWriteDtos.java
new file mode 100644
index 0000000..01ebbab
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentWriteDtos.java
@@ -0,0 +1,194 @@
+package common.ecommerce.walmart.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+/**
+ * 沃尔玛报文结构:标发({@code POST /v3/orders/{purchaseOrderId}/shipping})与查询发货信息。
+ *
+ * 两者同形 :{@code orderShipment.orderLines.orderLine[]},
+ * 每行挂 {@code orderLineStatuses.orderLineStatus[]},发货信息在
+ * {@code trackingInfo} 里。
+ *
+ * ⚠ 沙箱实测两条路由都 404(mock 未实现),只能在生产环境验证。
+ */
+public final class WalmartShipmentWriteDtos {
+
+ private WalmartShipmentWriteDtos() {
+ }
+
+ /** 标发请求体。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class ShipmentRequest {
+
+ /** 发货单容器;必填。 */
+ @JsonProperty("orderShipment")
+ public OrderShipment orderShipment;
+ }
+
+ /** 发货单:行数组。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderShipment {
+
+ /**
+ * 处理模式;可选。
+ *
+ * 订单已发货后 只更新物流信息时传 {@code PARTIAL_UPDATE};
+ * 首次标发不要传。
+ */
+ @JsonProperty("processMode")
+ public String processMode;
+
+ /** 行容器;必填。 */
+ @JsonProperty("orderLines")
+ public OrderLines orderLines;
+ }
+
+ /** 行容器。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderLines {
+
+ /** 发货行数组;必填。 */
+ @JsonProperty("orderLine")
+ public List orderLine;
+ }
+
+ /**
+ * 一条发货行。
+ *
+ * 官方请求体 schema 的 {@code required} 是
+ * {@code ["lineNumber","orderLineStatuses","sellerOrderId"]}——
+ * 但该 schema 里 {@code lineNumber} 的描述写成了「待取消的行」,
+ * 明显是从取消接口复制来的,required 列表的可信度存疑。
+ * 所以 {@code sellerOrderId} 加了字段但不强制 :调用方不传时发空串占位,
+ * 由探针确认平台是否真的拒绝。
+ */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderLine {
+
+ /** 订单行号;必须与订单详情里的 {@code lineNumber} 一致。 */
+ @JsonProperty("lineNumber")
+ public String lineNumber;
+
+ /**
+ * 卖家自定义订单号;官方要求 ≤30 字符,会印在退货面单上。
+ *
+ * 通常填 {@code customerOrderId}。schema 里标为必填,这里按可选处理,
+ * 见类注释。
+ */
+ @JsonProperty("sellerOrderId")
+ public String sellerOrderId;
+
+ /**
+ * 客户已申请取消、但卖家仍然要发货时,必须传 {@code true} 作为确认。
+ *
+ * 普通标发不要传;官方默认 {@code false}。
+ */
+ @JsonProperty("intentToCancelOverride")
+ public Boolean intentToCancelOverride;
+
+ /** 行状态容器。 */
+ @JsonProperty("orderLineStatuses")
+ public OrderLineStatuses orderLineStatuses;
+ }
+
+ /** 行状态容器。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderLineStatuses {
+
+ /** 行状态数组。 */
+ @JsonProperty("orderLineStatus")
+ public List orderLineStatus;
+ }
+
+ /** 行状态:标发时固定 {@code Shipped}。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderLineStatus {
+
+ /** 状态;标发固定 {@code Shipped}。 */
+ @JsonProperty("status")
+ public String status;
+
+ /** 本次发货数量。 */
+ @JsonProperty("statusQuantity")
+ public Quantity statusQuantity;
+
+ /** 物流信息;标发时必填。 */
+ @JsonProperty("trackingInfo")
+ public TrackingInfo trackingInfo;
+ }
+
+ /** 数量:{@code amount} 是字符串 (与订单接口一致)。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class Quantity {
+
+ /** 计量单位,固定 {@code EACH}。 */
+ @JsonProperty("unitOfMeasurement")
+ public String unitOfMeasurement;
+
+ /** 数量,字符串。 */
+ @JsonProperty("amount")
+ public String amount;
+ }
+
+ /** 物流信息。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TrackingInfo {
+
+ /**
+ * 发货时间,epoch 毫秒整数 。
+ *
+ * 官方 schema:{@code "type":"integer","format":"int64"},
+ * 描述为 {@code Timestamp in UNIX epoch (int64) format},示例 {@code 1580821866000}。
+ * 注意与订单查询参数(ISO-8601)不同,这个接口收的是毫秒时间戳。
+ */
+ @JsonProperty("shipDateTime")
+ public Long shipDateTime;
+
+ /** 承运商;{@code carrier} 与 {@code otherCarrier} 二选一。 */
+ @JsonProperty("carrierName")
+ public CarrierName carrierName;
+
+ /** 运输方式编码;必须与承运商的方式对照表匹配。 */
+ @JsonProperty("methodCode")
+ public String methodCode;
+
+ /** 物流跟踪号。 */
+ @JsonProperty("trackingNumber")
+ public String trackingNumber;
+
+ /**
+ * 承运商跟踪页 URL;可选。
+ *
+ * 用非标准承运商({@code otherCarrier})时,第三方 SDK 注释称必须提供,
+ * 官方 schema 未明确约束。这里按可选处理。
+ */
+ @JsonProperty("trackingURL")
+ public String trackingURL;
+ }
+
+ /** 承运商。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class CarrierName {
+
+ /** 标准承运商编码,如 {@code UPS}、{@code FedEx}。 */
+ @JsonProperty("carrier")
+ public String carrier;
+
+ /** 非标准承运商名称。 */
+ @JsonProperty("otherCarrier")
+ public String otherCarrier;
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartReturnType.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartReturnType.java
index cf66e8e..8d25684 100644
--- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartReturnType.java
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartReturnType.java
@@ -5,18 +5,38 @@ import common.ecommerce.channel.model.aftersale.AfterSaleType;
/**
* 沃尔玛退货类型 {@code returnType} → 统一 {@link AfterSaleType}。
*
- * 沃尔玛只有两种:{@link #RETURN}(退货退款)和 {@link #REPLACEMENT}(换货)。
- * 换货在统一模型里叫 {@link AfterSaleType#EXCHANGE}。
+ * 官方 {@code reference/getreturns} 给出的枚举是
+ * {@code PREORDER} / {@code REPLACEMENT} / {@code REFUND} 。
+ *
+ * {@code REPLACEMENT} 在统一模型里叫 {@link AfterSaleType#EXCHANGE}(换货)。
+ *
+ * 兼容旧值 {@code RETURN} :早期的《沃尔玛沙箱接口说明》写的是
+ * {@code RETURN}/{@code REPLACEMENT},历史数据与第三方资料里仍会出现。
+ * 保留别名并映射到 {@link AfterSaleType#RETURN},避免解析失败——
+ * 识别不了的元素类型会让下游把它当 {@code UNKNOWN} 丢掉。
*
* 注意 {@code REPLACEMENT} 也会出现在 {@code refundMode} 等其它字段的枚举里,
* 这里只用于 {@code returnType}。
*/
public enum WalmartReturnType {
- /** 退货(退款)。 */
- RETURN("RETURN", AfterSaleType.RETURN),
+ /**
+ * 退款型退货(官方值)。
+ *
+ * {@code REFUND} 与历史别名 {@code RETURN} 都映射到这里。
+ */
+ REFUND("REFUND", AfterSaleType.RETURN),
+ /** 历史别名:早期文档写的 {@code RETURN},官方枚举里已改用 {@code REFUND}。 */
+ RETURN_ALIAS("RETURN", AfterSaleType.RETURN),
/** 换货 / 补发。 */
REPLACEMENT("REPLACEMENT", AfterSaleType.EXCHANGE),
+ /**
+ * 预购单退货。
+ *
+ * 官方只列了这个枚举值,没有说明它和普通退货的差异;统一模型里没有对应语义,
+ * 先落 {@link AfterSaleType#UNKNOWN} 并保留原值,不猜。
+ */
+ PREORDER("PREORDER", AfterSaleType.UNKNOWN),
/** 无法识别。 */
UNKNOWN(null, AfterSaleType.UNKNOWN);
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartRequestFactory.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartRequestFactory.java
index 9f77a75..f045889 100644
--- a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartRequestFactory.java
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartRequestFactory.java
@@ -1,6 +1,7 @@
package common.ecommerce.walmart.http;
import common.ecommerce.http.HttpRequest;
+import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.channel.sdk.ChannelContext;
import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.walmart.WalmartConstants;
@@ -83,6 +84,27 @@ public final class WalmartRequestFactory {
return query.charAt(0) == '?' ? query : "?" + query;
}
+ /**
+ * POST / PUT 业务请求:JSON 体 + 与 GET 相同的公共头。
+ *
+ * @param body 请求体对象,由 {@code JacksonJsonCodec} 序列化;为 null 时发空体
+ */
+ public HttpRequest write(String method, String baseUrl, String path, Map query,
+ Object body, JacksonJsonCodec json, AccessToken token,
+ ChannelContext ctx, String operation) {
+ return HttpRequest.builder()
+ .method(method)
+ .url(baseUrl + path + queryString(query))
+ .contentType(WalmartConstants.CONTENT_TYPE_JSON)
+ .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)
+ .body(body == null ? null : json.toJson(body))
+ .operation(operation)
+ .build();
+ }
+
/** 把查询参数拼成 {@code ?k=v&k2=v2};空 Map 返回空串。 */
public static String queryString(Map query) {
if (query == null || query.isEmpty()) {
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartFeedMapper.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartFeedMapper.java
new file mode 100644
index 0000000..6d2e992
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartFeedMapper.java
@@ -0,0 +1,105 @@
+package common.ecommerce.walmart.mapper;
+
+import common.ecommerce.walmart.dto.WalmartFeedDtos;
+import common.ecommerce.walmart.model.WalmartFeedCommand;
+import common.ecommerce.walmart.model.WalmartFeedStatus;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 商品 Feed:命令 ↔ 沃尔玛报文。
+ *
+ * 提交报文只有三层:{@code MPItemFeedHeader}(版本 / 语言 / 站点 / 子类目)
+ * 与 {@code MPItem[]}(每个元素结构见 Item Spec)。商品元素原样透传,
+ * 不做建模——不同 {@code productType} 的必填字段差异太大。
+ */
+public final class WalmartFeedMapper {
+
+ private WalmartFeedMapper() {
+ }
+
+ /** 命令 → 提交报文。 */
+ public static WalmartFeedDtos.FeedRequest toRequest(WalmartFeedCommand command) {
+ WalmartFeedDtos.FeedHeader header = new WalmartFeedDtos.FeedHeader();
+ header.version = command.version();
+ header.locale = command.locale();
+ header.businessUnit = command.businessUnit();
+ header.subCategory = command.subCategory();
+
+ WalmartFeedDtos.FeedRequest request = new WalmartFeedDtos.FeedRequest();
+ request.header = header;
+ request.items = new ArrayList(command.items());
+ return request;
+ }
+
+ /** 状态响应 → {@link WalmartFeedStatus};null 时返回一个空状态。 */
+ public static WalmartFeedStatus toStatus(WalmartFeedDtos.FeedStatusResponse dto) {
+ WalmartFeedStatus.Builder builder = WalmartFeedStatus.builder();
+ if (dto == null) {
+ return builder.build();
+ }
+ builder.feedId(dto.feedId)
+ .feedType(dto.feedType)
+ .status(dto.feedStatus)
+ .counters(intOf(dto.itemsReceived), intOf(dto.itemsProcessing),
+ intOf(dto.itemsSucceeded), intOf(dto.itemsFailed))
+ .submittedAt(dto.feedSubmissionDate)
+ .ingestedAt(dto.ingestedDate);
+
+ if (dto.itemDetails != null && dto.itemDetails.itemIngestionStatus != null) {
+ for (WalmartFeedDtos.ItemIngestionStatus item : dto.itemDetails.itemIngestionStatus) {
+ if (item == null) {
+ continue;
+ }
+ builder.item(new WalmartFeedStatus.ItemResult(
+ item.wpid, item.sku, item.index, item.ingestionStatus,
+ errorTextOf(item.ingestionErrors)));
+ }
+ }
+ return builder.build();
+ }
+
+ /** 把错误列表压成一行;没有错误时返回 null。 */
+ static String errorTextOf(WalmartFeedDtos.IngestionErrors errors) {
+ if (errors == null || errors.ingestionError == null || errors.ingestionError.isEmpty()) {
+ return null;
+ }
+ List parts = new ArrayList();
+ for (WalmartFeedDtos.IngestionError error : errors.ingestionError) {
+ if (error == null) {
+ continue;
+ }
+ StringBuilder sb = new StringBuilder();
+ if (error.code != null) {
+ sb.append('[').append(error.code).append(']');
+ }
+ if (error.field != null) {
+ sb.append(error.field).append(": ");
+ }
+ if (error.description != null) {
+ sb.append(error.description);
+ }
+ if (sb.length() > 0) {
+ parts.add(sb.toString());
+ }
+ }
+ return parts.isEmpty() ? null : join(parts, "; ");
+ }
+
+ private static String join(List parts, String sep) {
+ StringBuilder sb = new StringBuilder();
+ for (String part : parts) {
+ if (sb.length() > 0) {
+ sb.append(sep);
+ }
+ sb.append(part);
+ }
+ return sb.toString();
+ }
+
+ /** null 按 0 处理。 */
+ private static int intOf(Integer value) {
+ return value == null ? 0 : value.intValue();
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java
new file mode 100644
index 0000000..6cb618d
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java
@@ -0,0 +1,103 @@
+package common.ecommerce.walmart.mapper;
+
+import common.ecommerce.channel.model.aftersale.RefundCommand;
+import common.ecommerce.channel.model.aftersale.RefundResult;
+import common.ecommerce.walmart.dto.WalmartRefundDtos;
+import common.ecommerce.walmart.dto.WalmartReturnDtos;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 退款:{@link RefundCommand} → 沃尔玛请求体;沃尔玛响应 → {@link RefundResult}。
+ *
+ * 沃尔玛要求:{@code returnOrderId} 与路径一致、{@code returnOrderLineNumber} 对应
+ * 退货详情里的行号、每个费用项给 {@code chargeName} + {@code chargeType} + 金额。
+ */
+public final class WalmartRefundMapper {
+
+ private WalmartRefundMapper() {
+ }
+
+ /**
+ * 命令 → 请求体。
+ *
+ * @param command 退款命令
+ * @param returnOrderId 路径里的退货单号(与命令里的应一致,以路径为准)
+ * @throws IllegalArgumentException 行号不是整数(沃尔玛要求 integer)
+ */
+ public static WalmartRefundDtos.RefundRequest toRequest(RefundCommand command, String returnOrderId) {
+ WalmartRefundDtos.RefundRequest request = new WalmartRefundDtos.RefundRequest();
+ request.returnOrderId = returnOrderId;
+ request.refundLines = new ArrayList(command.lines().size());
+
+ for (RefundCommand.Line line : command.lines()) {
+ WalmartRefundDtos.RefundLine refundLine = new WalmartRefundDtos.RefundLine();
+ refundLine.returnOrderLineNumber = parseLineNumber(line.lineId());
+ refundLine.refundCharges = new ArrayList(line.charges().size());
+
+ for (RefundCommand.Charge charge : line.charges()) {
+ WalmartRefundDtos.CurrencyAmount amount = new WalmartRefundDtos.CurrencyAmount();
+ amount.currencyUnit = charge.amount().currencyCode();
+ amount.currencyAmount = charge.amount().amount();
+
+ WalmartRefundDtos.RefundCharge refundCharge = new WalmartRefundDtos.RefundCharge();
+ refundCharge.chargeName = charge.chargeName();
+ refundCharge.chargeType = charge.chargeType();
+ refundCharge.refundAmount = amount;
+ refundLine.refundCharges.add(refundCharge);
+ }
+ request.refundLines.add(refundLine);
+ }
+ return request;
+ }
+
+ /**
+ * 沃尔玛响应 → {@link RefundResult}。
+ *
+ * 文档只给出请求体,响应结构未实测。这里做**尽力解析**:
+ * 若响应是退货单形状(含 {@code returnOrderLines}),取行级退款状态;
+ * 若是别的形状,只保留状态原值,行级为空。
+ *
+ * @param dto 响应体;可能为 null(204 / 空体)
+ * @param command 原始命令,用于补全退货单号
+ * @param applyResult 解析出的退货单(可能为 null)
+ */
+ public static RefundResult toResult(WalmartReturnDtos.ReturnOrder applyResult,
+ RefundCommand command) {
+ RefundResult.Builder builder = RefundResult.builder()
+ .afterSaleId(command.afterSaleId());
+
+ if (applyResult == null || applyResult.returnOrderLines == null) {
+ return builder.build();
+ }
+ String firstRefundStatus = null;
+ for (WalmartReturnDtos.ReturnOrderLine line : applyResult.returnOrderLines) {
+ if (line == null) {
+ continue;
+ }
+ builder.line(new RefundResult.LineResult(
+ line.returnOrderLineNumber == null ? null : String.valueOf(line.returnOrderLineNumber),
+ line.currentRefundStatus));
+ if (firstRefundStatus == null) {
+ firstRefundStatus = line.currentRefundStatus;
+ }
+ }
+ builder.rawStatus(firstRefundStatus);
+ return builder.build();
+ }
+
+ /**
+ * 退货行号:沃尔玛要求 integer。
+ *
+ * @throws IllegalArgumentException 不是整数(如 {@code "1a"})
+ */
+ static Integer parseLineNumber(String lineId) {
+ try {
+ return Integer.valueOf(lineId.trim());
+ } catch (NumberFormatException e) {
+ throw new IllegalArgumentException(
+ "walmart refund line id must be numeric (returnOrderLineNumber), got: " + lineId, e);
+ }
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java
new file mode 100644
index 0000000..c36802b
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java
@@ -0,0 +1,203 @@
+package common.ecommerce.walmart.mapper;
+
+import common.ecommerce.channel.model.fulfillment.ShipmentCommand;
+import common.ecommerce.channel.model.fulfillment.ShipmentResult;
+import common.ecommerce.walmart.dto.WalmartOrderDtos;
+import common.ecommerce.walmart.dto.WalmartShipmentWriteDtos;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 标发:{@link ShipmentCommand} → 沃尔玛请求体;沃尔玛订单响应 → {@link ShipmentResult}。
+ *
+ * 沃尔玛的要求(缺一项整单被拒):
+ *
+ * {@code lineNumber} 必须与订单详情里的一致
+ * {@code status} 固定 {@code Shipped},{@code unitOfMeasurement} 固定 {@code EACH}
+ * {@code statusQuantity.amount} 是字符串
+ * {@code shipDateTime} 是 epoch 毫秒整数 (官方 schema {@code int64}),
+ * 与订单查询参数的 ISO-8601 不同
+ * {@code sellerOrderId} 官方标为必填(≤30 字符),这里不强制,未给时不发
+ * {@code carrier} 与 {@code otherCarrier} 至少填一个
+ * {@code methodCode} 必须与承运商的方式对照表匹配
+ *
+ */
+public final class WalmartShipmentWriteMapper {
+
+ /** 卖家自定义订单号长度上限;官方 {@code sellerOrderId} 限制 30 字符。 */
+ static final int MAX_SELLER_ORDER_ID_LENGTH = 30;
+
+ private WalmartShipmentWriteMapper() {
+ }
+
+ /**
+ * 命令 → 请求体。
+ *
+ * @param command 发货命令
+ * @param clock 发货时间缺省时用的时钟
+ */
+ public static WalmartShipmentWriteDtos.ShipmentRequest toRequest(ShipmentCommand command, Clock clock) {
+ WalmartShipmentWriteDtos.OrderLines orderLines = new WalmartShipmentWriteDtos.OrderLines();
+ orderLines.orderLine = new ArrayList(command.lines().size());
+
+ for (ShipmentCommand.Line line : command.lines()) {
+ WalmartShipmentWriteDtos.CarrierName carrierName = new WalmartShipmentWriteDtos.CarrierName();
+ // 标准编码与非标准名称二选一:有 carrier 时优先用它
+ if (line.carrier() != null && !line.carrier().trim().isEmpty()) {
+ carrierName.carrier = line.carrier().trim();
+ } else {
+ carrierName.otherCarrier = line.carrierName().trim();
+ }
+
+ WalmartShipmentWriteDtos.TrackingInfo tracking = new WalmartShipmentWriteDtos.TrackingInfo();
+ // 官方 schema 是 int64 epoch 毫秒,不是 ISO 字符串
+ tracking.shipDateTime = (line.shippedAt() != null ? line.shippedAt() : Instant.now(clock))
+ .toEpochMilli();
+ tracking.carrierName = carrierName;
+ tracking.methodCode = line.methodCode();
+ tracking.trackingNumber = line.trackingNumber();
+ tracking.trackingURL = blankToNull(line.trackingUrl());
+
+ WalmartShipmentWriteDtos.Quantity quantity = new WalmartShipmentWriteDtos.Quantity();
+ quantity.unitOfMeasurement = "EACH";
+ // 沃尔玛要求字符串
+ quantity.amount = String.valueOf(line.quantity());
+
+ WalmartShipmentWriteDtos.OrderLineStatus status = new WalmartShipmentWriteDtos.OrderLineStatus();
+ status.status = "Shipped";
+ status.statusQuantity = quantity;
+ status.trackingInfo = tracking;
+
+ WalmartShipmentWriteDtos.OrderLineStatuses statuses = new WalmartShipmentWriteDtos.OrderLineStatuses();
+ statuses.orderLineStatus = new ArrayList(1);
+ statuses.orderLineStatus.add(status);
+
+ WalmartShipmentWriteDtos.OrderLine orderLine = new WalmartShipmentWriteDtos.OrderLine();
+ orderLine.lineNumber = line.lineNumber();
+ orderLine.sellerOrderId = sellerOrderIdOf(line);
+ orderLine.intentToCancelOverride = line.intentToCancelOverride() ? Boolean.TRUE : null;
+ orderLine.orderLineStatuses = statuses;
+ orderLines.orderLine.add(orderLine);
+ }
+
+ WalmartShipmentWriteDtos.OrderShipment shipment = new WalmartShipmentWriteDtos.OrderShipment();
+ shipment.orderLines = orderLines;
+
+ WalmartShipmentWriteDtos.ShipmentRequest request = new WalmartShipmentWriteDtos.ShipmentRequest();
+ request.orderShipment = shipment;
+ return request;
+ }
+
+ /**
+ * 标发成功后沃尔玛回更新后的订单对象 → {@link ShipmentResult}。
+ *
+ * 响应可能有两种包裹:{@code {"order": {...}}} 或直接是订单对象;
+ * 解包由调用方完成,这里只看订单本体。
+ *
+ * 行上的数量是该状态对应的数量 (沃尔玛按状态累计),
+ * 不是本次实发数量;这里原样传出去,由调用方决定怎么解释。
+ *
+ * @param order 平台返回的订单;null 时返回只带订单号的最小结果
+ * @param command 原始命令,用于补全订单号与缺省跟踪号
+ */
+ public static ShipmentResult toResult(WalmartOrderDtos.Order order, ShipmentCommand command) {
+ ShipmentResult.Builder builder = ShipmentResult.builder()
+ .channelOrderId(command.channelOrderId());
+
+ if (order == null || order.orderLines == null || order.orderLines.orderLine == null) {
+ // 平台只回受理成功、不回订单体:至少把命令里的跟踪号带回去
+ builder.trackingNumber(firstTrackingNumberOf(command));
+ return builder.build();
+ }
+
+ boolean trackingSet = false;
+ for (WalmartOrderDtos.OrderLine line : order.orderLines.orderLine) {
+ if (line == null || line.lineNumber == null) {
+ continue;
+ }
+ int quantity = 0;
+ String status = null;
+ String tracking = null;
+ if (line.orderLineStatuses != null && line.orderLineStatuses.orderLineStatus != null) {
+ for (WalmartOrderDtos.OrderLineStatus s : line.orderLineStatuses.orderLineStatus) {
+ if (s == null) {
+ continue;
+ }
+ if (s.status != null) {
+ status = s.status;
+ }
+ if (s.statusQuantity != null && s.statusQuantity.amount != null) {
+ quantity = parseInt(s.statusQuantity.amount, quantity);
+ }
+ if (s.trackingInfo != null) {
+ if (!trackingSet && s.trackingInfo.trackingNumber != null) {
+ tracking = s.trackingInfo.trackingNumber;
+ }
+ // shipDateTime 是 ISO-8601 字符串,与订单其它时间的 epoch 毫秒不同
+ if (!trackingSet && s.trackingInfo.shipDateTime != null) {
+ builder.shippedAt(parseInstant(s.trackingInfo.shipDateTime));
+ }
+ }
+ }
+ }
+ builder.line(new ShipmentResult.LineShipment(line.lineNumber, quantity, status));
+ if (!trackingSet && tracking != null) {
+ builder.trackingNumber(tracking);
+ trackingSet = true;
+ }
+ }
+ if (!trackingSet) {
+ builder.trackingNumber(firstTrackingNumberOf(command));
+ }
+ return builder.build();
+ }
+
+ /**
+ * 卖家自定义订单号:优先用命令里给的,否则回落到渠道订单号。
+ *
+ * 超 30 字符时不截断而是返回 null——截断会让面单上的单号对不上,
+ * 宁可让平台按「未提供」处理。
+ */
+ static String sellerOrderIdOf(ShipmentCommand.Line line) {
+ String value = blankToNull(line.sellerOrderId());
+ if (value == null) {
+ return null;
+ }
+ return value.length() <= MAX_SELLER_ORDER_ID_LENGTH ? value : null;
+ }
+
+ private static String blankToNull(String value) {
+ return value == null || value.trim().isEmpty() ? null : value.trim();
+ }
+
+ /** 命令里第一条行的跟踪号,作为响应缺省值。 */
+ static String firstTrackingNumberOf(ShipmentCommand command) {
+ for (ShipmentCommand.Line line : command.lines()) {
+ if (line.trackingNumber() != null) {
+ return line.trackingNumber();
+ }
+ }
+ return null;
+ }
+
+ /** 数量解析;非法值保留旧值,不抛。 */
+ private static int parseInt(String raw, int fallback) {
+ try {
+ return Integer.parseInt(raw.trim());
+ } catch (NumberFormatException e) {
+ return fallback;
+ }
+ }
+
+ /** ISO-8601 字符串 → Instant;解析失败返回 null,不让脏时间卡住结果。 */
+ private static Instant parseInstant(String iso) {
+ try {
+ return Instant.parse(iso.trim());
+ } catch (RuntimeException e) {
+ return null;
+ }
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedCommand.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedCommand.java
new file mode 100644
index 0000000..f8325d3
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedCommand.java
@@ -0,0 +1,170 @@
+package common.ecommerce.walmart.model;
+
+/**
+ * 商品 Feed 提交的命令。
+ *
+ * 沃尔玛的商品写入走异步 Feed:提交后用 {@code feedId} 轮询处理结果。
+ * 报文结构随 {@code productType} 变化很大,所以这里只承载报文头 与
+ * 不透明的商品数组 ——每个元素的完整结构由调用方按 Walmart《Item Spec》给。
+ *
+ * ⚠ 沙箱实测提交返回 520(mock 未实现),只能在生产环境验证。
+ */
+public final class WalmartFeedCommand {
+
+ /** Feed 类型;本期只支持 {@link #FEED_TYPE_MP_ITEM}。 */
+ public static final String FEED_TYPE_MP_ITEM = "MP_ITEM";
+
+ /** Item Spec 版本;必填,需与后台开通版本一致。 */
+ private final String version;
+
+ /** 语言,通常 {@code en}。 */
+ private final String locale;
+
+ /** 站点,如 {@code WALMART_US}。 */
+ private final String businessUnit;
+
+ /** 子类目,如 {@code OTHER};可空。 */
+ private final String subCategory;
+
+ /** Feed 类型;默认 {@code MP_ITEM}。 */
+ private final String feedType;
+
+ /** 商品报文字段;每个元素结构见 Item Spec,不做建模。 */
+ private final java.util.List items;
+
+ private WalmartFeedCommand(Builder b) {
+ if (b.items.isEmpty()) {
+ throw new IllegalArgumentException("feed requires at least one item");
+ }
+ if (isBlank(b.version)) {
+ throw new IllegalArgumentException("Item Spec version must not be blank");
+ }
+ if (isBlank(b.locale)) {
+ throw new IllegalArgumentException("locale must not be blank");
+ }
+ if (isBlank(b.businessUnit)) {
+ throw new IllegalArgumentException("businessUnit must not be blank");
+ }
+ this.version = b.version.trim();
+ this.locale = b.locale.trim();
+ this.businessUnit = b.businessUnit.trim();
+ this.subCategory = b.subCategory;
+ this.feedType = isBlank(b.feedType) ? FEED_TYPE_MP_ITEM : b.feedType.trim();
+ this.items = java.util.Collections.unmodifiableList(
+ new java.util.ArrayList(b.items));
+ }
+
+ /** 新建构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** Item Spec 版本。 */
+ public String version() {
+ return version;
+ }
+
+ /** 语言。 */
+ public String locale() {
+ return locale;
+ }
+
+ /** 站点。 */
+ public String businessUnit() {
+ return businessUnit;
+ }
+
+ /** 子类目;可空。 */
+ public String subCategory() {
+ return subCategory;
+ }
+
+ /** Feed 类型。 */
+ public String feedType() {
+ return feedType;
+ }
+
+ /** 商品报文字段。 */
+ public java.util.List items() {
+ return items;
+ }
+
+ /** 幂等业务键:Feed 类型 + 商品 SKU 列表(按调用方给的内容算稳定摘要)。 */
+ public String businessRef() {
+ return feedType + ":" + items.size() + ":" + items.hashCode();
+ }
+
+ /** Feed 命令构建器。 */
+ public static final class Builder {
+
+ /** Item Spec 版本。 */
+ private String version;
+ /** 语言。 */
+ private String locale = "en";
+ /** 站点。 */
+ private String businessUnit;
+ /** 子类目。 */
+ private String subCategory;
+ /** Feed 类型。 */
+ private String feedType = FEED_TYPE_MP_ITEM;
+ /** 商品报文字段。 */
+ private final java.util.List items = new java.util.ArrayList();
+
+ /** 设置 Item Spec 版本;必填。 */
+ public Builder version(String version) {
+ this.version = version;
+ return this;
+ }
+
+ /** 设置语言;默认 {@code en}。 */
+ public Builder locale(String locale) {
+ this.locale = locale;
+ return this;
+ }
+
+ /** 设置站点;必填。 */
+ public Builder businessUnit(String businessUnit) {
+ this.businessUnit = businessUnit;
+ return this;
+ }
+
+ /** 设置子类目;可选。 */
+ public Builder subCategory(String subCategory) {
+ this.subCategory = subCategory;
+ return this;
+ }
+
+ /** 设置 Feed 类型;默认 {@code MP_ITEM}。 */
+ public Builder feedType(String feedType) {
+ this.feedType = feedType;
+ return this;
+ }
+
+ /** 追加一个商品报文(结构见 Item Spec)。 */
+ public Builder item(Object item) {
+ if (item != null) {
+ this.items.add(item);
+ }
+ return this;
+ }
+
+ /** 批量追加商品报文。 */
+ public Builder items(java.util.List> items) {
+ if (items != null) {
+ for (Object item : items) {
+ item(item);
+ }
+ }
+ return this;
+ }
+
+ /** 构建命令;缺版本 / 站点或没有商品时抛 {@link IllegalArgumentException}。 */
+ public WalmartFeedCommand build() {
+ return new WalmartFeedCommand(this);
+ }
+ }
+
+ private static boolean isBlank(String value) {
+ return value == null || value.trim().isEmpty();
+ }
+}
diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedStatus.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedStatus.java
new file mode 100644
index 0000000..b71beee
--- /dev/null
+++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedStatus.java
@@ -0,0 +1,248 @@
+package common.ecommerce.walmart.model;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Feed 处理状态(适配器扩展查询的返回类型)。
+ *
+ * 不在统一模型里:Feed 是沃尔玛的商品写入载体(异步批量),
+ * 其它平台没有同构概念,放进 {@code channel.model} 会让统一模型变形。
+ */
+public final class WalmartFeedStatus {
+
+ /** 批次 ID。 */
+ private final String feedId;
+
+ /** Feed 类型,如 {@code MP_ITEM}。 */
+ private final String feedType;
+
+ /** 处理状态:{@code RECEIVED} / {@code INPROGRESS} / {@code PROCESSED} / {@code ERROR}。 */
+ private final String status;
+
+ /** 接收商品数。 */
+ private final int itemsReceived;
+
+ /** 处理中数量。 */
+ private final int itemsProcessing;
+
+ /** 成功数量。 */
+ private final int itemsSucceeded;
+
+ /** 失败数量。 */
+ private final int itemsFailed;
+
+ /** 提交时间(ISO-8601 原值)。 */
+ private final String submittedAt;
+
+ /** 开始处理时间(ISO-8601 原值)。 */
+ private final String ingestedAt;
+
+ /** 逐商品结果;未请求明细时为空列表。 */
+ private final List items;
+
+ private WalmartFeedStatus(Builder b) {
+ this.feedId = b.feedId;
+ this.feedType = b.feedType;
+ this.status = b.status;
+ this.itemsReceived = b.itemsReceived;
+ this.itemsProcessing = b.itemsProcessing;
+ this.itemsSucceeded = b.itemsSucceeded;
+ this.itemsFailed = b.itemsFailed;
+ this.submittedAt = b.submittedAt;
+ this.ingestedAt = b.ingestedAt;
+ this.items = Collections.unmodifiableList(new ArrayList(b.items));
+ }
+
+ /** 新建构建器。 */
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 批次 ID。 */
+ public String feedId() {
+ return feedId;
+ }
+
+ /** Feed 类型。 */
+ public String feedType() {
+ return feedType;
+ }
+
+ /** 处理状态原值。 */
+ public String status() {
+ return status;
+ }
+
+ /** 接收商品数。 */
+ public int itemsReceived() {
+ return itemsReceived;
+ }
+
+ /** 处理中数量。 */
+ public int itemsProcessing() {
+ return itemsProcessing;
+ }
+
+ /** 成功数量。 */
+ public int itemsSucceeded() {
+ return itemsSucceeded;
+ }
+
+ /** 失败数量。 */
+ public int itemsFailed() {
+ return itemsFailed;
+ }
+
+ /** 提交时间。 */
+ public String submittedAt() {
+ return submittedAt;
+ }
+
+ /** 开始处理时间。 */
+ public String ingestedAt() {
+ return ingestedAt;
+ }
+
+ /** 逐商品结果;可能为空。 */
+ public List items() {
+ return items;
+ }
+
+ /** 处理是否已结束(成功或失败)。 */
+ public boolean isFinished() {
+ return "PROCESSED".equals(status) || "ERROR".equals(status);
+ }
+
+ /** 是否全部成功。 */
+ public boolean isFullySucceeded() {
+ return "PROCESSED".equals(status) && itemsFailed == 0;
+ }
+
+ /** 单个商品的处理结果。 */
+ public static final class ItemResult {
+
+ /** 平台商品 ID。 */
+ private final String wpid;
+ /** 卖家 SKU。 */
+ private final String sku;
+ /** 报文中该商品的下标。 */
+ private final Integer index;
+ /** 处理状态:{@code SUCCESS} / {@code DATA_ERROR} / {@code SYSTEM_ERROR}。 */
+ private final String status;
+ /** 错误描述(多条用分号拼接)。 */
+ private final String error;
+
+ /** 构造单个商品结果。 */
+ public ItemResult(String wpid, String sku, Integer index, String status, String error) {
+ this.wpid = wpid;
+ this.sku = sku;
+ this.index = index;
+ this.status = status;
+ this.error = error;
+ }
+
+ /** 平台商品 ID。 */
+ public String wpid() {
+ return wpid;
+ }
+
+ /** 卖家 SKU。 */
+ public String sku() {
+ return sku;
+ }
+
+ /** 报文中该商品的下标。 */
+ public Integer index() {
+ return index;
+ }
+
+ /** 处理状态原值。 */
+ public String status() {
+ return status;
+ }
+
+ /** 错误描述;成功时为 null。 */
+ public String error() {
+ return error;
+ }
+ }
+
+ /** Feed 状态构建器。 */
+ public static final class Builder {
+
+ /** 批次 ID。 */
+ private String feedId;
+ /** Feed 类型。 */
+ private String feedType;
+ /** 处理状态。 */
+ private String status;
+ /** 接收商品数。 */
+ private int itemsReceived;
+ /** 处理中数量。 */
+ private int itemsProcessing;
+ /** 成功数量。 */
+ private int itemsSucceeded;
+ /** 失败数量。 */
+ private int itemsFailed;
+ /** 提交时间。 */
+ private String submittedAt;
+ /** 开始处理时间。 */
+ private String ingestedAt;
+ /** 逐商品结果。 */
+ private final List items = new ArrayList();
+
+ /** 设置批次 ID。 */
+ public Builder feedId(String feedId) {
+ this.feedId = feedId;
+ return this;
+ }
+
+ /** 设置 Feed 类型。 */
+ public Builder feedType(String feedType) {
+ this.feedType = feedType;
+ return this;
+ }
+
+ /** 设置处理状态。 */
+ public Builder status(String status) {
+ this.status = status;
+ return this;
+ }
+
+ /** 设置各计数。 */
+ public Builder counters(int received, int processing, int succeeded, int failed) {
+ this.itemsReceived = received;
+ this.itemsProcessing = processing;
+ this.itemsSucceeded = succeeded;
+ this.itemsFailed = failed;
+ return this;
+ }
+
+ /** 设置提交时间。 */
+ public Builder submittedAt(String submittedAt) {
+ this.submittedAt = submittedAt;
+ return this;
+ }
+
+ /** 设置开始处理时间。 */
+ public Builder ingestedAt(String ingestedAt) {
+ this.ingestedAt = ingestedAt;
+ return this;
+ }
+
+ /** 追加一条商品结果。 */
+ public Builder item(ItemResult item) {
+ if (item != null) {
+ this.items.add(item);
+ }
+ return this;
+ }
+
+ /** 构建状态。 */
+ public WalmartFeedStatus build() {
+ return new WalmartFeedStatus(this);
+ }
+ }
+}
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/WalmartFacadeTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/WalmartFacadeTest.java
index ed9a4ef..3c94887 100644
--- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/WalmartFacadeTest.java
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/WalmartFacadeTest.java
@@ -93,14 +93,18 @@ class WalmartFacadeTest {
}
@Test
- void capabilityReportIsExactlyReadOnlyThree() {
+ void capabilityReportCoversReadsAndMarkShipped() {
ChannelSdk sdk = sdkWithRecording(transport(), accounts());
CapabilityReport report = sdk.capabilities(WM);
- assertEquals(EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS),
+ assertEquals(EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS,
+ Capability.MARK_SHIPPED, Capability.REFUND),
report.supported());
- assertFalse(report.supports(Capability.MARK_SHIPPED));
+ assertTrue(report.supports(Capability.MARK_SHIPPED));
+ assertTrue(report.supports(Capability.REFUND));
+ // 商品写入 / 结算 / 面单仍未实现
assertFalse(report.supports(Capability.BILLING));
+ assertFalse(report.supports(Capability.LABEL));
}
@Test
@@ -126,8 +130,9 @@ class WalmartFacadeTest {
}
@Test
- void writeOperationsAreRejectedNotSilentlyIgnored() {
+ void unimplementedWriteOperationsAreRejected() {
ChannelSdk sdk = sdkWithRecording(transport(), accounts());
+ // 快速出库未实现:走 OutboundCapable,与标发无关
ChannelException.UnsupportedCapabilityException ex = assertThrows(
ChannelException.UnsupportedCapabilityException.class,
() -> sdk.outbounds(WM, CONNECTION).submit(java.util.Collections.emptyList()));
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartFeedTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartFeedTest.java
new file mode 100644
index 0000000..cbee714
--- /dev/null
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartFeedTest.java
@@ -0,0 +1,230 @@
+package common.ecommerce.walmart.adapter;
+
+import common.ecommerce.http.JacksonJsonCodec;
+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.model.WalmartFeedCommand;
+import common.ecommerce.walmart.model.WalmartFeedStatus;
+import org.junit.jupiter.api.Test;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+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.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 商品 Feed:提交与状态查询。
+ *
+ * 报文严格按文档 §3.5 / §3.6:
+ * {@code MPItemFeedHeader.version/locale/businessUnit/subCategory} + {@code MPItem[]};
+ * 提交回 {@code feedId},状态查询按文档枚举映射。
+ */
+class WalmartFeedTest {
+
+ private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
+
+ private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
+
+ private RecordingTransport transport(String submitBody, String statusBody) {
+ return RecordingTransport.create()
+ .route("/v3/token", r -> Responses.ok(TOKEN_BODY))
+ .route("/v3/feeds/", r -> Responses.ok(statusBody))
+ .route("/v3/feeds", r -> Responses.ok(submitBody));
+ }
+
+ /** 与文档 §3.5 结构一致的商品报文(内容只取文档里的基础字段)。 */
+ private static Map itemPayload() {
+ Map item = new LinkedHashMap();
+ item.put("sku", "5212572");
+ item.put("productName", "Test Product");
+ return item;
+ }
+
+ private static WalmartFeedCommand command() {
+ return WalmartFeedCommand.builder()
+ .version("4.2")
+ .locale("en")
+ .businessUnit("WALMART_US")
+ .subCategory("OTHER")
+ .item(itemPayload())
+ .build();
+ }
+
+ // ---------------------------------------------------------------- 提交
+
+ @Test
+ void submitPostsToFeedsWithFeedType() {
+ RecordingTransport transport = transport("{\"feedId\":\"FEED-1\"}", "{}");
+ adapter(transport).submitFeed(context(), command());
+
+ String url = lastUrl(transport);
+ assertUrlContains(url, ENDPOINT + WalmartConstants.PATH_FEEDS);
+ assertUrlContains(url, "feedType=MP_ITEM");
+ }
+
+ @Test
+ void submitBodyMatchesDocumentShape() {
+ RecordingTransport transport = transport("{\"feedId\":\"FEED-1\"}", "{}");
+ adapter(transport).submitFeed(context(), command());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ // 文档 §3.5:MPItemFeedHeader.version / locale / businessUnit / subCategory + MPItem[]
+ assertTrue(body.contains("\"MPItemFeedHeader\""), body);
+ assertTrue(body.contains("\"version\":\"4.2\""), body);
+ assertTrue(body.contains("\"locale\":\"en\""), body);
+ assertTrue(body.contains("\"businessUnit\":\"WALMART_US\""), body);
+ assertTrue(body.contains("\"subCategory\":\"OTHER\""), body);
+ assertTrue(body.contains("\"MPItem\""), body);
+ assertTrue(body.contains("\"sku\":\"5212572\""), body);
+ }
+
+ @Test
+ void submitReturnsFeedId() {
+ RecordingTransport transport = transport("{\"feedId\":\"FEED-1\"}", "{}");
+ assertEquals("FEED-1", adapter(transport).submitFeed(context(), command()));
+ }
+
+ @Test
+ void submitWithoutFeedIdIsRejected() {
+ RecordingTransport transport = transport("{}", "{}");
+ ValidationException ex = assertThrows(ValidationException.class,
+ () -> adapter(transport).submitFeed(context(), command()));
+ assertTrue(ex.getMessage().contains("no feedId"), ex.getMessage());
+ }
+
+ @Test
+ void submitNullCommandIsRejected() {
+ RecordingTransport transport = transport("{\"feedId\":\"F\"}", "{}");
+ assertThrows(ValidationException.class, () -> adapter(transport).submitFeed(context(), null));
+ assertEquals(0, transport.recorded().size());
+ }
+
+ // ---------------------------------------------------------------- 状态
+
+ @Test
+ void statusUsesFeedIdPathAndIncludeDetails() {
+ RecordingTransport transport = transport("{}", "{\"feedId\":\"FEED-1\",\"feedStatus\":\"PROCESSED\"}");
+ adapter(transport).getFeedStatus(context(), "FEED-1", true);
+
+ String url = lastUrl(transport);
+ assertUrlContains(url, ENDPOINT + "/v3/feeds/FEED-1");
+ assertUrlContains(url, "includeDetails=true");
+ }
+
+ @Test
+ void statusWithoutDetailsOmitsQuery() {
+ RecordingTransport transport = transport("{}", "{\"feedId\":\"FEED-1\"}");
+ adapter(transport).getFeedStatus(context(), "FEED-1", false);
+ assertTrue(!lastUrl(transport).contains("includeDetails"), lastUrl(transport));
+ }
+
+ @Test
+ void statusMapsCountersAndDetails() {
+ String body = "{\"feedId\":\"FEED-1\",\"feedType\":\"MP_ITEM\",\"feedStatus\":\"PROCESSED\","
+ + "\"itemsReceived\":3,\"itemsProcessing\":0,\"itemsSucceeded\":2,\"itemsFailed\":1,"
+ + "\"feedSubmissionDate\":\"2026-11-19T01:00:00.000Z\","
+ + "\"itemDetails\":{\"itemIngestionStatus\":["
+ + "{\"sku\":\"S1\",\"index\":0,\"ingestionStatus\":\"SUCCESS\",\"wpid\":\"W1\"},"
+ + "{\"sku\":\"S2\",\"index\":1,\"ingestionStatus\":\"DATA_ERROR\","
+ + "\"ingestionErrors\":{\"ingestionError\":[{\"code\":\"ERR_1\","
+ + "\"field\":\"price\",\"description\":\"invalid price\"}]}}]}}";
+
+ WalmartFeedStatus status = adapter(transport("{}", body))
+ .getFeedStatus(context(), "FEED-1", true);
+
+ assertEquals("FEED-1", status.feedId());
+ assertEquals("MP_ITEM", status.feedType());
+ assertEquals("PROCESSED", status.status());
+ assertEquals(3, status.itemsReceived());
+ assertEquals(2, status.itemsSucceeded());
+ assertEquals(1, status.itemsFailed());
+ assertTrue(status.isFinished());
+ assertFalse(status.isFullySucceeded());
+
+ assertEquals(2, status.items().size());
+ assertEquals("S1", status.items().get(0).sku());
+ assertEquals("SUCCESS", status.items().get(0).status());
+ assertEquals("W1", status.items().get(0).wpid());
+ // 错误压成一行:code + field + description
+ assertEquals("[ERR_1]price: invalid price", status.items().get(1).error());
+ }
+
+ @Test
+ void fullySucceededFeedIsRecognised() {
+ String body = "{\"feedStatus\":\"PROCESSED\",\"itemsSucceeded\":2,\"itemsFailed\":0}";
+ assertTrue(adapter(transport("{}", body)).getFeedStatus(context(), "F", false).isFullySucceeded());
+ }
+
+ @Test
+ void inProgressIsNotFinished() {
+ String body = "{\"feedStatus\":\"INPROGRESS\",\"itemsProcessing\":2}";
+ WalmartFeedStatus status = adapter(transport("{}", body)).getFeedStatus(context(), "F", false);
+ assertFalse(status.isFinished());
+ assertEquals(2, status.itemsProcessing());
+ }
+
+ @Test
+ void errorFeedIsFinishedButNotSucceeded() {
+ String body = "{\"feedStatus\":\"ERROR\"}";
+ WalmartFeedStatus status = adapter(transport("{}", body)).getFeedStatus(context(), "F", false);
+ assertTrue(status.isFinished());
+ assertFalse(status.isFullySucceeded());
+ }
+
+ @Test
+ void blankFeedIdIsRejected() {
+ RecordingTransport transport = transport("{}", "{}");
+ assertThrows(ValidationException.class,
+ () -> adapter(transport).getFeedStatus(context(), " ", true));
+ assertEquals(0, transport.recorded().size());
+ }
+
+ // ---------------------------------------------------------------- 命令校验
+
+ @Test
+ void commandRequiresHeaderFieldsAndItems() {
+ assertThrows(IllegalArgumentException.class, () -> WalmartFeedCommand.builder().build());
+ assertThrows(IllegalArgumentException.class,
+ () -> WalmartFeedCommand.builder().businessUnit("WALMART_US").item(itemPayload()).build());
+ assertThrows(IllegalArgumentException.class,
+ () -> WalmartFeedCommand.builder().version("4.2").businessUnit("WALMART_US").build());
+ }
+
+ @Test
+ void localeDefaultsToEn() {
+ WalmartFeedCommand cmd = WalmartFeedCommand.builder()
+ .version("4.2").businessUnit("WALMART_US").item(itemPayload()).build();
+ assertEquals("en", cmd.locale());
+ assertEquals("MP_ITEM", cmd.feedType());
+ }
+
+ @Test
+ void jsonDoesNotContainNulls() {
+ RecordingTransport transport = transport("{\"feedId\":\"F\"}", "{}");
+ adapter(transport).submitFeed(context(), WalmartFeedCommand.builder()
+ .version("4.2").businessUnit("WALMART_US").item(itemPayload()).build());
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ // subCategory 未设置时不能出现 "subCategory":null
+ assertTrue(!body.contains(":null"), body);
+ }
+
+ @Test
+ void mpItemIsSerialisedAsArray() throws Exception {
+ // 确保 MPItem 数组能序列化自定义对象,而不是引用
+ RecordingTransport transport = transport("{\"feedId\":\"F\"}", "{}");
+ adapter(transport).submitFeed(context(), command());
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ assertTrue(JSON.mapper().readTree(body).get("MPItem").isArray(), body);
+ }
+}
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java
new file mode 100644
index 0000000..fd66230
--- /dev/null
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java
@@ -0,0 +1,304 @@
+package common.ecommerce.walmart.adapter;
+
+import common.ecommerce.channel.model.fulfillment.ShipmentCommand;
+import common.ecommerce.channel.model.fulfillment.ShipmentResult;
+import common.ecommerce.shared.error.PlatformBusinessException;
+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 org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+
+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.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/** 标发:请求报文 + 响应映射 + 错误分类。 */
+class WalmartMarkShippedTest {
+
+ private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
+
+ /** 标发成功后平台回更新后的订单。 */
+ private static String shippedOrderBody() {
+ return "{\"order\":{"
+ + "\"purchaseOrderId\":\"108816631915371\","
+ + "\"customerOrderId\":\"C-1\","
+ + "\"orderDate\":1686736267000,"
+ + "\"orderLines\":{\"orderLine\":[{"
+ + "\"lineNumber\":\"1\","
+ + "\"item\":{\"sku\":\"SKU-1\"},"
+ + "\"orderLineQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"2\"},"
+ + "\"orderLineStatuses\":{\"orderLineStatus\":["
+ + "{\"status\":\"Shipped\",\"statusQuantity\":{\"unitOfMeasurement\":\"EACH\",\"amount\":\"2\"},"
+ + "\"trackingInfo\":{\"shipDateTime\":\"2026-11-19T02:00:00.000Z\","
+ + "\"carrierName\":{\"carrier\":\"UPS\"},\"methodCode\":\"Standard\","
+ + "\"trackingNumber\":\"1Z999AA10123456784\"}}]}}]}}}";
+ }
+
+ private RecordingTransport transport(String body) {
+ return RecordingTransport.create()
+ .route("/v3/token", r -> Responses.ok(TOKEN_BODY))
+ .route("/shipping", r -> Responses.ok(body));
+ }
+
+ private static ShipmentCommand command() {
+ return ShipmentCommand.builder()
+ .channelOrderId("108816631915371")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1")
+ .quantity(2)
+ .carrier("UPS")
+ .methodCode("Standard")
+ .trackingNumber("1Z999AA10123456784")
+ .shippedAt(Instant.parse("2026-11-19T02:00:00Z"))
+ .build())
+ .build();
+ }
+
+ // ---------------------------------------------------------------- 请求
+
+ @Test
+ void postsToOrderShippingPath() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), command());
+
+ String url = lastUrl(transport);
+ assertUrlContains(url, ENDPOINT + "/v3/orders/108816631915371/shipping");
+ }
+
+ @Test
+ void bodyFollowsWalmartShape() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), command());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ // 单数包装 + 固定状态 + 字符串数量,缺一项沃尔玛就拒
+ assertTrue(body.contains("\"orderShipment\""), body);
+ assertTrue(body.contains("\"orderLines\""), body);
+ assertTrue(body.contains("\"orderLine\""), body);
+ assertTrue(body.contains("\"status\":\"Shipped\""), body);
+ assertTrue(body.contains("\"unitOfMeasurement\":\"EACH\""), body);
+ assertTrue(body.contains("\"amount\":\"2\""), body);
+ assertTrue(body.contains("\"carrier\":\"UPS\""), body);
+ assertTrue(body.contains("\"methodCode\":\"Standard\""), body);
+ assertTrue(body.contains("\"trackingNumber\":\"1Z999AA10123456784\""), body);
+ }
+
+ @Test
+ void shipDateTimeIsEpochMillisNotIsoString() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), command());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ // 官方 schema:type=integer, format=int64(UNIX epoch)
+ long expected = Instant.parse("2026-11-19T02:00:00Z").toEpochMilli();
+ assertTrue(body.contains("\"shipDateTime\":" + expected), body);
+ assertTrue(!body.contains("shipDateTime\":\"2026"), body);
+ }
+
+ @Test
+ void sellerOrderIdIsSentWhenProvided() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), ShipmentCommand.builder()
+ .channelOrderId("PO-1")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1").quantity(1).carrier("UPS")
+ .methodCode("Standard").trackingNumber("T-1")
+ .sellerOrderId("SO-1")
+ .build())
+ .build());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ assertTrue(body.contains("\"sellerOrderId\":\"SO-1\""), body);
+ }
+
+ @Test
+ void overlongSellerOrderIdIsOmittedNotTruncated() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ String tooLong = "0123456789012345678901234567890";
+ adapter(transport).markShipped(context(), ShipmentCommand.builder()
+ .channelOrderId("PO-1")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1").quantity(1).carrier("UPS")
+ .methodCode("Standard").trackingNumber("T-1")
+ .sellerOrderId(tooLong)
+ .build())
+ .build());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ // 截断会让面单上的单号对不上,宁可不发
+ assertTrue(!body.contains("sellerOrderId"), body);
+ }
+
+ @Test
+ void intentToCancelOverrideOnlySentWhenTrue() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), ShipmentCommand.builder()
+ .channelOrderId("PO-1")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1").quantity(1).carrier("UPS")
+ .methodCode("Standard").trackingNumber("T-1")
+ .intentToCancelOverride(true)
+ .build())
+ .build());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ assertTrue(body.contains("\"intentToCancelOverride\":true"), body);
+ }
+
+ @Test
+ void trackingUrlIsOptional() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), ShipmentCommand.builder()
+ .channelOrderId("PO-1")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1").quantity(1).carrierName("Local Courier")
+ .methodCode("Freight").trackingNumber("LC-1")
+ .trackingUrl("https://track.example.com/LC-1")
+ .build())
+ .build());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ assertTrue(body.contains("\"trackingURL\":\"https://track.example.com/LC-1\""), body);
+ }
+
+ @Test
+ void nonStandardCarrierUsesOtherCarrier() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), ShipmentCommand.builder()
+ .channelOrderId("PO-1")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1")
+ .quantity(1)
+ .carrierName("Local Courier")
+ .methodCode("Freight")
+ .trackingNumber("LC-1")
+ .build())
+ .build());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ assertTrue(body.contains("\"otherCarrier\":\"Local Courier\""), body);
+ assertTrue(!body.contains("\"carrier\":"), body);
+ }
+
+ @Test
+ void shipTimeDefaultsToContextClock() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), ShipmentCommand.builder()
+ .channelOrderId("PO-1")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1").quantity(1).carrier("UPS")
+ .methodCode("Standard").trackingNumber("T-1")
+ .build())
+ .build());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ // 测试时钟固定为 2026-11-18T00:00:00Z,报文字段是 epoch 毫秒
+ assertTrue(body.contains("\"shipDateTime\":" + Instant.parse("2026-11-18T00:00:00Z").toEpochMilli()),
+ body);
+ }
+
+ @Test
+ void orderIdIsUrlEncoded() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ adapter(transport).markShipped(context(), ShipmentCommand.builder()
+ .channelOrderId("PO 1/2")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1").quantity(1).carrier("UPS")
+ .methodCode("Standard").trackingNumber("T-1")
+ .build())
+ .build());
+ assertUrlContains(lastUrl(transport), "/v3/orders/PO%201%2F2/shipping");
+ }
+
+ // ---------------------------------------------------------------- 响应
+
+ @Test
+ void mapsResponseToResult() {
+ ShipmentResult result = adapter(transport(shippedOrderBody()))
+ .markShipped(context(), command());
+
+ assertEquals("108816631915371", result.channelOrderId());
+ assertEquals("1Z999AA10123456784", result.trackingNumber());
+ assertEquals(Instant.parse("2026-11-19T02:00:00Z"), result.shippedAt());
+ assertEquals(1, result.lines().size());
+ assertEquals("Shipped", result.lines().get("1").status());
+ assertEquals(2, result.lines().get("1").quantity());
+ }
+
+ @Test
+ void emptyResponseStillReturnsCommandTracking() {
+ RecordingTransport transport = transport("{}");
+ ShipmentResult result = adapter(transport).markShipped(context(), command());
+
+ assertEquals("108816631915371", result.channelOrderId());
+ // 平台只回受理结果时,至少把命令里的跟踪号带回去
+ assertEquals("1Z999AA10123456784", result.trackingNumber());
+ assertTrue(result.lines().isEmpty());
+ }
+
+ // ---------------------------------------------------------------- 错误
+
+ @Test
+ void cancelledOrderIsBusinessError() {
+ RecordingTransport transport = RecordingTransport.create()
+ .route("/v3/token", r -> Responses.ok(TOKEN_BODY))
+ .route("/shipping", r -> Responses.status(400,
+ "{\"error\":[{\"code\":\"INVALID_ORDER_STATUS\",\"description\":"
+ + "\"order is cancelled\"}]}"));
+ ValidationException ex = assertThrows(ValidationException.class,
+ () -> adapter(transport).markShipped(context(), command()));
+ assertEquals("INVALID_ORDER_STATUS", ex.platformCode());
+ }
+
+ @Test
+ void nullCommandIsRejectedBeforeAnyRequest() {
+ RecordingTransport transport = transport(shippedOrderBody());
+ assertThrows(ValidationException.class, () -> adapter(transport).markShipped(context(), null));
+ assertEquals(0, transport.recorded().size());
+ }
+
+ @Test
+ void businessRefIsStableAndOrderIndependent() {
+ ShipmentCommand a = ShipmentCommand.builder()
+ .channelOrderId("PO-1")
+ .line(line("2", 1))
+ .line(line("1", 2))
+ .build();
+ ShipmentCommand b = ShipmentCommand.builder()
+ .channelOrderId("PO-1")
+ .line(line("1", 2))
+ .line(line("2", 1))
+ .build();
+
+ assertEquals(a.businessRef(), b.businessRef());
+ assertEquals("PO-1|1:2,2:1", a.businessRef());
+ // 数量不同 = 不同业务动作(部分发货第二次调用)
+ assertEquals("PO-1|1:1", ShipmentCommand.builder()
+ .channelOrderId("PO-1").line(line("1", 1)).build().businessRef());
+ }
+
+ @Test
+ void commandRejectsMissingRequiredFields() {
+ assertThrows(IllegalArgumentException.class,
+ () -> ShipmentCommand.builder().channelOrderId("PO-1").build());
+ assertThrows(IllegalArgumentException.class,
+ () -> ShipmentCommand.builder().line(line("1", 1)).build());
+ }
+
+ private static ShipmentCommand.Line line(String number, int quantity) {
+ return ShipmentCommand.Line.builder()
+ .lineNumber(number).quantity(quantity).carrier("UPS")
+ .methodCode("Standard").trackingNumber("T-" + number)
+ .build();
+ }
+}
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartOrderTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartOrderTest.java
index 64d10ac..0050e80 100644
--- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartOrderTest.java
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartOrderTest.java
@@ -308,8 +308,9 @@ class WalmartOrderTest {
// ---------------------------------------------------------------- 能力
@Test
- void declaresOnlyReadCapabilities() {
- assertEquals(EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS),
+ void declaresReadCapabilitiesPlusWrites() {
+ assertEquals(EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS,
+ Capability.MARK_SHIPPED, Capability.REFUND),
adapter(transport()).capabilities());
assertEquals(ChannelProvider.DIRECT, adapter(transport()).provider());
assertEquals(EnumSet.of(Platform.WALMART_SC), adapter(transport()).platforms());
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartProductTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartProductTest.java
index efd7540..4cb5e2c 100644
--- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartProductTest.java
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartProductTest.java
@@ -56,10 +56,28 @@ class WalmartProductTest {
}
@Test
- void limitIsCappedAtPlatformMaximum() {
+ void limitIsCappedAtOneThousand() {
+ // 官方:cannot be more than 1000 entities per request(默认 20)
+ assertEquals(1000, WalmartConstants.MAX_ITEM_PAGE_SIZE);
RecordingTransport transport = transport();
adapter(transport).pull(context(), ProductQuery.builder().pageSize(5_000).build());
- assertUrlContains(lastUrl(transport), "limit=" + WalmartConstants.MAX_ITEM_PAGE_SIZE);
+ assertUrlContains(lastUrl(transport), "limit=1000");
+ }
+
+ @Test
+ void pageSizeOverTwoHundredIsStillAllowed() {
+ // 200 只是「建议改用游标」的阈值,不是上限
+ RecordingTransport transport = transport();
+ adapter(transport).pull(context(), ProductQuery.builder().pageSize(500).build());
+ assertUrlContains(lastUrl(transport), "limit=500");
+ }
+
+ @Test
+ void firstPageDoesNotSendCursor() {
+ // 官方 default 是 "*",但首页不传更稳;这里锁住「首页不带 nextCursor」
+ RecordingTransport transport = transport();
+ adapter(transport).pull(context(), ProductQuery.builder().build());
+ assertTrue(!lastUrl(transport).contains("nextCursor"), lastUrl(transport));
}
@Test
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartRefundTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartRefundTest.java
new file mode 100644
index 0000000..9135fb9
--- /dev/null
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartRefundTest.java
@@ -0,0 +1,209 @@
+package common.ecommerce.walmart.adapter;
+
+import common.ecommerce.channel.model.aftersale.RefundCommand;
+import common.ecommerce.channel.model.aftersale.RefundResult;
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.shared.model.Capability;
+import common.ecommerce.shared.support.Money;
+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 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;
+
+/**
+ * 退款:报文严格对齐文档 §5.3 的请求示例。
+ *
+ * 文档示例:
+ * {@code {"returnOrderId":"...","refundLines":[{"returnOrderLineNumber":1,
+ * "refundCharges":[{"chargeName":"ItemPrice","chargeType":"PRODUCT",
+ * "refundAmount":{"currencyUnit":"USD","currencyAmount":119.95}}]}]}}
+ */
+class WalmartRefundTest {
+
+ private static final String TOKEN_BODY = JsonFixture.load("fixtures/walmart/token/success.json");
+
+ private RecordingTransport transport(String body) {
+ return RecordingTransport.create()
+ .route("/v3/token", r -> Responses.ok(TOKEN_BODY))
+ .route("/refund", r -> Responses.ok(body));
+ }
+
+ /** 与文档 §5.3 示例完全同构的命令。 */
+ private static RefundCommand docExampleCommand() {
+ return RefundCommand.builder()
+ .afterSaleId("103738048909818825")
+ .line(RefundCommand.Line.builder()
+ .lineId("1")
+ .charge(RefundCommand.Charge.builder()
+ .chargeName("ItemPrice")
+ .chargeType("PRODUCT")
+ .amount(Money.of("119.95", "USD"))
+ .build())
+ .build())
+ .build();
+ }
+
+ // ---------------------------------------------------------------- 请求
+
+ @Test
+ void postsToRefundPath() {
+ RecordingTransport transport = transport("{}");
+ adapter(transport).refund(context(), docExampleCommand());
+ assertUrlContains(lastUrl(transport), ENDPOINT + "/v3/returns/103738048909818825/refund");
+ }
+
+ @Test
+ void bodyMatchesDocumentExample() {
+ RecordingTransport transport = transport("{}");
+ adapter(transport).refund(context(), docExampleCommand());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ // 逐字段对照文档 §5.3
+ assertTrue(body.contains("\"returnOrderId\":\"103738048909818825\""), body);
+ assertTrue(body.contains("\"refundLines\""), body);
+ assertTrue(body.contains("\"returnOrderLineNumber\":1"), body);
+ assertTrue(body.contains("\"refundCharges\""), body);
+ assertTrue(body.contains("\"chargeName\":\"ItemPrice\""), body);
+ assertTrue(body.contains("\"chargeType\":\"PRODUCT\""), body);
+ assertTrue(body.contains("\"refundAmount\""), body);
+ assertTrue(body.contains("\"currencyUnit\":\"USD\""), body);
+ assertTrue(body.contains("\"currencyAmount\":119.95"), body);
+ }
+
+ @Test
+ void multiLineMultiChargeIsPreserved() {
+ RecordingTransport transport = transport("{}");
+ adapter(transport).refund(context(), RefundCommand.builder()
+ .afterSaleId("R-1")
+ .line(RefundCommand.Line.builder()
+ .lineId("1")
+ .charge(RefundCommand.Charge.builder()
+ .chargeName("ItemPrice").chargeType("PRODUCT")
+ .amount(Money.of("10.00", "USD")).build())
+ .charge(RefundCommand.Charge.builder()
+ .chargeName("Shipping").chargeType("SHIPPING")
+ .amount(Money.of("5.00", "USD")).build())
+ .build())
+ .line(RefundCommand.Line.builder()
+ .lineId("2")
+ .charge(RefundCommand.Charge.builder()
+ .chargeName("ItemPrice").chargeType("PRODUCT")
+ .amount(Money.of("7.50", "USD")).build())
+ .build())
+ .build());
+
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ assertTrue(body.contains("\"returnOrderLineNumber\":1"), body);
+ assertTrue(body.contains("\"returnOrderLineNumber\":2"), body);
+ assertTrue(body.contains("\"chargeName\":\"Shipping\""), body);
+ }
+
+ @Test
+ void nullFieldsAreOmitted() {
+ RecordingTransport transport = transport("{}");
+ adapter(transport).refund(context(), docExampleCommand());
+ String body = transport.recorded().get(transport.recorded().size() - 1).body();
+ // @JsonInclude(NON_NULL):沃尔玛对 null 字段会报格式错误
+ assertTrue(!body.contains(":null"), body);
+ }
+
+ @Test
+ void nonNumericLineNumberIsRejectedLocally() {
+ RecordingTransport transport = transport("{}");
+ ValidationException ex = assertThrows(ValidationException.class,
+ () -> adapter(transport).refund(context(), RefundCommand.builder()
+ .afterSaleId("R-1")
+ .line(RefundCommand.Line.builder()
+ .lineId("1a")
+ .charge(RefundCommand.Charge.builder()
+ .chargeName("ItemPrice").chargeType("PRODUCT")
+ .amount(Money.of("1.00", "USD")).build())
+ .build())
+ .build()));
+ assertTrue(ex.getMessage().contains("numeric"), ex.getMessage());
+ assertEquals(0, transport.recorded().size());
+ }
+
+ @Test
+ void nullCommandIsRejected() {
+ RecordingTransport transport = transport("{}");
+ assertThrows(ValidationException.class, () -> adapter(transport).refund(context(), null));
+ assertEquals(0, transport.recorded().size());
+ }
+
+ // ---------------------------------------------------------------- 响应
+
+ @Test
+ void mapsReturnOrderResponse() {
+ RecordingTransport transport = transport(
+ "{\"returnOrderId\":\"103738048909818825\",\"returnOrderLines\":["
+ + "{\"returnOrderLineNumber\":1,\"currentRefundStatus\":\"REFUND_PROCESSED\"}]}");
+
+ RefundResult result = adapter(transport).refund(context(), docExampleCommand());
+ assertEquals("103738048909818825", result.afterSaleId());
+ assertEquals("REFUND_PROCESSED", result.rawStatus());
+ assertEquals(1, result.lines().size());
+ assertEquals("1", result.lines().get(0).lineId());
+ }
+
+ @Test
+ void emptyResponseStillReturnsAfterSaleId() {
+ RefundResult result = adapter(transport("")).refund(context(), docExampleCommand());
+ assertEquals("103738048909818825", result.afterSaleId());
+ assertTrue(result.lines().isEmpty());
+ }
+
+ // ---------------------------------------------------------------- 能力与命令
+
+ @Test
+ void refundCapabilityIsDeclared() {
+ assertTrue(adapter(transport("{}")).capabilities().contains(Capability.REFUND));
+ }
+
+ @Test
+ void commandValidatesItself() {
+ assertThrows(IllegalArgumentException.class, () -> RefundCommand.builder().build());
+ assertThrows(IllegalArgumentException.class,
+ () -> RefundCommand.builder().afterSaleId("R").build());
+ assertThrows(IllegalArgumentException.class,
+ () -> RefundCommand.Line.builder().lineId("1").build());
+ assertThrows(IllegalArgumentException.class,
+ () -> RefundCommand.Charge.builder()
+ .chargeName("ItemPrice").chargeType("PRODUCT")
+ .amount(Money.of("-1.00", "USD")).build());
+ }
+
+ @Test
+ void totalAmountSumsCharges() {
+ RefundCommand cmd = RefundCommand.builder()
+ .afterSaleId("R-1")
+ .line(RefundCommand.Line.builder()
+ .lineId("1")
+ .charge(RefundCommand.Charge.builder()
+ .chargeName("ItemPrice").chargeType("PRODUCT")
+ .amount(Money.of("10.00", "USD")).build())
+ .charge(RefundCommand.Charge.builder()
+ .chargeName("Shipping").chargeType("SHIPPING")
+ .amount(Money.of("5.00", "USD")).build())
+ .build())
+ .build();
+ assertEquals("15.00", cmd.totalAmount().amount().toPlainString());
+ }
+
+ @Test
+ void constantPathMatchesDocument() {
+ assertEquals("/refund", WalmartConstants.PATH_RETURN_REFUND);
+ // 与文档 §5.3 的 POST /v3/returns/{returnOrderId}/refund 一致
+ assertEquals("/v3/returns/", WalmartConstants.PATH_RETURN_BY_ID);
+ }
+}
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartReturnTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartReturnTest.java
index 5abc8a6..3d5c071 100644
--- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartReturnTest.java
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartReturnTest.java
@@ -47,16 +47,19 @@ class WalmartReturnTest {
// ---------------------------------------------------------------- 请求
@Test
- void pullSendsCreatedWindowAndLimit() {
+ void pullSendsCreationWindowAndLimit() {
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");
+ // 官方参数名是 returnCreationStartDate/EndDate
+ assertUrlContains(url, "returnCreationStartDate=2026-11-01T00%3A00%3A00.000Z");
+ assertUrlContains(url, "returnCreationEndDate=2026-11-18T00%3A00%3A00.000Z");
assertUrlContains(url, "limit=100");
- assertUrlContains(url, "offset=0");
+ // 官方退货接口没有 offset 参数
+ assertTrue(!url.contains("offset="), url);
+ assertTrue(!url.contains("createdStartDate"), url);
}
@Test
@@ -74,17 +77,32 @@ class WalmartReturnTest {
}
@Test
- void nonSaleTimeDateTypeIsRejected() {
+ void purchaseTimeDateTypeIsRejected() {
+ // 官方没有按原订单下单时间过滤的参数
RecordingTransport transport = transport();
ValidationException ex = assertThrows(ValidationException.class,
() -> adapter(transport).pull(context(), query().toBuilder()
- .dateType(AfterSaleQuery.DateType.UPDATE_TIME)
+ .dateType(AfterSaleQuery.DateType.PURCHASE_TIME)
.build()));
- assertTrue(ex.getMessage().contains("return-created date"), ex.getMessage());
+ assertTrue(ex.getMessage().contains("purchase-time"), ex.getMessage());
assertEquals(0, transport.recorded().size());
}
@Test
+ void updateTimeUsesLastModifiedParams() {
+ RecordingTransport transport = transport();
+ adapter(transport).pull(context(), query().toBuilder()
+ .dateType(AfterSaleQuery.DateType.UPDATE_TIME)
+ .build());
+
+ String url = lastUrl(transport);
+ assertUrlContains(url, "returnLastModifiedStartDate=2026-11-01T00%3A00%3A00.000Z");
+ assertUrlContains(url, "returnLastModifiedEndDate=2026-11-18T00%3A00%3A00.000Z");
+ // 不能同时带创建时间参数
+ assertTrue(!url.contains("returnCreationStartDate"), url);
+ }
+
+ @Test
void orderIdFilterIsRejected() {
RecordingTransport transport = transport();
assertThrows(ValidationException.class,
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/enums/WalmartStatusMappingTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/enums/WalmartStatusMappingTest.java
index 4d5a62f..b1a051a 100644
--- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/enums/WalmartStatusMappingTest.java
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/enums/WalmartStatusMappingTest.java
@@ -122,10 +122,27 @@ class WalmartStatusMappingTest {
// ---------------------------------------------------------------- 售后类型
@Test
- void returnTypeMapping() {
- assertEquals(AfterSaleType.RETURN, WalmartReturnType.toCore("RETURN"));
+ void returnTypeMappingFollowsOfficialEnum() {
+ // 官方枚举:PREORDER / REPLACEMENT / REFUND
+ assertEquals(AfterSaleType.RETURN, WalmartReturnType.toCore("REFUND"));
assertEquals(AfterSaleType.EXCHANGE, WalmartReturnType.toCore("REPLACEMENT"));
+ // PREORDER 官方没解释语义,落 UNKNOWN 保留原值,不猜
+ assertEquals(AfterSaleType.UNKNOWN, WalmartReturnType.toCore("PREORDER"));
assertEquals(AfterSaleType.UNKNOWN, WalmartReturnType.toCore("SOMETHING"));
assertEquals(AfterSaleType.UNKNOWN, WalmartReturnType.toCore(null));
}
+
+ @Test
+ void legacyReturnValueStillParses() {
+ // 早期文档写的是 RETURN,历史数据里还有,不能解析成 UNKNOWN 丢掉
+ assertEquals(AfterSaleType.RETURN, WalmartReturnType.toCore("RETURN"));
+ assertEquals("RETURN", WalmartReturnType.fromRaw("RETURN").raw());
+ }
+
+ @Test
+ void preOrderKeepsRawValue() {
+ WalmartReturnType type = WalmartReturnType.fromRaw("PREORDER");
+ assertEquals("PREORDER", type.raw());
+ assertEquals(AfterSaleType.UNKNOWN, type.toCore());
+ }
}
diff --git a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/probe/WalmartProbeTest.java b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/probe/WalmartProbeTest.java
index 9d94356..a315cb0 100644
--- a/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/probe/WalmartProbeTest.java
+++ b/channel-sdk-walmart/src/test/java/common/ecommerce/walmart/probe/WalmartProbeTest.java
@@ -244,6 +244,48 @@ class WalmartProbeTest {
});
}
+ @Test
+ @Order(8)
+ void probeMarkShipped() {
+ requireCredentials();
+ List orders = ordersOfLastWindow();
+ if (orders.isEmpty()) {
+ System.out.println("skip markShipped: no order in last 7 days");
+ return;
+ }
+ SalesOrder order = orders.get(0);
+ String lineNumber = order.lines().isEmpty() ? null : order.lines().get(0).lineId();
+ if (lineNumber == null) {
+ System.out.println("skip markShipped: order has no line");
+ return;
+ }
+ section("POST /v3/orders/" + order.channelOrderId() + "/shipping"
+ + "(沙箱 404 属正常;这是写操作,只在显式开启时才跑)");
+ // 写操作默认不跑:必须额外传 -Dwalmart.probe.write=true
+ if (!Boolean.getBoolean("walmart.probe.write")) {
+ System.out.println(" (skipped: pass -Dwalmart.probe.write=true to actually ship)");
+ return;
+ }
+ probe(() -> {
+ common.ecommerce.channel.model.fulfillment.ShipmentResult result =
+ adapter.markShipped(ctx,
+ common.ecommerce.channel.model.fulfillment.ShipmentCommand.builder()
+ .channelOrderId(order.channelOrderId())
+ .line(common.ecommerce.channel.model.fulfillment.ShipmentCommand.Line
+ .builder()
+ .lineNumber(lineNumber)
+ .quantity(1)
+ .carrier("UPS")
+ .methodCode("Standard")
+ .trackingNumber("PROBE-" + System.currentTimeMillis())
+ .build())
+ .build());
+ System.out.println(" shipped order=" + result.channelOrderId()
+ + " tracking=" + result.trackingNumber()
+ + " lines=" + result.lines().size());
+ });
+ }
+
// ---------------------------------------------------------------- internals
/** 探针不因平台 404 / 固定条数失败:打印异常后继续跑下一段。 */
diff --git a/docs/walmart/README.md b/docs/walmart/README.md
index 49e127b..a779524 100644
--- a/docs/walmart/README.md
+++ b/docs/walmart/README.md
@@ -3,7 +3,8 @@
> 模块:`channel-sdk-walmart` 通道:`ChannelProvider.DIRECT` 平台:`Platform.WALMART_SC`
> 协议依据:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱 `https://sandbox.walmartapis.com`
-只读三件套:**订单 / 商品 / 售后**。标发、退款、商品写入、`WALMART_1P`、结算、Webhook 不在本期。
+已接:**订单 / 商品 / 售后(读)+ 标发 / 退款(写)+ 商品 Feed(提交与状态查询)**。
+未接:单个商品创建/更新(Item Spec 版本管理)、创建退货 / 取消退货(无报文)、`WALMART_1P`、结算、Webhook。
---
@@ -74,7 +75,7 @@ ChannelConnection conn = ChannelConnection.of(
| `RETURNS` 退货列表(按行展开) | ✅ |
| 退货单详情 `WalmartAdapter.getReturn` | ✅(⚠ 沙箱 404) |
| 发货信息 `WalmartAdapter.getShipping` | ✅(⚠ 沙箱 404) |
-| `MARK_SHIPPED` 标发 | ❌ 下一期 |
+| `MARK_SHIPPED` 标发 | ✅(⚠ 沙箱 404,见 §7) |
| `REFUND` 退款 | ❌ 沙箱 404 |
| 商品写入(Feed / 单个) | ❌ 沙箱 520 |
@@ -116,9 +117,12 @@ mvn -pl channel-sdk-walmart -am test
| `WalmartErrorsTest` | 两种错误格式、401/429/5xx/`SYSTEM_ERROR` 分类、报文截断 |
| `WalmartStatusMappingTest` | 精确匹配(不做 contains)、未知值、空值 |
| `WalmartExtraQueryTest` | 退货详情、发货信息两个扩展查询 |
-| `WalmartFacadeTest` | 门面路由、能力矩阵、写能力被拒、未注册平台报错 |
+| `WalmartFacadeTest` | 门面路由、能力矩阵、未实现写能力被拒、未注册平台报错 |
+| `WalmartMarkShippedTest` | 标发报文(单数包装 / 固定状态 / 字符串数量 / ISO 时间)、非标准承运商、响应映射、幂等键稳定性 |
+| `WalmartRefundTest` | 退款报文逐字段对齐 §5.3 示例、多行多费用项、非整数行号本地拒绝 |
+| `WalmartFeedTest` | Feed 提交报文头、feedId 返回、状态计数与逐商品明细、错误压行 |
-### 5.2 沙箱探针(只读,默认跳过)
+### 5.2 沙箱探针(读写开关分离)
```bash
mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
@@ -162,25 +166,146 @@ mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
| 问题 | 状态 |
|---|---|
| 沙箱商品详情 404 | 生产环境再验 |
-| 沙箱退货详情 / 退款 404 | 详情已按文档实现(`getReturn`),退款未实现 |
-| 沙箱 Feed 520 | 未实现 |
+| 沙箱退货详情 / 退款 404 | 两条都已按文档实现(`getReturn` / `refund`),生产再验 |
+| 沙箱 Feed 520 | 提交 / 状态查询已按文档实现(`submitFeed` / `getFeedStatus`),生产再验 |
| 沙箱过滤参数不生效 | 以生产为准 |
| 订单列表 `status` 过滤是否生效 | 探针未覆盖写操作,读侧以生产为准 |
| `pullOpenOrders` 的 `status=Created,Acknowledged` 多值是否成立 | **未验证**,文档只给了单值示例;探针跑通后确认 |
| 订单翻页时是否仍需带时间窗 | **未验证**,退货游标是完整查询串,暗示游标已蕴含条件 |
| `createdStartDate` 最大回溯窗口 | 代码按 180 天硬校验,待探针核实 |
| `x-current-token-count` 实际值 | 待探针核实 |
-| 标发 | 下一期:新增 `MarkShippedCapable` + `SalesOrders.markShipped(...)` |
---
-## 7. 下一期(标发)
+## 7. 标发(MARK_SHIPPED)
-设计已定,实现待排:
+沃尔玛没有批量标发接口,**一次一个订单**;支持部分发货。
-- 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` 确认行状态与数量
+```java
+ShipmentCommand cmd = ShipmentCommand.builder()
+ .channelOrderId("108816631915371")
+ .line(ShipmentCommand.Line.builder()
+ .lineNumber("1") // 必须与订单详情一致
+ .quantity(2) // 本次实发
+ .carrier("UPS") // 或 carrierName("非标准承运商")
+ .methodCode("Standard") // 必须与承运商方式对照表匹配
+ .trackingNumber("1Z999...")
+ // .shippedAt(...) // 不传则取 ctx.clock()
+ .build())
+ .build();
+
+// 写操作必须包在 sdk.writes() 里
+WriteResult r = sdk.writes().execute(
+ WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC,
+ "oms-wm-001", "wm-seller-01", "markShipped", cmd.businessRef()),
+ () -> sdk.salesOrders(key, conn).markShipped(cmd),
+ ShipmentResult::channelOrderId);
+```
+
+**幂等键**:`ShipmentCommand.businessRef()` = `订单号|行号:数量,行号:数量`(行号排序)。
+不带金额与跟踪号——换跟踪号属于修正,不应产生新动作;数量不同则是新的一次部分发货。
+
+**报文要求**(依据官方 `reference/shippingupdates` schema):
+
+| 字段 | 要求 |
+|---|---|
+| `lineNumber` | 与订单详情一致 |
+| `status` | 固定 `Shipped` |
+| `statusQuantity.unitOfMeasurement` | 固定 `EACH`(官方枚举 `EACH`/`EA`) |
+| `statusQuantity.amount` | **字符串** |
+| `trackingInfo.shipDateTime` | **epoch 毫秒整数**(官方 `int64`,不是 ISO 字符串) |
+| `trackingInfo.carrierName` | `carrier` 与 `otherCarrier` 至少一个 |
+| `trackingInfo.methodCode` | 官方枚举:`Standard` / `Express` / `OneDay` / `Freight` / `WhiteGlove` / `Value` |
+| `trackingInfo.trackingNumber` | 必填 |
+| `trackingInfo.trackingURL` | 可空;用 `otherCarrier` 时建议给 |
+| `sellerOrderId` | 官方标必填(≤30 字符,印在退货面单上);适配器**不强制**,超长时省略而不是截断 |
+| `intentToCancelOverride` | 客户已申请取消但仍要发货时传 `true`;默认不发 |
+| `processMode` | 发货后只更新物流信息时传 `PARTIAL_UPDATE`;首次标发不传 |
+
+DTO 上标了 `@JsonInclude(NON_NULL)`,未设置字段不会被发成 `null`。
+
+---
+
+## 8. 退款(REFUND)
+
+报文按文档 §5.3,细到**退货行 × 费用项**:
+
+```java
+RefundCommand cmd = RefundCommand.builder()
+ .afterSaleId("103738048909818825")
+ .line(RefundCommand.Line.builder()
+ .lineId("1") // 平台退货行号,必须是整数
+ .charge(RefundCommand.Charge.builder()
+ .chargeName("ItemPrice")
+ .chargeType("PRODUCT") // PRODUCT / FEE / SHIPPING
+ .amount(Money.of("119.95", "USD"))
+ .build())
+ .build())
+ .build();
+
+sdk.writes().execute(
+ WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC,
+ "oms-wm-001", "wm-seller-01", "refund", "103738048909818825:1"),
+ () -> sdk.afterSales(key, conn).refund(cmd),
+ RefundResult::afterSaleId);
+```
+
+业务规则(文档 §5.3):部分售后由平台自动退款,只有 `currentRefundStatus` 需要卖家处理
+(或 `refundChannels` 含 `SELLER_MANUAL_REFUND`)时才调用;调用前先查详情核对
+`refundedQty` / `cancellableQty`,避免超退。
+
+退货列表的官方过滤参数(`reference/getreturns`):
+
+| 参数 | 说明 |
+|---|---|
+| `returnCreationStartDate` / `returnCreationEndDate` | 按退货单创建时间(ISO-8601) |
+| `returnLastModifiedStartDate` / `returnLastModifiedEndDate` | 按退货单修改时间(ISO-8601) |
+| `returnType` | `PREORDER` / `REPLACEMENT` / `REFUND` |
+| `status` | `INITIATED` / `DELIVERED` / `COMPLETED` |
+| `limit` | 默认 10,上限 200;**没有 `offset`** |
+
+统一模型 `AfterSaleQuery.DateType` 的映射:
+
+- `AFTER_SALE_TIME` → `returnCreation*`
+- `UPDATE_TIME` → `returnLastModified*`
+- `PURCHASE_TIME` → 没有对应参数,本地报错
+
+行号不是整数时本地抛 `ValidationException`,不发请求。
+
+---
+
+## 9. 商品 Feed(扩展方法)
+
+单商品写接口要管理 Item Spec 版本,先做 Feed——沃尔玛商品写入的主流方式。
+
+```java
+WalmartAdapter wm = (WalmartAdapter) sdk.resolve(key);
+
+String feedId = wm.submitFeed(ctx, WalmartFeedCommand.builder()
+ .version("4.2") // 必须与后台开通版本一致
+ .businessUnit("WALMART_US")
+ .locale("en") // 默认 en
+ .subCategory("OTHER") // 可选
+ .item(itemPayload) // 结构见 Item Spec,原样透传
+ .build());
+
+WalmartFeedStatus status = wm.getFeedStatus(ctx, feedId, true);
+if (status.isFinished()) {
+ status.isFullySucceeded(); // PROCESSED 且 itemsFailed == 0
+ status.items(); // 逐商品 SUCCESS / DATA_ERROR / SYSTEM_ERROR
+}
+```
+
+商品数组原样透传,适配器只补 `MPItemFeedHeader`——不同 `productType` 的必填字段差异太大,
+建模反而会挡住合法报文。
+
+---
+
+## 10. 未接入的接口
+
+| 接口 | 原因 |
+|---|---|
+| `POST /v3/items` 创建商品 | 报文只有「精简示例」,正式对接需按《Item Spec》生成;版本管理未定 |
+| `PUT /v3/items/{sku}` 更新商品 | 同上;且 PUT 是覆盖式,需先定「先查后写」的约定 |
+| `POST /v3/returns` 创建退货 | **文档只给路径,没有请求报文** |
+| `POST /v3/returns/{id}/cancel` 取消退货 | 同上 |