Browse Source

feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数

【新增写操作】
- MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货;
  幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号)
- RefundCapable + AfterSales.refund:按退货行 × 费用项退款
- WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法,
  不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形)

【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】
标发 POST /v3/orders/{id}/shipping:
- shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64)
- 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断)
- 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空)
- OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE)

退货 GET /v3/returns:
- 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate
- DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate;
  PURCHASE_TIME 无对应参数,本地报错
- 去掉官方不存在的 offset 参数
- returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据
- limit 加上限 200

商品 GET /v3/items:
- limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值)
- 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor

商品 Feed POST /v3/feeds:
- feedType 按官方 13 个枚举值本地校验,非法值直接拒绝
- 成功响应是 200 而非 202

【校验与容错】
- 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页
- 行金额除不尽时 unitPrice 留 null,不四舍五入倒推
- 运费不冒充商品单价;同单多币种时 totalAmount 为 null
- 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误

【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、
状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。

Co-Authored-By: Claude Code <noreply@anthropic.com>
lml 1 day ago
parent
commit
a3c5931c5c
  1. 28
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java
  2. 39
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java
  3. 35
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java
  4. 27
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java
  5. 275
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java
  6. 134
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundResult.java
  7. 345
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentCommand.java
  8. 142
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentResult.java
  9. 45
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java
  10. 261
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java
  11. 209
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartFeedDtos.java
  12. 82
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartRefundDtos.java
  13. 194
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentWriteDtos.java
  14. 28
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartReturnType.java
  15. 22
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartRequestFactory.java
  16. 105
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartFeedMapper.java
  17. 103
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java
  18. 203
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java
  19. 170
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedCommand.java
  20. 248
      channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedStatus.java
  21. 13
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/WalmartFacadeTest.java
  22. 230
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartFeedTest.java
  23. 304
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java
  24. 5
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartOrderTest.java
  25. 22
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartProductTest.java
  26. 209
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartRefundTest.java
  27. 32
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartReturnTest.java
  28. 21
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/enums/WalmartStatusMappingTest.java
  29. 42
      channel-sdk-walmart/src/test/java/common/ecommerce/walmart/probe/WalmartProbeTest.java
  30. 155
      docs/walmart/README.md

28
channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java

@ -6,6 +6,8 @@ import common.ecommerce.shared.model.Capability; @@ -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 { @@ -72,6 +74,32 @@ public final class AfterSales {
});
}
/**
* 发起退款(写操作,调用方需包在 {@code sdk.writes()} 里)。
*
* <p>推荐幂等键:{@code action=refund}、
* {@code businessRef=退货单号:行号,行号}(行号排序);不含金额——
* 金额修正不应被当成重复退款。</p>
*
* @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)) {

39
channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java

@ -0,0 +1,39 @@ @@ -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 标发能力:把订单行标记为已发货并回传物流信息。
*
* <p>这是一次真实的外部动作(买家会看到物流),<b>写操作,必须经
* {@code IdempotencyGuard} 执行</b>。推荐幂等键:
* {@code action=markShipped}、{@code businessRef=订单号:行号:数量}
* ——不带金额,金额变化不应产生新的业务动作。</p>
*
* <p>与 {@link OutboundCapable} 的区别:快速出库是「提交出库任务、异步回查结果」;
* 标发是同步确认订单行的发货状态,一次调用对应一个平台订单。</p>
*
* <p>支持部分发货的平台(如沃尔玛),同一行可以分多次调用,
* 每次只给本次实发数量;不支持部分发货的平台在数量不一致时应抛业务异常,
* 不能静默按整行发货。</p>
*
* <p>能力位 {@link common.ecommerce.shared.model.Capability#MARK_SHIPPED}。</p>
*/
public interface MarkShippedCapable extends PlatformAdapter {
/**
* 标发一个订单。
*
* <p>平台按订单返回结果;部分发货时结果里的行数量是<b>累计已发</b>数量。
* 订单状态已不允许发货(如已取消)时应抛
* {@link common.ecommerce.shared.error.PlatformBusinessException},
* 不要返回一个「看起来成功」的空结果。</p>
*
* @param ctx 调用上下文
* @param command 发货命令,一个命令对应一个平台订单
* @return 平台确认后的发货结果
*/
ShipmentResult markShipped(ChannelContext ctx, ShipmentCommand command);
}

35
channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java

