Browse Source
【新增写操作】
- 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>
30 changed files with 3670 additions and 58 deletions
@ -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); |
||||
} |
||||
@ -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); |
||||
} |
||||
@ -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(); |
||||
} |
||||
} |
||||
@ -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); |
||||
} |
||||
} |
||||
} |
||||
@ -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(); |
||||
} |
||||
} |
||||
@ -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); |
||||
} |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
@ -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(); |
||||
} |
||||
} |
||||
@ -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); |
||||
} |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
} |
||||
@ -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(); |
||||
} |
||||
} |
||||
@ -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); |
||||
} |
||||
} |
||||
} |
||||
@ -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); |
||||
} |
||||
} |
||||
@ -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(); |
||||
} |
||||
} |
||||
@ -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); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue