diff --git a/core/src/main/java/common/ecommerce/capability/OrderEditCapable.java b/core/src/main/java/common/ecommerce/capability/OrderEditCapable.java new file mode 100644 index 0000000..9ce7c53 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/OrderEditCapable.java @@ -0,0 +1,23 @@ +package common.ecommerce.capability; + +import common.ecommerce.model.Capability; +import common.ecommerce.model.fulfillment.OrderEditRequest; +import common.ecommerce.model.fulfillment.OrderEditResult; +import common.ecommerce.sdk.ChannelContext; + +import java.util.List; + +/** + * 订单编辑能力(仓库、物流方式、包裹预估规格、报关信息)。 + * + *

写操作,必须经 {@code IdempotencyGuard} 执行;幂等键按系统单号。

+ * + *

能力单独成一项 {@link Capability#ORDER_EDIT},不复用 + * {@link Capability#SALES_ORDER}:编辑是 ERP 级接口,不依赖订单列表接口, + * 某些子平台只有编辑能力、没有订单同步能力。

+ */ +public interface OrderEditCapable extends PlatformAdapter { + + /** 批量编辑订单;平台按单返回失败原因。 */ + OrderEditResult edit(ChannelContext ctx, List requests); +} diff --git a/core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java b/core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java new file mode 100644 index 0000000..c8ac327 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java @@ -0,0 +1,18 @@ +package common.ecommerce.capability; + +import common.ecommerce.model.fulfillment.OutboundOrder; +import common.ecommerce.model.fulfillment.OutboundOrderQuery; +import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.ChannelContext; + +/** + * 销售出库单(仓库出库单据)查询能力。 + * + *

只读。主键是销售出库单号 {@code woNumber},不是订单号: + * 一张订单可以拆成多张出库单。

+ */ +public interface OutboundOrderCapable extends PlatformAdapter { + + /** 分页拉取销售出库单。 */ + Page pull(ChannelContext ctx, OutboundOrderQuery query); +} diff --git a/core/src/main/java/common/ecommerce/capability/Outbounds.java b/core/src/main/java/common/ecommerce/capability/Outbounds.java index 4267a7c..3984d18 100644 --- a/core/src/main/java/common/ecommerce/capability/Outbounds.java +++ b/core/src/main/java/common/ecommerce/capability/Outbounds.java @@ -3,14 +3,23 @@ package common.ecommerce.capability; import common.ecommerce.error.ChannelException; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.fulfillment.LabelQuery; +import common.ecommerce.model.fulfillment.OutboundOrder; +import common.ecommerce.model.fulfillment.OutboundOrderQuery; import common.ecommerce.model.fulfillment.OutboundPackage; import common.ecommerce.model.fulfillment.OutboundResult; +import common.ecommerce.model.fulfillment.ShipmentReviewResult; +import common.ecommerce.model.fulfillment.ShippingLabel; +import common.ecommerce.model.support.Page; import common.ecommerce.sdk.ChannelContext; import java.util.List; /** - * 门面持有的出库视图。调用前做能力检查,缺失时显式拒绝。 + * 门面持有的履约视图:快速出库、销售出库单、面单、审核发货。 + * + *

每个方法调用前做能力检查,缺失时显式拒绝;写操作仍由调用方包在 + * {@code sdk.writes()} 里执行。

*/ public final class Outbounds { @@ -34,9 +43,33 @@ public final class Outbounds { return ((OutboundCapable) adapter).results(ctx, globalOrderNos); } + /** 销售出库单列表。 */ + public Page pull(OutboundOrderQuery query) { + require(Capability.OUTBOUND_ORDER, OutboundOrderCapable.class); + return ((OutboundOrderCapable) adapter).pull(ctx, query); + } + + /** 销售出库单物流面单。 */ + public List labels(LabelQuery query) { + require(Capability.LABEL, ShippingLabelCapable.class); + return ((ShippingLabelCapable) adapter).labels(ctx, query); + } + + /** 审核发货(写操作,调用方需包在 {@code sdk.writes()} 里)。 */ + public ShipmentReviewResult review(List globalOrderNos) { + require(Capability.SHIPMENT_REVIEW, ShipmentReviewCapable.class); + return ((ShipmentReviewCapable) adapter).review(ctx, globalOrderNos); + } + private void requireOutboundCapable() { if (!adapter.supports(account, Capability.MARK_SHIPPED) || !(adapter instanceof OutboundCapable)) { throw new ChannelException.UnsupportedCapabilityException(Capability.MARK_SHIPPED); } } + + private void require(Capability capability, Class type) { + if (!adapter.supports(account, capability) || !type.isInstance(adapter)) { + throw new ChannelException.UnsupportedCapabilityException(capability); + } + } } diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrders.java b/core/src/main/java/common/ecommerce/capability/SalesOrders.java index bc7e560..fad45d2 100644 --- a/core/src/main/java/common/ecommerce/capability/SalesOrders.java +++ b/core/src/main/java/common/ecommerce/capability/SalesOrders.java @@ -3,12 +3,16 @@ package common.ecommerce.capability; import common.ecommerce.model.Capability; import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.error.ChannelException; +import common.ecommerce.model.fulfillment.OrderEditRequest; +import common.ecommerce.model.fulfillment.OrderEditResult; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.model.order.SalesOrderQuery; import common.ecommerce.model.order.SalesOrderRef; import common.ecommerce.model.support.Page; import common.ecommerce.sdk.ChannelContext; +import java.util.List; + /** * 门面持有的销售订单视图。调用前做能力检查,缺失时显式拒绝。 */ @@ -34,6 +38,14 @@ public final class SalesOrders { return ((SalesOrderCapable) adapter).get(ctx, SalesOrderRef.of(channelOrderId)); } + /** 批量编辑订单(写操作,调用方需包在 {@code sdk.writes()} 里)。 */ + public OrderEditResult edit(List requests) { + if (!adapter.supports(account, Capability.ORDER_EDIT) || !(adapter instanceof OrderEditCapable)) { + throw new ChannelException.UnsupportedCapabilityException(Capability.ORDER_EDIT); + } + return ((OrderEditCapable) adapter).edit(ctx, requests); + } + private void requireSalesOrderCapable() { if (!adapter.supports(account, Capability.SALES_ORDER) || !(adapter instanceof SalesOrderCapable)) { throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER); diff --git a/core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java b/core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java new file mode 100644 index 0000000..4f63099 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java @@ -0,0 +1,19 @@ +package common.ecommerce.capability; + +import common.ecommerce.model.fulfillment.ShipmentReviewResult; +import common.ecommerce.sdk.ChannelContext; + +import java.util.List; + +/** + * 审核发货能力(订单管理里的待审核发货)。 + * + *

写操作,必须经 {@code IdempotencyGuard} 执行;幂等键按系统单号。 + * 与 {@link OutboundCapable} 的快速出库不是同一动作:审核发货只推进订单状态, + * 不创建出库单。

+ */ +public interface ShipmentReviewCapable extends PlatformAdapter { + + /** 按系统单号批量审核发货;逐单返回成功或失败原因。 */ + ShipmentReviewResult review(ChannelContext ctx, List globalOrderNos); +} diff --git a/core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java b/core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java new file mode 100644 index 0000000..21256a5 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java @@ -0,0 +1,18 @@ +package common.ecommerce.capability; + +import common.ecommerce.model.fulfillment.LabelQuery; +import common.ecommerce.model.fulfillment.ShippingLabel; +import common.ecommerce.sdk.ChannelContext; + +import java.util.List; + +/** + * 物流面单查询能力。 + * + *

只读;面单以 base64 返回,SDK 不落文件、不访问对象存储。

+ */ +public interface ShippingLabelCapable extends PlatformAdapter { + + /** 按销售出库单号或系统单号批量取面单。 */ + List labels(ChannelContext ctx, LabelQuery query); +} diff --git a/core/src/main/java/common/ecommerce/model/Capability.java b/core/src/main/java/common/ecommerce/model/Capability.java index a2fdb4d..9521cb7 100644 --- a/core/src/main/java/common/ecommerce/model/Capability.java +++ b/core/src/main/java/common/ecommerce/model/Capability.java @@ -16,6 +16,12 @@ public enum Capability { PURCHASE_ORDER, /** 3P 标发 */ MARK_SHIPPED, + /** 审核发货(订单管理里的待审核发货) */ + SHIPMENT_REVIEW, + /** 编辑自发货订单(仓库 / 物流方式 / 包裹规格 / 报关) */ + ORDER_EDIT, + /** 销售出库单(仓库出库单据查询) */ + OUTBOUND_ORDER, /** 1P DF/DSV 发货确认 */ VENDOR_SHIPMENT, /** 1P Retail ASN(856) */ diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java b/core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java new file mode 100644 index 0000000..bd0bc9f --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java @@ -0,0 +1,198 @@ +package common.ecommerce.model.fulfillment; + +import java.math.BigDecimal; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 编辑订单时的报关明细。 + * + *

{@code id} 是原有报关明细主键,不是订单商品 id:编辑已有行时保留, + * 新增行可不传或传 0。

+ */ +public final class DeclaredItem { + + private final String sku; + private final Long id; + private final String cnName; + private final String enName; + private final BigDecimal unitPrice; + private final String currencyCode; + private final BigDecimal weight; + private final int quantity; + private final String hsCode; + private final List specialAttributes; + + private DeclaredItem(Builder b) { + this.sku = requireText(b.sku, "sku"); + this.id = b.id; + this.cnName = requireText(b.cnName, "cnName"); + this.enName = requireText(b.enName, "enName"); + this.unitPrice = requirePositive(b.unitPrice, "unitPrice"); + this.currencyCode = requireText(b.currencyCode, "currencyCode"); + this.weight = requirePositive(b.weight, "weight"); + this.quantity = requirePositive(b.quantity, "quantity"); + this.hsCode = b.hsCode; + this.specialAttributes = Collections.unmodifiableList( + new ArrayList(b.specialAttributes)); + } + + public static Builder builder() { + return new Builder(); + } + + /** 商品本地 SKU。 */ + public String sku() { + return sku; + } + + /** 原有报关明细主键;新增行为 null。 */ + public Long id() { + return id; + } + + public String cnName() { + return cnName; + } + + public String enName() { + return enName; + } + + /** 目的国申报单价,必须大于 0。 */ + public BigDecimal unitPrice() { + return unitPrice; + } + + public String currencyCode() { + return currencyCode; + } + + /** 申报重量,单位 g,必须大于 0。 */ + public BigDecimal weight() { + return weight; + } + + public int quantity() { + return quantity; + } + + public String hsCode() { + return hsCode; + } + + /** 特殊属性编码:1 含电、2 纯电、3 液体、4 粉末、5 膏体、6 带磁、7 纺织品。 */ + public List specialAttributes() { + return specialAttributes; + } + + private static String requireText(String value, String name) { + if (value == null || value.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return value.trim(); + } + + private static BigDecimal requirePositive(BigDecimal value, String name) { + if (value == null || value.signum() <= 0) { + throw new IllegalArgumentException(name + " must be positive"); + } + return value; + } + + private static int requirePositive(int value, String name) { + if (value <= 0) { + throw new IllegalArgumentException(name + " must be positive"); + } + return value; + } + + public static final class Builder { + + private String sku; + private Long id; + private String cnName; + private String enName; + private BigDecimal unitPrice; + private String currencyCode; + private BigDecimal weight; + private int quantity; + private String hsCode; + private List specialAttributes = Collections.emptyList(); + + public Builder sku(String sku) { + this.sku = sku; + return this; + } + + public Builder id(Long id) { + this.id = id; + return this; + } + + public Builder cnName(String cnName) { + this.cnName = cnName; + return this; + } + + public Builder enName(String enName) { + this.enName = enName; + return this; + } + + public Builder unitPrice(BigDecimal unitPrice) { + this.unitPrice = unitPrice; + return this; + } + + public Builder unitPrice(String unitPrice) { + this.unitPrice = unitPrice == null ? null : new BigDecimal(unitPrice.trim()); + return this; + } + + public Builder currencyCode(String currencyCode) { + this.currencyCode = currencyCode; + return this; + } + + public Builder weight(BigDecimal weight) { + this.weight = weight; + return this; + } + + public Builder weight(String weight) { + this.weight = weight == null ? null : new BigDecimal(weight.trim()); + return this; + } + + public Builder quantity(int quantity) { + this.quantity = quantity; + return this; + } + + public Builder hsCode(String hsCode) { + this.hsCode = hsCode; + return this; + } + + public Builder specialAttributes(List specialAttributes) { + this.specialAttributes = specialAttributes == null + ? Collections.emptyList() : specialAttributes; + return this; + } + + public Builder specialAttributes(String... specialAttributes) { + List values = new ArrayList(); + if (specialAttributes != null) { + Collections.addAll(values, specialAttributes); + } + this.specialAttributes = values; + return this; + } + + public DeclaredItem build() { + return new DeclaredItem(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java b/core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java new file mode 100644 index 0000000..6224ee8 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java @@ -0,0 +1,74 @@ +package common.ecommerce.model.fulfillment; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 物流面单查询条件。 + * + *

销售出库单号与系统单号二选一:平台要求至少给一组,单次上限通常为 50。 + * 两个都传属于调用方错误,适配器会显式拒绝,避免平台静默忽略其中一组。

+ */ +public final class LabelQuery { + + private final List woNumbers; + private final List orderNumbers; + + private LabelQuery(Builder b) { + this.woNumbers = Collections.unmodifiableList(new ArrayList(b.woNumbers)); + this.orderNumbers = Collections.unmodifiableList(new ArrayList(b.orderNumbers)); + } + + public static Builder builder() { + return new Builder(); + } + + /** 销售出库单号。 */ + public List woNumbers() { + return woNumbers; + } + + /** 领星系统单号。 */ + public List orderNumbers() { + return orderNumbers; + } + + public static final class Builder { + + private List woNumbers = Collections.emptyList(); + private List orderNumbers = Collections.emptyList(); + + public Builder woNumbers(List woNumbers) { + this.woNumbers = woNumbers == null ? Collections.emptyList() : woNumbers; + return this; + } + + public Builder woNumbers(String... woNumbers) { + List values = new ArrayList(); + if (woNumbers != null) { + Collections.addAll(values, woNumbers); + } + this.woNumbers = values; + return this; + } + + public Builder orderNumbers(List orderNumbers) { + this.orderNumbers = orderNumbers == null ? Collections.emptyList() : orderNumbers; + return this; + } + + public Builder orderNumbers(String... orderNumbers) { + List values = new ArrayList(); + if (orderNumbers != null) { + Collections.addAll(values, orderNumbers); + } + this.orderNumbers = values; + return this; + } + + public LabelQuery build() { + return new LabelQuery(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java b/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java new file mode 100644 index 0000000..33ddfd3 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java @@ -0,0 +1,216 @@ +package common.ecommerce.model.fulfillment; + +import java.math.BigDecimal; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 编辑订单请求(订单管理里的待审核自发货订单)。 + * + *

一次可以只改仓库/物流,只改包裹规格,或只改报关,也可以组合。适配器按 + * 「非空才发送」处理,未设置的维度保持平台原值。

+ * + *

平台约束:

+ *
    + *
  • 改仓库必须同时给 {@code logisticsTypeId}
  • + *
  • 包裹预估长宽高与总重量必须四项一起给
  • + *
  • 报关开关打开时,报关明细不能为空
  • + *
+ */ +public final class OrderEditRequest { + + private final String globalOrderNo; + private final Long warehouseId; + private final Long logisticsTypeId; + private final BigDecimal packageLength; + private final BigDecimal packageWidth; + private final BigDecimal packageHeight; + private final BigDecimal packageWeight; + private final boolean modifyDeclared; + private final List declaredItems; + + private OrderEditRequest(Builder b) { + this.globalOrderNo = requireText(b.globalOrderNo, "globalOrderNo"); + this.warehouseId = b.warehouseId; + this.logisticsTypeId = b.logisticsTypeId; + this.packageLength = b.packageLength; + this.packageWidth = b.packageWidth; + this.packageHeight = b.packageHeight; + this.packageWeight = b.packageWeight; + this.modifyDeclared = b.modifyDeclared; + this.declaredItems = Collections.unmodifiableList(new ArrayList(b.declaredItems)); + + int packageFields = 0; + if (packageLength != null) { + packageFields++; + } + if (packageWidth != null) { + packageFields++; + } + if (packageHeight != null) { + packageFields++; + } + if (packageWeight != null) { + packageFields++; + } + if (packageFields != 0 && packageFields != 4) { + throw new IllegalArgumentException( + "packageLength/packageWidth/packageHeight/packageWeight must be set together"); + } + if (modifyDeclared != !declaredItems.isEmpty()) { + // 打开开关必须有明细;有关闭开关却传明细说明调用方语义不一致 + throw new IllegalArgumentException( + "modifyDeclared and declaredItems must be set consistently"); + } + if (warehouseId == null && logisticsTypeId == null && packageFields == 0 && !modifyDeclared) { + throw new IllegalArgumentException("order edit request has nothing to change: " + globalOrderNo); + } + } + + public static Builder builder() { + return new Builder(); + } + + /** 领星系统单号。 */ + public String globalOrderNo() { + return globalOrderNo; + } + + /** 发货仓库 wid。 */ + public Long warehouseId() { + return warehouseId; + } + + /** 物流方式 id。 */ + public Long logisticsTypeId() { + return logisticsTypeId; + } + + /** 包裹预估长,单位 cm。 */ + public BigDecimal packageLength() { + return packageLength; + } + + /** 包裹预估宽,单位 cm。 */ + public BigDecimal packageWidth() { + return packageWidth; + } + + /** 包裹预估高,单位 cm。 */ + public BigDecimal packageHeight() { + return packageHeight; + } + + /** 包裹预估总重量,单位 g。 */ + public BigDecimal packageWeight() { + return packageWeight; + } + + public boolean modifyDeclared() { + return modifyDeclared; + } + + public List declaredItems() { + return declaredItems; + } + + private static String requireText(String value, String name) { + if (value == null || value.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return value.trim(); + } + + public static final class Builder { + + private String globalOrderNo; + private Long warehouseId; + private Long logisticsTypeId; + private BigDecimal packageLength; + private BigDecimal packageWidth; + private BigDecimal packageHeight; + private BigDecimal packageWeight; + private boolean modifyDeclared; + private List declaredItems = Collections.emptyList(); + + public Builder globalOrderNo(String globalOrderNo) { + this.globalOrderNo = globalOrderNo; + return this; + } + + public Builder warehouseId(Long warehouseId) { + this.warehouseId = warehouseId; + return this; + } + + public Builder logisticsTypeId(Long logisticsTypeId) { + this.logisticsTypeId = logisticsTypeId; + return this; + } + + public Builder packageLength(BigDecimal packageLength) { + this.packageLength = packageLength; + return this; + } + + public Builder packageLength(String packageLength) { + this.packageLength = packageLength == null ? null : new BigDecimal(packageLength.trim()); + return this; + } + + public Builder packageWidth(BigDecimal packageWidth) { + this.packageWidth = packageWidth; + return this; + } + + public Builder packageWidth(String packageWidth) { + this.packageWidth = packageWidth == null ? null : new BigDecimal(packageWidth.trim()); + return this; + } + + public Builder packageHeight(BigDecimal packageHeight) { + this.packageHeight = packageHeight; + return this; + } + + public Builder packageHeight(String packageHeight) { + this.packageHeight = packageHeight == null ? null : new BigDecimal(packageHeight.trim()); + return this; + } + + public Builder packageWeight(BigDecimal packageWeight) { + this.packageWeight = packageWeight; + return this; + } + + public Builder packageWeight(String packageWeight) { + this.packageWeight = packageWeight == null ? null : new BigDecimal(packageWeight.trim()); + return this; + } + + public Builder modifyDeclared(boolean modifyDeclared) { + this.modifyDeclared = modifyDeclared; + return this; + } + + public Builder declaredItems(List declaredItems) { + this.declaredItems = declaredItems == null + ? Collections.emptyList() : declaredItems; + return this; + } + + public Builder declaredItems(DeclaredItem... declaredItems) { + List values = new ArrayList(); + if (declaredItems != null) { + Collections.addAll(values, declaredItems); + } + this.declaredItems = values; + return this; + } + + public OrderEditRequest build() { + return new OrderEditRequest(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java b/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java new file mode 100644 index 0000000..8de31a5 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java @@ -0,0 +1,96 @@ +package common.ecommerce.model.fulfillment; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 编辑订单结果。 + * + *

平台按批返回三种业务码:{@code 0} 全部成功、{@code 10001} 部分成功、 + * {@code 10000} 全部失败。即使整体失败,也要看 {@link #failures()} 里逐单的原因。

+ */ +public final class OrderEditResult { + + public static final String CODE_SUCCESS = "0"; + public static final String CODE_ALL_FAILED = "10000"; + public static final String CODE_PARTIAL = "10001"; + + private final String code; + private final String message; + private final List failures; + + private OrderEditResult(Builder b) { + this.code = b.code; + this.message = b.message; + this.failures = Collections.unmodifiableList(new ArrayList(b.failures)); + } + + public static Builder builder() { + return new Builder(); + } + + /** 平台业务码。 */ + public String code() { + return code; + } + + public String message() { + return message; + } + + public List failures() { + return failures; + } + + /** 全部成功。 */ + public boolean allSucceeded() { + return CODE_SUCCESS.equals(code) && failures.isEmpty(); + } + + /** 单笔失败原因。 */ + public static final class Failure { + + private final String globalOrderNo; + private final String errorMessage; + + public Failure(String globalOrderNo, String errorMessage) { + this.globalOrderNo = globalOrderNo; + this.errorMessage = errorMessage; + } + + public String globalOrderNo() { + return globalOrderNo; + } + + public String errorMessage() { + return errorMessage; + } + } + + public static final class Builder { + + private String code; + private String message; + private List failures = Collections.emptyList(); + + public Builder code(String code) { + this.code = code; + return this; + } + + public Builder message(String message) { + this.message = message; + return this; + } + + public Builder failures(List failures) { + this.failures = failures == null ? Collections.emptyList() : failures; + return this; + } + + public OrderEditResult build() { + return new OrderEditResult(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java new file mode 100644 index 0000000..209f5bf --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java @@ -0,0 +1,475 @@ +package common.ecommerce.model.fulfillment; + +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.support.Money; +import common.ecommerce.model.support.PlatformTime; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.Objects; + +/** + * 销售出库单。 + * + *

对应平台「仓库 > 销售出库单」,是订单进入仓库作业后的单据视角: + * 一张销售订单可能拆成多张出库单,因此 {@code woNumber}(销售出库单号)才是主键, + * 不是 {@code orderNumber}(系统单号)。

+ * + *

状态字段保留平台原值,由宿主解释:{@code status} 是出库单状态, + * {@code logisticsStatus} 是物流下单状态,两者不要混用。

+ */ +public final class OutboundOrder { + + private final String omsStoreId; + private final ChannelProvider sourceProvider; + private final String sourceAccountId; + private final String woNumber; + private final String woId; + private final String orderNumber; + private final List platformOrderNos; + private final Integer sid; + private final String sellerName; + private final Integer warehouseId; + private final String warehouseName; + private final Integer warehouseType; + private final Integer status; + private final String statusName; + private final Integer logisticsStatus; + private final String logisticsStatusName; + private final String logisticsMessage; + private final Long logisticsProviderId; + private final String logisticsProviderName; + private final Long logisticsTypeId; + private final String logisticsTypeName; + private final String waybillNo; + private final String trackingNo; + private final Money orderAmount; + private final String targetCountry; + private final String packageWeight; + private final String packageRealWeight; + private final String packageFeeWeight; + private final String packageWeightUnit; + private final String surfaceFileUrl; + private final PlatformTime createdAt; + private final PlatformTime updatedAt; + private final PlatformTime deliveredAt; + private final PlatformTime purchasedAt; + private final List lines; + + private OutboundOrder(Builder b) { + this.omsStoreId = Objects.requireNonNull(b.omsStoreId, "omsStoreId"); + this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider"); + this.sourceAccountId = b.sourceAccountId; + this.woNumber = Objects.requireNonNull(b.woNumber, "woNumber"); + this.woId = b.woId; + this.orderNumber = b.orderNumber; + this.platformOrderNos = Collections.unmodifiableList(new ArrayList(b.platformOrderNos)); + this.sid = b.sid; + this.sellerName = b.sellerName; + this.warehouseId = b.warehouseId; + this.warehouseName = b.warehouseName; + this.warehouseType = b.warehouseType; + this.status = b.status; + this.statusName = b.statusName; + this.logisticsStatus = b.logisticsStatus; + this.logisticsStatusName = b.logisticsStatusName; + this.logisticsMessage = b.logisticsMessage; + this.logisticsProviderId = b.logisticsProviderId; + this.logisticsProviderName = b.logisticsProviderName; + this.logisticsTypeId = b.logisticsTypeId; + this.logisticsTypeName = b.logisticsTypeName; + this.waybillNo = b.waybillNo; + this.trackingNo = b.trackingNo; + this.orderAmount = b.orderAmount; + this.targetCountry = b.targetCountry; + this.packageWeight = b.packageWeight; + this.packageRealWeight = b.packageRealWeight; + this.packageFeeWeight = b.packageFeeWeight; + this.packageWeightUnit = b.packageWeightUnit; + this.surfaceFileUrl = b.surfaceFileUrl; + this.createdAt = b.createdAt; + this.updatedAt = b.updatedAt; + this.deliveredAt = b.deliveredAt; + this.purchasedAt = b.purchasedAt; + this.lines = Collections.unmodifiableList(new ArrayList(b.lines)); + } + + public static Builder builder() { + return new Builder(); + } + + public String omsStoreId() { + return omsStoreId; + } + + public ChannelProvider sourceProvider() { + return sourceProvider; + } + + public String sourceAccountId() { + return sourceAccountId; + } + + /** 销售出库单号,主键。 */ + public String woNumber() { + return woNumber; + } + + /** 领星出库单 id。 */ + public String woId() { + return woId; + } + + /** 领星系统单号。 */ + public String orderNumber() { + return orderNumber; + } + + /** 平台单号;合并单可能多于一个。 */ + public List platformOrderNos() { + return platformOrderNos; + } + + /** 领星店铺 id。 */ + public Integer sid() { + return sid; + } + + public String sellerName() { + return sellerName; + } + + public Integer warehouseId() { + return warehouseId; + } + + public String warehouseName() { + return warehouseName; + } + + /** 仓库类型:1 本地仓库、2 FBA 仓、3 第三方海外仓。 */ + public Integer warehouseType() { + return warehouseType; + } + + /** 出库单状态:1 物流下单、2 待出库、3 已出库、4 已截单。 */ + public Integer status() { + return status; + } + + public String statusName() { + return statusName; + } + + /** 物流下单状态:1 待导入 … 5 下单完成 … 43 物流取消完成。 */ + public Integer logisticsStatus() { + return logisticsStatus; + } + + public String logisticsStatusName() { + return logisticsStatusName; + } + + public String logisticsMessage() { + return logisticsMessage; + } + + public Long logisticsProviderId() { + return logisticsProviderId; + } + + public String logisticsProviderName() { + return logisticsProviderName; + } + + public Long logisticsTypeId() { + return logisticsTypeId; + } + + public String logisticsTypeName() { + return logisticsTypeName; + } + + public String waybillNo() { + return waybillNo; + } + + public String trackingNo() { + return trackingNo; + } + + /** 订单金额;平台未给币种时为 null。 */ + public Money orderAmount() { + return orderAmount; + } + + public String targetCountry() { + return targetCountry; + } + + /** 预估重量,保留平台原始字符串与单位。 */ + public String packageWeight() { + return packageWeight; + } + + /** 包裹实重,保留平台原始字符串。 */ + public String packageRealWeight() { + return packageRealWeight; + } + + /** 包裹计费重,保留平台原始字符串。 */ + public String packageFeeWeight() { + return packageFeeWeight; + } + + public String packageWeightUnit() { + return packageWeightUnit; + } + + /** 面单文件链接;接口给的是 30 分钟有效的 COS 链接。 */ + public String surfaceFileUrl() { + return surfaceFileUrl; + } + + public PlatformTime createdAt() { + return createdAt; + } + + public PlatformTime updatedAt() { + return updatedAt; + } + + /** 出库时间【单据操作】。 */ + public PlatformTime deliveredAt() { + return deliveredAt; + } + + /** 下单时间。 */ + public PlatformTime purchasedAt() { + return purchasedAt; + } + + public List lines() { + return lines; + } + + public static final class Builder { + + private String omsStoreId; + private ChannelProvider sourceProvider; + private String sourceAccountId; + private String woNumber; + private String woId; + private String orderNumber; + private List platformOrderNos = Collections.emptyList(); + private Integer sid; + private String sellerName; + private Integer warehouseId; + private String warehouseName; + private Integer warehouseType; + private Integer status; + private String statusName; + private Integer logisticsStatus; + private String logisticsStatusName; + private String logisticsMessage; + private Long logisticsProviderId; + private String logisticsProviderName; + private Long logisticsTypeId; + private String logisticsTypeName; + private String waybillNo; + private String trackingNo; + private Money orderAmount; + private String targetCountry; + private String packageWeight; + private String packageRealWeight; + private String packageFeeWeight; + private String packageWeightUnit; + private String surfaceFileUrl; + private PlatformTime createdAt; + private PlatformTime updatedAt; + private PlatformTime deliveredAt; + private PlatformTime purchasedAt; + private List lines = Collections.emptyList(); + + public Builder omsStoreId(String omsStoreId) { + this.omsStoreId = omsStoreId; + return this; + } + + public Builder sourceProvider(ChannelProvider sourceProvider) { + this.sourceProvider = sourceProvider; + return this; + } + + public Builder sourceAccountId(String sourceAccountId) { + this.sourceAccountId = sourceAccountId; + return this; + } + + public Builder woNumber(String woNumber) { + this.woNumber = woNumber; + return this; + } + + public Builder woId(String woId) { + this.woId = woId; + return this; + } + + public Builder orderNumber(String orderNumber) { + this.orderNumber = orderNumber; + return this; + } + + public Builder platformOrderNos(List platformOrderNos) { + this.platformOrderNos = platformOrderNos == null + ? Collections.emptyList() : platformOrderNos; + return this; + } + + public Builder sid(Integer sid) { + this.sid = sid; + return this; + } + + public Builder sellerName(String sellerName) { + this.sellerName = sellerName; + return this; + } + + public Builder warehouseId(Integer warehouseId) { + this.warehouseId = warehouseId; + return this; + } + + public Builder warehouseName(String warehouseName) { + this.warehouseName = warehouseName; + return this; + } + + public Builder warehouseType(Integer warehouseType) { + this.warehouseType = warehouseType; + return this; + } + + public Builder status(Integer status) { + this.status = status; + return this; + } + + public Builder statusName(String statusName) { + this.statusName = statusName; + return this; + } + + public Builder logisticsStatus(Integer logisticsStatus) { + this.logisticsStatus = logisticsStatus; + return this; + } + + public Builder logisticsStatusName(String logisticsStatusName) { + this.logisticsStatusName = logisticsStatusName; + return this; + } + + public Builder logisticsMessage(String logisticsMessage) { + this.logisticsMessage = logisticsMessage; + return this; + } + + public Builder logisticsProviderId(Long logisticsProviderId) { + this.logisticsProviderId = logisticsProviderId; + return this; + } + + public Builder logisticsProviderName(String logisticsProviderName) { + this.logisticsProviderName = logisticsProviderName; + return this; + } + + public Builder logisticsTypeId(Long logisticsTypeId) { + this.logisticsTypeId = logisticsTypeId; + return this; + } + + public Builder logisticsTypeName(String logisticsTypeName) { + this.logisticsTypeName = logisticsTypeName; + return this; + } + + public Builder waybillNo(String waybillNo) { + this.waybillNo = waybillNo; + return this; + } + + public Builder trackingNo(String trackingNo) { + this.trackingNo = trackingNo; + return this; + } + + public Builder orderAmount(Money orderAmount) { + this.orderAmount = orderAmount; + return this; + } + + public Builder targetCountry(String targetCountry) { + this.targetCountry = targetCountry; + return this; + } + + public Builder packageWeight(String packageWeight) { + this.packageWeight = packageWeight; + return this; + } + + public Builder packageRealWeight(String packageRealWeight) { + this.packageRealWeight = packageRealWeight; + return this; + } + + public Builder packageFeeWeight(String packageFeeWeight) { + this.packageFeeWeight = packageFeeWeight; + return this; + } + + public Builder packageWeightUnit(String packageWeightUnit) { + this.packageWeightUnit = packageWeightUnit; + return this; + } + + public Builder surfaceFileUrl(String surfaceFileUrl) { + this.surfaceFileUrl = surfaceFileUrl; + return this; + } + + public Builder createdAt(PlatformTime createdAt) { + this.createdAt = createdAt; + return this; + } + + public Builder updatedAt(PlatformTime updatedAt) { + this.updatedAt = updatedAt; + return this; + } + + public Builder deliveredAt(PlatformTime deliveredAt) { + this.deliveredAt = deliveredAt; + return this; + } + + public Builder purchasedAt(PlatformTime purchasedAt) { + this.purchasedAt = purchasedAt; + return this; + } + + public Builder lines(List lines) { + this.lines = lines == null ? Collections.emptyList() : lines; + return this; + } + + public OutboundOrder build() { + return new OutboundOrder(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java new file mode 100644 index 0000000..1a55950 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java @@ -0,0 +1,118 @@ +package common.ecommerce.model.fulfillment; + +import common.ecommerce.model.support.Money; + +import java.util.Objects; + +/** + * 销售出库单商品行。 + * + *

字段以领星「销售出库单列表」的 {@code product_info[]} 为准: + * {@code sku} 是领星本地 SKU,{@code sellerSku} 才是平台 MSKU。

+ */ +public final class OutboundOrderLine { + + private final String lineId; + private final String productId; + private final String sku; + private final String sellerSku; + private final String productName; + private final int quantity; + private final Money unitPrice; + + private OutboundOrderLine(Builder b) { + this.lineId = Objects.requireNonNull(b.lineId, "lineId"); + this.productId = b.productId; + this.sku = b.sku; + this.sellerSku = b.sellerSku; + this.productName = b.productName; + this.quantity = b.quantity; + this.unitPrice = b.unitPrice; + } + + public static Builder builder() { + return new Builder(); + } + + /** 出库单明细 id,映射自 {@code wod_id}。 */ + public String lineId() { + return lineId; + } + + public String productId() { + return productId; + } + + /** 领星本地 SKU。 */ + public String sku() { + return sku; + } + + /** 平台 MSKU。 */ + public String sellerSku() { + return sellerSku; + } + + public String productName() { + return productName; + } + + public int quantity() { + return quantity; + } + + /** 商品单价;平台未给币种时为 null。 */ + public Money unitPrice() { + return unitPrice; + } + + public static final class Builder { + + private String lineId; + private String productId; + private String sku; + private String sellerSku; + private String productName; + private int quantity; + private Money unitPrice; + + public Builder lineId(String lineId) { + this.lineId = lineId; + return this; + } + + public Builder productId(String productId) { + this.productId = productId; + return this; + } + + public Builder sku(String sku) { + this.sku = sku; + return this; + } + + public Builder sellerSku(String sellerSku) { + this.sellerSku = sellerSku; + return this; + } + + public Builder productName(String productName) { + this.productName = productName; + return this; + } + + public Builder quantity(int quantity) { + this.quantity = quantity; + return this; + } + + public Builder unitPrice(Money unitPrice) { + this.unitPrice = unitPrice; + return this; + } + + public OutboundOrderLine build() { + return new OutboundOrderLine(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java new file mode 100644 index 0000000..563cc3c --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java @@ -0,0 +1,253 @@ +package common.ecommerce.model.fulfillment; + +import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 销售出库单查询条件(单次查询,不推进水位线)。 + * + *

平台一般要求时间窗;不传时由平台按默认区间返回(领星默认最近一个月)。 + * 时间字段类型用 {@link #timeType()} 指定,取值见本类常量。

+ */ +public final class OutboundOrderQuery { + + /** 创建时间。 */ + public static final String TIME_CREATED = "create_at"; + /** 出库时间【单据操作】。 */ + public static final String TIME_DELIVERED = "delivered_at"; + /** 库存流水出库时间。 */ + public static final String TIME_STOCK_DELIVERED = "stock_delivered_at"; + /** 变更时间。 */ + public static final String TIME_UPDATED = "update_at"; + + private final Instant after; + private final Instant before; + private final String timeType; + private final List sids; + private final List statuses; + private final List logisticsStatuses; + private final List platformOrderNos; + private final List orderNumbers; + private final List woNumbers; + private final int pageSize; + private final String cursor; + + private OutboundOrderQuery(Builder b) { + this.after = b.after; + this.before = b.before; + this.timeType = b.timeType; + this.sids = Collections.unmodifiableList(new ArrayList(b.sids)); + this.statuses = Collections.unmodifiableList(new ArrayList(b.statuses)); + this.logisticsStatuses = Collections.unmodifiableList(new ArrayList(b.logisticsStatuses)); + this.platformOrderNos = Collections.unmodifiableList(new ArrayList(b.platformOrderNos)); + this.orderNumbers = Collections.unmodifiableList(new ArrayList(b.orderNumbers)); + this.woNumbers = Collections.unmodifiableList(new ArrayList(b.woNumbers)); + this.pageSize = b.pageSize; + this.cursor = b.cursor; + } + + public static Builder builder() { + return new Builder(); + } + + /** 时间窗起点;为 null 时不传,由平台按默认区间处理。 */ + public Instant after() { + return after; + } + + /** 时间窗终点;为 null 时不传。 */ + public Instant before() { + return before; + } + + /** 时间字段类型,默认 {@link #TIME_UPDATED}。 */ + public String timeType() { + return timeType; + } + + /** + * 店铺 id 过滤;为空时适配器使用当前账户的店铺 id。 + * + *

领星侧是内部 {@code sid},对亚马逊 SC 即店铺列表返回的 {@code sid}。

+ */ + public List sids() { + return sids; + } + + /** 出库单状态:1 物流下单、2 待出库、3 已出库、4 已截单。 */ + public List statuses() { + return statuses; + } + + /** 物流下单状态。 */ + public List logisticsStatuses() { + return logisticsStatuses; + } + + public List platformOrderNos() { + return platformOrderNos; + } + + public List orderNumbers() { + return orderNumbers; + } + + public List woNumbers() { + return woNumbers; + } + + public int pageSize() { + return pageSize; + } + + public String cursor() { + return cursor; + } + + public Builder toBuilder() { + return builder() + .after(after) + .before(before) + .timeType(timeType) + .sids(sids) + .statuses(statuses) + .logisticsStatuses(logisticsStatuses) + .platformOrderNos(platformOrderNos) + .orderNumbers(orderNumbers) + .woNumbers(woNumbers) + .pageSize(pageSize) + .cursor(cursor); + } + + public static final class Builder { + + private Instant after; + private Instant before; + private String timeType = TIME_UPDATED; + private List sids = Collections.emptyList(); + private List statuses = Collections.emptyList(); + private List logisticsStatuses = Collections.emptyList(); + private List platformOrderNos = Collections.emptyList(); + private List orderNumbers = Collections.emptyList(); + private List woNumbers = Collections.emptyList(); + private int pageSize = 100; + private String cursor; + + public Builder after(Instant after) { + this.after = after; + return this; + } + + public Builder before(Instant before) { + this.before = before; + return this; + } + + public Builder timeType(String timeType) { + this.timeType = timeType; + return this; + } + + public Builder sids(List sids) { + this.sids = sids == null ? Collections.emptyList() : sids; + return this; + } + + public Builder sids(String... sids) { + List values = new ArrayList(); + if (sids != null) { + Collections.addAll(values, sids); + } + this.sids = values; + return this; + } + + public Builder statuses(List statuses) { + this.statuses = statuses == null ? Collections.emptyList() : statuses; + return this; + } + + public Builder statuses(Integer... statuses) { + List values = new ArrayList(); + if (statuses != null) { + Collections.addAll(values, statuses); + } + this.statuses = values; + return this; + } + + public Builder logisticsStatuses(List logisticsStatuses) { + this.logisticsStatuses = logisticsStatuses == null + ? Collections.emptyList() : logisticsStatuses; + return this; + } + + public Builder logisticsStatuses(Integer... logisticsStatuses) { + List values = new ArrayList(); + if (logisticsStatuses != null) { + Collections.addAll(values, logisticsStatuses); + } + this.logisticsStatuses = values; + return this; + } + + public Builder platformOrderNos(List platformOrderNos) { + this.platformOrderNos = platformOrderNos == null + ? Collections.emptyList() : platformOrderNos; + return this; + } + + public Builder platformOrderNos(String... platformOrderNos) { + List values = new ArrayList(); + if (platformOrderNos != null) { + Collections.addAll(values, platformOrderNos); + } + this.platformOrderNos = values; + return this; + } + + public Builder orderNumbers(List orderNumbers) { + this.orderNumbers = orderNumbers == null ? Collections.emptyList() : orderNumbers; + return this; + } + + public Builder orderNumbers(String... orderNumbers) { + List values = new ArrayList(); + if (orderNumbers != null) { + Collections.addAll(values, orderNumbers); + } + this.orderNumbers = values; + return this; + } + + public Builder woNumbers(List woNumbers) { + this.woNumbers = woNumbers == null ? Collections.emptyList() : woNumbers; + return this; + } + + public Builder woNumbers(String... woNumbers) { + List values = new ArrayList(); + if (woNumbers != null) { + Collections.addAll(values, woNumbers); + } + this.woNumbers = values; + return this; + } + + public Builder pageSize(int pageSize) { + this.pageSize = pageSize; + return this; + } + + public Builder cursor(String cursor) { + this.cursor = cursor; + return this; + } + + public OutboundOrderQuery build() { + return new OutboundOrderQuery(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java b/core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java new file mode 100644 index 0000000..5e8c6aa --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java @@ -0,0 +1,105 @@ +package common.ecommerce.model.fulfillment; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 审核发货结果。 + * + *

平台按单返回成功/失败,失败通常是「未设置仓库」「未设置物流」这类业务原因, + * 不影响同批其它订单。调用方必须逐单处理,不能只看整体是否成功。

+ */ +public final class ShipmentReviewResult { + + private final int successNum; + private final int failNum; + private final List successGlobalOrderNos; + private final List failures; + + private ShipmentReviewResult(Builder b) { + this.successNum = b.successNum; + this.failNum = b.failNum; + this.successGlobalOrderNos = Collections.unmodifiableList( + new ArrayList(b.successGlobalOrderNos)); + this.failures = Collections.unmodifiableList(new ArrayList(b.failures)); + } + + public static Builder builder() { + return new Builder(); + } + + public int successNum() { + return successNum; + } + + public int failNum() { + return failNum; + } + + public List successGlobalOrderNos() { + return successGlobalOrderNos; + } + + public List failures() { + return failures; + } + + /** 整批全部成功。 */ + public boolean allSucceeded() { + return failNum == 0 && failures.isEmpty(); + } + + /** 单笔失败原因。 */ + public static final class Failure { + + private final String globalOrderNo; + private final String message; + + public Failure(String globalOrderNo, String message) { + this.globalOrderNo = globalOrderNo; + this.message = message; + } + + public String globalOrderNo() { + return globalOrderNo; + } + + public String message() { + return message; + } + } + + public static final class Builder { + + private int successNum; + private int failNum; + private List successGlobalOrderNos = Collections.emptyList(); + private List failures = Collections.emptyList(); + + public Builder successNum(int successNum) { + this.successNum = successNum; + return this; + } + + public Builder failNum(int failNum) { + this.failNum = failNum; + return this; + } + + public Builder successGlobalOrderNos(List successGlobalOrderNos) { + this.successGlobalOrderNos = successGlobalOrderNos == null + ? Collections.emptyList() : successGlobalOrderNos; + return this; + } + + public Builder failures(List failures) { + this.failures = failures == null ? Collections.emptyList() : failures; + return this; + } + + public ShipmentReviewResult build() { + return new ShipmentReviewResult(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java b/core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java new file mode 100644 index 0000000..b5f2dd4 --- /dev/null +++ b/core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java @@ -0,0 +1,154 @@ +package common.ecommerce.model.fulfillment; + +import common.ecommerce.model.ChannelProvider; + +import java.util.Objects; + +/** + * 销售出库单物流面单。 + * + *

内容以 base64 返回,不落文件;{@code fileType} 是扩展名(如 {@code pdf}), + * 由调用方决定解码与存储方式。

+ */ +public final class ShippingLabel { + + private final String omsStoreId; + private final ChannelProvider sourceProvider; + private final String woNumber; + private final String orderNumber; + private final Long logisticsProviderId; + private final Long logisticsTypeId; + private final Long fileId; + private final String fileType; + private final String fileSize; + private final String contentBase64; + + private ShippingLabel(Builder b) { + this.omsStoreId = Objects.requireNonNull(b.omsStoreId, "omsStoreId"); + this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider"); + this.woNumber = Objects.requireNonNull(b.woNumber, "woNumber"); + this.orderNumber = b.orderNumber; + this.logisticsProviderId = b.logisticsProviderId; + this.logisticsTypeId = b.logisticsTypeId; + this.fileId = b.fileId; + this.fileType = b.fileType; + this.fileSize = b.fileSize; + this.contentBase64 = b.contentBase64; + } + + public static Builder builder() { + return new Builder(); + } + + public String omsStoreId() { + return omsStoreId; + } + + public ChannelProvider sourceProvider() { + return sourceProvider; + } + + /** 销售出库单号。 */ + public String woNumber() { + return woNumber; + } + + public String orderNumber() { + return orderNumber; + } + + public Long logisticsProviderId() { + return logisticsProviderId; + } + + public Long logisticsTypeId() { + return logisticsTypeId; + } + + public Long fileId() { + return fileId; + } + + /** 文件类型,如 {@code pdf}。 */ + public String fileType() { + return fileType; + } + + /** 文件尺寸描述,平台原值。 */ + public String fileSize() { + return fileSize; + } + + /** 面单 base64;平台可能返回空串。 */ + public String contentBase64() { + return contentBase64; + } + + public static final class Builder { + + private String omsStoreId; + private ChannelProvider sourceProvider; + private String woNumber; + private String orderNumber; + private Long logisticsProviderId; + private Long logisticsTypeId; + private Long fileId; + private String fileType; + private String fileSize; + private String contentBase64; + + public Builder omsStoreId(String omsStoreId) { + this.omsStoreId = omsStoreId; + return this; + } + + public Builder sourceProvider(ChannelProvider sourceProvider) { + this.sourceProvider = sourceProvider; + return this; + } + + public Builder woNumber(String woNumber) { + this.woNumber = woNumber; + return this; + } + + public Builder orderNumber(String orderNumber) { + this.orderNumber = orderNumber; + return this; + } + + public Builder logisticsProviderId(Long logisticsProviderId) { + this.logisticsProviderId = logisticsProviderId; + return this; + } + + public Builder logisticsTypeId(Long logisticsTypeId) { + this.logisticsTypeId = logisticsTypeId; + return this; + } + + public Builder fileId(Long fileId) { + this.fileId = fileId; + return this; + } + + public Builder fileType(String fileType) { + this.fileType = fileType; + return this; + } + + public Builder fileSize(String fileSize) { + this.fileSize = fileSize; + return this; + } + + public Builder contentBase64(String contentBase64) { + this.contentBase64 = contentBase64; + return this; + } + + public ShippingLabel build() { + return new ShippingLabel(this); + } + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java index 2c7fc1b..84a03e6 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java @@ -94,6 +94,18 @@ public enum LingxingApi { /** 快速出库结果查询。POST,qps 10,多平台通用。 */ FAST_OUTBOUND_RESULT("/pb/mp/order/v2/getFastOutboundResult", 10), + /** 销售出库单列表。POST,page/page_size 分页(上限 200),默认最近一个月,令牌桶 1。 */ + OUTBOUND_ORDER_LIST("/erp/sc/routing/wms/order/wmsOrderList", 1), + + /** 销售出库单物流面单。POST,按销售出库单号或系统单号查,单次上限 50。 */ + LOGISTICS_LABEL_LIST("/erp/sc/routing/wms/order/getWmsLogisticsLabels", 1), + + /** 审核发货。POST,global_order_no 数组,令牌桶 1。 */ + ORDER_REVIEW("/basicOpen/openapi/multiplatform/order/review", 1), + + /** 编辑订单(仓库 / 物流方式 / 包裹规格 / 报关)。POST,单次 1~50 单,令牌桶 10。 */ + ORDER_EDIT("/pb/mp/order/editOrder", 10), + /** 多平台订单列表;当前实现使用的跨平台接口。 */ ORDER_LIST("/pb/mp/order/v2/list", 10); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java index d12cfed..87377de 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java @@ -64,6 +64,13 @@ public final class LingxingConstants { /** 结算时间查询跨度上限:7 天(双闭区间)。 */ public static final int SETTLEMENT_MAX_QUERY_DAYS = 7; + /** 销售出库单分页 page_size 上限。 */ + public static final int OUTBOUND_ORDER_MAX_PAGE_SIZE = 200; + /** 物流面单单次查询上限(销售出库单号与系统单号各自上限 50)。 */ + public static final int LABEL_MAX_BATCH = 50; + /** 编辑订单单次上限。 */ + public static final int ORDER_EDIT_MAX_BATCH = 50; + private LingxingConstants() { } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java index 9399b70..dce9218 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java @@ -1,10 +1,14 @@ package common.ecommerce.lingxing.adapter; import common.ecommerce.capability.AggregatorCapable; +import common.ecommerce.capability.OrderEditCapable; import common.ecommerce.capability.OutboundCapable; +import common.ecommerce.capability.OutboundOrderCapable; import common.ecommerce.capability.ProductCapable; import common.ecommerce.capability.SalesOrderCapable; import common.ecommerce.capability.SettlementCapable; +import common.ecommerce.capability.ShipmentReviewCapable; +import common.ecommerce.capability.ShippingLabelCapable; import common.ecommerce.error.AuthException; import common.ecommerce.error.ChannelException; import common.ecommerce.http.HttpTransport; @@ -15,10 +19,18 @@ import common.ecommerce.lingxing.auth.LingxingTokenClient; import common.ecommerce.lingxing.http.LingxingRateLimiter; import common.ecommerce.lingxing.http.LingxingRequestFactory; import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.LingxingLabelSource; +import common.ecommerce.lingxing.platform.LingxingOrderEditSource; +import common.ecommerce.lingxing.platform.LingxingOutboundOrderSource; +import common.ecommerce.lingxing.platform.LingxingShipmentReviewSource; import common.ecommerce.lingxing.platform.LingxingSubPlatform; import common.ecommerce.lingxing.platform.LingxingSubPlatformDefaults; import common.ecommerce.lingxing.platform.LingxingOutboundSource; import common.ecommerce.lingxing.platform.LingxingSubPlatforms; +import common.ecommerce.lingxing.platform.wms.OrderEditSource; +import common.ecommerce.lingxing.platform.wms.ShipmentReviewSource; +import common.ecommerce.lingxing.platform.wms.WmsLabelSource; +import common.ecommerce.lingxing.platform.wms.WmsOutboundOrderSource; import common.ecommerce.model.Capability; import common.ecommerce.model.ChannelProvider; import common.ecommerce.model.Platform; @@ -26,8 +38,15 @@ import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.model.order.SalesOrderQuery; import common.ecommerce.model.order.SalesOrderRef; +import common.ecommerce.model.fulfillment.LabelQuery; +import common.ecommerce.model.fulfillment.OrderEditRequest; +import common.ecommerce.model.fulfillment.OrderEditResult; +import common.ecommerce.model.fulfillment.OutboundOrder; +import common.ecommerce.model.fulfillment.OutboundOrderQuery; import common.ecommerce.model.fulfillment.OutboundPackage; import common.ecommerce.model.fulfillment.OutboundResult; +import common.ecommerce.model.fulfillment.ShipmentReviewResult; +import common.ecommerce.model.fulfillment.ShippingLabel; import common.ecommerce.model.product.ProductListing; import common.ecommerce.model.product.ProductQuery; import common.ecommerce.model.product.ProductRef; @@ -57,7 +76,8 @@ import java.util.Set; * {@link LingxingSubPlatform}。

*/ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, SettlementCapable, - OutboundCapable, AggregatorCapable { + OutboundCapable, OutboundOrderCapable, ShippingLabelCapable, ShipmentReviewCapable, + OrderEditCapable, AggregatorCapable { private final HttpTransport transport; private final JacksonJsonCodec json; @@ -67,6 +87,15 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, private final LingxingSubPlatforms subPlatforms; /** + * ERP 级接口不区分平台,全部子平台共用同一实现,因此直接由适配器持有。 + * 这些 Source 无状态,构造一次即可复用。 + */ + private final LingxingOutboundOrderSource outboundOrderSource; + private final LingxingLabelSource labelSource; + private final LingxingShipmentReviewSource shipmentReviewSource; + private final LingxingOrderEditSource orderEditSource; + + /** * 适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用传入。 * *

子平台装配默认用 {@code LingxingSubPlatformDefaults.all(...)}; @@ -110,6 +139,10 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, this.requestFactory = new LingxingRequestFactory(json, clock); this.subPlatforms = subPlatforms != null ? subPlatforms : LingxingSubPlatformDefaults.all(transport, json); + this.outboundOrderSource = new WmsOutboundOrderSource(); + this.labelSource = new WmsLabelSource(); + this.shipmentReviewSource = new ShipmentReviewSource(); + this.orderEditSource = new OrderEditSource(); } @Override @@ -132,7 +165,9 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @Override public EnumSet capabilities() { - return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.BILLING, Capability.MARK_SHIPPED); + return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.BILLING, + Capability.MARK_SHIPPED, Capability.OUTBOUND_ORDER, Capability.LABEL, + Capability.SHIPMENT_REVIEW, Capability.ORDER_EDIT); } /** @@ -163,6 +198,19 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, if (capability == Capability.MARK_SHIPPED) { return impl.outboundSource() != null; } + // ERP 级接口(出库单 / 面单 / 审核发货)不按子平台区分,平台登记即支持 + if (capability == Capability.OUTBOUND_ORDER) { + return outboundOrderSource != null; + } + if (capability == Capability.LABEL) { + return labelSource != null; + } + if (capability == Capability.SHIPMENT_REVIEW) { + return shipmentReviewSource != null; + } + if (capability == Capability.ORDER_EDIT) { + return orderEditSource != null; + } return false; } @@ -259,6 +307,30 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, return source; } + /** 销售出库单列表(ERP 级,按店铺过滤)。 */ + @Override + public Page pull(ChannelContext ctx, OutboundOrderQuery query) { + return outboundOrderSource.outboundOrders(call(ctx), query); + } + + /** 销售出库单物流面单。 */ + @Override + public List labels(ChannelContext ctx, LabelQuery query) { + return labelSource.labels(call(ctx), query); + } + + /** 审核发货;逐单成败在返回值里,不靠异常表达。 */ + @Override + public ShipmentReviewResult review(ChannelContext ctx, List globalOrderNos) { + return shipmentReviewSource.review(call(ctx), globalOrderNos); + } + + /** 批量编辑订单(仓库 / 物流方式 / 包裹规格 / 报关)。 */ + @Override + public OrderEditResult edit(ChannelContext ctx, List requests) { + return orderEditSource.edit(call(ctx), requests); + } + @Override public ProductSyncStrategy syncStrategy() { // 亚马逊 Listing 支持按「All Listing 报表更新时间」增量;其它子平台接入时再各自声明 diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingLabelSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingLabelSource.java new file mode 100644 index 0000000..4022a18 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingLabelSource.java @@ -0,0 +1,17 @@ +package common.ecommerce.lingxing.platform; + +import common.ecommerce.model.fulfillment.LabelQuery; +import common.ecommerce.model.fulfillment.ShippingLabel; + +import java.util.List; + +/** + * 物流面单能力。 + * + *

领星按销售出库单号或系统单号批量返回 base64 面单,不区分平台。

+ */ +public interface LingxingLabelSource { + + /** 批量取面单。 */ + List labels(LingxingCall call, LabelQuery query); +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderEditSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderEditSource.java new file mode 100644 index 0000000..67343b8 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderEditSource.java @@ -0,0 +1,17 @@ +package common.ecommerce.lingxing.platform; + +import common.ecommerce.model.fulfillment.OrderEditRequest; +import common.ecommerce.model.fulfillment.OrderEditResult; + +import java.util.List; + +/** + * 订单编辑能力(仓库 / 物流方式 / 包裹规格 / 报关)。 + * + *

写操作;按领星系统单号批量编辑待审核的自发货订单。

+ */ +public interface LingxingOrderEditSource { + + /** 批量编辑订单。 */ + OrderEditResult edit(LingxingCall call, List requests); +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOutboundOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOutboundOrderSource.java new file mode 100644 index 0000000..018bebb --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOutboundOrderSource.java @@ -0,0 +1,16 @@ +package common.ecommerce.lingxing.platform; + +import common.ecommerce.model.fulfillment.OutboundOrder; +import common.ecommerce.model.fulfillment.OutboundOrderQuery; +import common.ecommerce.model.support.Page; + +/** + * 子平台 / 账户的销售出库单能力。 + * + *

领星这套接口不带平台维度,按当前账户的店铺 id 过滤,因此所有子平台共用同一实现。

+ */ +public interface LingxingOutboundOrderSource { + + /** 分页拉取销售出库单。 */ + Page outboundOrders(LingxingCall call, OutboundOrderQuery query); +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingShipmentReviewSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingShipmentReviewSource.java new file mode 100644 index 0000000..d300c8e --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingShipmentReviewSource.java @@ -0,0 +1,16 @@ +package common.ecommerce.lingxing.platform; + +import common.ecommerce.model.fulfillment.ShipmentReviewResult; + +import java.util.List; + +/** + * 审核发货能力。 + * + *

写操作;按领星系统单号批量推进订单状态。

+ */ +public interface LingxingShipmentReviewSource { + + /** 批量审核发货。 */ + ShipmentReviewResult review(LingxingCall call, List globalOrderNos); +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/OrderEditSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/OrderEditSource.java new file mode 100644 index 0000000..295e4d9 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/OrderEditSource.java @@ -0,0 +1,152 @@ +package common.ecommerce.lingxing.platform.wms; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.ValidationException; +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.Responses; +import common.ecommerce.lingxing.LingxingApi; +import common.ecommerce.lingxing.LingxingConstants; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.LingxingOrderEditSource; +import common.ecommerce.lingxing.platform.wms.dto.OrderEditErrorDto; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.fulfillment.DeclaredItem; +import common.ecommerce.model.fulfillment.OrderEditRequest; +import common.ecommerce.model.fulfillment.OrderEditResult; + +import java.math.BigDecimal; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 领星 · 编辑订单({@code POST /pb/mp/order/editOrder})。 + * + *

单次 1~50 单,可分别编辑仓库、物流方式、包裹预估规格与报关信息。

+ * + *

业务码不能交给 {@code LingxingEnvelope} 判:这个接口用 + * {@code 0} / {@code 10000} / {@code 10001} 表示「全成功 / 全失败 / 部分成功」, + * 都属于正常响应,逐单原因在 {@code data.error_details[]}。 + * 只有其它码(限流、token 失效、参数错误)才走统一信封抛异常。

+ */ +public final class OrderEditSource implements LingxingOrderEditSource { + + private static final String OP = "orders.edit"; + + private static final String CODE_SUCCESS = "0"; + private static final String CODE_ALL_FAILED = "10000"; + private static final String CODE_PARTIAL = "10001"; + + @Override + public OrderEditResult edit(LingxingCall call, List requests) { + if (requests == null || requests.isEmpty()) { + throw validation(call, "requests must not be empty"); + } + if (requests.size() > LingxingConstants.ORDER_EDIT_MAX_BATCH) { + throw validation(call, "at most " + LingxingConstants.ORDER_EDIT_MAX_BATCH + + " orders per call, got " + requests.size()); + } + + List> orderList = new ArrayList>(requests.size()); + for (OrderEditRequest request : requests) { + orderList.add(toBody(request)); + } + Map payload = new LinkedHashMap(); + payload.put("order_list", orderList); + + HttpRequest req = call.signed(LingxingApi.ORDER_EDIT, payload, OP); + HttpResponse resp = call.execute(req); + Responses.throwIfNotSuccess(resp, OP); + + String body = resp.body(); + String code = call.json().stringAt(body, "code"); + if (!CODE_SUCCESS.equals(code) && !CODE_ALL_FAILED.equals(code) && !CODE_PARTIAL.equals(code)) { + // 非业务结果码:交给统一信封抛限流 / 鉴权 / 业务异常 + call.envelope(resp, OP); + // 信封认为成功但码不在预期集合里(如 "200"),按业务失败处理 + throw validation(call, "unexpected lingxing code=" + code + " on " + OP); + } + + List errors = + call.json().listAt(body, "data.error_details", OrderEditErrorDto.class); + List failures = new ArrayList(errors.size()); + for (OrderEditErrorDto error : errors) { + failures.add(new OrderEditResult.Failure(error.getGlobalOrderNo(), error.getErrorMessage())); + } + return OrderEditResult.builder() + .code(code) + .message(call.json().stringAt(body, "message")) + .failures(failures) + .build(); + } + + /** 统一模型 → 领星请求体;为空的维度不发送,未发送即保持平台原值。 */ + private static Map toBody(OrderEditRequest request) { + Map item = new LinkedHashMap(); + item.put("global_order_no", request.globalOrderNo()); + + Map logistics = new LinkedHashMap(); + putIfNotNull(logistics, "sys_wid", request.warehouseId()); + putIfNotNull(logistics, "logistics_type_id", request.logisticsTypeId()); + putIfNotNull(logistics, "pre_pkg_length", decimal(request.packageLength())); + putIfNotNull(logistics, "pre_pkg_width", decimal(request.packageWidth())); + putIfNotNull(logistics, "pre_pkg_height", decimal(request.packageHeight())); + putIfNotNull(logistics, "pre_weight", decimal(request.packageWeight())); + if (!logistics.isEmpty()) { + item.put("logistics", logistics); + } + + if (request.modifyDeclared()) { + item.put("modify_declared", 1); + List> declared = new ArrayList>( + request.declaredItems().size()); + for (DeclaredItem declaredItem : request.declaredItems()) { + declared.add(toBody(declaredItem)); + } + item.put("declared_info", declared); + } + return item; + } + + private static Map toBody(DeclaredItem item) { + Map body = new LinkedHashMap(); + body.put("sku", item.sku()); + if (item.id() != null && item.id() > 0) { + body.put("id", item.id()); + } + body.put("cn_name", item.cnName()); + body.put("en_name", item.enName()); + // 文档要求 unit_price / weight 是数字字符串,用 toPlainString 避免科学计数法 + body.put("unit_price", decimal(item.unitPrice())); + body.put("currency_code", item.currencyCode()); + body.put("weight", decimal(item.weight())); + body.put("quantity", item.quantity()); + if (item.hsCode() != null && !item.hsCode().trim().isEmpty()) { + body.put("hs_code", item.hsCode().trim()); + } + body.put("special_attr", new ArrayList(item.specialAttributes())); + return body; + } + + private static String decimal(BigDecimal value) { + return value == null ? null : value.toPlainString(); + } + + private static void putIfNotNull(Map body, String key, Object value) { + if (value != null) { + body.put(key, value); + } + } + + private static ValidationException validation(LingxingCall call, String message) { + return new ValidationException(ChannelException.builder() + .message(message) + .operation(OP) + .provider(ChannelProvider.LINGXING.name()) + .omsStoreId(call.ctx().omsStoreId()) + .requestId(call.ctx().requestId()) + .retryable(false)); + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/ShipmentReviewSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/ShipmentReviewSource.java new file mode 100644 index 0000000..0fb8816 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/ShipmentReviewSource.java @@ -0,0 +1,90 @@ +package common.ecommerce.lingxing.platform.wms; + +import com.fasterxml.jackson.databind.JsonNode; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.ValidationException; +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.lingxing.LingxingApi; +import common.ecommerce.lingxing.http.LingxingEnvelope; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.LingxingShipmentReviewSource; +import common.ecommerce.lingxing.platform.wms.dto.ShipmentReviewDataDto; +import common.ecommerce.lingxing.platform.wms.dto.ShipmentReviewFailureDto; +import common.ecommerce.lingxing.platform.wms.dto.ShipmentReviewSuccessDto; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.fulfillment.ShipmentReviewResult; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 领星 · 审核发货 + * ({@code POST /basicOpen/openapi/multiplatform/order/review})。 + * + *

对「订单管理 > 待审核发货」的订单推进状态;接口本身返回 {@code code=0}, + * 但单笔成败在 {@code data.success_info[]} / {@code data.failure_info[]} 里, + * 所以调用方必须逐单判断,不能只看 {@code code}。

+ * + *

文档未给出批量上限,这里不自行加限;只拒绝空列表,避免发出无意义请求。

+ */ +public final class ShipmentReviewSource implements LingxingShipmentReviewSource { + + private static final String OP = "shipments.review"; + + @Override + public ShipmentReviewResult review(LingxingCall call, List globalOrderNos) { + if (globalOrderNos == null || globalOrderNos.isEmpty()) { + throw validation(call, "globalOrderNos must not be empty"); + } + + Map body = new LinkedHashMap(); + body.put("global_order_no", new ArrayList(globalOrderNos)); + + HttpRequest req = call.signed(LingxingApi.ORDER_REVIEW, body, OP); + HttpResponse resp = call.execute(req); + LingxingEnvelope envelope = call.envelope(resp, OP); + + JsonNode data = call.json().nodeAt(envelope.body(), "data"); + ShipmentReviewDataDto dto = data == null || data.isNull() + ? new ShipmentReviewDataDto() + : call.json().mapper().convertValue(data, ShipmentReviewDataDto.class); + + List ok = dto.getSuccessInfo() == null + ? new ArrayList() : dto.getSuccessInfo(); + List fail = dto.getFailureInfo() == null + ? new ArrayList() : dto.getFailureInfo(); + + List successNos = new ArrayList(ok.size()); + for (ShipmentReviewSuccessDto item : ok) { + successNos.add(item.getGlobalOrderNo()); + } + List failures = new ArrayList(fail.size()); + for (ShipmentReviewFailureDto item : fail) { + failures.add(new ShipmentReviewResult.Failure(item.getGlobalOrderNo(), item.getMessage())); + } + + // 计数缺失时用明细行数兜底,不把「没给计数」当成 0 + int successNum = dto.getSuccessNum() == null ? successNos.size() : dto.getSuccessNum(); + int failNum = dto.getFailNum() == null ? failures.size() : dto.getFailNum(); + return ShipmentReviewResult.builder() + .successNum(successNum) + .failNum(failNum) + .successGlobalOrderNos(successNos) + .failures(failures) + .build(); + } + + private static ValidationException validation(LingxingCall call, String message) { + return new ValidationException(ChannelException.builder() + .message(message) + .operation(OP) + .provider(ChannelProvider.LINGXING.name()) + .omsStoreId(call.ctx().omsStoreId()) + .requestId(call.ctx().requestId()) + .retryable(false)); + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsLabelSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsLabelSource.java new file mode 100644 index 0000000..3b0eb10 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsLabelSource.java @@ -0,0 +1,84 @@ +package common.ecommerce.lingxing.platform.wms; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.ValidationException; +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.lingxing.LingxingApi; +import common.ecommerce.lingxing.LingxingConstants; +import common.ecommerce.lingxing.http.LingxingEnvelope; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.LingxingLabelSource; +import common.ecommerce.lingxing.platform.wms.dto.WmsLogisticsLabelDto; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.fulfillment.LabelQuery; +import common.ecommerce.model.fulfillment.ShippingLabel; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 领星 · 销售出库单物流面单 + * ({@code POST /erp/sc/routing/wms/order/getWmsLogisticsLabels})。 + * + *

销售出库单号与系统单号二选一,各自上限 50。两组都传平台只认其中一组, + * 所以这里显式拒绝,避免调用方以为两组都生效。

+ * + *

返回的 {@code file_b64} 可能为空串(面单还没生成),SDK 原样返回,不补空、不重试。

+ */ +public final class WmsLabelSource implements LingxingLabelSource { + + private static final String OP = "shippingLabels.list"; + + @Override + public List labels(LingxingCall call, LabelQuery query) { + boolean hasWo = !query.woNumbers().isEmpty(); + boolean hasOrder = !query.orderNumbers().isEmpty(); + if (hasWo == hasOrder) { + throw validation(call, "exactly one of woNumbers / orderNumbers must be provided"); + } + + List values = hasWo ? query.woNumbers() : query.orderNumbers(); + if (values.size() > LingxingConstants.LABEL_MAX_BATCH) { + throw validation(call, "at most " + LingxingConstants.LABEL_MAX_BATCH + + " numbers per call, got " + values.size()); + } + + Map body = new LinkedHashMap(); + body.put(hasWo ? "wo_number_arr" : "order_number_arr", new ArrayList(values)); + + HttpRequest req = call.signed(LingxingApi.LOGISTICS_LABEL_LIST, body, OP); + HttpResponse resp = call.execute(req); + LingxingEnvelope envelope = call.envelope(resp, OP); + + List dtos = call.json().listAt(envelope.body(), "data", WmsLogisticsLabelDto.class); + List labels = new ArrayList(dtos.size()); + for (WmsLogisticsLabelDto dto : dtos) { + labels.add(ShippingLabel.builder() + .omsStoreId(call.ctx().omsStoreId()) + .sourceProvider(ChannelProvider.LINGXING) + .woNumber(dto.getWoNumber()) + .orderNumber(dto.getOrderNumber()) + .logisticsProviderId(dto.getLogisticsProviderId()) + .logisticsTypeId(dto.getLogisticsTypeId()) + .fileId(dto.getFileId()) + .fileType(dto.getFileType()) + .fileSize(dto.getFileSize()) + .contentBase64(dto.getFileB64()) + .build()); + } + return labels; + } + + private static ValidationException validation(LingxingCall call, String message) { + return new ValidationException(ChannelException.builder() + .message(message) + .operation(OP) + .provider(ChannelProvider.LINGXING.name()) + .omsStoreId(call.ctx().omsStoreId()) + .requestId(call.ctx().requestId()) + .retryable(false)); + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsOutboundOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsOutboundOrderSource.java new file mode 100644 index 0000000..b4a6b82 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsOutboundOrderSource.java @@ -0,0 +1,290 @@ +package common.ecommerce.lingxing.platform.wms; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.ValidationException; +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.lingxing.LingxingApi; +import common.ecommerce.lingxing.LingxingConstants; +import common.ecommerce.lingxing.http.LingxingEnvelope; +import common.ecommerce.lingxing.mapper.LingxingOrderMapper; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.LingxingOutboundOrderSource; +import common.ecommerce.lingxing.platform.wms.dto.WmsOutboundOrderDto; +import common.ecommerce.lingxing.platform.wms.dto.WmsOutboundOrderItemDto; +import common.ecommerce.lingxing.platform.wms.dto.WmsSurfaceFileDto; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.fulfillment.OutboundOrder; +import common.ecommerce.model.fulfillment.OutboundOrderLine; +import common.ecommerce.model.fulfillment.OutboundOrderQuery; +import common.ecommerce.model.support.Money; +import common.ecommerce.model.support.Page; +import common.ecommerce.model.support.PlatformTime; + +import java.time.Instant; +import java.time.LocalDateTime; +import java.time.ZoneId; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 领星 · 销售出库单列表 + * ({@code POST /erp/sc/routing/wms/order/wmsOrderList})。 + * + *

接口不带平台维度,按店铺 {@code sid_arr} 过滤,因此所有子平台共用同一实现: + * 默认用当前账户的 {@code externalStoreId},调用方也可以用 + * {@link OutboundOrderQuery#sids()} 覆盖。

+ * + *

分页是 {@code page} / {@code page_size}(上限 200),游标存的是字符串化的页码, + * 与 order 类接口的 offset 游标不同。

+ * + *

时间窗按 ERP 系统时间(北京时间)解释,格式 {@code Y-m-d}; + * 不传时由领星按「最近一个月」处理。

+ */ +public final class WmsOutboundOrderSource implements LingxingOutboundOrderSource { + + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + /** 领星用全零占位表示「没有时间」。 */ + private static final String ZERO_DATE_TIME = "0000-00-00 00:00:00"; + + /** 文档未注明时区,按 ERP 系统时间(北京时间)解释。 */ + private static final ZoneId SYSTEM_ZONE = PlatformTime.BEIJING_ZONE; + + private static final List TIME_TYPES = Collections.unmodifiableList(Arrays.asList( + OutboundOrderQuery.TIME_CREATED, + OutboundOrderQuery.TIME_DELIVERED, + OutboundOrderQuery.TIME_STOCK_DELIVERED, + OutboundOrderQuery.TIME_UPDATED)); + + private static final String OP = "outboundOrders.pull"; + + @Override + public Page outboundOrders(LingxingCall call, OutboundOrderQuery query) { + ChannelAccount account = call.ctx().account(); + String timeType = query.timeType() == null ? OutboundOrderQuery.TIME_UPDATED : query.timeType(); + if (!TIME_TYPES.contains(timeType)) { + throw validation(call, OP, "unsupported time_type: " + timeType); + } + + int pageSize = query.pageSize() <= 0 ? 20 + : Math.min(query.pageSize(), LingxingConstants.OUTBOUND_ORDER_MAX_PAGE_SIZE); + int page = query.cursor() == null ? 1 : Integer.parseInt(query.cursor()); + + Map body = new LinkedHashMap(); + body.put("page", page); + body.put("page_size", pageSize); + body.put("time_type", timeType); + putIfNotEmpty(body, "sid_arr", resolveSids(call, query)); + putIfNotEmpty(body, "status_arr", query.statuses()); + putIfNotEmpty(body, "logistics_status_arr", query.logisticsStatuses()); + putIfNotEmpty(body, "platform_order_no_arr", query.platformOrderNos()); + putIfNotEmpty(body, "order_number_arr", query.orderNumbers()); + putIfNotEmpty(body, "wo_number_arr", query.woNumbers()); + if (query.after() != null) { + body.put("start_date", DATE.format(LocalDateTime.ofInstant(query.after(), SYSTEM_ZONE))); + } + if (query.before() != null) { + body.put("end_date", DATE.format(LocalDateTime.ofInstant(query.before(), SYSTEM_ZONE))); + } + + HttpRequest req = call.signed(LingxingApi.OUTBOUND_ORDER_LIST, body, OP); + HttpResponse resp = call.execute(req); + LingxingEnvelope envelope = call.envelope(resp, OP); + + List dtos = call.json().listAt(envelope.body(), "data", WmsOutboundOrderDto.class); + ZoneId zone = ZoneId.of(account.marketplaceZone()); + List orders = new ArrayList(dtos.size()); + for (WmsOutboundOrderDto dto : dtos) { + try { + orders.add(toOutboundOrder(dto, call, account, zone)); + } catch (RuntimeException e) { + throw mappingFailure(e, envelope, call); + } + } + + boolean hasMore = dtos.size() >= pageSize + && (envelope.total() < 0 || (long) page * pageSize < envelope.total()); + return Page.of(orders, hasMore ? String.valueOf(page + 1) : null); + } + + /** + * 店铺过滤:调用方显式给了 {@code sids} 就用它,否则用当前账户的店铺。 + * + *

账户店铺 id 不是数字时显式失败:不带 {@code sid_arr} 会返回该 app 下 + * 所有店铺的出库单,等于跨店铺泄露数据。

+ */ + private static List resolveSids(LingxingCall call, OutboundOrderQuery query) { + if (!query.sids().isEmpty()) { + List sids = new ArrayList(query.sids().size()); + for (String raw : query.sids()) { + Long sid = parseLong(raw); + if (sid == null) { + throw validation(call, OP, "sid must be numeric: " + raw); + } + sids.add(sid); + } + return sids; + } + Long sid = parseLong(call.ctx().account().externalStoreId()); + if (sid == null) { + throw validation(call, OP, "account externalStoreId is not a numeric lingxing sid: " + + call.ctx().account().externalStoreId() + "; set OutboundOrderQuery.sids explicitly"); + } + return Collections.singletonList(sid); + } + + private static OutboundOrder toOutboundOrder(WmsOutboundOrderDto dto, LingxingCall call, + ChannelAccount account, ZoneId zone) { + WmsSurfaceFileDto surface = dto.getSurfaceFile(); + return OutboundOrder.builder() + .omsStoreId(call.ctx().omsStoreId()) + .sourceProvider(ChannelProvider.LINGXING) + .sourceAccountId(dto.getSid() == null ? null : String.valueOf(dto.getSid())) + .woNumber(dto.getWoNumber()) + .woId(dto.getWoId() == null ? null : String.valueOf(dto.getWoId())) + .orderNumber(trimToNull(dto.getOrderNumber())) + .platformOrderNos(safe(dto.getPlatformOrderNo())) + .sid(dto.getSid()) + .sellerName(trimToNull(dto.getSellerName())) + .warehouseId(dto.getWid()) + .warehouseName(trimToNull(dto.getWarehouseName())) + .warehouseType(dto.getWarehouseType()) + .status(dto.getStatus()) + .statusName(trimToNull(dto.getStatusName())) + .logisticsStatus(dto.getLogisticsStatus()) + .logisticsStatusName(trimToNull(dto.getLogisticsStatusName())) + .logisticsMessage(trimToNull(dto.getLogisticsMessage())) + .logisticsProviderId(dto.getLogisticsProviderId()) + .logisticsProviderName(trimToNull(dto.getLogisticsProviderName())) + .logisticsTypeId(dto.getLogisticsTypeId()) + .logisticsTypeName(trimToNull(dto.getLogisticsTypeName())) + .waybillNo(trimToNull(dto.getWaybillNo())) + .trackingNo(trimToNull(dto.getTrackingNo())) + .orderAmount(moneyOrNull(dto.getOrderOriginAmount(), dto.getOrderCurrencyCode())) + .targetCountry(trimToNull(dto.getTargetCountry())) + .packageWeight(trimToNull(dto.getPkgWeight())) + .packageRealWeight(trimToNull(dto.getPkgRealWeight())) + .packageFeeWeight(trimToNull(dto.getPkgFeeWeight())) + .packageWeightUnit(trimToNull(dto.getPkgWeightUnit())) + .surfaceFileUrl(surfaceUrl(surface)) + .createdAt(platformTime(dto.getCreateAt(), zone)) + .updatedAt(platformTime(dto.getUpdateAt(), zone)) + .deliveredAt(platformTime(dto.getDeliveredAt(), zone)) + .purchasedAt(platformTime(dto.getPurchaseTime(), zone)) + .lines(toLines(dto.getProductInfo())) + .build(); + } + + private static List toLines(List items) { + List lines = new ArrayList(items.size()); + for (WmsOutboundOrderItemDto item : items) { + lines.add(OutboundOrderLine.builder() + .lineId(item.getWodId() == null ? null : String.valueOf(item.getWodId())) + .productId(item.getProductId() == null ? null : String.valueOf(item.getProductId())) + .sku(trimToNull(item.getSku())) + .sellerSku(trimToNull(item.getSellerSku())) + .productName(trimToNull(item.getProductName())) + .quantity(item.getCount() == null ? 0 : item.getCount()) + .unitPrice(moneyOrNull(item.getUnitPrice(), item.getCurrencyCode())) + .build()); + } + return lines; + } + + private static PlatformTime platformTime(String value, ZoneId zone) { + Instant instant = parseDateTime(value); + return instant == null ? null : PlatformTime.of(instant, zone); + } + + /** 面单链接:优先 COS(30 分钟有效),旧 {@code uri} 仅兜底。 */ + private static String surfaceUrl(WmsSurfaceFileDto surface) { + if (surface == null) { + return null; + } + String cos = trimToNull(surface.getCosUrl()); + return cos != null ? cos : trimToNull(surface.getUri()); + } + + private static Instant parseDateTime(String value) { + String text = trimToNull(value); + if (text == null || ZERO_DATE_TIME.equals(text)) { + return null; + } + LocalDateTime local = LocalDateTime.parse(text, DATE_TIME); + return local.atZone(SYSTEM_ZONE).toInstant(); + } + + /** + * 金额映射。 + * + *

领星商品行里的 {@code currency_code} 可能是符号(文档示例是 {@code $}), + * 不是 ISO 代码,此时只保留金额无意义,直接返回 null,不猜币种。

+ */ + private static Money moneyOrNull(String amount, String currency) { + String cleaned = LingxingOrderMapper.cleanAmount(amount); + String code = trimToNull(currency); + if (cleaned == null || code == null || !code.matches("[A-Za-z]{3}")) { + return null; + } + return Money.of(cleaned, code.toUpperCase()); + } + + private static void putIfNotEmpty(Map body, String key, List values) { + if (values != null && !values.isEmpty()) { + body.put(key, values); + } + } + + private static Long parseLong(String value) { + String text = trimToNull(value); + if (text == null) { + return null; + } + try { + return Long.valueOf(text); + } catch (NumberFormatException e) { + return null; + } + } + + private static List safe(List in) { + return in == null ? Collections.emptyList() : in; + } + + private static String trimToNull(String value) { + if (value == null) { + return null; + } + String trimmed = value.trim(); + return trimmed.isEmpty() ? null : trimmed; + } + + private static ValidationException validation(LingxingCall call, String operation, String message) { + return new ValidationException(ChannelException.builder() + .message(message) + .operation(operation) + .provider(ChannelProvider.LINGXING.name()) + .omsStoreId(call.ctx().omsStoreId()) + .requestId(call.ctx().requestId()) + .retryable(false)); + } + + private static ValidationException mappingFailure(RuntimeException e, LingxingEnvelope envelope, + LingxingCall call) { + return new ValidationException(ChannelException.builder() + .message("lingxing outbound order mapping failed: " + e.getMessage()) + .operation(OP) + .provider(ChannelProvider.LINGXING.name()) + .omsStoreId(call.ctx().omsStoreId()) + .requestId(call.ctx().requestId()) + .rawResponse(envelope.body()), e); + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/OrderEditErrorDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/OrderEditErrorDto.java new file mode 100644 index 0000000..efc3570 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/OrderEditErrorDto.java @@ -0,0 +1,24 @@ +package common.ecommerce.lingxing.platform.wms.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** + * 编辑订单的逐单错误({@code data.error_details[]})。 + * + *

平台把 {@code global_order_no} 作为 long 返回,这里按字符串接收, + * 避免超出 JS/JavaScript 与 double 的安全整数范围。

+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class OrderEditErrorDto { + + @JsonProperty("global_order_no") + private String globalOrderNo; + + @JsonProperty("error_message") + private String errorMessage; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewDataDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewDataDto.java new file mode 100644 index 0000000..be3b9f5 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewDataDto.java @@ -0,0 +1,33 @@ +package common.ecommerce.lingxing.platform.wms.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +import java.util.ArrayList; +import java.util.List; + +/** + * 审核发货响应体({@code data})。 + * + *

接口按单返回结果:{@code success_num} / {@code fail_num} 是计数, + * 逐单明细在 {@code success_info} / {@code failure_info} 里。

+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class ShipmentReviewDataDto { + + @JsonProperty("success_num") + private Integer successNum; + + @JsonProperty("fail_num") + private Integer failNum; + + @JsonProperty("success_info") + private List successInfo = new ArrayList(); + + @JsonProperty("failure_info") + private List failureInfo = new ArrayList(); +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewFailureDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewFailureDto.java new file mode 100644 index 0000000..4db6595 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewFailureDto.java @@ -0,0 +1,21 @@ +package common.ecommerce.lingxing.platform.wms.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** 审核发货失败项({@code data.failure_info[]})。 */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class ShipmentReviewFailureDto { + + /** 系统单号。 */ + @JsonProperty("global_order_no") + private String globalOrderNo; + + /** 失败原因,如「未设置物流」。 */ + @JsonProperty("message") + private String message; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewSuccessDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewSuccessDto.java new file mode 100644 index 0000000..ee77ef0 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewSuccessDto.java @@ -0,0 +1,17 @@ +package common.ecommerce.lingxing.platform.wms.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** 审核发货成功项({@code data.success_info[]})。 */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class ShipmentReviewSuccessDto { + + /** 系统单号。 */ + @JsonProperty("global_order_no") + private String globalOrderNo; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsLogisticsLabelDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsLogisticsLabelDto.java new file mode 100644 index 0000000..afd6594 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsLogisticsLabelDto.java @@ -0,0 +1,47 @@ +package common.ecommerce.lingxing.platform.wms.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** + * 领星 · 销售出库单物流面单 + * ({@code /erp/sc/routing/wms/order/getWmsLogisticsLabels} 的 {@code data[]})。 + * + *

面单内容以 base64 返回,SDK 不落文件。

+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class WmsLogisticsLabelDto { + + /** 销售出库单号。 */ + @JsonProperty("wo_number") + private String woNumber; + + /** 领星系统单号。 */ + @JsonProperty("order_number") + private String orderNumber; + + @JsonProperty("logistics_provider_id") + private Long logisticsProviderId; + + @JsonProperty("logistics_type_id") + private Long logisticsTypeId; + + @JsonProperty("file_id") + private Long fileId; + + /** 文件类型,如 pdf。 */ + @JsonProperty("file_type") + private String fileType; + + /** 文件尺寸。 */ + @JsonProperty("file_size") + private String fileSize; + + /** 面单 base64。 */ + @JsonProperty("file_b64") + private String fileB64; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderDto.java new file mode 100644 index 0000000..b73962c --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderDto.java @@ -0,0 +1,162 @@ +package common.ecommerce.lingxing.platform.wms.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +import java.util.ArrayList; +import java.util.List; + +/** + * 领星 · 销售出库单 + * ({@code /erp/sc/routing/wms/order/wmsOrderList} 的 {@code data[]})。 + * + *

主键是 {@code wo_number}(销售出库单号),{@code order_number} 才是领星系统单号。

+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class WmsOutboundOrderDto { + + /** 出库单 id。 */ + @JsonProperty("wo_id") + private Long woId; + + /** 销售出库单号。 */ + @JsonProperty("wo_number") + private String woNumber; + + /** 店铺 id(领星内部 sid)。 */ + @JsonProperty("sid") + private Integer sid; + + @JsonProperty("seller_name") + private String sellerName; + + /** 站点名称,如 [Amazon].美国。 */ + @JsonProperty("site_text") + private String siteText; + + @JsonProperty("wid") + private Integer wid; + + @JsonProperty("warehouse_name") + private String warehouseName; + + /** 仓库类型:1 本地仓库、2 FBA 仓、3 第三方海外仓。 */ + @JsonProperty("warehouse_type") + private Integer warehouseType; + + /** 下单流程:1 物流、2 海外仓、3 仓配分离。 */ + @JsonProperty("logistics_way") + private Integer logisticsWay; + + @JsonProperty("batch_no") + private String batchNo; + + @JsonProperty("reference_no") + private String referenceNo; + + /** 运单号。 */ + @JsonProperty("waybill_no") + private String waybillNo; + + /** 跟踪号。 */ + @JsonProperty("tracking_no") + private String trackingNo; + + @JsonProperty("picker") + private String picker; + + @JsonProperty("platform_name") + private String platformName; + + /** 平台单号,数组。 */ + @JsonProperty("platform_order_no") + private List platformOrderNo = new ArrayList(); + + /** 领星系统单号。 */ + @JsonProperty("order_number") + private String orderNumber; + + @JsonProperty("order_from") + private String orderFrom; + + /** 订单类型:1 一单一件、2 多品多件、3 单品多件。 */ + @JsonProperty("order_type") + private Integer orderType; + + @JsonProperty("order_origin_amount") + private String orderOriginAmount; + + @JsonProperty("order_currency_code") + private String orderCurrencyCode; + + /** 出库单状态:1 物流下单、2 待出库、3 已出库、4 已截单。 */ + @JsonProperty("status") + private Integer status; + + @JsonProperty("status_name") + private String statusName; + + /** 物流下单状态。 */ + @JsonProperty("logistics_status") + private Integer logisticsStatus; + + @JsonProperty("logistics_status_name") + private String logisticsStatusName; + + @JsonProperty("logistics_message") + private String logisticsMessage; + + @JsonProperty("logistics_provider_id") + private Long logisticsProviderId; + + @JsonProperty("logistics_provider_name") + private String logisticsProviderName; + + @JsonProperty("logistics_type_id") + private Long logisticsTypeId; + + @JsonProperty("logistics_type_name") + private String logisticsTypeName; + + @JsonProperty("target_country") + private String targetCountry; + + @JsonProperty("pkg_weight") + private String pkgWeight; + + @JsonProperty("pkg_real_weight") + private String pkgRealWeight; + + @JsonProperty("pkg_fee_weight") + private String pkgFeeWeight; + + @JsonProperty("pkg_weight_unit") + private String pkgWeightUnit; + + /** 面单文件。 */ + @JsonProperty("surface_file") + private WmsSurfaceFileDto surfaceFile; + + @JsonProperty("delivered_at") + private String deliveredAt; + + @JsonProperty("stock_delivered_at") + private String stockDeliveredAt; + + @JsonProperty("create_at") + private String createAt; + + @JsonProperty("update_at") + private String updateAt; + + @JsonProperty("purchase_time") + private String purchaseTime; + + /** 商品行。 */ + @JsonProperty("product_info") + private List productInfo = new ArrayList(); +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderItemDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderItemDto.java new file mode 100644 index 0000000..7e59f74 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderItemDto.java @@ -0,0 +1,51 @@ +package common.ecommerce.lingxing.platform.wms.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** + * 领星 · 销售出库单商品行({@code product_info[]})。 + * + *

{@code sku} 是领星本地 SKU,{@code seller_sku} 才是平台 MSKU,两者不要混用。

+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class WmsOutboundOrderItemDto { + + /** 出库单明细 id。 */ + @JsonProperty("wod_id") + private Long wodId; + + @JsonProperty("product_id") + private Long productId; + + /** 领星本地 SKU。 */ + @JsonProperty("sku") + private String sku; + + /** 平台 MSKU。 */ + @JsonProperty("seller_sku") + private String sellerSku; + + @JsonProperty("product_name") + private String productName; + + @JsonProperty("count") + private Integer count; + + @JsonProperty("unit_price") + private String unitPrice; + + /** 币种;领星可能给符号而非代码。 */ + @JsonProperty("currency_code") + private String currencyCode; + + @JsonProperty("item_unit_price") + private String itemUnitPrice; + + @JsonProperty("item_total_price") + private String itemTotalPrice; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsSurfaceFileDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsSurfaceFileDto.java new file mode 100644 index 0000000..e744407 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsSurfaceFileDto.java @@ -0,0 +1,34 @@ +package common.ecommerce.lingxing.platform.wms.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** + * 领星 · 出库单面单文件({@code surface_file})。 + * + *

{@code cos_url} 是 30 分钟有效的 COS 链接,过期后需要重新查询; + * {@code uri} 官方已标记废弃,只做兜底。

+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class WmsSurfaceFileDto { + + /** COS 地址链接,30 分钟有效。 */ + @JsonProperty("cos_url") + private String cosUrl; + + /** 旧链接,已废弃。 */ + @JsonProperty("uri") + private String uri; + + /** 文件后缀,如 pdf。 */ + @JsonProperty("ext") + private String ext; + + /** 文件尺寸。 */ + @JsonProperty("size") + private String size; +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java index ec7bb17..4f7336d 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java @@ -12,6 +12,11 @@ import common.ecommerce.model.ChannelProvider; import common.ecommerce.model.Platform; import common.ecommerce.model.account.AccountKey; import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.fulfillment.LabelQuery; +import common.ecommerce.model.fulfillment.OutboundOrder; +import common.ecommerce.model.fulfillment.OutboundOrderLine; +import common.ecommerce.model.fulfillment.OutboundOrderQuery; +import common.ecommerce.model.fulfillment.ShippingLabel; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.model.order.SalesOrderQuery; import common.ecommerce.model.order.SalesOrderRef; @@ -32,6 +37,7 @@ import java.time.Clock; import java.time.Duration; import java.time.Instant; import java.time.LocalDate; +import java.util.ArrayList; import java.util.List; import static org.junit.jupiter.api.Assertions.assertFalse; @@ -64,6 +70,9 @@ class LingxingLiveSmokeTest { private static final int PLATFORM_CODE = 10008; private static final String BASE_URL = LingxingConstants.PRODUCTION_BASE_URL; + /** 面单冒烟只取前几单,避免把大段 base64 刷到控制台。 */ + private static final int LABEL_SMOKE_LIMIT = 5; + private final JacksonJsonCodec json = new JacksonJsonCodec(); private final LoggingTransport transport = new LoggingTransport(new OkHttpTransport("common-ecommerce-smoke")); private final InMemoryTokenStore tokenStore = new InMemoryTokenStore(); @@ -346,8 +355,126 @@ class LingxingLiveSmokeTest { } } + /** + * 第 7 步(仓库):拉一页销售出库单,打印单据与商品行,人工核对字段映射。 + * + *

{@code /erp/sc/routing/wms/order/wmsOrderList} 按店铺数字 sid 过滤, + * 所以用亚马逊店铺列表返回的 {@code sid},而不是多平台的 {@code store_id} + * (后者不是数字,适配器会直接拒绝,避免跨店铺返回数据)。

+ */ + @Test + void pullsOutboundOrders() { + requireCredentials(); + LingxingAdapter adapter = adapter(); + +// String sid = firstAmazonShopSid(adapter); +// if (sid == null) { +// System.out.println("[outbound orders] 没有亚马逊店铺(WMS 需要数字 sid),跳过"); +// return; +// } + String sid = "15898"; + + ChannelContext ctx = context(amazonAccount(sid), "smoke-outbound-orders-"); + Page page = pullOneOutboundPage(adapter, ctx); + + System.out.println("[outbound orders] sid=" + sid + + " window=最近 30 天 items=" + page.size() + + " nextCursor=" + page.nextCursor()); + for (OutboundOrder o : page.items()) { + System.out.println(" wo_number=" + o.woNumber() + + " order_number=" + o.orderNumber() + + " status=" + o.status() + "/" + o.statusName() + + " logistics=" + o.logisticsStatus() + "/" + o.logisticsStatusName() + + " warehouse=" + o.warehouseId() + "/" + o.warehouseName() + + " waybillNO=" + o.waybillNo() + + " amount=" + o.orderAmount() + + " lines=" + o.lines().size() + + " createdAt=" + (o.createdAt() == null ? null : o.createdAt().utc()) + + " surface=" + o.surfaceFileUrl()); + for (OutboundOrderLine line : o.lines()) { + System.out.println(" sku=" + line.sku() + + " msku=" + line.sellerSku() + + " qty=" + line.quantity() + + " unit=" + line.unitPrice()); + } + } + assertFalse(page.size() > 20, "pageSize 未被平台遵守"); + } + + /** + * 第 8 步(面单):用上一步的出库单号取面单,再按系统单号查一次。 + * + *

{@code wo_number_arr} 与 {@code order_number_arr} 二选一,两条路径都跑, + * 确认字段名与 base64 返回。文档提示面单可能尚未生成,此时 {@code file_b64} 为空串。

+ */ + @Test + void pullsShippingLabels() { + requireCredentials(); + LingxingAdapter adapter = adapter(); + +// String sid = firstAmazonShopSid(adapter); +// if (sid == null) { +// System.out.println("[labels] 没有亚马逊店铺(WMS 需要数字 sid),跳过"); +// return; +// } + + String sid = "15898"; + ChannelContext ctx = context(amazonAccount(sid), "smoke-labels-"); + Page page = pullOneOutboundPage(adapter, ctx); + if (page.items().isEmpty()) { + System.out.println("[labels] 最近 30 天没有出库单,跳过"); + return; + } + + List woNumbers = new ArrayList<>(); + List orderNumbers = new ArrayList<>(); + for (OutboundOrder o : page.items()) { + if (woNumbers.size() >= LABEL_SMOKE_LIMIT) { + break; + } + woNumbers.add(o.woNumber()); + if (o.orderNumber() != null) { + orderNumbers.add(o.orderNumber()); + } + } + + printLabels("wo_number_arr", adapter.labels(ctx, + LabelQuery.builder().woNumbers(woNumbers).build())); + if (!orderNumbers.isEmpty()) { + printLabels("order_number_arr", adapter.labels(ctx, + LabelQuery.builder().orderNumbers(orderNumbers).build())); + } + } + // ---------------------------------------------------------------- helpers + /** 拉一页销售出库单(最近 30 天,按创建时间),两个仓储用例共用。 */ + private static Page pullOneOutboundPage(LingxingAdapter adapter, ChannelContext ctx) { + Instant to = Instant.now(); + Instant from = to.minus(Duration.ofDays(30)); + return adapter.pull(ctx, OutboundOrderQuery.builder() + .after(from) + .before(to) + .timeType(OutboundOrderQuery.TIME_CREATED) + .pageSize(20) + .build()); + } + + /** 只打 base64 长度,避免把整张面单刷到控制台。 */ + private static void printLabels(String queryKey, List labels) { + System.out.println("[labels] " + queryKey + " count=" + labels.size()); + for (ShippingLabel label : labels) { + String base64 = label.contentBase64(); + System.out.println(" wo_number=" + label.woNumber() + + " order_number=" + label.orderNumber() + + " provider=" + label.logisticsProviderId() + + " typeId=" + label.logisticsTypeId() + + " fileType=" + label.fileType() + + " fileSize=" + label.fileSize() + + " b64=" + (base64 == null ? "null" : base64.length() + " chars")); + } + } + /** 认证只需要 AppID/AppSecret。 */ private static void requireCredentials() { org.junit.jupiter.api.Assumptions.assumeTrue(