@ -0,0 +1,35 @@ @@ -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;
/**
* 退款能力:按平台退货单发起退款。
*
* <p>写操作,涉及资金,<b>必须经 {@code IdempotencyGuard} 执行</b>。
* 推荐幂等键:{@code action=refund}、
* {@code businessRef=退货单号:行号,行号}——不带金额与费用项;
* 金额修正属于另一个动作,不应被当成「新的退款」重复执行。</p>
*
* <p>能力位 {@link Capability#REFUND},与只读的 {@link AfterSaleCapable} 分开声明:
* 有些平台只能查售后、不能发起退款。</p>
*
* <p>调用前应先查售后详情核对可退数量 / 可退金额,避免超退。
* 适配器只做报文校验,余额校验由平台负责。</p>
*/
public interface RefundCapable extends PlatformAdapter {
/**
* 发起一次退款。
*
* <p>部分平台退货单里含多行,可以只退其中几行或几项费用;
* 命令里给什么就退什么,适配器不做补全。</p>
*
* @param ctx 调用上下文
* @param command 退款命令
* @return 平台确认结果
* @throws common.ecommerce.shared.error.PlatformBusinessException 平台拒绝(如已退过、超过可退金额)
*/
RefundResult refund(ChannelContext ctx, RefundCommand command);
}

27
channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java

@ -7,6 +7,8 @@ import common.ecommerce.shared.model.Capability; @@ -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 { @@ -126,6 +128,31 @@ public final class SalesOrders {
});
}
/**
* 标发一个订单(写操作,调用方需包在 {@code sdk.writes()} 里)。
*
* <p>推荐幂等键:{@code action=markShipped}、
* {@code businessRef=订单号:行号:数量};同一行分多次部分发货时,
* 数量不同即视为不同业务动作。</p>
*
* @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) {

275
channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java

@ -0,0 +1,275 @@ @@ -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;
/**
* 退款命令。
*
* <p>按平台退货单发起退款。平台侧的退款通常细到<b>退货行 × 费用项</b>
* (沃尔玛 {@code refundLines[].refundCharges[]}),所以这里不是「退多少钱」,
* 而是逐行逐费用给金额。</p>
*
* <p>调用前应先查售后详情核对 {@code refundedQty} / {@code cancellableQty},
* 避免超退——各平台超额规则不同,适配器只做格式校验,不做余额校验。</p>
*/
public final class RefundCommand {
/** 平台退货单号;必填。 */
private final String afterSaleId;
/** 退款行;不可变,至少一行。 */
private final List<Line> 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<Line>(b.lines));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 平台退货单号。 */
public String afterSaleId() {
return afterSaleId;
}
/** 退款行;不可变,至少一行。 */
public List<Line> 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;
}
/**
* 一条退款行:对应平台的一个退货商品行。
*
* <p>{@code lineId} 是<b>平台退货行号</b>(沃尔玛 {@code returnOrderLineNumber}),
* 不是统一模型的 {@code afterSaleId()};后者是「退货单号:行号」的拼接。</p>
*/
public static final class Line {
/** 平台退货行号;必填。 */
private final String lineId;
/** 费用明细;不可变,至少一条。 */
private final List<Charge> 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<Charge>(b.charges));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 平台退货行号。 */
public String lineId() {
return lineId;
}
/** 费用明细。 */
public List<Charge> charges() {
return charges;
}
/** 退款行构建器。 */
public static final class Builder {
/** 平台退货行号。 */
private String lineId;
/** 费用明细。 */
private final List<Charge> charges = new ArrayList<Charge>();
/** 设置平台退货行号;必填。 */
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<Charge> charges) {
if (charges != null) {
for (Charge charge : charges) {
charge(charge);
}
}
return this;
}
/** 构建退款行;缺行号或没有费用项时抛 {@link IllegalArgumentException}。 */
public Line build() {
return new Line(this);
}
}
}
/**
* 一条退款费用项。
*
* <p>沃尔玛要求 {@code chargeName}(如 {@code ItemPrice})、
* {@code chargeType}({@code PRODUCT} / {@code FEE} / {@code SHIPPING})与金额三者都给;
* 费用名要与退货详情 {@code chargeTotals[].name} 对得上。</p>
*/
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<Line> lines = new ArrayList<Line>();
/** 设置平台退货单号;必填。 */
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<Line> 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();
}
}

134
channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundResult.java

@ -0,0 +1,134 @@ @@ -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;
/**
* 退款结果。
*
* <p>各平台对退款接口的响应差异很大:有的返回更新后的退货单,有的只返回受理状态,
* 有的什么都不回。所以这里只收敛三样调用方一定关心的东西:
* 哪个退货单、退款是否被受理、平台回传的金额(如果有)。</p>
*
* <p>平台若返回了完整退货单,行级状态放在 {@link #lines()};
* 原值始终可通过 {@link #rawStatus()} 取到,便于排查。</p>
*/
public final class RefundResult {
/** 平台退货单号;非 null。 */
private final String afterSaleId;
/** 平台返回的退款状态原值;平台不回时为 null。 */
private final String rawStatus;
/** 平台回传的退款金额;平台不回或没有币种时为 null(不猜)。 */
private final Money refundedAmount;
/** 行级退款结果;不可变,永不为 null,可能为空。 */
private final List<LineResult> lines;
private RefundResult(Builder b) {
this.afterSaleId = b.afterSaleId;
this.rawStatus = b.rawStatus;
this.refundedAmount = b.refundedAmount;
this.lines = Collections.unmodifiableList(new ArrayList<LineResult>(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<LineResult> 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<LineResult> lines = new ArrayList<LineResult>();
/** 设置平台退货单号。 */
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);
}
}
}

345
channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentCommand.java

@ -0,0 +1,345 @@ @@ -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;
/**
* 标发(订单发货)命令。
*
* <p>一个命令对应<b>一个平台订单</b>。沃尔玛没有批量标发接口,多订单要循环调用;
* 其它平台若支持批量,由适配器自行拆成多次调用,门面层保持「一命令一订单」的语义。</p>
*
* <p>支持部分发货:同一订单行可以分多次提交,每次给本次实发数量。
* 是否允许部分发货由平台决定,适配器在平台拒绝时抛业务异常。</p>
*/
public final class ShipmentCommand {
/** 平台订单号;必填。 */
private final String channelOrderId;
/** 发货行;不可变,至少一行。 */
private final List<Line> 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<Line>(b.lines));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 平台订单号。 */
public String channelOrderId() {
return channelOrderId;
}
/** 发货行;不可变,至少一行。 */
public List<Line> lines() {
return lines;
}
/**
* 幂等业务键:{@code 订单号:行号:数量, 行号:数量...}。
*
* <p>行号排序后拼接,保证同一组行无论顺序如何都得到同一个键。
* <b>不含金额与跟踪号</b>:重发同一批货不该因为换了跟踪号而变成新动作;
* 换了跟踪号属于「修正」,由宿主决定是否先作废原动作。</p>
*/
public String businessRef() {
List<String> parts = new ArrayList<String>(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;
}
/**
* 一条发货行:订单行 + 本次实发数量 + 物流信息。
*
* <p>沃尔玛要求 {@code lineNumber} 必须与订单详情里的一致,否则整单被拒。</p>
*/
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;可空。
*
* <p>部分平台在用非标准承运商时要求它,沃尔玛的官方 schema 未强制。</p>
*/
private final String trackingUrl;
/**
* 卖家自定义订单号;可空,平台有长度限制(沃尔玛 ≤30 字符)。
*
* <p>沃尔玛会把它印在退货面单上,通常填 customerOrderId。</p>
*/
private final String sellerOrderId;
/**
* 客户已申请取消但卖家仍要发货时的确认标记;默认 false。
*
* <p>只有平台明确要求时才有意义(沃尔玛 {@code intentToCancelOverride})。</p>
*/
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<Line> lines = new ArrayList<Line>();
/** 设置平台订单号。 */
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<Line> 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();
}
}

142
channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentResult.java

@ -0,0 +1,142 @@ @@ -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;
/**
* 标发结果。
*
* <p>标发是「一订单一次调用」,所以结果以订单为单位:成功时带平台确认的
* 发货时间与(可能的)新状态;平台只回订单对象时,这里只保留关键字段,
* 完整订单由调用方按需重新查询。</p>
*/
public final class ShipmentResult {
/** 平台订单号;非 null。 */
private final String channelOrderId;
/** 平台确认的发货时间;平台不回时为 null。 */
private final Instant shippedAt;
/** 平台侧记录的跟踪号;平台不回时为 null。 */
private final String trackingNumber;
/** 行级发货记录;不可变,永远不为 null,可能为空(平台只回整体状态时)。 */
private final Map<String, LineShipment> lines;
private ShipmentResult(Builder b) {
this.channelOrderId = b.channelOrderId;
this.shippedAt = b.shippedAt;
this.trackingNumber = b.trackingNumber;
this.lines = Collections.unmodifiableMap(new LinkedHashMap<String, LineShipment>(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<String, LineShipment> lines() {
return lines;
}
/**
* 单行的发货状态。
*
* <p>平台可能只回「部分发货」:同一行的 {@link #quantity()} 是累计已发数量,
* 不是本次实发数量。</p>
*/
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<String, LineShipment> lines = new LinkedHashMap<String, LineShipment>();
/** 设置平台订单号。 */
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);
}
}
}

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

