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` 取消退货 | 同上 |