From c761af121efc0fd436507313a64036142389a84f Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Fri, 20 Nov 2026 11:26:46 +0800 Subject: [PATCH] =?UTF-8?q?feat(channel-core):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E6=A0=87=E5=8F=91=E4=B8=8E=E9=80=80=E6=AC=BE=E8=83=BD=E5=8A=9B?= =?UTF-8?q?=E4=BD=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 统一门面原来只有读能力,补上两个写能力: - MarkShippedCapable / SalesOrders#markShipped(ShipmentCommand) → ShipmentResult - RefundCapable / AfterSales#refund(RefundCommand) → RefundResult 未声明对应能力位时门面抛 UnsupportedCapabilityException,不会静默成功; 两个命令模型都按「平台动作」建模,幂等键由调用方经 sdk.writes() 给出。 --- .../ecommerce/channel/capability/AfterSales.java | 28 ++ .../channel/capability/MarkShippedCapable.java | 39 +++ .../channel/capability/RefundCapable.java | 35 +++ .../ecommerce/channel/capability/SalesOrders.java | 27 ++ .../channel/model/aftersale/RefundCommand.java | 275 ++++++++++++++++ .../channel/model/aftersale/RefundResult.java | 134 ++++++++ .../channel/model/fulfillment/ShipmentCommand.java | 345 +++++++++++++++++++++ .../channel/model/fulfillment/ShipmentResult.java | 142 +++++++++ 8 files changed, 1025 insertions(+) create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundResult.java create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentCommand.java create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/fulfillment/ShipmentResult.java diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java index 6a1a634..83c2a72 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/AfterSales.java @@ -6,6 +6,8 @@ import common.ecommerce.shared.model.Capability; import common.ecommerce.channel.model.account.ChannelAccount; import common.ecommerce.channel.model.aftersale.AfterSale; import common.ecommerce.channel.model.aftersale.AfterSaleQuery; +import common.ecommerce.channel.model.aftersale.RefundCommand; +import common.ecommerce.channel.model.aftersale.RefundResult; import common.ecommerce.shared.support.Page; import common.ecommerce.shared.audit.CallSupport; import common.ecommerce.channel.sdk.ChannelContext; @@ -72,6 +74,32 @@ public final class AfterSales { }); } + /** + * 发起退款(写操作,调用方需包在 {@code sdk.writes()} 里)。 + * + *
推荐幂等键:{@code action=refund}、 + * {@code businessRef=退货单号:行号,行号}(行号排序);不含金额—— + * 金额修正不应被当成重复退款。
+ * + * @throws ChannelException.UnsupportedCapabilityException 未声明 REFUND 或未实现 RefundCapable + */ + public RefundResult refund(final RefundCommand command) { + return CallSupport.observe(observer, ctx, "afterSales.refund", + CallSupport.params( + "afterSaleId", command == null ? null : command.afterSaleId(), + "lineCount", command == null ? 0 : command.lines().size(), + "amount", command == null || command.totalAmount() == null + ? null : command.totalAmount().toString()), + result -> 1, + () -> { + if (!adapter.supports(account, Capability.REFUND) + || !(adapter instanceof RefundCapable)) { + throw new ChannelException.UnsupportedCapabilityException(Capability.REFUND); + } + return ((RefundCapable) adapter).refund(ctx, command); + }); + } + /** 能力双检:账户级能力声明 + 接口实现,缺一即拒绝。 */ private void requireAfterSaleCapable() { if (!adapter.supports(account, Capability.RETURNS) || !(adapter instanceof AfterSaleCapable)) { diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java new file mode 100644 index 0000000..6b45e50 --- /dev/null +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/MarkShippedCapable.java @@ -0,0 +1,39 @@ +package common.ecommerce.channel.capability; + +import common.ecommerce.channel.model.fulfillment.ShipmentCommand; +import common.ecommerce.channel.model.fulfillment.ShipmentResult; +import common.ecommerce.channel.sdk.ChannelContext; + +/** + * 3P 标发能力:把订单行标记为已发货并回传物流信息。 + * + *这是一次真实的外部动作(买家会看到物流),写操作,必须经 + * {@code IdempotencyGuard} 执行。推荐幂等键: + * {@code action=markShipped}、{@code businessRef=订单号:行号:数量} + * ——不带金额,金额变化不应产生新的业务动作。
+ * + *与 {@link OutboundCapable} 的区别:快速出库是「提交出库任务、异步回查结果」; + * 标发是同步确认订单行的发货状态,一次调用对应一个平台订单。
+ * + *支持部分发货的平台(如沃尔玛),同一行可以分多次调用, + * 每次只给本次实发数量;不支持部分发货的平台在数量不一致时应抛业务异常, + * 不能静默按整行发货。
+ * + *能力位 {@link common.ecommerce.shared.model.Capability#MARK_SHIPPED}。
+ */ +public interface MarkShippedCapable extends PlatformAdapter { + + /** + * 标发一个订单。 + * + *平台按订单返回结果;部分发货时结果里的行数量是累计已发数量。 + * 订单状态已不允许发货(如已取消)时应抛 + * {@link common.ecommerce.shared.error.PlatformBusinessException}, + * 不要返回一个「看起来成功」的空结果。
+ * + * @param ctx 调用上下文 + * @param command 发货命令,一个命令对应一个平台订单 + * @return 平台确认后的发货结果 + */ + ShipmentResult markShipped(ChannelContext ctx, ShipmentCommand command); +} diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java new file mode 100644 index 0000000..75ad922 --- /dev/null +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/RefundCapable.java @@ -0,0 +1,35 @@ +package common.ecommerce.channel.capability; + +import common.ecommerce.channel.model.aftersale.RefundCommand; +import common.ecommerce.channel.model.aftersale.RefundResult; +import common.ecommerce.channel.sdk.ChannelContext; + +/** + * 退款能力:按平台退货单发起退款。 + * + *写操作,涉及资金,必须经 {@code IdempotencyGuard} 执行。 + * 推荐幂等键:{@code action=refund}、 + * {@code businessRef=退货单号:行号,行号}——不带金额与费用项; + * 金额修正属于另一个动作,不应被当成「新的退款」重复执行。
+ * + *能力位 {@link Capability#REFUND},与只读的 {@link AfterSaleCapable} 分开声明: + * 有些平台只能查售后、不能发起退款。
+ * + *调用前应先查售后详情核对可退数量 / 可退金额,避免超退。 + * 适配器只做报文校验,余额校验由平台负责。
+ */ +public interface RefundCapable extends PlatformAdapter { + + /** + * 发起一次退款。 + * + *部分平台退货单里含多行,可以只退其中几行或几项费用; + * 命令里给什么就退什么,适配器不做补全。
+ * + * @param ctx 调用上下文 + * @param command 退款命令 + * @return 平台确认结果 + * @throws common.ecommerce.shared.error.PlatformBusinessException 平台拒绝(如已退过、超过可退金额) + */ + RefundResult refund(ChannelContext ctx, RefundCommand command); +} diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java index e770aca..47df885 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/capability/SalesOrders.java @@ -7,6 +7,8 @@ import common.ecommerce.shared.model.Capability; import common.ecommerce.channel.model.account.ChannelAccount; import common.ecommerce.channel.model.fulfillment.OrderEditRequest; import common.ecommerce.channel.model.fulfillment.OrderEditResult; +import common.ecommerce.channel.model.fulfillment.ShipmentCommand; +import common.ecommerce.channel.model.fulfillment.ShipmentResult; import common.ecommerce.channel.model.order.SalesOrder; import common.ecommerce.channel.model.order.SalesOrderQuery; import common.ecommerce.channel.model.order.SalesOrderRef; @@ -126,6 +128,31 @@ public final class SalesOrders { }); } + /** + * 标发一个订单(写操作,调用方需包在 {@code sdk.writes()} 里)。 + * + *推荐幂等键:{@code action=markShipped}、 + * {@code businessRef=订单号:行号:数量};同一行分多次部分发货时, + * 数量不同即视为不同业务动作。
+ * + * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 MARK_SHIPPED 或未实现 MarkShippedCapable + */ + public ShipmentResult markShipped(final ShipmentCommand command) { + return CallSupport.observe(observer, ctx, "salesOrders.markShipped", + CallSupport.params( + "channelOrderId", command == null ? null : command.channelOrderId(), + "lineCount", command == null ? 0 : command.lines().size(), + "quantity", command == null ? 0 : command.totalQuantity()), + result -> 1, + () -> { + if (!adapter.supports(account, Capability.MARK_SHIPPED) + || !(adapter instanceof MarkShippedCapable)) { + throw new ChannelException.UnsupportedCapabilityException(Capability.MARK_SHIPPED); + } + return ((MarkShippedCapable) adapter).markShipped(ctx, command); + }); + } + /** 把批量编辑结果映射成成功 / 部分成功 / 失败摘要。 */ private static CallSupport.ResultSummary editSummary(OrderEditResult result) { if (result == null) { diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java new file mode 100644 index 0000000..d4813e2 --- /dev/null +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/aftersale/RefundCommand.java @@ -0,0 +1,275 @@ +package common.ecommerce.channel.model.aftersale; + +import common.ecommerce.shared.support.Money; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 退款命令。 + * + *按平台退货单发起退款。平台侧的退款通常细到退货行 × 费用项 + * (沃尔玛 {@code refundLines[].refundCharges[]}),所以这里不是「退多少钱」, + * 而是逐行逐费用给金额。
+ * + *调用前应先查售后详情核对 {@code refundedQty} / {@code cancellableQty}, + * 避免超退——各平台超额规则不同,适配器只做格式校验,不做余额校验。
+ */ +public final class RefundCommand { + + /** 平台退货单号;必填。 */ + private final String afterSaleId; + + /** 退款行;不可变,至少一行。 */ + private final List{@code lineId} 是平台退货行号(沃尔玛 {@code returnOrderLineNumber}), + * 不是统一模型的 {@code afterSaleId()};后者是「退货单号:行号」的拼接。
+ */ + public static final class Line { + + /** 平台退货行号;必填。 */ + private final String lineId; + + /** 费用明细;不可变,至少一条。 */ + private final List沃尔玛要求 {@code chargeName}(如 {@code ItemPrice})、 + * {@code chargeType}({@code PRODUCT} / {@code FEE} / {@code SHIPPING})与金额三者都给; + * 费用名要与退货详情 {@code chargeTotals[].name} 对得上。
+ */ + public static final class Charge { + + /** 费用名称;必填。 */ + private final String chargeName; + + /** 费用类型;必填。 */ + private final String chargeType; + + /** 退款金额;必填,不能为负。 */ + private final Money amount; + + private Charge(Builder b) { + if (isBlank(b.chargeName)) { + throw new IllegalArgumentException("chargeName must not be blank"); + } + if (isBlank(b.chargeType)) { + throw new IllegalArgumentException("chargeType must not be blank"); + } + if (b.amount == null) { + throw new IllegalArgumentException("refund amount must not be null"); + } + if (b.amount.isNegative()) { + throw new IllegalArgumentException("refund amount must not be negative"); + } + this.chargeName = b.chargeName.trim(); + this.chargeType = b.chargeType.trim(); + this.amount = b.amount; + } + + /** 新建构建器。 */ + public static Builder builder() { + return new Builder(); + } + + /** 费用名称。 */ + public String chargeName() { + return chargeName; + } + + /** 费用类型。 */ + public String chargeType() { + return chargeType; + } + + /** 退款金额。 */ + public Money amount() { + return amount; + } + + /** 费用项构建器。 */ + public static final class Builder { + + /** 费用名称。 */ + private String chargeName; + /** 费用类型。 */ + private String chargeType; + /** 退款金额。 */ + private Money amount; + + /** 设置费用名称;必填。 */ + public Builder chargeName(String chargeName) { + this.chargeName = chargeName; + return this; + } + + /** 设置费用类型;必填。 */ + public Builder chargeType(String chargeType) { + this.chargeType = chargeType; + return this; + } + + /** 设置退款金额;必填且不能为负。 */ + public Builder amount(Money amount) { + this.amount = amount; + return this; + } + + /** 构建费用项;缺字段或金额为负时抛 {@link IllegalArgumentException}。 */ + public Charge build() { + return new Charge(this); + } + } + } + + /** 退款命令构建器。 */ + public static final class Builder { + + /** 平台退货单号。 */ + private String afterSaleId; + /** 退款行。 */ + private final List各平台对退款接口的响应差异很大:有的返回更新后的退货单,有的只返回受理状态, + * 有的什么都不回。所以这里只收敛三样调用方一定关心的东西: + * 哪个退货单、退款是否被受理、平台回传的金额(如果有)。
+ * + *平台若返回了完整退货单,行级状态放在 {@link #lines()}; + * 原值始终可通过 {@link #rawStatus()} 取到,便于排查。
+ */ +public final class RefundResult { + + /** 平台退货单号;非 null。 */ + private final String afterSaleId; + + /** 平台返回的退款状态原值;平台不回时为 null。 */ + private final String rawStatus; + + /** 平台回传的退款金额;平台不回或没有币种时为 null(不猜)。 */ + private final Money refundedAmount; + + /** 行级退款结果;不可变,永不为 null,可能为空。 */ + private final List一个命令对应一个平台订单。沃尔玛没有批量标发接口,多订单要循环调用; + * 其它平台若支持批量,由适配器自行拆成多次调用,门面层保持「一命令一订单」的语义。
+ * + *支持部分发货:同一订单行可以分多次提交,每次给本次实发数量。 + * 是否允许部分发货由平台决定,适配器在平台拒绝时抛业务异常。
+ */ +public final class ShipmentCommand { + + /** 平台订单号;必填。 */ + private final String channelOrderId; + + /** 发货行;不可变,至少一行。 */ + private final List行号排序后拼接,保证同一组行无论顺序如何都得到同一个键。 + * 不含金额与跟踪号:重发同一批货不该因为换了跟踪号而变成新动作; + * 换了跟踪号属于「修正」,由宿主决定是否先作废原动作。
+ */ + public String businessRef() { + List沃尔玛要求 {@code lineNumber} 必须与订单详情里的一致,否则整单被拒。
+ */ + public static final class Line { + + /** 平台订单行号;必填。 */ + private final String lineNumber; + + /** 本次实发数量;必须大于 0。 */ + private final int quantity; + + /** 承运商编码,如 {@code UPS} / {@code FedEx};与 {@link #carrierName} 二选一。 */ + private final String carrier; + + /** 非标准承运商名称;与 {@link #carrier} 二选一。 */ + private final String carrierName; + + /** 运输方式编码;平台要求与承运商匹配(如沃尔玛的 {@code Standard})。 */ + private final String methodCode; + + /** 物流跟踪号;必填。 */ + private final String trackingNumber; + + /** + * 承运商跟踪页 URL;可空。 + * + *部分平台在用非标准承运商时要求它,沃尔玛的官方 schema 未强制。
+ */ + private final String trackingUrl; + + /** + * 卖家自定义订单号;可空,平台有长度限制(沃尔玛 ≤30 字符)。 + * + *沃尔玛会把它印在退货面单上,通常填 customerOrderId。
+ */ + private final String sellerOrderId; + + /** + * 客户已申请取消但卖家仍要发货时的确认标记;默认 false。 + * + *只有平台明确要求时才有意义(沃尔玛 {@code intentToCancelOverride})。
+ */ + private final boolean intentToCancelOverride; + + /** 发货时间;null 表示由适配器取当前时钟。 */ + private final Instant shippedAt; + + private Line(Builder b) { + if (b.lineNumber == null || b.lineNumber.trim().isEmpty()) { + throw new IllegalArgumentException("lineNumber must not be blank"); + } + if (b.quantity <= 0) { + throw new IllegalArgumentException("quantity must be positive"); + } + if (b.trackingNumber == null || b.trackingNumber.trim().isEmpty()) { + throw new IllegalArgumentException("trackingNumber must not be blank"); + } + if (isBlank(b.carrier) && isBlank(b.carrierName)) { + throw new IllegalArgumentException("carrier or carrierName is required"); + } + this.lineNumber = b.lineNumber.trim(); + this.quantity = b.quantity; + this.carrier = b.carrier; + this.carrierName = b.carrierName; + this.methodCode = b.methodCode; + this.trackingNumber = b.trackingNumber.trim(); + this.trackingUrl = b.trackingUrl; + this.sellerOrderId = b.sellerOrderId; + this.intentToCancelOverride = b.intentToCancelOverride; + this.shippedAt = b.shippedAt; + } + + /** 平台订单行号。 */ + public String lineNumber() { + return lineNumber; + } + + /** 本次实发数量。 */ + public int quantity() { + return quantity; + } + + /** 标准承运商编码;可空。 */ + public String carrier() { + return carrier; + } + + /** 非标准承运商名称;可空。 */ + public String carrierName() { + return carrierName; + } + + /** 运输方式编码;可空。 */ + public String methodCode() { + return methodCode; + } + + /** 物流跟踪号。 */ + public String trackingNumber() { + return trackingNumber; + } + + /** 承运商跟踪页 URL;可空。 */ + public String trackingUrl() { + return trackingUrl; + } + + /** 卖家自定义订单号;可空。 */ + public String sellerOrderId() { + return sellerOrderId; + } + + /** 客户已申请取消仍要发货时的确认标记。 */ + public boolean intentToCancelOverride() { + return intentToCancelOverride; + } + + /** 发货时间;null 表示由适配器取当前时钟。 */ + public Instant shippedAt() { + return shippedAt; + } + + /** 新建发货行构建器。 */ + public static Builder builder() { + return new Builder(); + } + + /** 发货行构建器。 */ + public static final class Builder { + + /** 平台订单行号;必填。 */ + private String lineNumber; + /** 本次实发数量。 */ + private int quantity; + /** 标准承运商编码。 */ + private String carrier; + /** 非标准承运商名称。 */ + private String carrierName; + /** 运输方式编码。 */ + private String methodCode; + /** 物流跟踪号。 */ + private String trackingNumber; + /** 承运商跟踪页 URL;可空。 */ + private String trackingUrl; + /** 卖家自定义订单号;可空。 */ + private String sellerOrderId; + /** 客户已申请取消仍要发货时的确认标记;默认 false。 */ + private boolean intentToCancelOverride; + /** 发货时间;null 由适配器取当前时钟。 */ + private Instant shippedAt; + + /** 设置行号;必填。 */ + public Builder lineNumber(String lineNumber) { + this.lineNumber = lineNumber; + return this; + } + + /** 设置本次实发数量;必须大于 0。 */ + public Builder quantity(int quantity) { + this.quantity = quantity; + return this; + } + + /** 设置标准承运商编码。 */ + public Builder carrier(String carrier) { + this.carrier = carrier; + return this; + } + + /** 设置非标准承运商名称。 */ + public Builder carrierName(String carrierName) { + this.carrierName = carrierName; + return this; + } + + /** 设置运输方式编码。 */ + public Builder methodCode(String methodCode) { + this.methodCode = methodCode; + return this; + } + + /** 设置物流跟踪号;必填。 */ + public Builder trackingNumber(String trackingNumber) { + this.trackingNumber = trackingNumber; + return this; + } + + /** 设置承运商跟踪页 URL;可空。 */ + public Builder trackingUrl(String trackingUrl) { + this.trackingUrl = trackingUrl; + return this; + } + + /** 设置卖家自定义订单号;可空,平台长度上限见各适配器。 */ + public Builder sellerOrderId(String sellerOrderId) { + this.sellerOrderId = sellerOrderId; + return this; + } + + /** 设置「客户已申请取消但仍要发货」的确认标记。 */ + public Builder intentToCancelOverride(boolean intentToCancelOverride) { + this.intentToCancelOverride = intentToCancelOverride; + return this; + } + + /** 设置发货时间;不设置时由适配器取当前时钟。 */ + public Builder shippedAt(Instant shippedAt) { + this.shippedAt = shippedAt; + return this; + } + + /** 构建发货行;缺必填字段时抛 {@link IllegalArgumentException}。 */ + public Line build() { + return new Line(this); + } + } + } + + /** 发货命令构建器。 */ + public static final class Builder { + + /** 平台订单号;必填。 */ + private String channelOrderId; + + /** 发货行。 */ + private final List标发是「一订单一次调用」,所以结果以订单为单位:成功时带平台确认的 + * 发货时间与(可能的)新状态;平台只回订单对象时,这里只保留关键字段, + * 完整订单由调用方按需重新查询。
+ */ +public final class ShipmentResult { + + /** 平台订单号;非 null。 */ + private final String channelOrderId; + + /** 平台确认的发货时间;平台不回时为 null。 */ + private final Instant shippedAt; + + /** 平台侧记录的跟踪号;平台不回时为 null。 */ + private final String trackingNumber; + + /** 行级发货记录;不可变,永远不为 null,可能为空(平台只回整体状态时)。 */ + private final Map平台可能只回「部分发货」:同一行的 {@link #quantity()} 是累计已发数量, + * 不是本次实发数量。
+ */ + public static final class LineShipment { + + /** 平台订单行号。 */ + private final String lineNumber; + /** 平台侧该行累计已发数量。 */ + private final int quantity; + /** 行状态原值,如 {@code Shipped}、{@code Created}。 */ + private final String status; + + /** 构造单行发货状态。 */ + public LineShipment(String lineNumber, int quantity, String status) { + this.lineNumber = lineNumber; + this.quantity = quantity; + this.status = status; + } + + /** 平台订单行号。 */ + public String lineNumber() { + return lineNumber; + } + + /** 该行累计已发数量。 */ + public int quantity() { + return quantity; + } + + /** 行状态原值。 */ + public String status() { + return status; + } + } + + /** 标发结果构建器。 */ + public static final class Builder { + + /** 平台订单号。 */ + private String channelOrderId; + /** 平台确认的发货时间。 */ + private Instant shippedAt; + /** 跟踪号。 */ + private String trackingNumber; + /** 行级记录。 */ + private final Map