@ -8,8 +8,10 @@ package common.ecommerce.walmart; @@ -8,8 +8,10 @@ package common.ecommerce.walmart;
* 端点由调用方每次经 {@code ChannelConnection} 传入(沙箱还是生产由宿主决定,
* 账户上的 {@code ChannelAccount.sandbox()} 只是元数据)。</p>
*
* <p>来源:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱
* {@code https://sandbox.walmartapis.com} 实测。</p>
* <p>来源:Walmart Developer Portal 官方 reference(2026-11 核对):
* {@code /us-marketplace/reference/} 下的 {@code shippingupdates}、{@code getallorders}、
* {@code getreturns}、{@code getallitems}、{@code itembulkuploads}、{@code getallfeedstatuses}。
* 与《沃尔玛沙箱接口说明》v1.0 冲突时<b>以官方 schema 为准</b>。</p>
*/
public final class WalmartConstants {
@ -48,6 +50,17 @@ 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}})。
*
* <p>⚠ 沙箱实测两条路由都 520(mock 未实现);本期只做常量与 DTO,
* 没有对外方法——沃尔玛的商品写入是 Feed 的载体,等商品写接入时一起开放。</p>
*/
public static final String PATH_FEEDS = "/v3/feeds";
// ---------------------------------------------------------------- 请求头
/** 服务名,固定值。 */
@ -71,27 +84,41 @@ public final class WalmartConstants { @@ -71,27 +84,41 @@ public final class WalmartConstants {
// ---------------------------------------------------------------- 限制
/**
* 商品列表单页上限(官方值,超了本地截断)。
* 商品列表单页上限。
*
* <p>与领星不同,这里是<b>平台硬上限</b>:静默截断是安全的,因为调用方本来
* 就只能拿到这么多,且用 {@code nextCursor} 翻页。</p>
* <p>官方原文:{@code cannot be more than 1000 entities per request},默认 20。
* 注意 {@code nextCursor} 描述里的「more than 200 items」是<b>建议改用游标的阈值</b>,
* 不是 limit 上限——两者容易混。</p>
*/
public static final int MAX_ITEM_PAGE_SIZE = 200;
public static final int MAX_ITEM_PAGE_SIZE = 1000;
/**
* 商品列表 {@code nextCursor} 的初始值。
*
* <p>官方 schema 的 {@code default} 与 {@code example} 都是 {@code *}。
* 不过首页不传也能用平台默认,适配器选择<b>不显式传</b>,避免平台版本差异导致 400。</p>
*/
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,与商品一致)。
* 订单列表单页上限。
*
* <p>文档没给订单的 {@code limit} 上限;这里与商品保持同一策略:超了本地截断,
* 而不是把大值原样发给平台(沙箱 mock 不校验,生产会被拒)。</p>
* <p>官方原文:{@code Cannot be larger than 200.}</p>
*/
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 核实)。
*

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

@ -1,12 +1,16 @@ @@ -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; @@ -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; @@ -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; @@ -75,7 +89,8 @@ import org.slf4j.LoggerFactory;
* 「老单状态变化」需要宿主用 {@link #pullOpenOrders} 单独对账,两者不混在一起,
* 免得 {@code pull} 的语义变得不可预测。</p>
*/
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, @@ -125,7 +140,8 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
@Override
public EnumSet<Capability> 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, @@ -364,15 +380,18 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
* <p>分页特殊:{@code meta.nextCursor} 本身是一段查询串
* (如 {@code "?sellerId=151&limit=10&offset=10"}),翻页时整串拼到 URL 后面。</p>
*
* <p>时间窗只支持按退货单创建时间;{@code PURCHASE_TIME} / {@code UPDATE_TIME}
* 显式报错,不做「拿售后时间顶替」的静默降级。</p>
* <p>时间窗映射:{@link AfterSaleQuery.DateType#AFTER_SALE_TIME} 用
* {@code returnCreationStartDate/EndDate},
* {@link AfterSaleQuery.DateType#UPDATE_TIME} 用
* {@code returnLastModifiedStartDate/EndDate}(官方两套参数都有)。
* {@code PURCHASE_TIME} 没有对应参数,显式报错,不做「拿别的字段顶替」的静默降级。</p>
*/
@Override
public Page<AfterSale> pull(ChannelContext ctx, AfterSaleQuery query) {
ChannelAccount account = ctx.account();
if (query.dateType() != AfterSaleQuery.DateType.AFTER_SALE_TIME) {
throw unsupportedFilter("walmart /v3/returns only filters by return-created date, got "
+ query.dateType());
if (query.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, @@ -391,13 +410,23 @@ public final class WalmartAdapter implements SalesOrderCapable, ProductCapable,
}
Map<String, Object> queryParams = WalmartRequestFactory.query();
queryParams.put("createdStartDate", WALMART_TIME_FORMAT.format(
query.startDate().atStartOfDay(ZoneId.of("UTC")).toInstant()));
queryParams.put("createdEndDate", WALMART_TIME_FORMAT.format(
query.endDate().atStartOfDay(ZoneId.of("UTC")).toInstant()));
// 官方参数名是 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, @@ -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}。
*
* <p>沃尔玛<b>没有批量标发接口</b>,一次一个订单。支持部分发货:同一行可以
* 多次调用,{@code statusQuantity.amount} 累计;剩余数量标完后行状态才变
* {@code Shipped}。</p>
*
* <p>幂等由调用方经 {@code sdk.writes()} 保证,推荐业务键
* {@link ShipmentCommand#businessRef()}:订单号 + 行号 + 数量。</p>
*
* <p>⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。</p>
*
* @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}。
*
* <p>沃尔玛退款细到<b>退货行 × 费用项</b>:每个退货行可只退部分费用
* (商品价 / 运费 / 税)。命令里给什么就退什么,适配器不补全。</p>
*
* <p>业务规则(文档 §5.3):部分售后由平台自动退款,只有
* {@code currentRefundStatus} 需要卖家处理时才需调用;调用前应查详情核对
* {@code refundedQty} / {@code cancellableQty},避免超退。</p>
*
* <p>幂等由调用方经 {@code sdk.writes()} 保证。</p>
*
* <p>⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。</p>
*
* @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}。
*
* <p>沃尔玛的商品写入是<b>异步批量</b>:提交只回一个 {@code feedId},
* 真正的成败要用 {@link #getFeedStatus} 轮询。成功响应是 <b>HTTP 200</b>
* 且 body 带 {@code feedId}(官方 schema 只声明了 200,没有 202)。</p>
*
* <p>商品报文字段原样透传({@code MPItem[]} 每个元素的结构由调用方按
* Walmart《Item Spec》给),本适配器只补报文头。</p>
*
* <p>⚠ 沙箱实测返回 520(mock 未实现),只能在生产环境验证。</p>
*
* @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<String, Object> 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}}。
*
* <p>典型轮询:{@code RECEIVED} → {@code INPROGRESS} → {@code PROCESSED} / {@code ERROR}。
* {@code PROCESSED} 也可能有部分失败,看 {@code itemsFailed()} 与
* {@code items()} 里的逐条 {@code DATA_ERROR}。</p>
*
* @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<String, Object> 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);
}
// ---------------------------------------------------------------- 发货信息(非能力接口)
/**

209
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartFeedDtos.java

@ -0,0 +1,209 @@ @@ -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。
*
* <ul>
* <li>提交:{@code POST /v3/feeds?feedType=MP_ITEM},返回 {@code feedId}</li>
* <li>查询:{@code GET /v3/feeds/{feedId}},返回处理进度与逐商品明细</li>
* </ul>
*
* <p><b>在本模块里的实际用法</b>:商品写入走 {@code POST /v3/feeds}(Bulk Item Setup),
* 该接口在官方 reference 的 {@code itembulkuploads} 里,官方 {@code feedType} 枚举见
* {@link #FEED_TYPES}; 提交成功返回 <b>HTTP 200</b> 且带 {@code feedId},不是 202。</p>
*
* <p>⚠ 沙箱实测两条路由都不可用(提交 520、查询 520),只能在生产环境验证。</p>
*/
public final class WalmartFeedDtos {
/**
* 官方 {@code feedType} 全量枚举({@code reference/itembulkuploads})。
*
* <p>注意《沃尔玛沙箱接口说明》里列的 {@code INVENTORY} / {@code PRICE} /
* {@code PROMO} / {@code LAG_TIME} <b>不在</b>这个接口的枚举里——库存、价格、
* 备货时效各有独立接口。</p>
*/
public static final java.util.Set<String> FEED_TYPES = java.util.Collections.unmodifiableSet(
new java.util.LinkedHashSet<String>(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} 类型)。
*
* <p>字段名与沃尔玛一致;{@code MPItem} 里每个元素的完整结构由
* Walmart《Item Spec》决定,随 {@code productType} 不同而不同,
* 因此这里用 {@code Object} 承载,由调用方给完整报文。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class FeedRequest {
/** 报文头;必填。 */
@JsonProperty("MPItemFeedHeader")
public FeedHeader header;
/** 商品数组;必填。每个元素结构见 Item Spec。 */
@JsonProperty("MPItem")
public List<Object> 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> 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> 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;
}
}

82
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartRefundDtos.java

@ -0,0 +1,82 @@ @@ -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})。
*
* <p>⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。</p>
*
* <p>金额结构是退货接口那一套({@code currencyUnit} + {@code currencyAmount}),
* 与订单接口的 {@code {"currency","amount"}} 不同。</p>
*/
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<RefundLine> 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<RefundCharge> 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;
}
}

