Browse Source

feat(channel-core): 新增标发与退款能力位

统一门面原来只有读能力,补上两个写能力:

- MarkShippedCapable / SalesOrders#markShipped(ShipmentCommand) → ShipmentResult
- RefundCapable / AfterSales#refund(RefundCommand) → RefundResult

未声明对应能力位时门面抛 UnsupportedCapabilityException,不会静默成功;
两个命令模型都按「平台动作」建模,幂等键由调用方经 sdk.writes() 给出。
feature/walmart
lml 16 hours ago
parent
commit
c761af121e
  1. 28
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java
  2. 39
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java
  3. 35
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java
  4. 27
      channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java
  5. 275
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java
  6. 134
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundResult.java
  7. 345
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentCommand.java
  8. 142
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentResult.java

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

@ -6,6 +6,8 @@ import common.ecommerce.shared.model.Capability; @@ -6,6 +6,8 @@ import common.ecommerce.shared.model.Capability;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.model.aftersale.AfterSale;
import common.ecommerce.channel.model.aftersale.AfterSaleQuery;
import common.ecommerce.channel.model.aftersale.RefundCommand;
import common.ecommerce.channel.model.aftersale.RefundResult;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.audit.CallSupport;
import common.ecommerce.channel.sdk.ChannelContext;
@ -72,6 +74,32 @@ public final class AfterSales { @@ -72,6 +74,32 @@ public final class AfterSales {
});
}
/**
* 发起退款(写操作,调用方需包在 {@code sdk.writes()} 里)。
*
* <p>推荐幂等键:{@code action=refund}、
* {@code businessRef=退货单号:行号,行号}(行号排序);不含金额——
* 金额修正不应被当成重复退款。</p>
*
* @throws ChannelException.UnsupportedCapabilityException 未声明 REFUND 或未实现 RefundCapable
*/
public RefundResult refund(final RefundCommand command) {
return CallSupport.observe(observer, ctx, "afterSales.refund",
CallSupport.params(
"afterSaleId", command == null ? null : command.afterSaleId(),
"lineCount", command == null ? 0 : command.lines().size(),
"amount", command == null || command.totalAmount() == null
? null : command.totalAmount().toString()),
result -> 1,
() -> {
if (!adapter.supports(account, Capability.REFUND)
|| !(adapter instanceof RefundCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.REFUND);
}
return ((RefundCapable) adapter).refund(ctx, command);
});
}
/** 能力双检:账户级能力声明 + 接口实现,缺一即拒绝。 */
private void requireAfterSaleCapable() {
if (!adapter.supports(account, Capability.RETURNS) || !(adapter instanceof AfterSaleCapable)) {

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

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

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

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

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

@ -7,6 +7,8 @@ import common.ecommerce.shared.model.Capability; @@ -7,6 +7,8 @@ import common.ecommerce.shared.model.Capability;
import common.ecommerce.channel.model.account.ChannelAccount;
import common.ecommerce.channel.model.fulfillment.OrderEditRequest;
import common.ecommerce.channel.model.fulfillment.OrderEditResult;
import common.ecommerce.channel.model.fulfillment.ShipmentCommand;
import common.ecommerce.channel.model.fulfillment.ShipmentResult;
import common.ecommerce.channel.model.order.SalesOrder;
import common.ecommerce.channel.model.order.SalesOrderQuery;
import common.ecommerce.channel.model.order.SalesOrderRef;
@ -126,6 +128,31 @@ public final class SalesOrders { @@ -126,6 +128,31 @@ public final class SalesOrders {
});
}
/**
* 标发一个订单(写操作,调用方需包在 {@code sdk.writes()} 里)。
*
* <p>推荐幂等键:{@code action=markShipped}、
* {@code businessRef=订单号:行号:数量};同一行分多次部分发货时,
* 数量不同即视为不同业务动作。</p>
*
* @throws ChannelException.UnsupportedCapabilityException 适配器未声明 MARK_SHIPPED 或未实现 MarkShippedCapable
*/
public ShipmentResult markShipped(final ShipmentCommand command) {
return CallSupport.observe(observer, ctx, "salesOrders.markShipped",
CallSupport.params(
"channelOrderId", command == null ? null : command.channelOrderId(),
"lineCount", command == null ? 0 : command.lines().size(),
"quantity", command == null ? 0 : command.totalQuantity()),
result -> 1,
() -> {
if (!adapter.supports(account, Capability.MARK_SHIPPED)
|| !(adapter instanceof MarkShippedCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.MARK_SHIPPED);
}
return ((MarkShippedCapable) adapter).markShipped(ctx, command);
});
}
/** 把批量编辑结果映射成成功 / 部分成功 / 失败摘要。 */
private static CallSupport.ResultSummary editSummary(OrderEditResult result) {
if (result == null) {

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

@ -0,0 +1,275 @@ @@ -0,0 +1,275 @@
package common.ecommerce.channel.model.aftersale;
import common.ecommerce.shared.support.Money;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 退款命令。
*
* <p>按平台退货单发起退款。平台侧的退款通常细到<b>退货行 × 费用项</b>
* (沃尔玛 {@code refundLines[].refundCharges[]}),所以这里不是「退多少钱」,
* 而是逐行逐费用给金额。</p>
*
* <p>调用前应先查售后详情核对 {@code refundedQty} / {@code cancellableQty},
* 避免超退——各平台超额规则不同,适配器只做格式校验,不做余额校验。</p>
*/
public final class RefundCommand {
/** 平台退货单号;必填。 */
private final String afterSaleId;
/** 退款行;不可变,至少一行。 */
private final List<Line> lines;
private RefundCommand(Builder b) {
if (isBlank(b.afterSaleId)) {
throw new IllegalArgumentException("afterSaleId must not be blank");
}
if (b.lines.isEmpty()) {
throw new IllegalArgumentException("refund requires at least one line");
}
this.afterSaleId = b.afterSaleId.trim();
this.lines = Collections.unmodifiableList(new ArrayList<Line>(b.lines));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 平台退货单号。 */
public String afterSaleId() {
return afterSaleId;
}
/** 退款行;不可变,至少一行。 */
public List<Line> lines() {
return lines;
}
/** 退款总额;币种不一致时抛 {@link IllegalArgumentException},为空行返回 null。 */
public Money totalAmount() {
Money total = null;
for (Line line : lines) {
for (Charge charge : line.charges()) {
total = total == null ? charge.amount() : total.add(charge.amount());
}
}
return total;
}
/**
* 一条退款行:对应平台的一个退货商品行。
*
* <p>{@code lineId} 是<b>平台退货行号</b>(沃尔玛 {@code returnOrderLineNumber}),
* 不是统一模型的 {@code afterSaleId()};后者是「退货单号:行号」的拼接。</p>
*/
public static final class Line {
/** 平台退货行号;必填。 */
private final String lineId;
/** 费用明细;不可变,至少一条。 */
private final List<Charge> charges;
private Line(Builder b) {
if (isBlank(b.lineId)) {
throw new IllegalArgumentException("refund lineId must not be blank");
}
if (b.charges.isEmpty()) {
throw new IllegalArgumentException("refund line requires at least one charge");
}
this.lineId = b.lineId.trim();
this.charges = Collections.unmodifiableList(new ArrayList<Charge>(b.charges));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 平台退货行号。 */
public String lineId() {
return lineId;
}
/** 费用明细。 */
public List<Charge> charges() {
return charges;
}
/** 退款行构建器。 */
public static final class Builder {
/** 平台退货行号。 */
private String lineId;
/** 费用明细。 */
private final List<Charge> charges = new ArrayList<Charge>();
/** 设置平台退货行号;必填。 */
public Builder lineId(String lineId) {
this.lineId = lineId;
return this;
}
/** 追加一条费用明细。 */
public Builder charge(Charge charge) {
if (charge != null) {
this.charges.add(charge);
}
return this;
}
/** 批量追加费用明细;null 视为不加。 */
public Builder charges(List<Charge> charges) {
if (charges != null) {
for (Charge charge : charges) {
charge(charge);
}
}
return this;
}
/** 构建退款行;缺行号或没有费用项时抛 {@link IllegalArgumentException}。 */
public Line build() {
return new Line(this);
}
}
}
/**
* 一条退款费用项。
*
* <p>沃尔玛要求 {@code chargeName}(如 {@code ItemPrice})、
* {@code chargeType}({@code PRODUCT} / {@code FEE} / {@code SHIPPING})与金额三者都给;
* 费用名要与退货详情 {@code chargeTotals[].name} 对得上。</p>
*/
public static final class Charge {
/** 费用名称;必填。 */
private final String chargeName;
/** 费用类型;必填。 */
private final String chargeType;
/** 退款金额;必填,不能为负。 */
private final Money amount;
private Charge(Builder b) {
if (isBlank(b.chargeName)) {
throw new IllegalArgumentException("chargeName must not be blank");
}
if (isBlank(b.chargeType)) {
throw new IllegalArgumentException("chargeType must not be blank");
}
if (b.amount == null) {
throw new IllegalArgumentException("refund amount must not be null");
}
if (b.amount.isNegative()) {
throw new IllegalArgumentException("refund amount must not be negative");
}
this.chargeName = b.chargeName.trim();
this.chargeType = b.chargeType.trim();
this.amount = b.amount;
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 费用名称。 */
public String chargeName() {
return chargeName;
}
/** 费用类型。 */
public String chargeType() {
return chargeType;
}
/** 退款金额。 */
public Money amount() {
return amount;
}
/** 费用项构建器。 */
public static final class Builder {
/** 费用名称。 */
private String chargeName;
/** 费用类型。 */
private String chargeType;
/** 退款金额。 */
private Money amount;
/** 设置费用名称;必填。 */
public Builder chargeName(String chargeName) {
this.chargeName = chargeName;
return this;
}
/** 设置费用类型;必填。 */
public Builder chargeType(String chargeType) {
this.chargeType = chargeType;
return this;
}
/** 设置退款金额;必填且不能为负。 */
public Builder amount(Money amount) {
this.amount = amount;
return this;
}
/** 构建费用项;缺字段或金额为负时抛 {@link IllegalArgumentException}。 */
public Charge build() {
return new Charge(this);
}
}
}
/** 退款命令构建器。 */
public static final class Builder {
/** 平台退货单号。 */
private String afterSaleId;
/** 退款行。 */
private final List<Line> lines = new ArrayList<Line>();
/** 设置平台退货单号;必填。 */
public Builder afterSaleId(String afterSaleId) {
this.afterSaleId = afterSaleId;
return this;
}
/** 追加一条退款行。 */
public Builder line(Line line) {
if (line != null) {
this.lines.add(line);
}
return this;
}
/** 批量追加退款行;null 视为不加。 */
public Builder lines(List<Line> lines) {
if (lines != null) {
for (Line line : lines) {
line(line);
}
}
return this;
}
/** 构建命令;缺单号或没有退款行时抛 {@link IllegalArgumentException}。 */
public RefundCommand build() {
return new RefundCommand(this);
}
}
private static boolean isBlank(String value) {
return value == null || value.trim().isEmpty();
}
}

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

@ -0,0 +1,134 @@ @@ -0,0 +1,134 @@
package common.ecommerce.channel.model.aftersale;
import common.ecommerce.shared.support.Money;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 退款结果。
*
* <p>各平台对退款接口的响应差异很大:有的返回更新后的退货单,有的只返回受理状态,
* 有的什么都不回。所以这里只收敛三样调用方一定关心的东西:
* 哪个退货单、退款是否被受理、平台回传的金额(如果有)。</p>
*
* <p>平台若返回了完整退货单,行级状态放在 {@link #lines()};
* 原值始终可通过 {@link #rawStatus()} 取到,便于排查。</p>
*/
public final class RefundResult {
/** 平台退货单号;非 null。 */
private final String afterSaleId;
/** 平台返回的退款状态原值;平台不回时为 null。 */
private final String rawStatus;
/** 平台回传的退款金额;平台不回或没有币种时为 null(不猜)。 */
private final Money refundedAmount;
/** 行级退款结果;不可变,永不为 null,可能为空。 */
private final List<LineResult> lines;
private RefundResult(Builder b) {
this.afterSaleId = b.afterSaleId;
this.rawStatus = b.rawStatus;
this.refundedAmount = b.refundedAmount;
this.lines = Collections.unmodifiableList(new ArrayList<LineResult>(b.lines));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 平台退货单号。 */
public String afterSaleId() {
return afterSaleId;
}
/** 平台返回的退款状态原值;可空。 */
public String rawStatus() {
return rawStatus;
}
/** 平台回传的退款金额;可空。 */
public Money refundedAmount() {
return refundedAmount;
}
/** 行级结果;可能为空。 */
public List<LineResult> lines() {
return lines;
}
/** 单行的退款结果。 */
public static final class LineResult {
/** 平台退货行号。 */
private final String lineId;
/** 平台该行的退款状态原值。 */
private final String status;
/** 构造单行结果;两个字段都可空。 */
public LineResult(String lineId, String status) {
this.lineId = lineId;
this.status = status;
}
/** 平台退货行号。 */
public String lineId() {
return lineId;
}
/** 平台退款状态原值。 */
public String status() {
return status;
}
}
/** 退款结果构建器。 */
public static final class Builder {
/** 平台退货单号。 */
private String afterSaleId;
/** 平台状态原值。 */
private String rawStatus;
/** 平台回传金额。 */
private Money refundedAmount;
/** 行级结果。 */
private final List<LineResult> lines = new ArrayList<LineResult>();
/** 设置平台退货单号。 */
public Builder afterSaleId(String afterSaleId) {
this.afterSaleId = afterSaleId;
return this;
}
/** 设置平台状态原值。 */
public Builder rawStatus(String rawStatus) {
this.rawStatus = rawStatus;
return this;
}
/** 设置平台回传的退款金额。 */
public Builder refundedAmount(Money refundedAmount) {
this.refundedAmount = refundedAmount;
return this;
}
/** 追加一条行级结果。 */
public Builder line(LineResult line) {
if (line != null) {
this.lines.add(line);
}
return this;
}
/** 构建结果。 */
public RefundResult build() {
return new RefundResult(this);
}
}
}

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

@ -0,0 +1,345 @@ @@ -0,0 +1,345 @@
package common.ecommerce.channel.model.fulfillment;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 标发(订单发货)命令。
*
* <p>一个命令对应<b>一个平台订单</b>。沃尔玛没有批量标发接口,多订单要循环调用;
* 其它平台若支持批量,由适配器自行拆成多次调用,门面层保持「一命令一订单」的语义。</p>
*
* <p>支持部分发货:同一订单行可以分多次提交,每次给本次实发数量。
* 是否允许部分发货由平台决定,适配器在平台拒绝时抛业务异常。</p>
*/
public final class ShipmentCommand {
/** 平台订单号;必填。 */
private final String channelOrderId;
/** 发货行;不可变,至少一行。 */
private final List<Line> lines;
private ShipmentCommand(Builder b) {
if (b.channelOrderId == null || b.channelOrderId.trim().isEmpty()) {
throw new IllegalArgumentException("channelOrderId must not be blank");
}
if (b.lines.isEmpty()) {
throw new IllegalArgumentException("shipment requires at least one line");
}
this.channelOrderId = b.channelOrderId.trim();
this.lines = Collections.unmodifiableList(new ArrayList<Line>(b.lines));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 平台订单号。 */
public String channelOrderId() {
return channelOrderId;
}
/** 发货行;不可变,至少一行。 */
public List<Line> lines() {
return lines;
}
/**
* 幂等业务键:{@code 订单号:行号:数量, 行号:数量...}。
*
* <p>行号排序后拼接,保证同一组行无论顺序如何都得到同一个键。
* <b>不含金额与跟踪号</b>:重发同一批货不该因为换了跟踪号而变成新动作;
* 换了跟踪号属于「修正」,由宿主决定是否先作废原动作。</p>
*/
public String businessRef() {
List<String> parts = new ArrayList<String>(lines.size());
for (Line line : lines) {
parts.add(line.lineNumber() + ":" + line.quantity());
}
java.util.Collections.sort(parts);
StringBuilder sb = new StringBuilder(channelOrderId).append('|');
for (int i = 0; i < parts.size(); i++) {
if (i > 0) {
sb.append(',');
}
sb.append(parts.get(i));
}
return sb.toString();
}
/** 本次发货的总件数,便于埋点与幂等键构造。 */
public int totalQuantity() {
int total = 0;
for (Line line : lines) {
total += line.quantity();
}
return total;
}
/**
* 一条发货行:订单行 + 本次实发数量 + 物流信息。
*
* <p>沃尔玛要求 {@code lineNumber} 必须与订单详情里的一致,否则整单被拒。</p>
*/
public static final class Line {
/** 平台订单行号;必填。 */
private final String lineNumber;
/** 本次实发数量;必须大于 0。 */
private final int quantity;
/** 承运商编码,如 {@code UPS} / {@code FedEx};与 {@link #carrierName} 二选一。 */
private final String carrier;
/** 非标准承运商名称;与 {@link #carrier} 二选一。 */
private final String carrierName;
/** 运输方式编码;平台要求与承运商匹配(如沃尔玛的 {@code Standard})。 */
private final String methodCode;
/** 物流跟踪号;必填。 */
private final String trackingNumber;
/**
* 承运商跟踪页 URL;可空。
*
* <p>部分平台在用非标准承运商时要求它,沃尔玛的官方 schema 未强制。</p>
*/
private final String trackingUrl;
/**
* 卖家自定义订单号;可空,平台有长度限制(沃尔玛 ≤30 字符)。
*
* <p>沃尔玛会把它印在退货面单上,通常填 customerOrderId。</p>
*/
private final String sellerOrderId;
/**
* 客户已申请取消但卖家仍要发货时的确认标记;默认 false。
*
* <p>只有平台明确要求时才有意义(沃尔玛 {@code intentToCancelOverride})。</p>
*/
private final boolean intentToCancelOverride;
/** 发货时间;null 表示由适配器取当前时钟。 */
private final Instant shippedAt;
private Line(Builder b) {
if (b.lineNumber == null || b.lineNumber.trim().isEmpty()) {
throw new IllegalArgumentException("lineNumber must not be blank");
}
if (b.quantity <= 0) {
throw new IllegalArgumentException("quantity must be positive");
}
if (b.trackingNumber == null || b.trackingNumber.trim().isEmpty()) {
throw new IllegalArgumentException("trackingNumber must not be blank");
}
if (isBlank(b.carrier) && isBlank(b.carrierName)) {
throw new IllegalArgumentException("carrier or carrierName is required");
}
this.lineNumber = b.lineNumber.trim();
this.quantity = b.quantity;
this.carrier = b.carrier;
this.carrierName = b.carrierName;
this.methodCode = b.methodCode;
this.trackingNumber = b.trackingNumber.trim();
this.trackingUrl = b.trackingUrl;
this.sellerOrderId = b.sellerOrderId;
this.intentToCancelOverride = b.intentToCancelOverride;
this.shippedAt = b.shippedAt;
}
/** 平台订单行号。 */
public String lineNumber() {
return lineNumber;
}
/** 本次实发数量。 */
public int quantity() {
return quantity;
}
/** 标准承运商编码;可空。 */
public String carrier() {
return carrier;
}
/** 非标准承运商名称;可空。 */
public String carrierName() {
return carrierName;
}
/** 运输方式编码;可空。 */
public String methodCode() {
return methodCode;
}
/** 物流跟踪号。 */
public String trackingNumber() {
return trackingNumber;
}
/** 承运商跟踪页 URL;可空。 */
public String trackingUrl() {
return trackingUrl;
}
/** 卖家自定义订单号;可空。 */
public String sellerOrderId() {
return sellerOrderId;
}
/** 客户已申请取消仍要发货时的确认标记。 */
public boolean intentToCancelOverride() {
return intentToCancelOverride;
}
/** 发货时间;null 表示由适配器取当前时钟。 */
public Instant shippedAt() {
return shippedAt;
}
/** 新建发货行构建器。 */
public static Builder builder() {
return new Builder();
}
/** 发货行构建器。 */
public static final class Builder {
/** 平台订单行号;必填。 */
private String lineNumber;
/** 本次实发数量。 */
private int quantity;
/** 标准承运商编码。 */
private String carrier;
/** 非标准承运商名称。 */
private String carrierName;
/** 运输方式编码。 */
private String methodCode;
/** 物流跟踪号。 */
private String trackingNumber;
/** 承运商跟踪页 URL;可空。 */
private String trackingUrl;
/** 卖家自定义订单号;可空。 */
private String sellerOrderId;
/** 客户已申请取消仍要发货时的确认标记;默认 false。 */
private boolean intentToCancelOverride;
/** 发货时间;null 由适配器取当前时钟。 */
private Instant shippedAt;
/** 设置行号;必填。 */
public Builder lineNumber(String lineNumber) {
this.lineNumber = lineNumber;
return this;
}
/** 设置本次实发数量;必须大于 0。 */
public Builder quantity(int quantity) {
this.quantity = quantity;
return this;
}
/** 设置标准承运商编码。 */
public Builder carrier(String carrier) {
this.carrier = carrier;
return this;
}
/** 设置非标准承运商名称。 */
public Builder carrierName(String carrierName) {
this.carrierName = carrierName;
return this;
}
/** 设置运输方式编码。 */
public Builder methodCode(String methodCode) {
this.methodCode = methodCode;
return this;
}
/** 设置物流跟踪号;必填。 */
public Builder trackingNumber(String trackingNumber) {
this.trackingNumber = trackingNumber;
return this;
}
/** 设置承运商跟踪页 URL;可空。 */
public Builder trackingUrl(String trackingUrl) {
this.trackingUrl = trackingUrl;
return this;
}
/** 设置卖家自定义订单号;可空,平台长度上限见各适配器。 */
public Builder sellerOrderId(String sellerOrderId) {
this.sellerOrderId = sellerOrderId;
return this;
}
/** 设置「客户已申请取消但仍要发货」的确认标记。 */
public Builder intentToCancelOverride(boolean intentToCancelOverride) {
this.intentToCancelOverride = intentToCancelOverride;
return this;
}
/** 设置发货时间;不设置时由适配器取当前时钟。 */
public Builder shippedAt(Instant shippedAt) {
this.shippedAt = shippedAt;
return this;
}
/** 构建发货行;缺必填字段时抛 {@link IllegalArgumentException}。 */
public Line build() {
return new Line(this);
}
}
}
/** 发货命令构建器。 */
public static final class Builder {
/** 平台订单号;必填。 */
private String channelOrderId;
/** 发货行。 */
private final List<Line> lines = new ArrayList<Line>();
/** 设置平台订单号。 */
public Builder channelOrderId(String channelOrderId) {
this.channelOrderId = channelOrderId;
return this;
}
/** 追加一条发货行。 */
public Builder line(Line line) {
if (line != null) {
this.lines.add(line);
}
return this;
}
/** 批量追加发货行;null 视为不加。 */
public Builder lines(List<Line> lines) {
if (lines != null) {
for (Line line : lines) {
line(line);
}
}
return this;
}
/** 构建命令;订单号为空或没有发货行时抛 {@link IllegalArgumentException}。 */
public ShipmentCommand build() {
return new ShipmentCommand(this);
}
}
private static boolean isBlank(String value) {
return value == null || value.trim().isEmpty();
}
}

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

@ -0,0 +1,142 @@ @@ -0,0 +1,142 @@
package common.ecommerce.channel.model.fulfillment;
import java.time.Instant;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* 标发结果。
*
* <p>标发是「一订单一次调用」,所以结果以订单为单位:成功时带平台确认的
* 发货时间与(可能的)新状态;平台只回订单对象时,这里只保留关键字段,
* 完整订单由调用方按需重新查询。</p>
*/
public final class ShipmentResult {
/** 平台订单号;非 null。 */
private final String channelOrderId;
/** 平台确认的发货时间;平台不回时为 null。 */
private final Instant shippedAt;
/** 平台侧记录的跟踪号;平台不回时为 null。 */
private final String trackingNumber;
/** 行级发货记录;不可变,永远不为 null,可能为空(平台只回整体状态时)。 */
private final Map<String, LineShipment> lines;
private ShipmentResult(Builder b) {
this.channelOrderId = b.channelOrderId;
this.shippedAt = b.shippedAt;
this.trackingNumber = b.trackingNumber;
this.lines = Collections.unmodifiableMap(new LinkedHashMap<String, LineShipment>(b.lines));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 平台订单号。 */
public String channelOrderId() {
return channelOrderId;
}
/** 平台确认的发货时间;可空。 */
public Instant shippedAt() {
return shippedAt;
}
/** 平台记录的跟踪号;可空。 */
public String trackingNumber() {
return trackingNumber;
}
/** 行级发货记录,键为平台订单行号;可能为空 Map。 */
public Map<String, LineShipment> lines() {
return lines;
}
/**
* 单行的发货状态。
*
* <p>平台可能只回「部分发货」:同一行的 {@link #quantity()} 是累计已发数量,
* 不是本次实发数量。</p>
*/
public static final class LineShipment {
/** 平台订单行号。 */
private final String lineNumber;
/** 平台侧该行累计已发数量。 */
private final int quantity;
/** 行状态原值,如 {@code Shipped}、{@code Created}。 */
private final String status;
/** 构造单行发货状态。 */
public LineShipment(String lineNumber, int quantity, String status) {
this.lineNumber = lineNumber;
this.quantity = quantity;
this.status = status;
}
/** 平台订单行号。 */
public String lineNumber() {
return lineNumber;
}
/** 该行累计已发数量。 */
public int quantity() {
return quantity;
}
/** 行状态原值。 */
public String status() {
return status;
}
}
/** 标发结果构建器。 */
public static final class Builder {
/** 平台订单号。 */
private String channelOrderId;
/** 平台确认的发货时间。 */
private Instant shippedAt;
/** 跟踪号。 */
private String trackingNumber;
/** 行级记录。 */
private final Map<String, LineShipment> lines = new LinkedHashMap<String, LineShipment>();
/** 设置平台订单号。 */
public Builder channelOrderId(String channelOrderId) {
this.channelOrderId = channelOrderId;
return this;
}
/** 设置平台确认的发货时间。 */
public Builder shippedAt(Instant shippedAt) {
this.shippedAt = shippedAt;
return this;
}
/** 设置平台记录的跟踪号。 */
public Builder trackingNumber(String trackingNumber) {
this.trackingNumber = trackingNumber;
return this;
}
/** 追加一条行级记录。 */
public Builder line(LineShipment line) {
if (line != null && line.lineNumber() != null) {
this.lines.put(line.lineNumber(), line);
}
return this;
}
/** 构建结果。 */
public ShipmentResult build() {
return new ShipmentResult(this);
}
}
}
Loading…
Cancel
Save