Browse Source
统一门面原来只有读能力,补上两个写能力: - MarkShippedCapable / SalesOrders#markShipped(ShipmentCommand) → ShipmentResult - RefundCapable / AfterSales#refund(RefundCommand) → RefundResult 未声明对应能力位时门面抛 UnsupportedCapabilityException,不会静默成功; 两个命令模型都按「平台动作」建模,幂等键由调用方经 sdk.writes() 给出。feature/walmart
8 changed files with 1025 additions and 0 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); |
||||
} |
||||
} |
||||
} |
||||
Loading…
Reference in new issue