194
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentWriteDtos.java

@ -0,0 +1,194 @@ @@ -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})与查询发货信息。
*
* <p>两者<b>同形</b>:{@code orderShipment.orderLines.orderLine[]},
* 每行挂 {@code orderLineStatuses.orderLineStatus[]},发货信息在
* {@code trackingInfo} 里。</p>
*
* <p>⚠ 沙箱实测两条路由都 404(mock 未实现),只能在生产环境验证。</p>
*/
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 {
/**
* 处理模式;可选。
*
* <p>订单<b>已发货后</b>只更新物流信息时传 {@code PARTIAL_UPDATE};
* 首次标发不要传。</p>
*/
@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> orderLine;
}
/**
* 一条发货行。
*
* <p>官方请求体 schema 的 {@code required} 是
* {@code ["lineNumber","orderLineStatuses","sellerOrderId"]}——
* 但该 schema 里 {@code lineNumber} 的描述写成了「待取消的行」,
* 明显是从取消接口复制来的,required 列表的可信度存疑。
* 所以 {@code sellerOrderId} <b>加了字段但不强制</b>:调用方不传时发空串占位,
* 由探针确认平台是否真的拒绝。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderLine {
/** 订单行号;必须与订单详情里的 {@code lineNumber} 一致。 */
@JsonProperty("lineNumber")
public String lineNumber;
/**
* 卖家自定义订单号;官方要求 ≤30 字符,会印在退货面单上。
*
* <p>通常填 {@code customerOrderId}。schema 里标为必填,这里按可选处理,
* 见类注释。</p>
*/
@JsonProperty("sellerOrderId")
public String sellerOrderId;
/**
* 客户已申请取消、但卖家仍然要发货时,必须传 {@code true} 作为确认。
*
* <p>普通标发不要传;官方默认 {@code false}。</p>
*/
@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> 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} 是<b>字符串</b>(与订单接口一致)。 */
@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 {
/**
* 发货时间,<b>epoch 毫秒整数</b>。
*
* <p>官方 schema:{@code "type":"integer","format":"int64"},
* 描述为 {@code Timestamp in UNIX epoch (int64) format},示例 {@code 1580821866000}。
* 注意与订单查询参数(ISO-8601)不同,这个接口收的是毫秒时间戳。</p>
*/
@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;可选。
*
* <p>用非标准承运商({@code otherCarrier})时,第三方 SDK 注释称必须提供,
* 官方 schema 未明确约束。这里按可选处理。</p>
*/
@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;
}
}

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

@ -5,18 +5,38 @@ import common.ecommerce.channel.model.aftersale.AfterSaleType; @@ -5,18 +5,38 @@ import common.ecommerce.channel.model.aftersale.AfterSaleType;
/**
* 沃尔玛退货类型 {@code returnType} → 统一 {@link AfterSaleType}。
*
* <p>沃尔玛只有两种:{@link #RETURN}(退货退款)和 {@link #REPLACEMENT}(换货)。
* 换货在统一模型里叫 {@link AfterSaleType#EXCHANGE}。</p>
* <p>官方 {@code reference/getreturns} 给出的枚举是
* <b>{@code PREORDER} / {@code REPLACEMENT} / {@code REFUND}</b>。</p>
*
* <p>{@code REPLACEMENT} 在统一模型里叫 {@link AfterSaleType#EXCHANGE}(换货)。</p>
*
* <p><b>兼容旧值 {@code RETURN}</b>:早期的《沃尔玛沙箱接口说明》写的是
* {@code RETURN}/{@code REPLACEMENT},历史数据与第三方资料里仍会出现。
* 保留别名并映射到 {@link AfterSaleType#RETURN},避免解析失败——
* 识别不了的元素类型会让下游把它当 {@code UNKNOWN} 丢掉。</p>
*
* <p>注意 {@code REPLACEMENT} 也会出现在 {@code refundMode} 等其它字段的枚举里,
* 这里只用于 {@code returnType}。</p>
*/
public enum WalmartReturnType {
/** 退货(退款)。 */
RETURN("RETURN", AfterSaleType.RETURN),
/**
* 退款型退货(官方值)。
*
* <p>{@code REFUND} 与历史别名 {@code RETURN} 都映射到这里。</p>
*/
REFUND("REFUND", AfterSaleType.RETURN),
/** 历史别名:早期文档写的 {@code RETURN},官方枚举里已改用 {@code REFUND}。 */
RETURN_ALIAS("RETURN", AfterSaleType.RETURN),
/** 换货 / 补发。 */
REPLACEMENT("REPLACEMENT", AfterSaleType.EXCHANGE),
/**
* 预购单退货。
*
* <p>官方只列了这个枚举值,没有说明它和普通退货的差异;统一模型里没有对应语义,
* 先落 {@link AfterSaleType#UNKNOWN} 并保留原值,不猜。</p>
*/
PREORDER("PREORDER", AfterSaleType.UNKNOWN),
/** 无法识别。 */
UNKNOWN(null, AfterSaleType.UNKNOWN);

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

@ -1,6 +1,7 @@ @@ -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 { @@ -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<String, Object> 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<String, Object> query) {
if (query == null || query.isEmpty()) {

105
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartFeedMapper.java

@ -0,0 +1,105 @@ @@ -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:命令 ↔ 沃尔玛报文。
*
* <p>提交报文只有三层:{@code MPItemFeedHeader}(版本 / 语言 / 站点 / 子类目)
* 与 {@code MPItem[]}(每个元素结构见 Item Spec)。商品元素原样透传,
* 不做建模——不同 {@code productType} 的必填字段差异太大。</p>
*/
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<Object>(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<String> parts = new ArrayList<String>();
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<String> 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();
}
}

103
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartRefundMapper.java

@ -0,0 +1,103 @@ @@ -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}。
*
* <p>沃尔玛要求:{@code returnOrderId} 与路径一致、{@code returnOrderLineNumber} 对应
* 退货详情里的行号、每个费用项给 {@code chargeName} + {@code chargeType} + 金额。</p>
*/
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<WalmartRefundDtos.RefundLine>(command.lines().size());
for (RefundCommand.Line line : command.lines()) {
WalmartRefundDtos.RefundLine refundLine = new WalmartRefundDtos.RefundLine();
refundLine.returnOrderLineNumber = parseLineNumber(line.lineId());
refundLine.refundCharges = new ArrayList<WalmartRefundDtos.RefundCharge>(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}。
*
* <p>文档只给出请求体,响应结构未实测。这里做**尽力解析**:
* 若响应是退货单形状(含 {@code returnOrderLines}),取行级退款状态;
* 若是别的形状,只保留状态原值,行级为空。</p>
*
* @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);
}
}
}

203
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentWriteMapper.java

@ -0,0 +1,203 @@ @@ -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}。
*
* <p>沃尔玛的要求(缺一项整单被拒):</p>
* <ul>
* <li>{@code lineNumber} 必须与订单详情里的一致</li>
* <li>{@code status} 固定 {@code Shipped},{@code unitOfMeasurement} 固定 {@code EACH}</li>
* <li>{@code statusQuantity.amount} 是<b>字符串</b></li>
* <li>{@code shipDateTime} 是 <b>epoch 毫秒整数</b>(官方 schema {@code int64}),
* 与订单查询参数的 ISO-8601 不同</li>
* <li>{@code sellerOrderId} 官方标为必填(≤30 字符),这里不强制,未给时不发</li>
* <li>{@code carrier} 与 {@code otherCarrier} 至少填一个</li>
* <li>{@code methodCode} 必须与承运商的方式对照表匹配</li>
* </ul>
*/
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<WalmartShipmentWriteDtos.OrderLine>(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<WalmartShipmentWriteDtos.OrderLineStatus>(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}。
*
* <p>响应可能有两种包裹:{@code {"order": {...}}} 或直接是订单对象;
* 解包由调用方完成,这里只看订单本体。</p>
*
* <p>行上的数量是<b>该状态对应的数量</b>(沃尔玛按状态累计),
* 不是本次实发数量;这里原样传出去,由调用方决定怎么解释。</p>
*
* @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();
}
/**
* 卖家自定义订单号:优先用命令里给的,否则回落到渠道订单号。
*
* <p>超 30 字符时不截断而是返回 null——截断会让面单上的单号对不上,
* 宁可让平台按「未提供」处理。</p>
*/
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;
}
}
}

170
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedCommand.java

@ -0,0 +1,170 @@ @@ -0,0 +1,170 @@
package common.ecommerce.walmart.model;
/**
* 商品 Feed 提交的命令。
*
* <p>沃尔玛的商品写入走异步 Feed:提交后用 {@code feedId} 轮询处理结果。
* 报文结构随 {@code productType} 变化很大,所以这里只承载<b>报文头</b>与
* <b>不透明的商品数组</b>——每个元素的完整结构由调用方按 Walmart《Item Spec》给。</p>
*
* <p>⚠ 沙箱实测提交返回 520(mock 未实现),只能在生产环境验证。</p>
*/
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<Object> 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<Object>(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<Object> 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<Object> items = new java.util.ArrayList<Object>();
/** 设置 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();
}
}

248
channel-sdk-walmart/src/main/java/common/ecommerce/walmart/model/WalmartFeedStatus.java

@ -0,0 +1,248 @@ @@ -0,0 +1,248 @@
package common.ecommerce.walmart.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* Feed 处理状态(适配器扩展查询的返回类型)。
*
* <p>不在统一模型里:Feed 是沃尔玛的商品写入载体(异步批量),
* 其它平台没有同构概念,放进 {@code channel.model} 会让统一模型变形。</p>
*/
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<ItemResult> 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<ItemResult>(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<ItemResult> 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<ItemResult> items = new ArrayList<ItemResult>();
/** 设置批次 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);
}
}
}

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

@ -93,14 +93,18 @@ class WalmartFacadeTest { @@ -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 { @@ -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()));

230
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartFeedTest.java

@ -0,0 +1,230 @@ @@ -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:提交与状态查询。
*
* <p>报文严格按文档 §3.5 / §3.6:
* {@code MPItemFeedHeader.version/locale/businessUnit/subCategory} + {@code MPItem[]};
* 提交回 {@code feedId},状态查询按文档枚举映射。</p>
*/
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<String, Object> itemPayload() {
Map<String, Object> item = new LinkedHashMap<String, Object>();
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);
}
}

304
channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartMarkShippedTest.java

@ -0,0 +1,304 @@ @@ -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();
}
}

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

@ -308,8 +308,9 @@ class WalmartOrderTest { @@ -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());

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

@ -56,10 +56,28 @@ class WalmartProductTest { @@ -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

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

@ -0,0 +1,209 @@ @@ -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 的请求示例。
*
* <p>文档示例:
* {@code {"returnOrderId":"...","refundLines":[{"returnOrderLineNumber":1,
* "refundCharges":[{"chargeName":"ItemPrice","chargeType":"PRODUCT",
* "refundAmount":{"currencyUnit":"USD","currencyAmount":119.95}}]}]}}</p>
*/
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);
}
}

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

@ -47,16 +47,19 @@ class WalmartReturnTest { @@ -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 { @@ -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,

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

@ -122,10 +122,27 @@ class WalmartStatusMappingTest { @@ -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());
}
}

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

@ -244,6 +244,48 @@ class WalmartProbeTest { @@ -244,6 +244,48 @@ class WalmartProbeTest {
});
}
@Test
@Order(8)
void probeMarkShipped() {
requireCredentials();
List<SalesOrder> 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 / 固定条数失败:打印异常后继续跑下一段。 */

155
docs/walmart/README.md

@ -3,7 +3,8 @@ @@ -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( @@ -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 @@ -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 \ @@ -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<ShipmentResult> 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` 取消退货 | 同上 |

Loading…
Cancel
Save