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 bb0bd40..61daa41 100644
--- a/core/src/main/java/common/ecommerce/capability/Outbounds.java
+++ b/core/src/main/java/common/ecommerce/capability/Outbounds.java
@@ -26,15 +26,24 @@ import java.util.List;
*/
public final class Outbounds {
+ /** 实际执行调用的适配器。 */
private final PlatformAdapter adapter;
+
+ /** 账户配置,用于按账户细化能力检查。 */
private final ChannelAccount account;
+
+ /** 本次调用上下文(端点、凭据、链路 ID、时钟)。 */
private final ChannelContext ctx;
+
+ /** 调用观察者,默认空实现。 */
private final CallObserver observer;
+ /** 不记录调用日志的构造方式。 */
public Outbounds(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
this(adapter, account, ctx, CallObserver.NOOP);
}
+ /** 标准构造;observer 为 null 时退化为空实现。 */
public Outbounds(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
CallObserver observer) {
this.adapter = adapter;
@@ -52,6 +61,13 @@ public final class Outbounds {
return new Outbounds(adapter, account, ctx.withRequestId(requestId), observer);
}
+ /**
+ * 提交快速出库(写操作,调用方需包在 {@code sdk.writes()} 里)。
+ *
+ * 返回 true 只表示任务已受理,最终结果要用 {@link #results(java.util.List)} 回查。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 未声明 MARK_SHIPPED 或未实现 OutboundCapable
+ */
public boolean submit(final List packages) {
return CallSupport.observeSummary(observer, ctx, "outbounds.submit",
CallSupport.params("packageCount", packages == null ? 0 : packages.size()),
@@ -64,6 +80,11 @@ public final class Outbounds {
});
}
+ /**
+ * 按系统单号查询快速出库结果。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 未声明 MARK_SHIPPED 或未实现 OutboundCapable
+ */
public OutboundResult results(final List globalOrderNos) {
return CallSupport.observe(observer, ctx, "outbounds.results",
CallSupport.params("orderCount", globalOrderNos == null ? 0 : globalOrderNos.size()),
@@ -74,7 +95,12 @@ public final class Outbounds {
});
}
- /** 销售出库单列表。 */
+ /**
+ * 销售出库单列表。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException
+ * 未声明 OUTBOUND_ORDER 或未实现 OutboundOrderCapable
+ */
public Page pull(final OutboundOrderQuery query) {
return CallSupport.observe(observer, ctx, "outbounds.pull",
CallSupport.params(
@@ -93,7 +119,11 @@ public final class Outbounds {
});
}
- /** 销售出库单物流面单。 */
+ /**
+ * 销售出库单物流面单。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 未声明 LABEL 或未实现 ShippingLabelCapable
+ */
public List labels(final LabelQuery query) {
return CallSupport.observe(observer, ctx, "outbounds.labels",
CallSupport.params(
@@ -106,7 +136,14 @@ public final class Outbounds {
});
}
- /** 审核发货(写操作,调用方需包在 {@code sdk.writes()} 里)。 */
+ /**
+ * 审核发货(写操作,调用方需包在 {@code sdk.writes()} 里)。
+ *
+ * 全部失败时会抛 {@link PlatformBusinessException},避免幂等层误记为 SUCCEEDED。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException
+ * 未声明 SHIPMENT_REVIEW 或未实现 ShipmentReviewCapable
+ */
public ShipmentReviewResult review(final List globalOrderNos) {
return CallSupport.observeSummary(observer, ctx, "outbounds.review",
CallSupport.params("orderCount", globalOrderNos == null ? 0 : globalOrderNos.size()),
@@ -131,6 +168,7 @@ public final class Outbounds {
});
}
+ /** 把审核发货结果映射成成功 / 部分成功 / 失败摘要。 */
private static CallSupport.ResultSummary reviewSummary(ShipmentReviewResult result) {
if (result == null) {
return CallSupport.ResultSummary.success(CallSupport.NO_COUNT);
@@ -144,6 +182,7 @@ public final class Outbounds {
return CallSupport.ResultSummary.partial(result.successNum(), result.failNum(), null);
}
+ /** 拼接失败单号与原因,截断到 300 字符左右,避免异常消息过长。 */
private static String failureSummary(ShipmentReviewResult result) {
if (result.failures() == null || result.failures().isEmpty()) {
return "none";
@@ -162,12 +201,14 @@ public final class Outbounds {
return sb.toString();
}
+ /** 快速出库能力双检:账户级能力声明 + 接口实现。 */
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/PlatformAdapter.java b/core/src/main/java/common/ecommerce/capability/PlatformAdapter.java
index 8bf94b9..873e12f 100644
--- a/core/src/main/java/common/ecommerce/capability/PlatformAdapter.java
+++ b/core/src/main/java/common/ecommerce/capability/PlatformAdapter.java
@@ -16,12 +16,13 @@ public interface PlatformAdapter {
/** 适配器标识,如 amazon-sc / lingxing。 */
String adapterId();
+ /** 该适配器所属接入通道;provider 与 platform 是两个维度,不要混用。 */
ChannelProvider provider();
/** 该适配器覆盖的平台。 */
Set platforms();
- /** 适配器能力并集。 */
+ /** 适配器能力并集;聚合器在未看账户时的粗粒度声明。 */
EnumSet capabilities();
/**
@@ -29,6 +30,10 @@ public interface PlatformAdapter {
*
* 直连适配器默认使用 {@link #capabilities()};聚合器按账户的子平台覆盖,
* 例如领星对 Walmart 支持标发、对 eBay 只支持订单。
+ *
+ * @param account 账户配置;聚合器据此读取 platformCode / externalStoreId
+ * @param capability 待检查能力
+ * @return 该账户是否支持该能力
*/
default boolean supports(ChannelAccount account, Capability capability) {
return capabilities().contains(capability);
diff --git a/core/src/main/java/common/ecommerce/capability/ProductCapable.java b/core/src/main/java/common/ecommerce/capability/ProductCapable.java
index 0ebde8c..dd63a98 100644
--- a/core/src/main/java/common/ecommerce/capability/ProductCapable.java
+++ b/core/src/main/java/common/ecommerce/capability/ProductCapable.java
@@ -16,10 +16,25 @@ public interface ProductCapable extends PlatformAdapter {
/** 适配器声明自己支持哪一种同步策略。 */
ProductSyncStrategy syncStrategy();
+ /**
+ * 分页拉取商品 / Listing。
+ *
+ * 适配器负责:ProductSearchField 到平台搜索编码的映射、时间窗解释、
+ * 游标透传。平台不支持某个过滤条件时必须显式报错,不能静默忽略。
+ *
+ * @return 当前页;{@link Page#nextCursor()} 为 null 表示没有下一页
+ */
Page pull(ChannelContext ctx, ProductQuery query);
+ /**
+ * 按平台 SKU 取单个商品。
+ *
+ * @return 商品;平台返回不存在时由适配器抛 {@code PlatformBusinessException} 或返回 null,
+ * 具体以适配器约定为准
+ */
ProductListing get(ChannelContext ctx, ProductRef ref);
+ /** 本能力对应的能力位,默认 {@link Capability#PRODUCT}。 */
default Capability requiredCapability() {
return Capability.PRODUCT;
}
diff --git a/core/src/main/java/common/ecommerce/capability/Products.java b/core/src/main/java/common/ecommerce/capability/Products.java
index f82269d..a99e231 100644
--- a/core/src/main/java/common/ecommerce/capability/Products.java
+++ b/core/src/main/java/common/ecommerce/capability/Products.java
@@ -14,15 +14,24 @@ import common.ecommerce.sdk.ChannelContext;
/** 门面持有的商品视图。 */
public final class Products {
+ /** 实际执行拉取的适配器。 */
private final PlatformAdapter adapter;
+
+ /** 账户配置,用于按账户细化能力检查。 */
private final ChannelAccount account;
+
+ /** 本次调用上下文(端点、凭据、链路 ID、时钟)。 */
private final ChannelContext ctx;
+
+ /** 调用观察者,默认空实现。 */
private final CallObserver observer;
+ /** 不记录调用日志的构造方式。 */
public Products(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
this(adapter, account, ctx, CallObserver.NOOP);
}
+ /** 标准构造;observer 为 null 时退化为空实现。 */
public Products(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
CallObserver observer) {
this.adapter = adapter;
@@ -40,6 +49,11 @@ public final class Products {
return new Products(adapter, account, ctx.withRequestId(requestId), observer);
}
+ /**
+ * 拉取一页商品。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 PRODUCT 或未实现 ProductCapable
+ */
public Page pull(final ProductQuery query) {
return CallSupport.observe(observer, ctx, "products.pull",
CallSupport.params(
@@ -57,6 +71,11 @@ public final class Products {
});
}
+ /**
+ * 按平台 SKU 取单个商品。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 PRODUCT 或未实现 ProductCapable
+ */
public ProductListing get(final String platformSku) {
return CallSupport.observe(observer, ctx, "products.get",
CallSupport.params("platformSku", platformSku),
@@ -67,6 +86,7 @@ public final class Products {
});
}
+ /** 能力双检:账户级能力声明 + 接口实现,缺一即拒绝。 */
private void requireProductCapable() {
if (!adapter.supports(account, Capability.PRODUCT) || !(adapter instanceof ProductCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.PRODUCT);
diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java b/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java
index 0a9dede..18b9c20 100644
--- a/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java
+++ b/core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java
@@ -17,14 +17,24 @@ import common.ecommerce.sdk.ChannelContext;
*/
public interface SalesOrderCapable extends PlatformAdapter {
- /** 分页拉取。时间窗与游标由适配器解释。 */
+ /**
+ * 分页拉取。时间窗与游标由适配器解释。
+ *
+ * @return 当前页;{@link Page#nextCursor()} 为 null 表示没有下一页
+ */
Page pull(ChannelContext ctx, SalesOrderQuery query);
- /** 单订单详情。 */
+ /**
+ * 单订单详情。
+ *
+ * @param ref 平台订单号引用
+ */
SalesOrder get(ChannelContext ctx, SalesOrderRef ref);
/**
* 默认实现:未声明该能力即拒绝,避免适配器漏实现导致静默返回空。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 未声明 {@link Capability#SALES_ORDER}
*/
default void requireCapability() {
if (!capabilities().contains(Capability.SALES_ORDER)) {
diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrders.java b/core/src/main/java/common/ecommerce/capability/SalesOrders.java
index 469343d..22d17ff 100644
--- a/core/src/main/java/common/ecommerce/capability/SalesOrders.java
+++ b/core/src/main/java/common/ecommerce/capability/SalesOrders.java
@@ -24,15 +24,24 @@ import java.util.List;
*/
public final class SalesOrders {
+ /** 实际执行拉取的适配器。 */
private final PlatformAdapter adapter;
+
+ /** 账户配置,用于按账户细化能力检查。 */
private final ChannelAccount account;
+
+ /** 本次调用上下文(端点、凭据、链路 ID、时钟)。 */
private final ChannelContext ctx;
+
+ /** 调用观察者,默认空实现。 */
private final CallObserver observer;
+ /** 不记录调用日志的构造方式。 */
public SalesOrders(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
this(adapter, account, ctx, CallObserver.NOOP);
}
+ /** 标准构造;observer 为 null 时退化为空实现。 */
public SalesOrders(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
CallObserver observer) {
this.adapter = adapter;
@@ -50,6 +59,11 @@ public final class SalesOrders {
return new SalesOrders(adapter, account, ctx.withRequestId(requestId), observer);
}
+ /**
+ * 拉取一页销售订单。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 SALES_ORDER 或未实现 SalesOrderCapable
+ */
public Page pull(final SalesOrderQuery query) {
return CallSupport.observe(observer, ctx, "salesOrders.pull",
CallSupport.params(
@@ -64,6 +78,11 @@ public final class SalesOrders {
});
}
+ /**
+ * 按平台订单号取单个订单。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 SALES_ORDER 或未实现 SalesOrderCapable
+ */
public SalesOrder get(final String channelOrderId) {
return CallSupport.observe(observer, ctx, "salesOrders.get",
CallSupport.params("channelOrderId", channelOrderId),
@@ -74,7 +93,13 @@ public final class SalesOrders {
});
}
- /** 批量编辑订单(写操作,调用方需包在 {@code sdk.writes()} 里)。 */
+ /**
+ * 批量编辑订单(写操作,调用方需包在 {@code sdk.writes()} 里)。
+ *
+ * 全部失败时会抛 {@link PlatformBusinessException},避免幂等层误记为 SUCCEEDED。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 适配器未声明 ORDER_EDIT 或未实现 OrderEditCapable
+ */
public OrderEditResult edit(final List requests) {
return CallSupport.observeSummary(observer, ctx, "salesOrders.edit",
CallSupport.params("requestCount", requests == null ? 0 : requests.size()),
@@ -101,6 +126,7 @@ public final class SalesOrders {
});
}
+ /** 把批量编辑结果映射成成功 / 部分成功 / 失败摘要。 */
private static CallSupport.ResultSummary editSummary(OrderEditResult result) {
if (result == null) {
return CallSupport.ResultSummary.success(CallSupport.NO_COUNT);
@@ -115,6 +141,7 @@ public final class SalesOrders {
return CallSupport.ResultSummary.partial(CallSupport.NO_COUNT, failed, result.code());
}
+ /** 拼接失败单号与原因,截断到 300 字符左右,避免异常消息过长。 */
private static String failureSummary(OrderEditResult result) {
if (result.failures() == null || result.failures().isEmpty()) {
return "none";
@@ -133,6 +160,7 @@ public final class SalesOrders {
return sb.toString();
}
+ /** 能力双检:账户级能力声明 + 接口实现,缺一即拒绝。 */
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/SettlementCapable.java b/core/src/main/java/common/ecommerce/capability/SettlementCapable.java
index 29cb5e6..3b5f2d6 100644
--- a/core/src/main/java/common/ecommerce/capability/SettlementCapable.java
+++ b/core/src/main/java/common/ecommerce/capability/SettlementCapable.java
@@ -13,5 +13,10 @@ import common.ecommerce.sdk.ChannelContext;
*/
public interface SettlementCapable extends PlatformAdapter {
+ /**
+ * 分页拉取结算交易明细。
+ *
+ * @return 当前页;平台按结算周期或修改时间解释查询条件
+ */
Page pull(ChannelContext ctx, SettlementQuery query);
}
diff --git a/core/src/main/java/common/ecommerce/capability/Settlements.java b/core/src/main/java/common/ecommerce/capability/Settlements.java
index aa34eb3..80aedd3 100644
--- a/core/src/main/java/common/ecommerce/capability/Settlements.java
+++ b/core/src/main/java/common/ecommerce/capability/Settlements.java
@@ -15,15 +15,24 @@ import common.ecommerce.sdk.ChannelContext;
*/
public final class Settlements {
+ /** 实际执行拉取的适配器。 */
private final PlatformAdapter adapter;
+
+ /** 账户配置,用于按账户细化能力检查。 */
private final ChannelAccount account;
+
+ /** 本次调用上下文(端点、凭据、链路 ID、时钟)。 */
private final ChannelContext ctx;
+
+ /** 调用观察者,默认空实现。 */
private final CallObserver observer;
+ /** 不记录调用日志的构造方式。 */
public Settlements(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
this(adapter, account, ctx, CallObserver.NOOP);
}
+ /** 标准构造;observer 为 null 时退化为空实现。 */
public Settlements(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
CallObserver observer) {
this.adapter = adapter;
@@ -41,6 +50,11 @@ public final class Settlements {
return new Settlements(adapter, account, ctx.withRequestId(requestId), observer);
}
+ /**
+ * 拉取一页结算交易明细。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 未声明 BILLING 或未实现 SettlementCapable
+ */
public Page pull(final SettlementQuery query) {
return CallSupport.observe(observer, ctx, "settlements.pull",
CallSupport.params(
@@ -61,6 +75,7 @@ public final class Settlements {
});
}
+ /** 能力双检:账户级能力声明 + 接口实现,缺一即拒绝。 */
private void requireSettlementCapable() {
if (!adapter.supports(account, Capability.BILLING) || !(adapter instanceof SettlementCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.BILLING);
diff --git a/core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java b/core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java
index 4f63099..ef8b70f 100644
--- a/core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java
+++ b/core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java
@@ -14,6 +14,10 @@ import java.util.List;
*/
public interface ShipmentReviewCapable extends PlatformAdapter {
- /** 按系统单号批量审核发货;逐单返回成功或失败原因。 */
+ /**
+ * 按系统单号批量审核发货;逐单返回成功或失败原因。
+ *
+ * @return 逐单结果;全部失败时由门面转成 PlatformBusinessException
+ */
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
index 21256a5..25272a8 100644
--- a/core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java
+++ b/core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java
@@ -13,6 +13,10 @@ import java.util.List;
*/
public interface ShippingLabelCapable extends PlatformAdapter {
- /** 按销售出库单号或系统单号批量取面单。 */
+ /**
+ * 按销售出库单号或系统单号批量取面单。
+ *
+ * @return 面单列表;查不到时为 null 或空列表,由适配器约定
+ */
List labels(ChannelContext ctx, LabelQuery query);
}
diff --git a/core/src/main/java/common/ecommerce/error/AuthException.java b/core/src/main/java/common/ecommerce/error/AuthException.java
index 1f8acf3..b721c49 100644
--- a/core/src/main/java/common/ecommerce/error/AuthException.java
+++ b/core/src/main/java/common/ecommerce/error/AuthException.java
@@ -2,15 +2,23 @@ package common.ecommerce.error;
/**
* 认证失败:401/403、token 失效。刷新后重试一次;仍失败则告警并停用账户。
+ *
+ * 抛出于:HTTP 401/403,或平台业务码表示 token/签名问题(如领星
+ * {@code 2001003}、{@code 2001006}、{@code 2001007}、{@code 3001002})。
+ *
+ * 是否可重试:本类不自动设置 {@code retryable},默认 false;
+ * 调用方应先刷新 token 再重跑一次,二次失败按不可重试处理。
*/
public class AuthException extends ChannelException {
private static final long serialVersionUID = 1L;
+ /** @param b 异常字段构造器 */
public AuthException(Builder b) {
super(b, null);
}
+ /** @param b 异常字段构造器 @param cause 底层异常 */
public AuthException(Builder b, Throwable cause) {
super(b, cause);
}
diff --git a/core/src/main/java/common/ecommerce/error/ChannelException.java b/core/src/main/java/common/ecommerce/error/ChannelException.java
index 3ac630d..6211866 100644
--- a/core/src/main/java/common/ecommerce/error/ChannelException.java
+++ b/core/src/main/java/common/ecommerce/error/ChannelException.java
@@ -5,21 +5,46 @@ import common.ecommerce.model.Platform;
/**
* 统一异常基类。适配器把平台错误映射到这里;{@code rawResponse} 必须已脱敏。
+ *
+ * 平台错误、HTTP 错误、能力缺失、幂等冲突都归到本层;子类用于让调用方区分处理方式。
+ * 是否重试只看 {@link #retryable()},SDK 自身不做任何重试。
+ *
+ * 注意区分两个 ID:{@link #requestId()} 是我方链路 ID,
+ * {@link #platformRequestId()} 是平台工单号(如领星 {@code request_id})。
*/
public class ChannelException extends RuntimeException {
private static final long serialVersionUID = 1L;
+ /** 业务平台;未知时为 null。 */
private final Platform platform;
+ /** 接入通道名({@link common.ecommerce.model.ChannelProvider} 的 name);未知时为 null。 */
private final String provider;
+ /** 宿主侧店铺 ID;未知时为 null。 */
private final String omsStoreId;
+ /** 出错的门面操作名,如 {@code outbounds.review};主要用于生成默认 message。 */
private final String operation;
+ /** 我方链路 ID,用来串本地日志,可能为 null;不是平台工单号。 */
private final String requestId;
+ /** 平台业务码 / HTTP 状态码;无则为 null。 */
private final String platformCode;
+ /** 平台工单号(如领星 {@code request_id});无则为 null。 */
private final String platformRequestId;
+ /**
+ * 是否值得重试;由适配器按错误类型显式设置,SDK 本身不重试。
+ *
+ * 取值为 true 时只代表「宿主可以重跑」,不代表重跑一定安全;
+ * 写操作是否可重跑还要看幂等层裁决。
+ */
private final boolean retryable;
+ /** 已脱敏的原始响应片段;没有或不便保存时为 null。绝不能放密钥。 */
private final String rawResponse;
+ /**
+ * 由 Builder 构造;外部应走 {@link #builder()} 或子类构造器。
+ *
+ * @param cause 底层异常;可为 null
+ */
public ChannelException(Builder b, Throwable cause) {
super(b.message != null ? b.message : b.operation, cause);
this.platform = b.platform;
@@ -33,30 +58,37 @@ public class ChannelException extends RuntimeException {
this.rawResponse = b.rawResponse;
}
+ /** 新建 Builder;{@code retryable} 默认 false,需要的子类/适配器显式打开。 */
public static Builder builder() {
return new Builder();
}
+ /** 业务平台;未知时为 null。 */
public Platform platform() {
return platform;
}
+ /** 接入通道名;未知时为 null。 */
public String provider() {
return provider;
}
+ /** 宿主侧店铺 ID;未知时为 null。 */
public String omsStoreId() {
return omsStoreId;
}
+ /** 出错的门面操作名;未知时为 null。 */
public String operation() {
return operation;
}
+ /** 我方链路 ID,用于串本地日志;平台工单号见 {@link #platformRequestId()}。 */
public String requestId() {
return requestId;
}
+ /** 平台业务码 / HTTP 状态码;无则为 null。 */
public String platformCode() {
return platformCode;
}
@@ -71,57 +103,81 @@ public class ChannelException extends RuntimeException {
return platformRequestId;
}
+ /**
+ * 是否值得重试;由适配器显式设置,SDK 本身不重试。
+ *
+ * 与 {@code CallRecord.retryable()}、{@code IdempotencyGuard} 的失败终态判定一致。
+ */
public boolean retryable() {
return retryable;
}
+ /** 已脱敏的原始响应片段;无则为 null。 */
public String rawResponse() {
return rawResponse;
}
+ /** 异常字段构建器;子类可复用同一套字段。 */
public static class Builder {
+ /** 异常消息;为 null 时用 {@link #operation} 兜底。 */
protected String message;
+ /** 业务平台。 */
protected Platform platform;
+ /** 接入通道名。 */
protected String provider;
+ /** 宿主侧店铺 ID。 */
protected String omsStoreId;
+ /** 门面操作名。 */
protected String operation;
+ /** 我方链路 ID。 */
protected String requestId;
+ /** 平台业务码 / HTTP 状态码。 */
protected String platformCode;
+ /** 平台工单号(如领星 {@code request_id})。 */
protected String platformRequestId;
+ /** 是否值得重试;默认 false。 */
protected boolean retryable;
+ /** 已脱敏的原始响应片段;不可放密钥。 */
protected String rawResponse;
+ /** 异常消息;null 时最终用 operation 兜底。 */
public Builder message(String message) {
this.message = message;
return this;
}
+ /** 业务平台。 */
public Builder platform(Platform platform) {
this.platform = platform;
return this;
}
+ /** 接入通道名。 */
public Builder provider(String provider) {
this.provider = provider;
return this;
}
+ /** 宿主侧店铺 ID。 */
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
+ /** 门面操作名。 */
public Builder operation(String operation) {
this.operation = operation;
return this;
}
+ /** 我方链路 ID;不要填平台 {@code request_id}。 */
public Builder requestId(String requestId) {
this.requestId = requestId;
return this;
}
+ /** 平台业务码 / HTTP 状态码。 */
public Builder platformCode(String platformCode) {
this.platformCode = platformCode;
return this;
@@ -133,32 +189,43 @@ public class ChannelException extends RuntimeException {
return this;
}
+ /** 是否值得重试;只有确认重跑安全的场景才传 true。 */
public Builder retryable(boolean retryable) {
this.retryable = retryable;
return this;
}
+ /** 已脱敏的原始响应片段;不可放密钥、买家信息或完整报文。 */
public Builder rawResponse(String rawResponse) {
this.rawResponse = rawResponse;
return this;
}
+ /** 构造异常(无 cause)。 */
public ChannelException build() {
return new ChannelException(this, null);
}
+ /** 构造异常并保留底层 cause;网络/超时类错误应传。 */
public ChannelException build(Throwable cause) {
return new ChannelException(this, cause);
}
}
- /** 平台不支持该能力;调用方走 3PL 或人工兜底。 */
+ /**
+ * 平台不支持该能力;调用方走 3PL 或人工兜底。
+ *
+ * 抛出于:适配器未实现对应 Capable 接口或未声明该 Capability。
+ * 不可重试({@code retryable=false})。
+ */
public static class UnsupportedCapabilityException extends ChannelException {
private static final long serialVersionUID = 1L;
+ /** 缺失的能力;非 null。 */
private final Capability capability;
+ /** @param capability 适配器未声明/未实现的能力 */
public UnsupportedCapabilityException(Capability capability) {
super(ChannelException.builder()
.message("capability [" + capability + "] is not supported by this adapter")
@@ -166,6 +233,7 @@ public class ChannelException extends RuntimeException {
this.capability = capability;
}
+ /** 被拒绝的能力。 */
public Capability capability() {
return capability;
}
diff --git a/core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java b/core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java
index 879dd8c..18a9216 100644
--- a/core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java
+++ b/core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java
@@ -3,19 +3,29 @@ package common.ecommerce.error;
/**
* 跨 provider 冲突:同一业务动作已由另一个 provider 完成。
*
- * 不自动跨 provider 重试,必须人工确认。
+ * 业务键(platform + omsStoreId + businessRef + action)不带 provider,
+ * 直连与聚合器共用;当记录显示已由别家完成时抛出。
+ *
+ * 是否可重试:不可重试({@code retryable=false}),不自动跨 provider 重试,
+ * 必须人工确认以哪条通道的结果为准。
*/
public class CrossProviderConflictException extends ChannelException {
private static final long serialVersionUID = 1L;
+ /** 已完成该业务动作的 provider;非 null。 */
private final String completedByProvider;
+ /**
+ * @param b 异常字段构造器
+ * @param completedByProvider 已完成该动作的 provider 名
+ */
public CrossProviderConflictException(Builder b, String completedByProvider) {
super(b, null);
this.completedByProvider = completedByProvider;
}
+ /** 已完成该业务动作的 provider。 */
public String completedByProvider() {
return completedByProvider;
}
diff --git a/core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java b/core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java
index e270b25..9c3173f 100644
--- a/core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java
+++ b/core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java
@@ -1,17 +1,36 @@
package common.ecommerce.error;
-/** 写操作幂等冲突:重复写。返回已完成结果,不视为失败。 */
+/**
+ * 写操作幂等冲突:重复写。返回已完成结果,不视为失败。
+ *
+ * 抛出于:业务键处于 IN_PROGRESS(另一个实例正在执行同一动作)。
+ *
+ * 补充:真正的「已成功」场景不会走本异常,
+ * {@code IdempotencyGuard} 会直接回放并返回 {@code WriteResult.ALREADY_COMPLETED}。
+ *
+ * 是否可重试:不应立即重试;等对方完成或抢占 TTL 过期后再来,
+ * 届时会走回放而不是再次执行。构造时 {@code retryable} 默认 false。
+ */
public class IdempotencyConflictException extends ChannelException {
private static final long serialVersionUID = 1L;
+ /**
+ * 冲突的幂等键。注意实际填的是业务键(跨 provider),
+ * 而不是 provider 请求键;排查时别拿去撞 provider 维度的记录。
+ */
private final String idempotencyKey;
+ /**
+ * @param b 异常字段构造器
+ * @param idempotencyKey 冲突的业务幂等键
+ */
public IdempotencyConflictException(Builder b, String idempotencyKey) {
super(b, null);
this.idempotencyKey = idempotencyKey;
}
+ /** 冲突的幂等键(实现传入的是业务键)。 */
public String idempotencyKey() {
return idempotencyKey;
}
diff --git a/core/src/main/java/common/ecommerce/error/PlatformBusinessException.java b/core/src/main/java/common/ecommerce/error/PlatformBusinessException.java
index 63ac702..ed2755c 100644
--- a/core/src/main/java/common/ecommerce/error/PlatformBusinessException.java
+++ b/core/src/main/java/common/ecommerce/error/PlatformBusinessException.java
@@ -2,11 +2,18 @@ package common.ecommerce.error;
/**
* 平台业务错误码。是否重试视错误码而定,保留 code/message/raw。
+ *
+ * 抛出于:平台返回非 0 业务码但又不是限流/认证问题;或批处理全部失败
+ * (如审核发货 {@code successNum=0 && failNum>0})。
+ *
+ * 是否可重试:默认不可重试;只有明确知道错误码可重跑时,
+ * 调用方才应把 {@code retryable(true)} 传进 Builder。
*/
public class PlatformBusinessException extends ChannelException {
private static final long serialVersionUID = 1L;
+ /** @param b 异常字段构造器 */
public PlatformBusinessException(Builder b) {
super(b, null);
}
diff --git a/core/src/main/java/common/ecommerce/error/RateLimitException.java b/core/src/main/java/common/ecommerce/error/RateLimitException.java
index d1be84d..1c3183a 100644
--- a/core/src/main/java/common/ecommerce/error/RateLimitException.java
+++ b/core/src/main/java/common/ecommerce/error/RateLimitException.java
@@ -2,18 +2,29 @@ package common.ecommerce.error;
/**
* 限流:429。遵守 Retry-After 并退避。
+ *
+ * 抛出于:HTTP 429,或平台业务码表示限流(如领星 {@code 3001008})。
+ *
+ * 是否可重试:语义上可以,但必须等待 {@link #retryAfterMillis()};
+ * 本类构造时不会自动把 {@code retryable} 置为 true,SDK 也不自动重试。
*/
public class RateLimitException extends ChannelException {
private static final long serialVersionUID = 1L;
+ /** 建议退避时长(毫秒),非负;平台没带 Retry-After 时由适配器给默认值。 */
private final long retryAfterMillis;
+ /**
+ * @param b 异常字段构造器
+ * @param retryAfterMillis 建议退避毫秒数;无法解析时传默认值(如 1000)
+ */
public RateLimitException(Builder b, long retryAfterMillis) {
super(b, null);
this.retryAfterMillis = retryAfterMillis;
}
+ /** 建议退避时长(毫秒)。 */
public long retryAfterMillis() {
return retryAfterMillis;
}
diff --git a/core/src/main/java/common/ecommerce/error/TransientException.java b/core/src/main/java/common/ecommerce/error/TransientException.java
index 14f597c..f8f5e88 100644
--- a/core/src/main/java/common/ecommerce/error/TransientException.java
+++ b/core/src/main/java/common/ecommerce/error/TransientException.java
@@ -2,11 +2,17 @@ package common.ecommerce.error;
/**
* 瞬时错误:5xx / 网络 / 超时。退避加抖动后重试,超过上限进入补偿队列。
+ *
+ * 抛出于:HTTP 5xx、连接失败、读写超时。
+ *
+ * 是否可重试:通常可以;构造时由适配器显式 {@code retryable(true)}
+ * (SDK 不自动重试)。超时属于「结果未知」,适配器应先回查再决定能否重跑。
*/
public class TransientException extends ChannelException {
private static final long serialVersionUID = 1L;
+ /** @param b 异常字段构造器(通常已设 {@code retryable(true)}) @param cause 底层异常 */
public TransientException(Builder b, Throwable cause) {
super(b, cause);
}
diff --git a/core/src/main/java/common/ecommerce/error/ValidationException.java b/core/src/main/java/common/ecommerce/error/ValidationException.java
index 6597f45..0adff2f 100644
--- a/core/src/main/java/common/ecommerce/error/ValidationException.java
+++ b/core/src/main/java/common/ecommerce/error/ValidationException.java
@@ -2,15 +2,21 @@ package common.ecommerce.error;
/**
* 参数或映射错误:4xx。不重试,保留原始报文由人工修正映射。
+ *
+ * 抛出于:请求参数不合法、平台 4xx(401/403/429 除外),或响应字段无法映射。
+ *
+ * 是否可重试:不可重试,原样重跑只会再失败。
*/
public class ValidationException extends ChannelException {
private static final long serialVersionUID = 1L;
+ /** @param b 异常字段构造器 */
public ValidationException(Builder b) {
super(b, null);
}
+ /** @param b 异常字段构造器 @param cause 底层异常(如 JSON 解析错误) */
public ValidationException(Builder b, Throwable cause) {
super(b, cause);
}
diff --git a/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java b/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java
index d84eb4b..2137083 100644
--- a/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java
+++ b/core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java
@@ -58,18 +58,38 @@ import java.util.function.Supplier;
*/
public final class IdempotencyGuard {
+ /** 默认抢占有效期(秒):超时未见结果即允许重新抢占。 */
public static final long DEFAULT_CLAIM_TTL_SECONDS = 300L;
+ /** 幂等存储,非 null;原子性由宿主实现保证。 */
private final IdempotencyStore store;
+ /** 本实例标识,写入记录用于判断并发与 owner 归属;非 null。 */
private final String owner;
+ /** 取当前时间用的时钟;非 null,测试可注入固定时钟。 */
private final Clock clock;
+ /** 抢占有效期(秒),必须大于 0。 */
private final long claimTtlSeconds;
+ /** 审计观察者;非 null,未注入时为 {@link CallObserver#NOOP}。 */
private final CallObserver observer;
+ /**
+ * 使用随机 owner 与默认 TTL({@value #DEFAULT_CLAIM_TTL_SECONDS} 秒)、无审计。
+ *
+ * @param store 幂等存储
+ * @param clock 时钟,通常 {@link Clock#systemUTC()}
+ */
public IdempotencyGuard(IdempotencyStore store, Clock clock) {
this(store, UUID.randomUUID().toString(), clock, DEFAULT_CLAIM_TTL_SECONDS);
}
+ /**
+ * 指定 owner 与 TTL,无审计。
+ *
+ * @param store 幂等存储
+ * @param owner 实例标识,多实例部署时应稳定可区分
+ * @param clock 时钟
+ * @param claimTtlSeconds 抢占有效期(秒),必须大于 0
+ */
public IdempotencyGuard(IdempotencyStore store, String owner, Clock clock, long claimTtlSeconds) {
this(store, owner, clock, claimTtlSeconds, CallObserver.NOOP);
}
@@ -96,6 +116,10 @@ public final class IdempotencyGuard {
* @param action 平台写操作;抛 {@link ChannelException} 时按其 {@code retryable()} 决定是否可重试。
* 业务失败必须抛异常,返回「失败结果」会被记成已成功
* @param resultRef 从执行结果中提取结果引用(订单号 / 包裹号等),可为 null
+ * @return 本次执行或回放的结果;回放时 {@code value()} 为 null
+ * @throws IdempotencyConflictException 业务键处于 IN_PROGRESS
+ * @throws CrossProviderConflictException 已由另一个 provider 完成
+ * @throws ChannelException 业务键 FAILED_FINAL,或 {@code action} 自己抛出
*/
public WriteResult execute(WriteScope scope, Supplier action, Function super T, String> resultRef) {
Objects.requireNonNull(scope, "scope");
@@ -151,6 +175,12 @@ public final class IdempotencyGuard {
// ---------------------------------------------------------------- internals
+ /**
+ * 业务键或 provider 键未抢到时的统一裁决:回放、并发冲突或终态失败。
+ *
+ * 只处理非 ACQUIRED 的结果;ACQUIRED 走到这里属于实现缺陷,直接抛
+ * {@link IllegalStateException}。
+ */
private WriteResult handleNotAcquired(WriteScope scope, IdempotencyClaim claim,
String businessKey, String providerKey) {
IdempotencyRecord record = claim.record();
@@ -187,6 +217,10 @@ public final class IdempotencyGuard {
}
}
+ /**
+ * 回放已成功的结果;若原完成方是另一个 provider,则改抛
+ * {@link CrossProviderConflictException}(不自动跨 provider 重试)。
+ */
private WriteResult replay(WriteScope scope, IdempotencyRecord record,
String businessKey, String providerKey,
WriteAudit.Stage stage) {
@@ -219,16 +253,21 @@ public final class IdempotencyGuard {
return e instanceof ChannelException && ((ChannelException) e).retryable();
}
+ /** 本实例标识。 */
public String owner() {
return owner;
}
- /** 只读查询,供运维排查。 */
+ /**
+ * 按业务键查询当前幂等记录,只读查询,供运维排查。
+ *
+ * @return 无记录时为空 Optional
+ */
public Optional status(WriteScope scope) {
return store.get(scope.businessKey());
}
- /** 该状态是否可安全重跑。 */
+ /** 该状态是否可安全重跑;只有 FAILED_RETRYABLE 返回 true。 */
public static boolean isRetryableStatus(IdempotencyStatus status) {
return status == IdempotencyStatus.FAILED_RETRYABLE;
}
diff --git a/core/src/main/java/common/ecommerce/idempotency/WriteAudit.java b/core/src/main/java/common/ecommerce/idempotency/WriteAudit.java
index 29d598b..2ae51ca 100644
--- a/core/src/main/java/common/ecommerce/idempotency/WriteAudit.java
+++ b/core/src/main/java/common/ecommerce/idempotency/WriteAudit.java
@@ -23,6 +23,7 @@ import java.util.Map;
*/
final class WriteAudit {
+ /** 观察者自身异常时只在本类留痕,不影响写操作。 */
private static final Logger LOG = LoggerFactory.getLogger(WriteAudit.class);
/**
@@ -32,6 +33,7 @@ final class WriteAudit {
*/
static final String OPERATION_PREFIX = "writes.";
+ /** 工具类,不实例化。 */
private WriteAudit() {
}
@@ -52,6 +54,8 @@ final class WriteAudit {
* 只有「观察者自身抛异常」才允许被吞掉。
*
* @param observer 观察者;null 等价于 NOOP
+ * @param clock 取审计时间用的时钟;null 时 {@link Instant#now(Clock)} 会抛 NPE
+ * (属于调用方缺陷,不吞)
* @param scope 标识维度
* @param outcome 结论
* @param stage 守卫阶段
diff --git a/core/src/main/java/common/ecommerce/idempotency/WriteResult.java b/core/src/main/java/common/ecommerce/idempotency/WriteResult.java
index d0accd8..702fb33 100644
--- a/core/src/main/java/common/ecommerce/idempotency/WriteResult.java
+++ b/core/src/main/java/common/ecommerce/idempotency/WriteResult.java
@@ -15,10 +15,15 @@ public final class WriteResult {
ALREADY_COMPLETED
}
+ /** 执行结论;非 null。 */
private final Outcome outcome;
+ /** 本次执行的返回值;只有 EXECUTED 有值,回放时为 null。 */
private final T value;
+ /** 结果引用(订单号 / 包裹号等);可能为 null。 */
private final String resultRef;
+ /** 本次使用的跨 provider 业务幂等键;非 null。 */
private final String businessKey;
+ /** 本次使用的单 provider 请求幂等键;非 null。 */
private final String providerKey;
private WriteResult(Outcome outcome, T value, String resultRef, String businessKey, String providerKey) {
@@ -29,6 +34,7 @@ public final class WriteResult {
this.providerKey = providerKey;
}
+ /** 本次真正调用了平台并成功。 */
public static WriteResult executed(T value, String resultRef, String businessKey, String providerKey) {
return new WriteResult(Outcome.EXECUTED, value, resultRef, businessKey, providerKey);
}
@@ -38,6 +44,7 @@ public final class WriteResult {
return new WriteResult(Outcome.ALREADY_COMPLETED, null, resultRef, businessKey, providerKey);
}
+ /** 执行结论。 */
public Outcome outcome() {
return outcome;
}
@@ -47,23 +54,27 @@ public final class WriteResult {
return value;
}
- /** 结果引用(订单号 / 包裹号等);可能为 null。 */
+ /** 结果引用(订单号 / 包裹号等);平台没返回时为 null。 */
public String resultRef() {
return resultRef;
}
+ /** 跨 provider 业务幂等键。 */
public String businessKey() {
return businessKey;
}
+ /** 单 provider 请求幂等键。 */
public String providerKey() {
return providerKey;
}
+ /** 是否为回放(此前已成功,本次未调平台)。 */
public boolean alreadyCompleted() {
return outcome == Outcome.ALREADY_COMPLETED;
}
+ /** 便于日志输出;只含结论与结果引用。 */
@Override
public String toString() {
return "WriteResult{" + outcome + (resultRef == null ? "" : " -> " + resultRef) + '}';
diff --git a/core/src/main/java/common/ecommerce/idempotency/WriteScope.java b/core/src/main/java/common/ecommerce/idempotency/WriteScope.java
index 2257647..f5d7a8f 100644
--- a/core/src/main/java/common/ecommerce/idempotency/WriteScope.java
+++ b/core/src/main/java/common/ecommerce/idempotency/WriteScope.java
@@ -18,11 +18,17 @@ import java.util.Objects;
*/
public final class WriteScope {
+ /** 接入通道;非 null,参与 {@link #providerKey()} 但不参与 {@link #businessKey()}。 */
private final ChannelProvider provider;
+ /** 业务平台;非 null。 */
private final Platform platform;
+ /** 宿主侧店铺 ID,已 trim;非空。 */
private final String omsStoreId;
+ /** 渠道侧店铺 ID,已 trim;非空。只参与 provider 键。 */
private final String externalStoreId;
+ /** 业务动作名(如 {@code markShipped}),已 trim;非空。 */
private final String action;
+ /** 业务自然键(如 {@code PO-1:pkg-1}),已 trim;非空。 */
private final String businessRef;
private WriteScope(ChannelProvider provider, Platform platform, String omsStoreId, String externalStoreId,
@@ -36,6 +42,8 @@ public final class WriteScope {
}
/**
+ * 构造标识维度;所有字符串参数都会 trim,null/空白抛 {@link IllegalArgumentException}。
+ *
* @param businessRef 业务自然键,如 {@code PO-1:pkg-1} 或 {@code RET-1:ITEM-1:REFUND-1};
* 不得使用金额
*/
@@ -44,40 +52,56 @@ public final class WriteScope {
return new WriteScope(provider, platform, omsStoreId, externalStoreId, action, businessRef);
}
+ /** 接入通道;不参与业务键,故直连与聚合器可以共用同一业务键。 */
public ChannelProvider provider() {
return provider;
}
+ /** 业务平台。 */
public Platform platform() {
return platform;
}
+ /** 宿主侧店铺 ID。 */
public String omsStoreId() {
return omsStoreId;
}
+ /** 渠道侧店铺 ID;只进 provider 键,切换 provider 时允许不同。 */
public String externalStoreId() {
return externalStoreId;
}
+ /** 业务动作名。 */
public String action() {
return action;
}
+ /** 业务自然键。 */
public String businessRef() {
return businessRef;
}
- /** 跨 provider 的业务幂等键。 */
+ /**
+ * 跨 provider 的业务幂等键:{@code platform + omsStoreId + businessRef + action}。
+ *
+ * 不带 provider,直连与聚合器共用,保证同一业务动作只成功一次。
+ */
public String businessKey() {
return CanonicalKeys.businessIdempotencyKey(platform, omsStoreId, businessRef, action);
}
- /** 单 provider 内的请求幂等键。 */
+ /**
+ * 单 provider 内的请求幂等键:
+ * {@code provider + platform + externalStoreId + action + businessRef}。
+ *
+ * 只防单 provider 内的重复请求/重试,不能替代 {@link #businessKey()}。
+ */
public String providerKey() {
return CanonicalKeys.providerRequestKey(provider, platform, externalStoreId, action, businessRef);
}
+ /** 便于排查;不是业务键或 provider 键,不要拿去当幂等键用。 */
@Override
public String toString() {
return provider + ":" + platform + ":" + omsStoreId + ":" + action + ":" + businessRef;
diff --git a/core/src/main/java/common/ecommerce/model/FulfillmentMode.java b/core/src/main/java/common/ecommerce/model/FulfillmentMode.java
index 859d9a2..6973294 100644
--- a/core/src/main/java/common/ecommerce/model/FulfillmentMode.java
+++ b/core/src/main/java/common/ecommerce/model/FulfillmentMode.java
@@ -7,6 +7,6 @@ public enum FulfillmentMode {
THIRD_PARTY_SHIP,
/** C:1P 代发(VC DF / 沃尔玛 DSV) */
VENDOR_DF_SHIP,
- /** D:1P Retail 供应商供货 */
+ /** D:1P Retail 供应商供货(856 ASN) */
VENDOR_RETAIL_ASN
}
diff --git a/core/src/main/java/common/ecommerce/model/Platform.java b/core/src/main/java/common/ecommerce/model/Platform.java
index fc2d531..21c177d 100644
--- a/core/src/main/java/common/ecommerce/model/Platform.java
+++ b/core/src/main/java/common/ecommerce/model/Platform.java
@@ -39,11 +39,15 @@ public enum Platform {
BESTBUY,
/** AEPH(领星 platform_code 10005 / 10031)。 */
AEPH,
+ /** Wayfair。 */
WAYFAIR,
+ /** Michaels。 */
MICHAELS,
+ /** Echo。 */
ECHO,
+ /** Losdlius。 */
LOSDLIUS,
- /** 自定义平台 */
+ /** 自定义平台:由适配器自行解释。 */
CUSTOM;
/** 是否属于 1P(平台向供应商采购)语义。 */
diff --git a/core/src/main/java/common/ecommerce/model/account/AccountKey.java b/core/src/main/java/common/ecommerce/model/account/AccountKey.java
index 1f27609..f66f628 100644
--- a/core/src/main/java/common/ecommerce/model/account/AccountKey.java
+++ b/core/src/main/java/common/ecommerce/model/account/AccountKey.java
@@ -14,8 +14,13 @@ import java.util.Objects;
*/
public final class AccountKey {
+ /** 接入通道(直连 / 领星聚合等)。 */
private final ChannelProvider provider;
+
+ /** 电商平台。 */
private final Platform platform;
+
+ /** OMS 店铺 ID(业务归属),不是平台店铺 ID。 */
private final String omsStoreId;
private AccountKey(ChannelProvider provider, Platform platform, String omsStoreId) {
@@ -27,22 +32,32 @@ public final class AccountKey {
this.omsStoreId = omsStoreId.trim();
}
+ /**
+ * 创建账户标识。
+ *
+ * @throws NullPointerException provider 或 platform 为 null
+ * @throws IllegalArgumentException omsStoreId 为空白
+ */
public static AccountKey of(ChannelProvider provider, Platform platform, String omsStoreId) {
return new AccountKey(provider, platform, omsStoreId);
}
+ /** 接入通道。 */
public ChannelProvider provider() {
return provider;
}
+ /** 电商平台。 */
public Platform platform() {
return platform;
}
+ /** OMS 店铺 ID。 */
public String omsStoreId() {
return omsStoreId;
}
+ /** 三维字段全部相等才相等。 */
@Override
public boolean equals(Object o) {
if (this == o) {
@@ -57,11 +72,13 @@ public final class AccountKey {
&& omsStoreId.equals(that.omsStoreId);
}
+ /** 与 {@link #equals(Object)} 一致。 */
@Override
public int hashCode() {
return Objects.hash(provider, platform, omsStoreId);
}
+ /** 形如 {@code LINGXING:WALMART_SC:store-001}。 */
@Override
public String toString() {
return provider + ":" + platform + ":" + omsStoreId;
diff --git a/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java b/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java
index 2efe426..3a6e971 100644
--- a/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java
+++ b/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java
@@ -16,15 +16,34 @@ import java.util.Objects;
*/
public final class ChannelAccount {
+ /** 三维账户标识。 */
private final AccountKey key;
+
+ /** 平台店铺 ID / 领星 store_id;不是 OMS 的 storeId。 */
private final String externalStoreId;
+
+ /** 领星 platform_code;直连账户为 null。 */
private final Integer platformCode;
+
+ /** 站点简称,如 na / eu;平台无关时可为 null。 */
private final String region;
+
+ /** 市场 ID 列表;单市场平台可为空列表。 */
private final List marketplaceIds;
+
+ /** 凭证引用(SecretProvider 的键),不是密钥本身。 */
private final String credentialRef;
+
+ /** 市场时区 IANA ID,如 America/Los_Angeles。 */
private final String marketplaceZone;
+
+ /** 结算/展示币种代码,如 USD。 */
private final String currency;
+
+ /** 发货节点,如亚马逊 ship_from;平台不需要时为 null。 */
private final String shipNode;
+
+ /** 是否沙箱账户。 */
private final boolean sandbox;
private ChannelAccount(Builder b) {
@@ -40,22 +59,27 @@ public final class ChannelAccount {
this.sandbox = b.sandbox;
}
+ /** 创建账户构建器。 */
public static Builder builder() {
return new Builder();
}
+ /** 三维账户标识。 */
public AccountKey key() {
return key;
}
+ /** OMS 店铺 ID(业务归属)。 */
public String omsStoreId() {
return key.omsStoreId();
}
+ /** 电商平台。 */
public Platform platform() {
return key.platform();
}
+ /** 接入通道。 */
public ChannelProvider provider() {
return key.provider();
}
@@ -70,10 +94,12 @@ public final class ChannelAccount {
return platformCode;
}
+ /** 站点简称,如 na / eu;平台无关时可为 null。 */
public String region() {
return region;
}
+ /** 市场 ID 列表;不可变,单市场平台为空列表。 */
public List marketplaceIds() {
return marketplaceIds;
}
@@ -88,81 +114,120 @@ public final class ChannelAccount {
return marketplaceZone;
}
+ /** 结算/展示币种代码,如 USD。 */
public String currency() {
return currency;
}
+ /** 发货节点,可为 null。 */
public String shipNode() {
return shipNode;
}
+ /** 是否沙箱账户。 */
public boolean sandbox() {
return sandbox;
}
+ /** 账户构建器。 */
public static final class Builder {
+ /** 三维账户标识;必填。 */
private AccountKey key;
+
+ /** 平台店铺 ID / 领星 store_id;必填。 */
private String externalStoreId;
+
+ /** 领星 platform_code;直连账户留空。 */
private Integer platformCode;
+
+ /** 站点简称。 */
private String region;
+
+ /** 市场 ID 列表;null 视为空列表。 */
private List marketplaceIds = Collections.emptyList();
+
+ /** 凭证引用;必填。 */
private String credentialRef;
+
+ /** 市场时区 IANA ID;必填。 */
private String marketplaceZone;
+
+ /** 币种代码;必填。 */
private String currency;
+
+ /** 发货节点。 */
private String shipNode;
+
+ /** 是否沙箱账户。 */
private boolean sandbox;
+ /** 设置三维账户标识。 */
public Builder key(AccountKey key) {
this.key = key;
return this;
}
+ /** 设置平台店铺 ID / 领星 store_id。 */
public Builder externalStoreId(String externalStoreId) {
this.externalStoreId = externalStoreId;
return this;
}
+ /** 设置领星 platform_code;直连账户不设置。 */
public Builder platformCode(Integer platformCode) {
this.platformCode = platformCode;
return this;
}
+ /** 设置站点简称。 */
public Builder region(String region) {
this.region = region;
return this;
}
+ /** 设置市场 ID 列表;null 视为空列表。 */
public Builder marketplaceIds(List marketplaceIds) {
this.marketplaceIds = marketplaceIds == null ? Collections.emptyList() : marketplaceIds;
return this;
}
+ /** 设置凭证引用(不是密钥本身)。 */
public Builder credentialRef(String credentialRef) {
this.credentialRef = credentialRef;
return this;
}
+ /** 设置市场时区 IANA ID。 */
public Builder marketplaceZone(String marketplaceZone) {
this.marketplaceZone = marketplaceZone;
return this;
}
+ /** 设置币种代码。 */
public Builder currency(String currency) {
this.currency = currency;
return this;
}
+ /** 设置发货节点。 */
public Builder shipNode(String shipNode) {
this.shipNode = shipNode;
return this;
}
+ /** 设置是否沙箱账户。 */
public Builder sandbox(boolean sandbox) {
this.sandbox = sandbox;
return this;
}
+ /**
+ * 构建账户。
+ *
+ * @throws NullPointerException key、externalStoreId、credentialRef、
+ * marketplaceZone 或 currency 为 null
+ */
public ChannelAccount build() {
return new ChannelAccount(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/aftersale/AfterSale.java b/core/src/main/java/common/ecommerce/model/aftersale/AfterSale.java
index 9af1379..d42d862 100644
--- a/core/src/main/java/common/ecommerce/model/aftersale/AfterSale.java
+++ b/core/src/main/java/common/ecommerce/model/aftersale/AfterSale.java
@@ -16,35 +16,85 @@ import java.util.Objects;
* 统一售后单(一行 = 一个售后商品行)。
*
* 平台侧的「售后单」往往是按订单聚合、按商品行拆分的(领星一份数据里带
- * {@code item_list})。统一模型按商品行展开:一行对应一个
- * {@link AfterSaleItem},避免下游再拆。
+ * {@code item_list})。统一模型按商品行展开:一行对应一个商品行
+ * ({@link AfterSale} 本身),避免下游再拆。
*
* 唯一标识 {@link #afterSaleId()} 参与 upsert;必须是稳定的平台侧标识。
*/
public final class AfterSale {
+ /** 业务平台;必填,参与 canonicalKey。 */
private final Platform platform;
+
+ /** 宿主(OMS)侧店铺标识;必填,参与 canonicalKey。与平台店铺 ID(externalStoreId)不是一回事。 */
private final String omsStoreId;
+
+ /**
+ * 售后行唯一标识;必填,参与 upsert。
+ *
+ * 领星优先取 {@code md5_v2},其次 {@code item_identifier},
+ * 再退化为 {@code 订单号|msku|after_time|row_index};{@code id} 不唯一,不可用。
+ */
private final String afterSaleId;
+
+ /** 原始订单的平台订单号;领星取 {@code amazon_order_id},可空。 */
private final String channelOrderId;
+
+ /** 归一化售后类型;构造时 null 会落为 {@link AfterSaleType#UNKNOWN},不会为 null。 */
private final AfterSaleType type;
+
+ /** 平台原始售后类型值(领星中文标签「退款 / 退货 / 换货」或数字),保留原值便于排查;可空。 */
private final String rawType;
+
+ /** 平台原始退货状态(领星 {@code return_status});可空。 */
private final String status;
+
+ /** 售后原因(领星 {@code after_reason});可空。 */
private final String reason;
+
+ /** 售后数量;平台未给时为 0。 */
private final int quantity;
+
+ /** 平台侧 SKU;领星取行级 {@code msku},缺失回落订单级 msku;可空。可用于关联商品 canonicalKey。 */
private final String platformSku;
+
+ /** 本地(ERP)SKU;领星 {@code local_sku},可空。 */
private final String localSku;
+
+ /** 亚马逊 ASIN;领星行级优先、订单级回落,非亚马逊平台为 null。 */
private final String asin;
+
+ /** 本行退款金额(Money);币种来自平台,缺失币种时整体为 null,不猜。 */
private final Money refundAmount;
+
+ /** 本行退款花费 / 平台手续费(Money);没有或无法确定币种时为 null。 */
private final Money refundCost;
+
+ /** 售后发生时间;领星行级 {@code after_time} 优先,缺失回落订单级 {@code deal_time};可空。 */
private final PlatformTime afterSaleTime;
+
+ /** 本行数据更新时间;增量同步用它判断。领星 {@code data_update_time} 优先,回落 {@code gmt_modified};可空。 */
private final PlatformTime updatedAt;
+
+ /** 退货授权号(RMA);领星 {@code rma_order_number},可空。 */
private final String rmaNumber;
+
+ /** 退货运单承运商;领星 {@code carriers},可空。 */
private final String carrier;
+
+ /** 退货运单号;领星 {@code waybill_number},可空。 */
private final String trackingNumber;
+
+ /** 换货产生的新订单号;领星 {@code exchange_order_number},无换货时为 null。 */
private final String exchangeOrderId;
+
+ /** 买家留言;可空。 */
private final String buyerNote;
+
+ /** 未标准化的原始字段(金额明细、库存属性、多渠道标记等),键名与平台一致;不为 null,可能为空 Map。 */
private final Map attributes;
+
+ /** 接入通道(直连 / 领星等);必填,不参与 canonicalKey。 */
private final ChannelProvider sourceProvider;
private AfterSale(Builder b) {
@@ -73,14 +123,17 @@ public final class AfterSale {
this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider");
}
+ /** 创建 Builder。 */
public static Builder builder() {
return new Builder();
}
+ /** 业务平台。 */
public Platform platform() {
return platform;
}
+ /** 宿主(OMS)侧店铺标识。 */
public String omsStoreId() {
return omsStoreId;
}
@@ -95,6 +148,7 @@ public final class AfterSale {
return channelOrderId;
}
+ /** 归一化售后类型;不会为 null。 */
public AfterSaleType type() {
return type;
}
@@ -109,6 +163,7 @@ public final class AfterSale {
return status;
}
+ /** 售后原因;无则为 null。 */
public String reason() {
return reason;
}
@@ -123,10 +178,12 @@ public final class AfterSale {
return platformSku;
}
+ /** 本地(ERP)SKU;无则为 null。 */
public String localSku() {
return localSku;
}
+ /** 亚马逊 ASIN;非亚马逊平台为 null。 */
public String asin() {
return asin;
}
@@ -156,10 +213,12 @@ public final class AfterSale {
return rmaNumber;
}
+ /** 退货运单承运商;无则为 null。 */
public String carrier() {
return carrier;
}
+ /** 退货运单号;无则为 null。 */
public String trackingNumber() {
return trackingNumber;
}
@@ -169,6 +228,7 @@ public final class AfterSale {
return exchangeOrderId;
}
+ /** 买家留言;无则为 null。 */
public String buyerNote() {
return buyerNote;
}
@@ -178,63 +238,155 @@ public final class AfterSale {
return attributes;
}
+ /** 接入通道。 */
public ChannelProvider sourceProvider() {
return sourceProvider;
}
public static final class Builder {
+ /** 业务平台;必填。 */
private Platform platform;
+
+ /** 宿主(OMS)侧店铺标识;必填。 */
private String omsStoreId;
+
+ /** 售后行唯一标识;必填且必须稳定。 */
private String afterSaleId;
+
+ /** 原始订单的平台订单号;可空。 */
private String channelOrderId;
+
+ /** 归一化售后类型;不设置时落为 UNKNOWN。 */
private AfterSaleType type;
+
+ /** 平台原始售后类型值;可空。 */
private String rawType;
+
+ /** 平台原始退货状态;可空。 */
private String status;
+
+ /** 售后原因;可空。 */
private String reason;
+
+ /** 售后数量;未设置时为 0。 */
private int quantity;
+
+ /** 平台侧 SKU;可空。 */
private String platformSku;
+
+ /** 本地(ERP)SKU;可空。 */
private String localSku;
+
+ /** 亚马逊 ASIN;可空。 */
private String asin;
+
+ /** 本行退款金额;可空。 */
private Money refundAmount;
+
+ /** 本行退款花费 / 平台手续费;可空。 */
private Money refundCost;
+
+ /** 售后发生时间;可空。 */
private PlatformTime afterSaleTime;
+
+ /** 本行数据更新时间;可空。 */
private PlatformTime updatedAt;
+
+ /** 退货授权号(RMA);可空。 */
private String rmaNumber;
+
+ /** 退货运单承运商;可空。 */
private String carrier;
+
+ /** 退货运单号;可空。 */
private String trackingNumber;
+
+ /** 换货产生的新订单号;可空。 */
private String exchangeOrderId;
+
+ /** 买家留言;可空。 */
private String buyerNote;
+
+ /** 原始字段;默认空 Map,传入 null 按空 Map 处理。 */
private Map attributes = Collections.emptyMap();
+
+ /** 接入通道;必填。 */
private ChannelProvider sourceProvider;
+ /** 设置业务平台;必填。 */
public Builder platform(Platform v) { this.platform = v; return this; }
+
+ /** 设置宿主(OMS)侧店铺标识;必填。 */
public Builder omsStoreId(String v) { this.omsStoreId = v; return this; }
+
+ /** 设置售后行唯一标识;必填。 */
public Builder afterSaleId(String v) { this.afterSaleId = v; return this; }
+
+ /** 设置原始订单的平台订单号;可空。 */
public Builder channelOrderId(String v) { this.channelOrderId = v; return this; }
+
+ /** 设置归一化售后类型;不设置时为 UNKNOWN。 */
public Builder type(AfterSaleType v) { this.type = v; return this; }
+
+ /** 设置平台原始售后类型值;可空。 */
public Builder rawType(String v) { this.rawType = v; return this; }
+
+ /** 设置平台原始退货状态;可空。 */
public Builder status(String v) { this.status = v; return this; }
+
+ /** 设置售后原因;可空。 */
public Builder reason(String v) { this.reason = v; return this; }
+
+ /** 设置售后数量。 */
public Builder quantity(int v) { this.quantity = v; return this; }
+
+ /** 设置平台侧 SKU;可空。 */
public Builder platformSku(String v) { this.platformSku = v; return this; }
+
+ /** 设置本地(ERP)SKU;可空。 */
public Builder localSku(String v) { this.localSku = v; return this; }
+
+ /** 设置亚马逊 ASIN;可空。 */
public Builder asin(String v) { this.asin = v; return this; }
+
+ /** 设置本行退款金额;可空。 */
public Builder refundAmount(Money v) { this.refundAmount = v; return this; }
+
+ /** 设置本行退款花费 / 平台手续费;可空。 */
public Builder refundCost(Money v) { this.refundCost = v; return this; }
+
+ /** 设置售后发生时间;可空。 */
public Builder afterSaleTime(PlatformTime v) { this.afterSaleTime = v; return this; }
+
+ /** 设置本行数据更新时间;可空。 */
public Builder updatedAt(PlatformTime v) { this.updatedAt = v; return this; }
+
+ /** 设置退货授权号(RMA);可空。 */
public Builder rmaNumber(String v) { this.rmaNumber = v; return this; }
+
+ /** 设置退货运单承运商;可空。 */
public Builder carrier(String v) { this.carrier = v; return this; }
+
+ /** 设置退货运单号;可空。 */
public Builder trackingNumber(String v) { this.trackingNumber = v; return this; }
+
+ /** 设置换货产生的新订单号;可空。 */
public Builder exchangeOrderId(String v) { this.exchangeOrderId = v; return this; }
+
+ /** 设置买家留言;可空。 */
public Builder buyerNote(String v) { this.buyerNote = v; return this; }
+
+ /** 设置原始字段;传 null 等价于空 Map。 */
public Builder attributes(Map v) {
this.attributes = v == null ? Collections.emptyMap() : v;
return this;
}
+
+ /** 设置接入通道;必填。 */
public Builder sourceProvider(ChannelProvider v) { this.sourceProvider = v; return this; }
+ /** 构建不可变售后行;缺少必填字段时抛 {@link NullPointerException}。 */
public AfterSale build() {
return new AfterSale(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/aftersale/AfterSaleQuery.java b/core/src/main/java/common/ecommerce/model/aftersale/AfterSaleQuery.java
index 5a7a2d8..a880332 100644
--- a/core/src/main/java/common/ecommerce/model/aftersale/AfterSaleQuery.java
+++ b/core/src/main/java/common/ecommerce/model/aftersale/AfterSaleQuery.java
@@ -15,12 +15,25 @@ import java.util.Objects;
*/
public final class AfterSaleQuery {
+ /** 查询起点(含);必填。对应领星 {@code start_date},格式 {@code yyyy-MM-dd}。 */
private final LocalDate startDate;
+
+ /** 查询终点(不含);必填。对应领星 {@code end_date},必须严格晚于 {@link #startDate}。 */
private final LocalDate endDate;
+
+ /** 时间窗按哪个字段过滤;null 时构造器落为 {@link DateType#AFTER_SALE_TIME},不会为 null。 */
private final DateType dateType;
+
+ /** 售后类型过滤;不为 null,空列表表示不过滤。领星编码 1 退款 / 2 退货 / 3 换货。 */
private final List types;
+
+ /** 按平台订单号过滤(领星 {@code amazon_order_id_list});空列表表示不过滤,单次最多 50 个。 */
private final List channelOrderIds;
+
+ /** 单页条数;0 或负数时由适配器使用默认值(领星默认 1000)。 */
private final int pageSize;
+
+ /** 分页游标:上一页 {@code Page.nextCursor()} 的返回值;首次查询为 null,领星内部存 offset。 */
private final String cursor;
private AfterSaleQuery(Builder b) {
@@ -36,6 +49,7 @@ public final class AfterSaleQuery {
this.cursor = b.cursor;
}
+ /** 创建 Builder。 */
public static Builder builder() {
return new Builder();
}
@@ -50,6 +64,7 @@ public final class AfterSaleQuery {
return endDate;
}
+ /** 时间窗按哪个字段过滤;不会为 null。 */
public DateType dateType() {
return dateType;
}
@@ -64,14 +79,17 @@ public final class AfterSaleQuery {
return channelOrderIds;
}
+ /** 单页条数;0 或负数由适配器取默认值。 */
public int pageSize() {
return pageSize;
}
+ /** 字符串化游标;领星等 offset 分页的渠道内部存的是 offset。 */
public String cursor() {
return cursor;
}
+ /** 复制当前条件,便于翻页时只替换 cursor。 */
public Builder toBuilder() {
return builder()
.startDate(startDate)
@@ -96,50 +114,71 @@ public final class AfterSaleQuery {
public static final class Builder {
+ /** 查询起点(必填,含)。 */
private LocalDate startDate;
+
+ /** 查询终点(必填,不含),必须严格晚于 startDate。 */
private LocalDate endDate;
+
+ /** 时间窗字段;默认 AFTER_SALE_TIME。 */
private DateType dateType;
+
+ /** 售后类型过滤;默认空列表表示不过滤。 */
private List types = Collections.emptyList();
+
+ /** 平台订单号过滤;默认空列表表示不过滤。 */
private List channelOrderIds = Collections.emptyList();
+
+ /** 单页条数;默认 100,0 或负数由适配器兜底。 */
private int pageSize = 100;
+
+ /** 分页游标;首次查询留空。 */
private String cursor;
+ /** 设置查询起点(必填,含)。 */
public Builder startDate(LocalDate startDate) {
this.startDate = startDate;
return this;
}
+ /** 设置查询终点(必填,不含),必须严格晚于 startDate。 */
public Builder endDate(LocalDate endDate) {
this.endDate = endDate;
return this;
}
+ /** 设置时间窗字段;null 表示使用默认售后时间。 */
public Builder dateType(DateType dateType) {
this.dateType = dateType;
return this;
}
+ /** 设置售后类型过滤;null 等价于空列表(不过滤)。 */
public Builder types(List types) {
this.types = types == null ? Collections.emptyList() : types;
return this;
}
+ /** 设置平台订单号过滤;null 等价于空列表(不过滤)。 */
public Builder channelOrderIds(List channelOrderIds) {
this.channelOrderIds = channelOrderIds == null
? Collections.emptyList() : channelOrderIds;
return this;
}
+ /** 设置单页条数;0 或负数由适配器取默认值。 */
public Builder pageSize(int pageSize) {
this.pageSize = pageSize;
return this;
}
+ /** 设置分页游标;首次查询留空。 */
public Builder cursor(String cursor) {
this.cursor = cursor;
return this;
}
+ /** 构建查询条件;时间窗缺失或左右颠倒时抛异常。 */
public AfterSaleQuery build() {
return new AfterSaleQuery(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/aftersale/AfterSaleType.java b/core/src/main/java/common/ecommerce/model/aftersale/AfterSaleType.java
index 4b44408..75321e2 100644
--- a/core/src/main/java/common/ecommerce/model/aftersale/AfterSaleType.java
+++ b/core/src/main/java/common/ecommerce/model/aftersale/AfterSaleType.java
@@ -14,6 +14,6 @@ public enum AfterSaleType {
RETURN,
/** 换货。 */
EXCHANGE,
- /** 无法识别;原值见 {@link AfterSaleItem#rawAfterType()}。 */
+ /** 无法识别;原值见 {@link AfterSale#rawType()}。 */
UNKNOWN
}
diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java b/core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java
index bd0bc9f..0adfeb9 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java
@@ -13,15 +13,25 @@ import java.util.List;
*/
public final class DeclaredItem {
+ /** 商品本地 SKU(领星 {@code sku}),必填。 */
private final String sku;
+ /** 原有报关明细主键(领星 {@code id});新增行为 null,适配器不会发送。 */
private final Long id;
+ /** 中文品名(领星 {@code cn_name}),必填。 */
private final String cnName;
+ /** 英文品名(领星 {@code en_name}),必填。 */
private final String enName;
+ /** 目的国申报单价(领星 {@code unit_price}),必填且必须大于 0。 */
private final BigDecimal unitPrice;
+ /** 申报币种(领星 {@code currency_code}),必填,ISO 4217 三位代码。 */
private final String currencyCode;
+ /** 申报重量(领星 {@code weight}),单位 g,必填且必须大于 0。 */
private final BigDecimal weight;
+ /** 申报数量(领星 {@code quantity}),必填且必须大于 0。 */
private final int quantity;
+ /** HS 海关编码(领星 {@code hs_code});可选,空白时不发送。 */
private final String hsCode;
+ /** 特殊属性编码列表(领星 {@code special_attr}),不可变,永不为 null;空表示无特殊属性。 */
private final List specialAttributes;
private DeclaredItem(Builder b) {
@@ -38,6 +48,7 @@ public final class DeclaredItem {
new ArrayList(b.specialAttributes));
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@@ -52,10 +63,12 @@ public final class DeclaredItem {
return id;
}
+ /** 中文品名。 */
public String cnName() {
return cnName;
}
+ /** 英文品名。 */
public String enName() {
return enName;
}
@@ -65,6 +78,7 @@ public final class DeclaredItem {
return unitPrice;
}
+ /** 申报币种,ISO 4217 代码。 */
public String currencyCode() {
return currencyCode;
}
@@ -74,10 +88,12 @@ public final class DeclaredItem {
return weight;
}
+ /** 申报数量,必须大于 0。 */
public int quantity() {
return quantity;
}
+ /** HS 海关编码;可为 null。 */
public String hsCode() {
return hsCode;
}
@@ -108,80 +124,104 @@ public final class DeclaredItem {
return value;
}
+ /** {@link DeclaredItem} 构建器;必填项在 {@code build()} 时校验,空白串与 null 都会被拒。 */
public static final class Builder {
+ /** 商品本地 SKU,必填。 */
private String sku;
+ /** 原有报关明细主键;新增行不传。 */
private Long id;
+ /** 中文品名,必填。 */
private String cnName;
+ /** 英文品名,必填。 */
private String enName;
+ /** 申报单价,必填且大于 0。 */
private BigDecimal unitPrice;
+ /** 申报币种,必填。 */
private String currencyCode;
+ /** 申报重量,单位 g,必填且大于 0。 */
private BigDecimal weight;
+ /** 申报数量,必填且大于 0。 */
private int quantity;
+ /** HS 海关编码,可选。 */
private String hsCode;
+ /** 特殊属性编码;默认空列表,setter 传 null 也归一为空列表。 */
private List specialAttributes = Collections.emptyList();
+ /** 设置商品本地 SKU。 */
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;
}
+ /** 设置申报单价,必须大于 0。 */
public Builder unitPrice(BigDecimal unitPrice) {
this.unitPrice = unitPrice;
return this;
}
+ /** 以字符串设置申报单价,自动 trim;null 保持 null。 */
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;
}
+ /** 设置申报重量,单位 g,必须大于 0。 */
public Builder weight(BigDecimal weight) {
this.weight = weight;
return this;
}
+ /** 以字符串设置申报重量,单位 g,自动 trim;null 保持 null。 */
public Builder weight(String weight) {
this.weight = weight == null ? null : new BigDecimal(weight.trim());
return this;
}
+ /** 设置申报数量,必须大于 0。 */
public Builder quantity(int quantity) {
this.quantity = quantity;
return this;
}
+ /** 设置 HS 海关编码。 */
public Builder hsCode(String hsCode) {
this.hsCode = hsCode;
return this;
}
+ /** 设置特殊属性编码列表;null 视为空列表。 */
public Builder specialAttributes(List specialAttributes) {
this.specialAttributes = specialAttributes == null
? Collections.emptyList() : specialAttributes;
return this;
}
+ /** 以可变参数设置特殊属性编码;null 视为空列表。 */
public Builder specialAttributes(String... specialAttributes) {
List values = new ArrayList();
if (specialAttributes != null) {
@@ -191,6 +231,7 @@ public final class DeclaredItem {
return this;
}
+ /** 构建报关明细;必填项缺失或非正数时抛 {@link IllegalArgumentException}。 */
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
index 6224ee8..ad41a2b 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java
@@ -12,7 +12,9 @@ import java.util.List;
*/
public final class LabelQuery {
+ /** 销售出库单号列表(领星 {@code wo_number_arr}),与 {@link #orderNumbers} 二选一。 */
private final List woNumbers;
+ /** 领星系统单号列表(领星 {@code order_number_arr}),与 {@link #woNumbers} 二选一。 */
private final List orderNumbers;
private LabelQuery(Builder b) {
@@ -20,6 +22,7 @@ public final class LabelQuery {
this.orderNumbers = Collections.unmodifiableList(new ArrayList(b.orderNumbers));
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@@ -34,16 +37,21 @@ public final class LabelQuery {
return orderNumbers;
}
+ /** {@link LabelQuery} 构建器;构建时不校验,二选一由适配器在调用时显式检查。 */
public static final class Builder {
+ /** 销售出库单号;默认空列表,setter 传 null 也归一为空列表。 */
private List woNumbers = Collections.emptyList();
+ /** 领星系统单号;默认空列表,setter 传 null 也归一为空列表。 */
private List orderNumbers = Collections.emptyList();
+ /** 设置销售出库单号列表;null 视为空列表。 */
public Builder woNumbers(List woNumbers) {
this.woNumbers = woNumbers == null ? Collections.emptyList() : woNumbers;
return this;
}
+ /** 以可变参数设置销售出库单号;null 视为空列表。 */
public Builder woNumbers(String... woNumbers) {
List values = new ArrayList();
if (woNumbers != null) {
@@ -53,11 +61,13 @@ public final class LabelQuery {
return this;
}
+ /** 设置领星系统单号列表;null 视为空列表。 */
public Builder orderNumbers(List orderNumbers) {
this.orderNumbers = orderNumbers == null ? Collections.emptyList() : orderNumbers;
return this;
}
+ /** 以可变参数设置领星系统单号;null 视为空列表。 */
public Builder orderNumbers(String... orderNumbers) {
List values = new ArrayList();
if (orderNumbers != null) {
@@ -67,6 +77,7 @@ public final class LabelQuery {
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
index 33ddfd3..b7cf26b 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java
@@ -20,14 +20,23 @@ import java.util.List;
*/
public final class OrderEditRequest {
+ /** 领星系统单号({@code global_order_no}),必填,定位要编辑的订单。 */
private final String globalOrderNo;
+ /** 发货仓库 id(领星 {@code sys_wid});可选,平台要求改仓库时与 {@link #logisticsTypeId} 一起给。 */
private final Long warehouseId;
+ /** 物流方式 id(领星 {@code logistics_type_id});可选。 */
private final Long logisticsTypeId;
+ /** 包裹预估长({@code pre_pkg_length}),单位 cm;与宽高、重量四项同进同退。 */
private final BigDecimal packageLength;
+ /** 包裹预估宽({@code pre_pkg_width}),单位 cm。 */
private final BigDecimal packageWidth;
+ /** 包裹预估高({@code pre_pkg_height}),单位 cm。 */
private final BigDecimal packageHeight;
+ /** 包裹预估总重量({@code pre_weight}),单位 g。 */
private final BigDecimal packageWeight;
+ /** 是否修改报关信息;为 true 时 {@link #declaredItems} 必须非空,为 false 时必须为空。 */
private final boolean modifyDeclared;
+ /** 报关明细(领星 {@code declared_info[]}),不可变,永不为 null。 */
private final List declaredItems;
private OrderEditRequest(Builder b) {
@@ -68,6 +77,7 @@ public final class OrderEditRequest {
}
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@@ -107,10 +117,12 @@ public final class OrderEditRequest {
return packageWeight;
}
+ /** 是否修改报关信息。 */
public boolean modifyDeclared() {
return modifyDeclared;
}
+ /** 报关明细,不可变列表;未开启报关时为空列表。 */
public List declaredItems() {
return declaredItems;
}
@@ -122,84 +134,108 @@ public final class OrderEditRequest {
return value.trim();
}
+ /** {@link OrderEditRequest} 构建器;三维约束在 {@code build()} 时统一校验。 */
public static final class Builder {
+ /** 领星系统单号,必填。 */
private String globalOrderNo;
+ /** 发货仓库 id;可选。 */
private Long warehouseId;
+ /** 物流方式 id;可选。 */
private Long logisticsTypeId;
+ /** 包裹预估长,单位 cm。 */
private BigDecimal packageLength;
+ /** 包裹预估宽,单位 cm。 */
private BigDecimal packageWidth;
+ /** 包裹预估高,单位 cm。 */
private BigDecimal packageHeight;
+ /** 包裹预估总重量,单位 g。 */
private BigDecimal packageWeight;
+ /** 是否修改报关信息。 */
private boolean modifyDeclared;
+ /** 报关明细;默认空列表,setter 传 null 也归一为空列表。 */
private List declaredItems = Collections.emptyList();
+ /** 设置领星系统单号。 */
public Builder globalOrderNo(String globalOrderNo) {
this.globalOrderNo = globalOrderNo;
return this;
}
+ /** 设置发货仓库 id。 */
public Builder warehouseId(Long warehouseId) {
this.warehouseId = warehouseId;
return this;
}
+ /** 设置物流方式 id。 */
public Builder logisticsTypeId(Long logisticsTypeId) {
this.logisticsTypeId = logisticsTypeId;
return this;
}
+ /** 设置包裹预估长,单位 cm。 */
public Builder packageLength(BigDecimal packageLength) {
this.packageLength = packageLength;
return this;
}
+ /** 以字符串设置包裹预估长,单位 cm,自动 trim;null 保持 null。 */
public Builder packageLength(String packageLength) {
this.packageLength = packageLength == null ? null : new BigDecimal(packageLength.trim());
return this;
}
+ /** 设置包裹预估宽,单位 cm。 */
public Builder packageWidth(BigDecimal packageWidth) {
this.packageWidth = packageWidth;
return this;
}
+ /** 以字符串设置包裹预估宽,单位 cm,自动 trim;null 保持 null。 */
public Builder packageWidth(String packageWidth) {
this.packageWidth = packageWidth == null ? null : new BigDecimal(packageWidth.trim());
return this;
}
+ /** 设置包裹预估高,单位 cm。 */
public Builder packageHeight(BigDecimal packageHeight) {
this.packageHeight = packageHeight;
return this;
}
+ /** 以字符串设置包裹预估高,单位 cm,自动 trim;null 保持 null。 */
public Builder packageHeight(String packageHeight) {
this.packageHeight = packageHeight == null ? null : new BigDecimal(packageHeight.trim());
return this;
}
+ /** 设置包裹预估总重量,单位 g。 */
public Builder packageWeight(BigDecimal packageWeight) {
this.packageWeight = packageWeight;
return this;
}
+ /** 以字符串设置包裹预估总重量,单位 g,自动 trim;null 保持 null。 */
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;
}
+ /** 设置报关明细列表;null 视为空列表。 */
public Builder declaredItems(List declaredItems) {
this.declaredItems = declaredItems == null
? Collections.emptyList() : declaredItems;
return this;
}
+ /** 以可变参数设置报关明细;null 视为空列表。 */
public Builder declaredItems(DeclaredItem... declaredItems) {
List values = new ArrayList();
if (declaredItems != null) {
@@ -209,6 +245,12 @@ public final class OrderEditRequest {
return this;
}
+ /**
+ * 构建请求。
+ *
+ * 包裹四项未同时设置、报关开关与明细不一致、或没有任何可改项时,
+ * 抛 {@link IllegalArgumentException}。
+ */
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
index 8de31a5..0abadce 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java
@@ -12,12 +12,18 @@ import java.util.List;
*/
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";
+ /** 平台业务码:{@link #CODE_SUCCESS} / {@link #CODE_ALL_FAILED} / {@link #CODE_PARTIAL}。 */
private final String code;
+ /** 平台返回的消息,原值。 */
private final String message;
+ /** 逐单失败明细(领星 {@code data.error_details[]}),不可变,永不为 null。 */
private final List failures;
private OrderEditResult(Builder b) {
@@ -26,6 +32,7 @@ public final class OrderEditResult {
this.failures = Collections.unmodifiableList(new ArrayList(b.failures));
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@@ -35,10 +42,12 @@ public final class OrderEditResult {
return code;
}
+ /** 平台返回的消息。 */
public String message() {
return message;
}
+ /** 逐单失败明细,不可变列表。 */
public List failures() {
return failures;
}
@@ -51,44 +60,57 @@ public final class OrderEditResult {
/** 单笔失败原因。 */
public static final class Failure {
+ /** 失败单的领星系统单号({@code global_order_no}),按字符串接收以避免精度丢失。 */
private final String globalOrderNo;
+ /** 失败原因({@code error_message}),平台原值。 */
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;
}
}
+ /** {@link OrderEditResult} 构建器。 */
public static final class Builder {
+ /** 平台业务码。 */
private String code;
+ /** 平台返回的消息。 */
private String message;
+ /** 逐单失败明细;默认空列表,setter 传 null 也归一为空列表。 */
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;
}
+ /** 设置逐单失败明细;null 视为空列表。 */
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
index 209f5bf..170d312 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java
@@ -21,40 +21,75 @@ import java.util.Objects;
*/
public final class OutboundOrder {
+ /** 宿主(OMS)侧店铺标识,必填;由调用上下文注入,不是平台店铺 ID。 */
private final String omsStoreId;
+ /** 接入通道(直连 / 领星聚合),必填。 */
private final ChannelProvider sourceProvider;
+ /** 通道侧账户标识;领星实现填领星 {@code sid},未给时为 null。 */
private final String sourceAccountId;
+ /** 销售出库单号(领星 {@code wo_number}),必填,是本模型的业务主键。 */
private final String woNumber;
+ /** 领星出库单 id({@code wo_id}),长整型转字符串。 */
private final String woId;
+ /** 领星系统单号({@code order_number}),不是平台订单号。 */
private final String orderNumber;
+ /** 平台订单号(领星 {@code platform_order_no[]});合并单可能多于一个,永不为 null。 */
private final List platformOrderNos;
+ /** 领星店铺 id({@code sid}),即领星内部店铺标识。 */
private final Integer sid;
+ /** 卖家名称,平台原值。 */
private final String sellerName;
+ /** 发货仓库 id(领星 {@code wid})。 */
private final Integer warehouseId;
+ /** 发货仓库名称。 */
private final String warehouseName;
+ /** 仓库类型:1 本地仓库、2 FBA 仓、3 第三方海外仓。 */
private final Integer warehouseType;
+ /** 出库单状态:1 物流下单、2 待出库、3 已出库、4 已截单。 */
private final Integer status;
+ /** 出库单状态名称,平台原值。 */
private final String statusName;
+ /** 物流下单状态:1 待导入 … 5 下单完成 … 43 物流取消完成。 */
private final Integer logisticsStatus;
+ /** 物流下单状态名称,平台原值。 */
private final String logisticsStatusName;
+ /** 物流下单结果消息;失败时为平台给出的原因。 */
private final String logisticsMessage;
+ /** 物流商 id({@code logistics_provider_id})。 */
private final Long logisticsProviderId;
+ /** 物流商名称。 */
private final String logisticsProviderName;
+ /** 物流方式 id({@code logistics_type_id})。 */
private final Long logisticsTypeId;
+ /** 物流方式名称。 */
private final String logisticsTypeName;
+ /** 运单号。 */
private final String waybillNo;
+ /** 跟踪号;与运单号不一定相同。 */
private final String trackingNo;
+ /** 订单金额;平台未给 ISO 币种时为 null。 */
private final Money orderAmount;
+ /** 目的国家/地区代码,平台原值(通常为 ISO 3166-1 alpha-2)。 */
private final String targetCountry;
+ /** 预估重量({@code pkg_weight}),保留平台原始字符串,单位见 {@link #packageWeightUnit}。 */
private final String packageWeight;
+ /** 包裹实重({@code pkg_real_weight}),保留平台原始字符串。 */
private final String packageRealWeight;
+ /** 包裹计费重({@code pkg_fee_weight}),保留平台原始字符串。 */
private final String packageFeeWeight;
+ /** 包裹重量单位({@code pkg_weight_unit}),作用于上面三个重量。 */
private final String packageWeightUnit;
+ /** 面单链接;优先领星 30 分钟有效的 COS 链接,旧 {@code uri} 仅兜底,可能为 null。 */
private final String surfaceFileUrl;
+ /** 创建时间(领星 {@code create_at}),按 ERP 系统时间(北京时间)解析;全零占位视为 null。 */
private final PlatformTime createdAt;
+ /** 更新时间(领星 {@code update_at}),时区处理同 {@link #createdAt}。 */
private final PlatformTime updatedAt;
+ /** 出库时间【单据操作】(领星 {@code delivered_at});全零占位视为 null。 */
private final PlatformTime deliveredAt;
+ /** 下单时间(领星 {@code purchase_time});全零占位视为 null。 */
private final PlatformTime purchasedAt;
+ /** 商品行(领星 {@code product_info[]}),不可变列表,永不为 null。 */
private final List lines;
private OutboundOrder(Builder b) {
@@ -95,18 +130,22 @@ public final class OutboundOrder {
this.lines = Collections.unmodifiableList(new ArrayList(b.lines));
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
+ /** 宿主(OMS)侧店铺标识。 */
public String omsStoreId() {
return omsStoreId;
}
+ /** 接入通道(直连 / 领星聚合)。 */
public ChannelProvider sourceProvider() {
return sourceProvider;
}
+ /** 通道侧账户标识。 */
public String sourceAccountId() {
return sourceAccountId;
}
@@ -136,14 +175,17 @@ public final class OutboundOrder {
return sid;
}
+ /** 卖家名称。 */
public String sellerName() {
return sellerName;
}
+ /** 发货仓库 id。 */
public Integer warehouseId() {
return warehouseId;
}
+ /** 发货仓库名称。 */
public String warehouseName() {
return warehouseName;
}
@@ -158,6 +200,7 @@ public final class OutboundOrder {
return status;
}
+ /** 出库单状态名称。 */
public String statusName() {
return statusName;
}
@@ -167,34 +210,42 @@ public final class OutboundOrder {
return logisticsStatus;
}
+ /** 物流下单状态名称。 */
public String logisticsStatusName() {
return logisticsStatusName;
}
+ /** 物流下单结果消息。 */
public String logisticsMessage() {
return logisticsMessage;
}
+ /** 物流商 id。 */
public Long logisticsProviderId() {
return logisticsProviderId;
}
+ /** 物流商名称。 */
public String logisticsProviderName() {
return logisticsProviderName;
}
+ /** 物流方式 id。 */
public Long logisticsTypeId() {
return logisticsTypeId;
}
+ /** 物流方式名称。 */
public String logisticsTypeName() {
return logisticsTypeName;
}
+ /** 运单号。 */
public String waybillNo() {
return waybillNo;
}
+ /** 跟踪号。 */
public String trackingNo() {
return trackingNo;
}
@@ -204,6 +255,7 @@ public final class OutboundOrder {
return orderAmount;
}
+ /** 目的国家/地区代码。 */
public String targetCountry() {
return targetCountry;
}
@@ -223,6 +275,7 @@ public final class OutboundOrder {
return packageFeeWeight;
}
+ /** 包裹重量单位。 */
public String packageWeightUnit() {
return packageWeightUnit;
}
@@ -232,10 +285,12 @@ public final class OutboundOrder {
return surfaceFileUrl;
}
+ /** 创建时间。 */
public PlatformTime createdAt() {
return createdAt;
}
+ /** 更新时间。 */
public PlatformTime updatedAt() {
return updatedAt;
}
@@ -250,224 +305,297 @@ public final class OutboundOrder {
return purchasedAt;
}
+ /** 商品行,不可变列表。 */
public List lines() {
return lines;
}
+ /** {@link OutboundOrder} 构建器;必填字段为 omsStoreId / sourceProvider / woNumber。 */
public static final class Builder {
+ /** 宿主(OMS)侧店铺标识,必填。 */
private String omsStoreId;
+ /** 接入通道(直连 / 领星聚合),必填。 */
private ChannelProvider sourceProvider;
+ /** 通道侧账户标识。 */
private String sourceAccountId;
+ /** 销售出库单号,必填。 */
private String woNumber;
+ /** 领星出库单 id。 */
private String woId;
+ /** 领星系统单号。 */
private String orderNumber;
+ /** 平台单号;默认空列表,setter 传 null 也归一为空列表。 */
private List platformOrderNos = Collections.emptyList();
+ /** 领星店铺 id。 */
private Integer sid;
+ /** 卖家名称。 */
private String sellerName;
+ /** 发货仓库 id。 */
private Integer warehouseId;
+ /** 发货仓库名称。 */
private String warehouseName;
+ /** 仓库类型:1 本地仓库、2 FBA 仓、3 第三方海外仓。 */
private Integer warehouseType;
+ /** 出库单状态:1 物流下单、2 待出库、3 已出库、4 已截单。 */
private Integer status;
+ /** 出库单状态名称。 */
private String statusName;
+ /** 物流下单状态。 */
private Integer logisticsStatus;
+ /** 物流下单状态名称。 */
private String logisticsStatusName;
+ /** 物流下单结果消息。 */
private String logisticsMessage;
+ /** 物流商 id。 */
private Long logisticsProviderId;
+ /** 物流商名称。 */
private String logisticsProviderName;
+ /** 物流方式 id。 */
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;
+ /** 商品行;默认空列表,setter 传 null 也归一为空列表。 */
private List lines = Collections.emptyList();
+ /** 设置宿主(OMS)侧店铺标识。 */
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;
}
+ /** 设置领星出库单 id。 */
public Builder woId(String woId) {
this.woId = woId;
return this;
}
+ /** 设置领星系统单号。 */
public Builder orderNumber(String orderNumber) {
this.orderNumber = orderNumber;
return this;
}
+ /** 设置平台单号列表;null 视为空列表。 */
public Builder platformOrderNos(List platformOrderNos) {
this.platformOrderNos = platformOrderNos == null
? Collections.emptyList() : platformOrderNos;
return this;
}
+ /** 设置领星店铺 id。 */
public Builder sid(Integer sid) {
this.sid = sid;
return this;
}
+ /** 设置卖家名称。 */
public Builder sellerName(String sellerName) {
this.sellerName = sellerName;
return this;
}
+ /** 设置发货仓库 id。 */
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;
}
+ /** 设置物流商 id。 */
public Builder logisticsProviderId(Long logisticsProviderId) {
this.logisticsProviderId = logisticsProviderId;
return this;
}
+ /** 设置物流商名称。 */
public Builder logisticsProviderName(String logisticsProviderName) {
this.logisticsProviderName = logisticsProviderName;
return this;
}
+ /** 设置物流方式 id。 */
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;
}
+ /** 设置商品行;null 视为空列表。 */
public Builder lines(List lines) {
this.lines = lines == null ? Collections.emptyList() : lines;
return this;
}
+ /** 构建出库单;{@code omsStoreId}/{@code sourceProvider}/{@code woNumber} 为 null 时抛 NPE。 */
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
index 1a55950..0db96c8 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java
@@ -12,12 +12,19 @@ import java.util.Objects;
*/
public final class OutboundOrderLine {
+ /** 出库单明细 id(领星 {@code wod_id}),必填,长整型转字符串。 */
private final String lineId;
+ /** 领星商品 id({@code product_id}),长整型转字符串。 */
private final String productId;
+ /** 领星本地 SKU({@code sku}),不是平台 MSKU。 */
private final String sku;
+ /** 平台 MSKU({@code seller_sku}),与 {@link #sku} 不要混用。 */
private final String sellerSku;
+ /** 商品名称,平台原值。 */
private final String productName;
+ /** 数量(领星 {@code count});平台缺失时适配器填 0,正常应大于 0。 */
private final int quantity;
+ /** 商品单价;币种不是 ISO 代码(如符号 {@code $})时为 null,不猜币种。 */
private final Money unitPrice;
private OutboundOrderLine(Builder b) {
@@ -30,6 +37,7 @@ public final class OutboundOrderLine {
this.unitPrice = b.unitPrice;
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@@ -39,6 +47,7 @@ public final class OutboundOrderLine {
return lineId;
}
+ /** 领星商品 id。 */
public String productId() {
return productId;
}
@@ -53,10 +62,12 @@ public final class OutboundOrderLine {
return sellerSku;
}
+ /** 商品名称。 */
public String productName() {
return productName;
}
+ /** 数量。 */
public int quantity() {
return quantity;
}
@@ -66,51 +77,67 @@ public final class OutboundOrderLine {
return unitPrice;
}
+ /** {@link OutboundOrderLine} 构建器;{@code lineId} 必填。 */
public static final class Builder {
+ /** 出库单明细 id,必填。 */
private String lineId;
+ /** 领星商品 id。 */
private String productId;
+ /** 领星本地 SKU。 */
private String sku;
+ /** 平台 MSKU。 */
private String sellerSku;
+ /** 商品名称。 */
private String productName;
+ /** 数量。 */
private int quantity;
+ /** 商品单价。 */
private Money unitPrice;
+ /** 设置出库单明细 id。 */
public Builder lineId(String lineId) {
this.lineId = lineId;
return this;
}
+ /** 设置领星商品 id。 */
public Builder productId(String productId) {
this.productId = productId;
return this;
}
+ /** 设置领星本地 SKU。 */
public Builder sku(String sku) {
this.sku = sku;
return this;
}
+ /** 设置平台 MSKU。 */
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;
}
+ /** 构建商品行;{@code lineId} 为 null 时抛 NPE。 */
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
index 563cc3c..2c138ce 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java
@@ -22,16 +22,27 @@ public final class OutboundOrderQuery {
/** 变更时间。 */
public static final String TIME_UPDATED = "update_at";
+ /** 时间窗起点(UTC);为 null 时不传,由平台按默认区间处理。领星按日期(北京时间)截断到天。 */
private final Instant after;
+ /** 时间窗终点(UTC);为 null 时不传。领星按日期(北京时间)截断到天。 */
private final Instant before;
+ /** 时间字段类型,取值见本类常量;默认 {@link #TIME_UPDATED}。 */
private final String timeType;
+ /** 领星店铺 id({@code sid})过滤,字符串形式;为空时适配器使用当前账户的店铺 id。 */
private final List sids;
+ /** 出库单状态过滤(领星 {@code status_arr}),含义见 {@link OutboundOrder#status()}。 */
private final List statuses;
+ /** 物流下单状态过滤(领星 {@code logistics_status_arr})。 */
private final List logisticsStatuses;
+ /** 平台订单号过滤(领星 {@code platform_order_no_arr})。 */
private final List platformOrderNos;
+ /** 领星系统单号过滤(领星 {@code order_number_arr})。 */
private final List orderNumbers;
+ /** 销售出库单号过滤(领星 {@code wo_number_arr})。 */
private final List woNumbers;
+ /** 每页条数;非正数时领星适配器回落到 20,超过 200 时截断到 200。 */
private final int pageSize;
+ /** 分页游标;领星存的是字符串化页码,null 表示第一页。 */
private final String cursor;
private OutboundOrderQuery(Builder b) {
@@ -48,6 +59,7 @@ public final class OutboundOrderQuery {
this.cursor = b.cursor;
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@@ -86,26 +98,32 @@ public final class OutboundOrderQuery {
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)
@@ -121,40 +139,57 @@ public final class OutboundOrderQuery {
.cursor(cursor);
}
+ /** {@link OutboundOrderQuery} 构建器;列表字段传 null 一律归一为空列表。 */
public static final class Builder {
+ /** 时间窗起点(UTC);null 表示不限制起点。 */
private Instant after;
+ /** 时间窗终点(UTC);null 表示不限制终点。 */
private Instant before;
+ /** 时间字段类型;默认 {@link #TIME_UPDATED}。 */
private String timeType = TIME_UPDATED;
+ /** 领星店铺 id 过滤;默认空列表。 */
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();
+ /** 每页条数;默认 100,领星上限 200。 */
private int pageSize = 100;
+ /** 分页游标;null 表示第一页。 */
private String cursor;
+ /** 设置时间窗起点。 */
public Builder after(Instant after) {
this.after = after;
return this;
}
+ /** 设置时间窗终点。 */
public Builder before(Instant before) {
this.before = before;
return this;
}
+ /** 设置时间字段类型,取值见本类常量;null 时适配器按默认 {@link #TIME_UPDATED} 处理。 */
public Builder timeType(String timeType) {
this.timeType = timeType;
return this;
}
+ /** 设置店铺 id 过滤;null 视为空列表。 */
public Builder sids(List sids) {
this.sids = sids == null ? Collections.emptyList() : sids;
return this;
}
+ /** 以可变参数设置店铺 id 过滤;null 视为空列表。 */
public Builder sids(String... sids) {
List values = new ArrayList();
if (sids != null) {
@@ -164,11 +199,13 @@ public final class OutboundOrderQuery {
return this;
}
+ /** 设置出库单状态过滤;null 视为空列表。 */
public Builder statuses(List statuses) {
this.statuses = statuses == null ? Collections.emptyList() : statuses;
return this;
}
+ /** 以可变参数设置出库单状态过滤;null 视为空列表。 */
public Builder statuses(Integer... statuses) {
List values = new ArrayList();
if (statuses != null) {
@@ -178,12 +215,14 @@ public final class OutboundOrderQuery {
return this;
}
+ /** 设置物流下单状态过滤;null 视为空列表。 */
public Builder logisticsStatuses(List logisticsStatuses) {
this.logisticsStatuses = logisticsStatuses == null
? Collections.emptyList() : logisticsStatuses;
return this;
}
+ /** 以可变参数设置物流下单状态过滤;null 视为空列表。 */
public Builder logisticsStatuses(Integer... logisticsStatuses) {
List values = new ArrayList();
if (logisticsStatuses != null) {
@@ -193,12 +232,14 @@ public final class OutboundOrderQuery {
return this;
}
+ /** 设置平台订单号过滤;null 视为空列表。 */
public Builder platformOrderNos(List platformOrderNos) {
this.platformOrderNos = platformOrderNos == null
? Collections.emptyList() : platformOrderNos;
return this;
}
+ /** 以可变参数设置平台订单号过滤;null 视为空列表。 */
public Builder platformOrderNos(String... platformOrderNos) {
List values = new ArrayList();
if (platformOrderNos != null) {
@@ -208,11 +249,13 @@ public final class OutboundOrderQuery {
return this;
}
+ /** 设置领星系统单号过滤;null 视为空列表。 */
public Builder orderNumbers(List orderNumbers) {
this.orderNumbers = orderNumbers == null ? Collections.emptyList() : orderNumbers;
return this;
}
+ /** 以可变参数设置领星系统单号过滤;null 视为空列表。 */
public Builder orderNumbers(String... orderNumbers) {
List values = new ArrayList();
if (orderNumbers != null) {
@@ -222,11 +265,13 @@ public final class OutboundOrderQuery {
return this;
}
+ /** 设置销售出库单号过滤;null 视为空列表。 */
public Builder woNumbers(List woNumbers) {
this.woNumbers = woNumbers == null ? Collections.emptyList() : woNumbers;
return this;
}
+ /** 以可变参数设置销售出库单号过滤;null 视为空列表。 */
public Builder woNumbers(String... woNumbers) {
List values = new ArrayList();
if (woNumbers != null) {
@@ -236,16 +281,19 @@ public final class OutboundOrderQuery {
return this;
}
+ /** 设置每页条数;领星适配器会截断到 200。 */
public Builder pageSize(int pageSize) {
this.pageSize = pageSize;
return this;
}
+ /** 设置分页游标;领星实现为字符串化页码,null 表示第一页。 */
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/OutboundPackage.java b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundPackage.java
index 90231c8..27b937a 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundPackage.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundPackage.java
@@ -11,19 +11,33 @@ import java.util.Objects;
*/
public final class OutboundPackage {
+ /** 领星系统单号(global_order_no),必填;同时是出库任务的定位键。 */
private final String globalOrderNo;
+ /** 领星发货仓库 id(wid);为 null 时不发送,由领星按订单原有仓库处理。 */
private final Long warehouseId;
+ /** 领星物流方式 id(logistics_type_id),模型按字符串保存;null 表示不指定。 */
private final String logisticsTypeId;
+ /** 运单号(waybill_no),由平台或物流商提供。 */
private final String waybillNo;
+ /** 跟踪号(tracking_no),用于买家侧查询;与运单号不一定相同。 */
private final String trackingNo;
+ /** 重量单位(weight_unit),如 g、kg;作用于实重与计费重,为 null 时不发送。 */
private final String weightUnit;
+ /** 实重(real_weight),保留平台要求的字符串,避免精度与格式变化。 */
private final String realWeight;
+ /** 尺寸单位(size_unit),如 cm;作用于长宽高。 */
private final String sizeUnit;
+ /** 包裹长(length),单位见 {@link #sizeUnit}。 */
private final String length;
+ /** 包裹宽(width),单位见 {@link #sizeUnit}。 */
private final String width;
+ /** 包裹高(height),单位见 {@link #sizeUnit}。 */
private final String height;
+ /** 计费重(fee_weight),字符串原值;通常由物流商按体积重规则计算。 */
private final String feeWeight;
+ /** 物流运费(logistics_freight),字符串原值,不在此处做币种或精度转换。 */
private final String logisticsFreight;
+ /** 运费币种(logistics_freight_currency_code);SDK 只透传,不校验是否为 ISO 代码。 */
private final String logisticsFreightCurrency;
private OutboundPackage(Builder b) {
@@ -43,57 +57,102 @@ public final class OutboundPackage {
this.logisticsFreightCurrency = b.logisticsFreightCurrency;
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
+ /** 领星系统单号,必填。 */
public String globalOrderNo() { return globalOrderNo; }
+ /** 领星发货仓库 id。 */
public Long warehouseId() { return warehouseId; }
+ /** 领星物流方式 id。 */
public String logisticsTypeId() { return logisticsTypeId; }
+ /** 运单号。 */
public String waybillNo() { return waybillNo; }
+ /** 跟踪号。 */
public String trackingNo() { return trackingNo; }
+ /** 重量单位。 */
public String weightUnit() { return weightUnit; }
+ /** 实重,字符串原值。 */
public String realWeight() { return realWeight; }
+ /** 尺寸单位。 */
public String sizeUnit() { return sizeUnit; }
+ /** 包裹长,单位见 {@link #sizeUnit}。 */
public String length() { return length; }
+ /** 包裹宽,单位见 {@link #sizeUnit}。 */
public String width() { return width; }
+ /** 包裹高,单位见 {@link #sizeUnit}。 */
public String height() { return height; }
+ /** 计费重,字符串原值。 */
public String feeWeight() { return feeWeight; }
+ /** 物流运费,字符串原值。 */
public String logisticsFreight() { return logisticsFreight; }
+ /** 运费币种,平台原值。 */
public String logisticsFreightCurrency() { return logisticsFreightCurrency; }
+ /** {@link OutboundPackage} 构建器;未设置的字段不发送给平台。 */
public static final class Builder {
+ /** 领星系统单号,必填。 */
private String globalOrderNo;
+ /** 领星发货仓库 id;null 时不发送。 */
private Long warehouseId;
+ /** 领星物流方式 id。 */
private String logisticsTypeId;
+ /** 运单号。 */
private String waybillNo;
+ /** 跟踪号。 */
private String trackingNo;
+ /** 重量单位。 */
private String weightUnit;
+ /** 实重,字符串原值。 */
private String realWeight;
+ /** 尺寸单位。 */
private String sizeUnit;
+ /** 包裹长。 */
private String length;
+ /** 包裹宽。 */
private String width;
+ /** 包裹高。 */
private String height;
+ /** 计费重,字符串原值。 */
private String feeWeight;
+ /** 物流运费,字符串原值。 */
private String logisticsFreight;
+ /** 运费币种,平台原值。 */
private String logisticsFreightCurrency;
+ /** 设置领星系统单号。 */
public Builder globalOrderNo(String v) { this.globalOrderNo = v; return this; }
+ /** 设置领星发货仓库 id。 */
public Builder warehouseId(Long v) { this.warehouseId = v; return this; }
+ /** 设置领星物流方式 id。 */
public Builder logisticsTypeId(String v) { this.logisticsTypeId = v; return this; }
+ /** 设置运单号。 */
public Builder waybillNo(String v) { this.waybillNo = v; return this; }
+ /** 设置跟踪号。 */
public Builder trackingNo(String v) { this.trackingNo = v; return this; }
+ /** 设置重量单位。 */
public Builder weightUnit(String v) { this.weightUnit = v; return this; }
+ /** 设置实重。 */
public Builder realWeight(String v) { this.realWeight = v; return this; }
+ /** 设置尺寸单位。 */
public Builder sizeUnit(String v) { this.sizeUnit = v; return this; }
+ /** 设置包裹长。 */
public Builder length(String v) { this.length = v; return this; }
+ /** 设置包裹宽。 */
public Builder width(String v) { this.width = v; return this; }
+ /** 设置包裹高。 */
public Builder height(String v) { this.height = v; return this; }
+ /** 设置计费重。 */
public Builder feeWeight(String v) { this.feeWeight = v; return this; }
+ /** 设置物流运费。 */
public Builder logisticsFreight(String v) { this.logisticsFreight = v; return this; }
+ /** 设置运费币种。 */
public Builder logisticsFreightCurrency(String v) { this.logisticsFreightCurrency = v; return this; }
+ /** 构建包裹;{@code globalOrderNo} 为 null 时抛出 NPE。 */
public OutboundPackage build() {
return new OutboundPackage(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundResult.java b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundResult.java
index 44331ed..d53cc0a 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/OutboundResult.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/OutboundResult.java
@@ -9,7 +9,9 @@ import java.util.List;
*/
public final class OutboundResult {
+ /** 出库成功组(领星 {@code data.success[]}),不可变,永不为 null。 */
private final List success;
+ /** 出库失败组(领星 {@code data.failure[]}),不可变,永不为 null。 */
private final List failure;
private OutboundResult(List success, List failure) {
@@ -17,24 +19,31 @@ public final class OutboundResult {
this.failure = Collections.unmodifiableList(new ArrayList(failure));
}
+ /** 构造结果;两个列表都会被复制为不可变列表。 */
public static OutboundResult of(List success, List failure) {
return new OutboundResult(success, failure);
}
+ /** 出库成功组。 */
public List success() { return success; }
+ /** 出库失败组。 */
public List failure() { return failure; }
/** 出库成功的单。 */
public static final class Success {
+ /** 领星系统单号({@code global_order_no})。 */
private final String globalOrderNo;
+ /** 领星生成的销售出库单号({@code wo_number})。 */
private final String woNumber;
+ /** 构造出库成功项。 */
public Success(String globalOrderNo, String woNumber) {
this.globalOrderNo = globalOrderNo;
this.woNumber = woNumber;
}
+ /** 领星系统单号。 */
public String globalOrderNo() { return globalOrderNo; }
/** 销售出库单号。 */
public String woNumber() { return woNumber; }
@@ -43,15 +52,20 @@ public final class OutboundResult {
/** 出库失败的单及原因。 */
public static final class Failure {
+ /** 领星系统单号({@code global_order_no})。 */
private final String globalOrderNo;
+ /** 失败原因({@code error_message}),平台原值。 */
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; }
}
}
diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java b/core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java
index 5e8c6aa..23e732e 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java
@@ -12,9 +12,13 @@ import java.util.List;
*/
public final class ShipmentReviewResult {
+ /** 成功单数(领星 {@code success_num});平台未给时适配器用成功明细行数兜底。 */
private final int successNum;
+ /** 失败单数(领星 {@code fail_num});平台未给时适配器用失败明细行数兜底。 */
private final int failNum;
+ /** 成功单的领星系统单号列表,不可变,永不为 null。 */
private final List successGlobalOrderNos;
+ /** 失败明细列表,不可变,永不为 null。 */
private final List failures;
private ShipmentReviewResult(Builder b) {
@@ -25,22 +29,27 @@ public final class ShipmentReviewResult {
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;
}
@@ -53,51 +62,66 @@ public final class ShipmentReviewResult {
/** 单笔失败原因。 */
public static final class Failure {
+ /** 失败单的领星系统单号({@code global_order_no}),按字符串接收以避免精度丢失。 */
private final String globalOrderNo;
+ /** 失败原因({@code message}),如「未设置物流」。 */
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;
}
}
+ /** {@link ShipmentReviewResult} 构建器。 */
public static final class Builder {
+ /** 成功单数。 */
private int successNum;
+ /** 失败单数。 */
private int failNum;
+ /** 成功单的领星系统单号;默认空列表,setter 传 null 也归一为空列表。 */
private List successGlobalOrderNos = Collections.emptyList();
+ /** 失败明细;默认空列表,setter 传 null 也归一为空列表。 */
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;
}
+ /** 设置成功单号列表;null 视为空列表。 */
public Builder successGlobalOrderNos(List successGlobalOrderNos) {
this.successGlobalOrderNos = successGlobalOrderNos == null
? Collections.emptyList() : successGlobalOrderNos;
return this;
}
+ /** 设置失败明细;null 视为空列表。 */
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
index b5f2dd4..82a9a2c 100644
--- a/core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java
+++ b/core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java
@@ -12,15 +12,25 @@ import java.util.Objects;
*/
public final class ShippingLabel {
+ /** 宿主(OMS)侧店铺标识,必填;由调用上下文注入,不是平台店铺 ID。 */
private final String omsStoreId;
+ /** 接入通道(直连 / 领星聚合),必填。 */
private final ChannelProvider sourceProvider;
+ /** 销售出库单号(领星 {@code wo_number}),必填。 */
private final String woNumber;
+ /** 领星系统单号({@code order_number}),不是平台订单号。 */
private final String orderNumber;
+ /** 物流商 id({@code logistics_provider_id})。 */
private final Long logisticsProviderId;
+ /** 物流方式 id({@code logistics_type_id})。 */
private final Long logisticsTypeId;
+ /** 平台侧面单文件 id({@code file_id})。 */
private final Long fileId;
+ /** 文件类型/扩展名({@code file_type}),如 {@code pdf}。 */
private final String fileType;
+ /** 文件尺寸描述({@code file_size}),平台原值,不是数值类型。 */
private final String fileSize;
+ /** 面单 base64({@code file_b64});平台可能在面单未生成时返回空串,SDK 原样保留。 */
private final String contentBase64;
private ShippingLabel(Builder b) {
@@ -36,14 +46,17 @@ public final class ShippingLabel {
this.contentBase64 = b.contentBase64;
}
+ /** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
+ /** 宿主(OMS)侧店铺标识。 */
public String omsStoreId() {
return omsStoreId;
}
+ /** 接入通道(直连 / 领星聚合)。 */
public ChannelProvider sourceProvider() {
return sourceProvider;
}
@@ -53,18 +66,22 @@ public final class ShippingLabel {
return woNumber;
}
+ /** 领星系统单号。 */
public String orderNumber() {
return orderNumber;
}
+ /** 物流商 id。 */
public Long logisticsProviderId() {
return logisticsProviderId;
}
+ /** 物流方式 id。 */
public Long logisticsTypeId() {
return logisticsTypeId;
}
+ /** 平台侧面单文件 id。 */
public Long fileId() {
return fileId;
}
@@ -84,69 +101,91 @@ public final class ShippingLabel {
return contentBase64;
}
+ /** {@link ShippingLabel} 构建器;必填字段为 omsStoreId / sourceProvider / woNumber。 */
public static final class Builder {
+ /** 宿主(OMS)侧店铺标识,必填。 */
private String omsStoreId;
+ /** 接入通道(直连 / 领星聚合),必填。 */
private ChannelProvider sourceProvider;
+ /** 销售出库单号,必填。 */
private String woNumber;
+ /** 领星系统单号。 */
private String orderNumber;
+ /** 物流商 id。 */
private Long logisticsProviderId;
+ /** 物流方式 id。 */
private Long logisticsTypeId;
+ /** 平台侧面单文件 id。 */
private Long fileId;
+ /** 文件类型,如 {@code pdf}。 */
private String fileType;
+ /** 文件尺寸描述,平台原值。 */
private String fileSize;
+ /** 面单 base64。 */
private String contentBase64;
+ /** 设置宿主(OMS)侧店铺标识。 */
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;
}
+ /** 设置物流商 id。 */
public Builder logisticsProviderId(Long logisticsProviderId) {
this.logisticsProviderId = logisticsProviderId;
return this;
}
+ /** 设置物流方式 id。 */
public Builder logisticsTypeId(Long logisticsTypeId) {
this.logisticsTypeId = logisticsTypeId;
return this;
}
+ /** 设置面单文件 id。 */
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;
}
+ /** 设置面单 base64,不做解码或校验。 */
public Builder contentBase64(String contentBase64) {
this.contentBase64 = contentBase64;
return this;
}
+ /** 构建面单;必填字段为 null 时抛 NPE。 */
public ShippingLabel build() {
return new ShippingLabel(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/order/OrderLine.java b/core/src/main/java/common/ecommerce/model/order/OrderLine.java
index 8f8f068..752ab1c 100644
--- a/core/src/main/java/common/ecommerce/model/order/OrderLine.java
+++ b/core/src/main/java/common/ecommerce/model/order/OrderLine.java
@@ -9,11 +9,30 @@ import java.util.Objects;
*/
public final class OrderLine {
+ /**
+ * 行标识,仅作展示/追溯;平台侧不一定稳定(如亚马逊 {@code order_item_id} 可能变更),
+ * 不要当 upsert 主键。平台不提供时为 null。
+ */
private final String lineId;
+
+ /**
+ * 平台侧 SKU;必填,可关联商品 canonicalKey。
+ *
+ * 领星取 {@code msku}(顺序 SKU),亚马逊取 {@code seller_sku};
+ * 适配器在缺失时会回落到本地 SKU 或空串占位,因此可能为空串而不是 null。
+ */
private final String platformSku;
+
+ /** 购买数量;0 表示平台未给或解析失败,非 null。 */
private final int quantity;
+
+ /** 商品单价;平台未给时为 null。币种通常与订单总额一致。 */
private final Money unitPrice;
+
+ /** 行税额;平台未给时为 null。 */
private final Money tax;
+
+ /** 行优惠/折扣金额;平台未给时为 null。 */
private final Money discount;
private OrderLine(Builder b) {
@@ -25,73 +44,98 @@ public final class OrderLine {
this.discount = b.discount;
}
+ /** 创建 Builder。 */
public static Builder builder() {
return new Builder();
}
+ /** 行标识;平台不提供时为 null,不适合作为稳定主键。 */
public String lineId() {
return lineId;
}
+ /** 平台侧 SKU(领星 msku / 亚马逊 seller_sku),可能为空串但不会为 null。 */
public String platformSku() {
return platformSku;
}
+ /** 购买数量;平台未给时为 0。 */
public int quantity() {
return quantity;
}
+ /** 商品单价;平台未给时为 null。 */
public Money unitPrice() {
return unitPrice;
}
+ /** 行税额;平台未给时为 null。 */
public Money tax() {
return tax;
}
+ /** 行优惠/折扣金额;平台未给时为 null。 */
public Money discount() {
return discount;
}
public static final class Builder {
+ /** 行标识;可空,仅作展示。 */
private String lineId;
+
+ /** 平台侧 SKU;必填。 */
private String platformSku;
+
+ /** 购买数量;平台未给时保持 0。 */
private int quantity;
+
+ /** 商品单价;可空。 */
private Money unitPrice;
+
+ /** 行税额;可空。 */
private Money tax;
+
+ /** 行优惠/折扣金额;可空。 */
private Money discount;
+ /** 设置行标识;可空。 */
public Builder lineId(String lineId) {
this.lineId = lineId;
return this;
}
+ /** 设置平台侧 SKU;必填。 */
public Builder platformSku(String platformSku) {
this.platformSku = platformSku;
return this;
}
+ /** 设置购买数量。 */
public Builder quantity(int quantity) {
this.quantity = quantity;
return this;
}
+ /** 设置商品单价;可空。 */
public Builder unitPrice(Money unitPrice) {
this.unitPrice = unitPrice;
return this;
}
+ /** 设置行税额;可空。 */
public Builder tax(Money tax) {
this.tax = tax;
return this;
}
+ /** 设置行优惠/折扣金额;可空。 */
public Builder discount(Money discount) {
this.discount = discount;
return this;
}
+ /** 构建明细行;缺 platformSku 时抛 {@link NullPointerException}。 */
public OrderLine build() {
return new OrderLine(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/order/SalesOrder.java b/core/src/main/java/common/ecommerce/model/order/SalesOrder.java
index 2c3858c..edfbcd3 100644
--- a/core/src/main/java/common/ecommerce/model/order/SalesOrder.java
+++ b/core/src/main/java/common/ecommerce/model/order/SalesOrder.java
@@ -17,15 +17,40 @@ import java.util.Objects;
*/
public final class SalesOrder {
+ /** 宿主(OMS)侧店铺标识;必填,参与 canonicalKey。与平台店铺 ID(externalStoreId)不是一回事。 */
private final String omsStoreId;
+
+ /**
+ * 平台订单号;必填,参与 canonicalKey,必须稳定。
+ *
+ * 领星多平台 / 亚马逊路由取 {@code platform_info[].platform_order_no},缺失时回落
+ * {@code platform_order_name}、{@code global_order_no};领星 FBM 路由例外,
+ * 它就是领星系统单号 {@code order_number}。
+ */
private final String channelOrderId;
+
+ /** 平台原始订单状态,未归一化,由宿主解释;领星为数字状态(1 同步中 … 9 平台发货),可空。 */
private final String status;
+
+ /** 买家姓名,平台字段原样;多数领星订单接口不返回,此时为 null。 */
private final String buyerName;
+
+ /** 收货国家代码(ISO 3166-1 alpha-2,如 US / DE);领星取 store_Country_code,可空。 */
private final String shipToCountryCode;
+
+ /** 订单明细行;不可变列表。空列表可能表示该接口未返回商品行(如 FBM 列表),不代表订单无商品。 */
private final List lines;
+
+ /** 订单总额(Money);币种随平台返回(领星取 amount_currency),平台未给金额时为 null。 */
private final Money totalAmount;
+
+ /** 下单时间;必填。领星取 global_purchase_time,缺失回落 purchase_time;同时带 UTC 与市场时区。 */
private final PlatformTime occurredAt;
+
+ /** 接入通道(直连 / 领星等);不参与 canonicalKey,同一业务单可来自不同 provider。 */
private final ChannelProvider sourceProvider;
+
+ /** 来源账户标识;领星为店铺 sid / store_id,直连可为 null。仅用于追溯原始账户。 */
private final String sourceAccountId;
private SalesOrder(Builder b) {
@@ -41,113 +66,154 @@ public final class SalesOrder {
this.sourceAccountId = b.sourceAccountId;
}
+ /** 创建 Builder。 */
public static Builder builder() {
return new Builder();
}
+ /** 宿主(OMS)侧店铺标识。 */
public String omsStoreId() {
return omsStoreId;
}
+ /** 平台订单号;领星 FBM 路由为领星系统单号 {@code order_number}。 */
public String channelOrderId() {
return channelOrderId;
}
+ /** 平台原始订单状态;可空。 */
public String status() {
return status;
}
+ /** 买家姓名;平台不返回时为 null。 */
public String buyerName() {
return buyerName;
}
+ /** 收货国家代码(ISO 3166-1 alpha-2);可空。 */
public String shipToCountryCode() {
return shipToCountryCode;
}
+ /** 订单明细行;不可变,可能为空列表。 */
public List lines() {
return lines;
}
+ /** 订单总额;平台未给金额时为 null。 */
public Money totalAmount() {
return totalAmount;
}
+ /** 下单时间(UTC + 市场时区)。 */
public PlatformTime occurredAt() {
return occurredAt;
}
+ /** 接入通道。 */
public ChannelProvider sourceProvider() {
return sourceProvider;
}
+ /** 来源账户标识;可空。 */
public String sourceAccountId() {
return sourceAccountId;
}
public static final class Builder {
+ /** 宿主(OMS)侧店铺标识;必填。 */
private String omsStoreId;
+
+ /** 平台订单号;必填且需稳定。 */
private String channelOrderId;
+
+ /** 平台原始订单状态;可空。 */
private String status;
+
+ /** 买家姓名;可空。 */
private String buyerName;
+
+ /** 收货国家代码;可空。 */
private String shipToCountryCode;
+
+ /** 订单明细行;默认空列表,传入 null 按空列表处理。 */
private List lines = Collections.emptyList();
+
+ /** 订单总额;可空。 */
private Money totalAmount;
+
+ /** 下单时间;必填。 */
private PlatformTime occurredAt;
+
+ /** 接入通道;必填。 */
private ChannelProvider sourceProvider;
+
+ /** 来源账户标识;可空。 */
private String sourceAccountId;
+ /** 设置宿主(OMS)侧店铺标识;必填。 */
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
+ /** 设置平台订单号;必填。 */
public Builder channelOrderId(String channelOrderId) {
this.channelOrderId = channelOrderId;
return this;
}
+ /** 设置平台原始订单状态;可空。 */
public Builder status(String status) {
this.status = status;
return this;
}
+ /** 设置买家姓名;可空。 */
public Builder buyerName(String buyerName) {
this.buyerName = buyerName;
return this;
}
+ /** 设置收货国家代码;可空。 */
public Builder shipToCountryCode(String shipToCountryCode) {
this.shipToCountryCode = shipToCountryCode;
return this;
}
+ /** 设置订单明细行;传 null 等价于空列表。 */
public Builder lines(List lines) {
this.lines = lines == null ? Collections.emptyList() : lines;
return this;
}
+ /** 设置订单总额;可空。 */
public Builder totalAmount(Money totalAmount) {
this.totalAmount = totalAmount;
return this;
}
+ /** 设置下单时间;必填。 */
public Builder occurredAt(PlatformTime occurredAt) {
this.occurredAt = occurredAt;
return this;
}
+ /** 设置接入通道;必填。 */
public Builder sourceProvider(ChannelProvider sourceProvider) {
this.sourceProvider = sourceProvider;
return this;
}
+ /** 设置来源账户标识;可空。 */
public Builder sourceAccountId(String sourceAccountId) {
this.sourceAccountId = sourceAccountId;
return this;
}
+ /** 构建不可变订单对象;缺少必填字段时抛 {@link NullPointerException}。 */
public SalesOrder build() {
return new SalesOrder(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java b/core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java
index 26f7f9e..7d67e3c 100644
--- a/core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java
+++ b/core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java
@@ -12,6 +12,7 @@ import java.util.Objects;
*/
public final class SalesOrderRef {
+ /** 平台订单号;不可为空,构造时去掉首尾空白。领星 FBM 路由下是领星系统单号 {@code order_number}。 */
private final String channelOrderId;
private SalesOrderRef(String channelOrderId) {
@@ -21,24 +22,29 @@ public final class SalesOrderRef {
this.channelOrderId = channelOrderId.trim();
}
+ /** 由平台订单号创建引用;空白值抛 {@link IllegalArgumentException}。 */
public static SalesOrderRef of(String channelOrderId) {
return new SalesOrderRef(channelOrderId);
}
+ /** 平台订单号(已 trim)。 */
public String channelOrderId() {
return channelOrderId;
}
+ /** 按渠道单号判断相等。 */
@Override
public boolean equals(Object o) {
return o instanceof SalesOrderRef && channelOrderId.equals(((SalesOrderRef) o).channelOrderId);
}
+ /** 与 {@link #equals(Object)} 一致。 */
@Override
public int hashCode() {
return Objects.hash(channelOrderId);
}
+ /** 调试输出,格式 {@code SalesOrderRef{channelOrderId}}。 */
@Override
public String toString() {
return "SalesOrderRef{" + channelOrderId + '}';
diff --git a/core/src/main/java/common/ecommerce/model/product/ProductListing.java b/core/src/main/java/common/ecommerce/model/product/ProductListing.java
index 1f445d1..03c16d1 100644
--- a/core/src/main/java/common/ecommerce/model/product/ProductListing.java
+++ b/core/src/main/java/common/ecommerce/model/product/ProductListing.java
@@ -27,7 +27,9 @@ public final class ProductListing {
// ---------------------------------------------------------------- 标识
+ /** 电商平台。 */
private final Platform platform;
+ /** OMS 店铺 ID(业务归属),不是平台店铺 ID。 */
private final String omsStoreId;
/** 平台侧 SKU,参与 canonicalKey。领星 SC 取 seller_sku,VC 取 msku。 */
private final String platformSku;
@@ -42,7 +44,9 @@ public final class ProductListing {
// ---------------------------------------------------------------- 内容
+ /** 商品标题。 */
private final String title;
+ /** 图片 URL 列表;不可变,可能为空列表。 */
private final List imageUrls;
/** 平台原始属性(尺寸、变体、排名等未标准化字段),键为渠道字段名。 */
private final java.util.Map attributes;
@@ -64,6 +68,7 @@ public final class ProductListing {
// ---------------------------------------------------------------- 来源
+ /** 该数据来自哪条接入通道;用于排查,不参与业务主键。 */
private final ChannelProvider sourceProvider;
private ProductListing(Builder b) {
@@ -86,188 +91,246 @@ public final class ProductListing {
this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider");
}
+ /** 创建商品构建器。 */
public static Builder builder() {
return new Builder();
}
// ---------------------------------------------------------------- getters
+ /** 电商平台。 */
public Platform platform() {
return platform;
}
+ /** OMS 店铺 ID(业务归属)。 */
public String omsStoreId() {
return omsStoreId;
}
+ /** 平台侧 SKU。 */
public String platformSku() {
return platformSku;
}
+ /** 平台 Listing 标识;平台不提供时为 null。 */
public String listingId() {
return listingId;
}
+ /** 平台商品编码(亚马逊 ASIN);平台不提供时为 null。 */
public String asin() {
return asin;
}
+ /** 父商品编码;非变体商品为 null。 */
public String parentAsin() {
return parentAsin;
}
+ /** 全球贸易项目代码;平台不提供时为 null。 */
public String gtin() {
return gtin;
}
+ /** 商品标题;平台不提供时为 null。 */
public String title() {
return title;
}
+ /** 图片 URL 列表;不可变。 */
public List imageUrls() {
return imageUrls;
}
+ /** 平台原始属性;不可变。 */
public java.util.Map attributes() {
return attributes;
}
+ /** 归一化状态,默认 {@link ProductStatus#UNKNOWN}。 */
public ProductStatus status() {
return status;
}
+ /** 平台原始状态值。 */
public String rawStatus() {
return rawStatus;
}
+ /** 平台价格;平台不提供时为 null。 */
public Money price() {
return price;
}
+ /** 币种代码;平台不提供时为 null。 */
public String currency() {
return currency;
}
+ /** 开售时间;平台不提供时为 null。 */
public PlatformTime listedAt() {
return listedAt;
}
+ /** 内容最后更新时间;平台不提供时为 null。 */
public PlatformTime updatedAt() {
return updatedAt;
}
+ /** 数据来源通道。 */
public ChannelProvider sourceProvider() {
return sourceProvider;
}
// ---------------------------------------------------------------- builder
+ /** 商品构建器。 */
public static final class Builder {
+ /** 电商平台;必填。 */
private Platform platform;
+ /** OMS 店铺 ID;必填。 */
private String omsStoreId;
+ /** 平台侧 SKU;必填。 */
private String platformSku;
+ /** 平台 Listing 标识。 */
private String listingId;
+ /** 平台商品编码。 */
private String asin;
+ /** 父商品编码。 */
private String parentAsin;
+ /** 全球贸易项目代码。 */
private String gtin;
+ /** 商品标题。 */
private String title;
+ /** 图片 URL 列表;null 视为空列表。 */
private List imageUrls = Collections.emptyList();
+ /** 平台原始属性;null 视为空 Map。 */
private java.util.Map attributes = Collections.emptyMap();
+ /** 归一化状态;null 时构建为 {@link ProductStatus#UNKNOWN}。 */
private ProductStatus status;
+ /** 平台原始状态值。 */
private String rawStatus;
+ /** 平台价格。 */
private Money price;
+ /** 币种代码。 */
private String currency;
+ /** 开售时间。 */
private PlatformTime listedAt;
+ /** 内容最后更新时间。 */
private PlatformTime updatedAt;
+ /** 数据来源通道;必填。 */
private ChannelProvider sourceProvider;
+ /** 设置电商平台。 */
public Builder platform(Platform platform) {
this.platform = platform;
return this;
}
+ /** 设置 OMS 店铺 ID。 */
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
+ /** 设置平台侧 SKU。 */
public Builder platformSku(String platformSku) {
this.platformSku = platformSku;
return this;
}
+ /** 设置平台 Listing 标识。 */
public Builder listingId(String listingId) {
this.listingId = listingId;
return this;
}
+ /** 设置平台商品编码(亚马逊 ASIN)。 */
public Builder asin(String asin) {
this.asin = asin;
return this;
}
+ /** 设置父商品编码。 */
public Builder parentAsin(String parentAsin) {
this.parentAsin = parentAsin;
return this;
}
+ /** 设置全球贸易项目代码。 */
public Builder gtin(String gtin) {
this.gtin = gtin;
return this;
}
+ /** 设置商品标题。 */
public Builder title(String title) {
this.title = title;
return this;
}
+ /** 设置图片 URL 列表;null 视为空列表。 */
public Builder imageUrls(List imageUrls) {
this.imageUrls = imageUrls == null ? Collections.emptyList() : imageUrls;
return this;
}
+ /** 设置平台原始属性;null 视为空 Map。 */
public Builder attributes(java.util.Map attributes) {
this.attributes = attributes == null
? Collections.emptyMap() : attributes;
return this;
}
+ /** 设置归一化状态;不设置时为 {@link ProductStatus#UNKNOWN}。 */
public Builder status(ProductStatus status) {
this.status = status;
return this;
}
+ /** 设置平台原始状态值。 */
public Builder rawStatus(String rawStatus) {
this.rawStatus = rawStatus;
return this;
}
+ /** 设置平台价格。 */
public Builder price(Money price) {
this.price = price;
return this;
}
+ /** 设置币种代码。 */
public Builder currency(String currency) {
this.currency = currency;
return this;
}
+ /** 设置开售时间。 */
public Builder listedAt(PlatformTime listedAt) {
this.listedAt = listedAt;
return this;
}
+ /** 设置内容最后更新时间。 */
public Builder updatedAt(PlatformTime updatedAt) {
this.updatedAt = updatedAt;
return this;
}
+ /** 设置数据来源通道。 */
public Builder sourceProvider(ChannelProvider sourceProvider) {
this.sourceProvider = sourceProvider;
return this;
}
+ /**
+ * 构建商品。
+ *
+ * @throws NullPointerException platform、omsStoreId、platformSku 或 sourceProvider 为 null
+ */
public ProductListing build() {
return new ProductListing(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/product/ProductQuery.java b/core/src/main/java/common/ecommerce/model/product/ProductQuery.java
index f6472db..27c689a 100644
--- a/core/src/main/java/common/ecommerce/model/product/ProductQuery.java
+++ b/core/src/main/java/common/ecommerce/model/product/ProductQuery.java
@@ -21,12 +21,19 @@ import java.util.Objects;
*/
public final class ProductQuery {
+ /** 增量起点(UTC,含);按平台的更新时间语义过滤,可为 null。 */
private final Instant updatedAfter;
+ /** 增量终点(UTC);为 null 表示不限制终点,部分适配器会用上下文时钟补齐。 */
private final Instant updatedBefore;
+ /** 每页条数,默认 100。 */
private final int pageSize;
+ /** 平台游标;首页为 null,后续页原样传回上一页的 nextCursor。 */
private final String cursor;
+ /** 搜索维度;null 表示不按 SKU 搜索。 */
private final ProductSearchField searchField;
+ /** 单个模糊搜索值;与 searchValues 互斥。 */
private final String searchValue;
+ /** 多个精确搜索值;不可变,未设置时为空列表。 */
private final List searchValues;
private ProductQuery(Builder b) {
@@ -45,22 +52,27 @@ public final class ProductQuery {
}
}
+ /** 创建查询构建器。 */
public static Builder builder() {
return new Builder();
}
+ /** 增量起点(UTC,含);为 null 表示不限制。 */
public Instant updatedAfter() {
return updatedAfter;
}
+ /** 增量终点(UTC);null 表示不限制,是否默认取当前时间由适配器决定。 */
public Instant updatedBefore() {
return updatedBefore;
}
+ /** 每页条数,默认 100。 */
public int pageSize() {
return pageSize;
}
+ /** 平台游标;首页为 null。 */
public String cursor() {
return cursor;
}
@@ -85,6 +97,7 @@ public final class ProductQuery {
return searchField != null && (searchValue != null || !searchValues.isEmpty());
}
+ /** 以当前条件复制一个构建器,便于翻页或改单个字段。 */
public Builder toBuilder() {
return builder()
.updatedAfter(updatedAfter)
@@ -96,31 +109,43 @@ public final class ProductQuery {
.searchValues(searchValues);
}
+ /** 商品查询构建器。 */
public static final class Builder {
+ /** 增量起点(UTC,含)。 */
private Instant updatedAfter;
+ /** 增量终点(UTC)。 */
private Instant updatedBefore;
+ /** 每页条数,默认 100。 */
private int pageSize = 100;
+ /** 平台游标。 */
private String cursor;
+ /** 搜索维度。 */
private ProductSearchField searchField;
+ /** 单个模糊搜索值。 */
private String searchValue;
+ /** 多个精确搜索值;null 视为空列表。 */
private List searchValues = Collections.emptyList();
+ /** 设置增量起点(UTC,含)。 */
public Builder updatedAfter(Instant updatedAfter) {
this.updatedAfter = updatedAfter;
return this;
}
+ /** 设置增量终点(UTC);不设置时由适配器决定是否取当前时间。 */
public Builder updatedBefore(Instant updatedBefore) {
this.updatedBefore = updatedBefore;
return this;
}
+ /** 设置每页条数,默认 100。 */
public Builder pageSize(int pageSize) {
this.pageSize = pageSize;
return this;
}
+ /** 设置平台游标;传上一页的 {@code nextCursor} 取下一页。 */
public Builder cursor(String cursor) {
this.cursor = cursor;
return this;
@@ -138,12 +163,17 @@ public final class ProductQuery {
return this;
}
- /** 多个精确搜索;与 {@link #searchValue(String)} 互斥。 */
+ /** 多个精确搜索;与 {@link #searchValue(String)} 互斥,null 视为空列表。 */
public Builder searchValues(List searchValues) {
this.searchValues = searchValues == null ? Collections.emptyList() : searchValues;
return this;
}
+ /**
+ * 构建查询。
+ *
+ * @throws IllegalArgumentException 只给了搜索值没给 searchField,或模糊/精确同时设置
+ */
public ProductQuery build() {
return new ProductQuery(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/product/ProductRef.java b/core/src/main/java/common/ecommerce/model/product/ProductRef.java
index 9e49ded..3e0f693 100644
--- a/core/src/main/java/common/ecommerce/model/product/ProductRef.java
+++ b/core/src/main/java/common/ecommerce/model/product/ProductRef.java
@@ -7,6 +7,7 @@ import java.util.Objects;
*/
public final class ProductRef {
+ /** 平台侧 SKU,构造时已 trim。 */
private final String platformSku;
private ProductRef(String platformSku) {
@@ -16,24 +17,33 @@ public final class ProductRef {
this.platformSku = platformSku.trim();
}
+ /**
+ * 由平台 SKU 创建引用。
+ *
+ * @throws IllegalArgumentException SKU 为空白
+ */
public static ProductRef of(String platformSku) {
return new ProductRef(platformSku);
}
+ /** 平台侧 SKU。 */
public String platformSku() {
return platformSku;
}
+ /** 平台 SKU 相同即相等。 */
@Override
public boolean equals(Object o) {
return o instanceof ProductRef && platformSku.equals(((ProductRef) o).platformSku);
}
+ /** 与 {@link #equals(Object)} 一致。 */
@Override
public int hashCode() {
return Objects.hash(platformSku);
}
+ /** 形如 {@code ProductRef{SKU-001}}。 */
@Override
public String toString() {
return "ProductRef{" + platformSku + '}';
diff --git a/core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java b/core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java
index c6dc1e2..e395b3e 100644
--- a/core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java
+++ b/core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java
@@ -3,10 +3,10 @@ package common.ecommerce.model.product;
/** 商品同步策略,适配器声明自己支持哪一种。 */
public enum ProductSyncStrategy {
- /** 时间窗增量 */
+ /** 时间窗增量:按更新时间区间拉取,适合有稳定 updated_at 的平台。 */
INCREMENTAL_TIME_WINDOW,
- /** 全量拉取 + 差异比对 */
+ /** 全量拉取 + 差异比对:平台不提供可靠增量时的退路,开销大。 */
FULL_PULL_DIFF,
- /** 报告 / 文件 */
+ /** 报告 / 文件:平台异步生成文件,适配器需自行轮询并下载。 */
REPORT
}
diff --git a/core/src/main/java/common/ecommerce/model/settlement/SettlementQuery.java b/core/src/main/java/common/ecommerce/model/settlement/SettlementQuery.java
index 08bc720..0fc20a0 100644
--- a/core/src/main/java/common/ecommerce/model/settlement/SettlementQuery.java
+++ b/core/src/main/java/common/ecommerce/model/settlement/SettlementQuery.java
@@ -14,15 +14,40 @@ import java.util.List;
*/
public final class SettlementQuery {
+ /**
+ * 结算时间起(含);按平台站点日期({@link LocalDate}),对应领星 {@code startDate}。
+ * 与 {@link #settledBefore} 组成双闭区间,跨度上限 7 天(含首尾)。
+ */
private final LocalDate settledAfter;
+
+ /** 结算时间止(含);对应领星 {@code endDate};可空,与 {@link #settledAfter} 语义见上。 */
private final LocalDate settledBefore;
+
+ /**
+ * 修改时间起(含);对应领星 {@code gmtModifiedStart},按北京时间格式化后发送。
+ * 可空,但需与结算窗口或 searchValues 至少提供其一。
+ */
private final Instant modifiedAfter;
+
+ /** 修改时间止(含);对应领星 {@code gmtModifiedEnd},按北京时间格式化;可空。 */
private final Instant modifiedBefore;
+
+ /** 来源事件,多个用逗号分隔,如 {@code ShipmentEventList,RefundEventList};可空。 */
private final String eventType;
+
+ /** 交易类型,如 Commission / Tax;对应领星请求字段 {@code type};可空。 */
private final String transactionType;
+
+ /** 精确搜索字段,如 {@code id} / {@code amazon_order_id} / {@code settlement_id};可空。 */
private final String searchField;
+
+ /** 精确搜索值(多值,对应领星 {@code searchValue} 数组);不为 null,空列表表示不使用搜索值。 */
private final List searchValues;
+
+ /** 单页条数;0 或负数时由适配器使用默认值(领星默认 100,上限 10000)。 */
private final int pageSize;
+
+ /** 分页游标:上一页 {@code Page.nextCursor()} 的返回值;首次查询为 null,领星内部存 offset。 */
private final String cursor;
private SettlementQuery(Builder b) {
@@ -38,6 +63,7 @@ public final class SettlementQuery {
this.cursor = b.cursor;
}
+ /** 创建 Builder。 */
public static Builder builder() {
return new Builder();
}
@@ -77,18 +103,22 @@ public final class SettlementQuery {
return searchField;
}
+ /** 精确搜索值列表;空列表表示不使用搜索值。 */
public List searchValues() {
return searchValues;
}
+ /** 单页条数;0 或负数由适配器取默认值。 */
public int pageSize() {
return pageSize;
}
+ /** 字符串化游标;领星 offset 分页内部存的是 offset。 */
public String cursor() {
return cursor;
}
+ /** 复制当前条件,便于翻页时只替换 cursor。 */
public Builder toBuilder() {
return builder()
.settledAfter(settledAfter)
@@ -105,58 +135,86 @@ public final class SettlementQuery {
public static final class Builder {
+ /** 结算时间起(含),站点日期;可空。 */
private LocalDate settledAfter;
+
+ /** 结算时间止(含),站点日期;可空。与起点跨度上限 7 天。 */
private LocalDate settledBefore;
+
+ /** 修改时间起(含);可空。 */
private Instant modifiedAfter;
+
+ /** 修改时间止(含);可空。 */
private Instant modifiedBefore;
+
+ /** 来源事件,逗号分隔;可空。 */
private String eventType;
+
+ /** 交易类型;可空。 */
private String transactionType;
+
+ /** 精确搜索字段;可空。 */
private String searchField;
+
+ /** 精确搜索值;默认空列表,null 按空列表处理。 */
private List searchValues = Collections.emptyList();
+
+ /** 单页条数;默认 100,0 或负数由适配器兜底。 */
private int pageSize = 100;
+
+ /** 分页游标;首次查询留空。 */
private String cursor;
+ /** 设置结算时间起(含),站点日期。 */
public Builder settledAfter(LocalDate settledAfter) {
this.settledAfter = settledAfter;
return this;
}
+ /** 设置结算时间止(含),站点日期。 */
public Builder settledBefore(LocalDate settledBefore) {
this.settledBefore = settledBefore;
return this;
}
+ /** 设置修改时间起(含)。 */
public Builder modifiedAfter(Instant modifiedAfter) {
this.modifiedAfter = modifiedAfter;
return this;
}
+ /** 设置修改时间止(含)。 */
public Builder modifiedBefore(Instant modifiedBefore) {
this.modifiedBefore = modifiedBefore;
return this;
}
+ /** 设置来源事件,多个用逗号分隔。 */
public Builder eventType(String eventType) {
this.eventType = eventType;
return this;
}
+ /** 设置交易类型。 */
public Builder transactionType(String transactionType) {
this.transactionType = transactionType;
return this;
}
+ /** 设置精确搜索字段。 */
public Builder searchField(String searchField) {
this.searchField = searchField;
return this;
}
+ /** 设置精确搜索值列表;null 等价于空列表。 */
public Builder searchValues(List searchValues) {
this.searchValues = searchValues == null
? Collections.emptyList() : searchValues;
return this;
}
+ /** 以可变参数设置精确搜索值;null 或空数组等价于空列表。 */
public Builder searchValues(String... searchValues) {
List values = new ArrayList();
if (searchValues != null) {
@@ -166,16 +224,19 @@ public final class SettlementQuery {
return this;
}
+ /** 设置单页条数;0 或负数由适配器取默认值。 */
public Builder pageSize(int pageSize) {
this.pageSize = pageSize;
return this;
}
+ /** 设置分页游标;首次查询留空。 */
public Builder cursor(String cursor) {
this.cursor = cursor;
return this;
}
+ /** 构建查询条件;窗口合法性由适配器在请求前校验。 */
public SettlementQuery build() {
return new SettlementQuery(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/settlement/SettlementTransaction.java b/core/src/main/java/common/ecommerce/model/settlement/SettlementTransaction.java
index fcd3f4a..88db768 100644
--- a/core/src/main/java/common/ecommerce/model/settlement/SettlementTransaction.java
+++ b/core/src/main/java/common/ecommerce/model/settlement/SettlementTransaction.java
@@ -16,25 +16,68 @@ import java.util.Objects;
*/
public final class SettlementTransaction {
+ /** 宿主(OMS)侧店铺标识;必填,取账户上的 omsStoreId。 */
private final String omsStoreId;
+
+ /**
+ * 交易明细唯一标识;必填,重复同步按它 upsert。
+ *
+ * 领星优先取 {@code uniqueKey},其次 {@code md5},再退 {@code id};三者都没有时映射失败。
+ */
private final String transactionKey;
+
+ /** 接入通道(直连 / 领星等);必填。 */
private final ChannelProvider sourceProvider;
+
+ /** 来源账户标识;领星取店铺 {@code sid},可空。 */
private final String sourceAccountId;
+
+ /** 平台订单号;领星取 {@code amazon_order_id},费用行可能没有订单号(如广告费),此时为 null。 */
private final String channelOrderId;
+
+ /** 平台店铺名称;展示用,可空。 */
private final String storeName;
+
+ /** 站点/国家代码(如 US / DE);可空。 */
private final String countryCode;
+
+ /** 配送方式(如 FBA / FBM);平台原值,可空。 */
private final String fulfillment;
+
+ /** 来源事件,如 Shipment / Refund / ServiceFee。 */
private final String eventType;
+
+ /** 交易类型,如 Commission / Tax / Refund。 */
private final String transactionType;
+
+ /** 平台侧卖家 SKU;可空。注意此处是 seller_sku,不是领星 msku。 */
private final String sellerSku;
+
+ /** 本地(ERP)SKU;可空。 */
private final String localSku;
+
+ /** 亚马逊 ASIN;可空。 */
private final String asin;
+
+ /** 金额(BigDecimal + 币种);平台未给金额或币种时整体为 null,不猜币种。 */
private final Money amount;
+
+ /** 数量;平台未给时为 0。 */
private final int quantity;
+
+ /** 结算状态:Open / Closed / Reconciled。 */
private final String processingStatus;
+
+ /** 转账状态:Succeeded / Processing / Failed / Unknown。 */
private final String fundTransferStatus;
+
+ /** 结算单号;领星取 {@code settlement_id},缺失回落 {@code fid},可空。 */
private final String settlementId;
+
+ /** 结算时间;平台未给可解析时间时为 null。同时带 UTC 与市场时区。 */
private final PlatformTime postedAt;
+
+ /** 站点名称,如 Amazon.com;可空。 */
private final String marketplaceName;
private SettlementTransaction(Builder b) {
@@ -60,10 +103,12 @@ public final class SettlementTransaction {
this.marketplaceName = b.marketplaceName;
}
+ /** 创建 Builder。 */
public static Builder builder() {
return new Builder();
}
+ /** 宿主(OMS)侧店铺标识。 */
public String omsStoreId() {
return omsStoreId;
}
@@ -73,26 +118,32 @@ public final class SettlementTransaction {
return transactionKey;
}
+ /** 接入通道。 */
public ChannelProvider sourceProvider() {
return sourceProvider;
}
+ /** 来源账户标识;领星为店铺 sid,可空。 */
public String sourceAccountId() {
return sourceAccountId;
}
+ /** 平台订单号;无关联订单的费用行为 null。 */
public String channelOrderId() {
return channelOrderId;
}
+ /** 平台店铺名称;可空。 */
public String storeName() {
return storeName;
}
+ /** 站点/国家代码;可空。 */
public String countryCode() {
return countryCode;
}
+ /** 配送方式(FBA / FBM 等);可空。 */
public String fulfillment() {
return fulfillment;
}
@@ -107,14 +158,17 @@ public final class SettlementTransaction {
return transactionType;
}
+ /** 平台侧卖家 SKU(seller_sku);可空。 */
public String sellerSku() {
return sellerSku;
}
+ /** 本地(ERP)SKU;可空。 */
public String localSku() {
return localSku;
}
+ /** 亚马逊 ASIN;可空。 */
public String asin() {
return asin;
}
@@ -124,6 +178,7 @@ public final class SettlementTransaction {
return amount;
}
+ /** 数量;平台未给时为 0。 */
public int quantity() {
return quantity;
}
@@ -138,6 +193,7 @@ public final class SettlementTransaction {
return fundTransferStatus;
}
+ /** 结算单号;可空。 */
public String settlementId() {
return settlementId;
}
@@ -147,133 +203,194 @@ public final class SettlementTransaction {
return postedAt;
}
+ /** 站点名称;可空。 */
public String marketplaceName() {
return marketplaceName;
}
public static final class Builder {
+ /** 宿主(OMS)侧店铺标识;必填。 */
private String omsStoreId;
+
+ /** 交易明细唯一标识;必填且必须稳定。 */
private String transactionKey;
+
+ /** 接入通道;必填。 */
private ChannelProvider sourceProvider;
+
+ /** 来源账户标识;可空。 */
private String sourceAccountId;
+
+ /** 平台订单号;可空。 */
private String channelOrderId;
+
+ /** 平台店铺名称;可空。 */
private String storeName;
+
+ /** 站点/国家代码;可空。 */
private String countryCode;
+
+ /** 配送方式;可空。 */
private String fulfillment;
+
+ /** 来源事件;可空。 */
private String eventType;
+
+ /** 交易类型;可空。 */
private String transactionType;
+
+ /** 平台侧卖家 SKU;可空。 */
private String sellerSku;
+
+ /** 本地(ERP)SKU;可空。 */
private String localSku;
+
+ /** 亚马逊 ASIN;可空。 */
private String asin;
+
+ /** 金额;可空。 */
private Money amount;
+
+ /** 数量;未设置时为 0。 */
private int quantity;
+
+ /** 结算状态;可空。 */
private String processingStatus;
+
+ /** 转账状态;可空。 */
private String fundTransferStatus;
+
+ /** 结算单号;可空。 */
private String settlementId;
+
+ /** 结算时间;可空。 */
private PlatformTime postedAt;
+
+ /** 站点名称;可空。 */
private String marketplaceName;
+ /** 设置宿主(OMS)侧店铺标识;必填。 */
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
+ /** 设置交易明细唯一标识;必填且必须稳定。 */
public Builder transactionKey(String transactionKey) {
this.transactionKey = transactionKey;
return this;
}
+ /** 设置接入通道;必填。 */
public Builder sourceProvider(ChannelProvider sourceProvider) {
this.sourceProvider = sourceProvider;
return this;
}
+ /** 设置来源账户标识;可空。 */
public Builder sourceAccountId(String sourceAccountId) {
this.sourceAccountId = sourceAccountId;
return this;
}
+ /** 设置平台订单号;可空。 */
public Builder channelOrderId(String channelOrderId) {
this.channelOrderId = channelOrderId;
return this;
}
+ /** 设置平台店铺名称;可空。 */
public Builder storeName(String storeName) {
this.storeName = storeName;
return this;
}
+ /** 设置站点/国家代码;可空。 */
public Builder countryCode(String countryCode) {
this.countryCode = countryCode;
return this;
}
+ /** 设置配送方式;可空。 */
public Builder fulfillment(String fulfillment) {
this.fulfillment = fulfillment;
return this;
}
+ /** 设置来源事件;可空。 */
public Builder eventType(String eventType) {
this.eventType = eventType;
return this;
}
+ /** 设置交易类型;可空。 */
public Builder transactionType(String transactionType) {
this.transactionType = transactionType;
return this;
}
+ /** 设置平台侧卖家 SKU;可空。 */
public Builder sellerSku(String sellerSku) {
this.sellerSku = sellerSku;
return this;
}
+ /** 设置本地(ERP)SKU;可空。 */
public Builder localSku(String localSku) {
this.localSku = localSku;
return this;
}
+ /** 设置亚马逊 ASIN;可空。 */
public Builder asin(String asin) {
this.asin = asin;
return this;
}
+ /** 设置金额;可空。 */
public Builder amount(Money amount) {
this.amount = amount;
return this;
}
+ /** 设置数量。 */
public Builder quantity(int quantity) {
this.quantity = quantity;
return this;
}
+ /** 设置结算状态;可空。 */
public Builder processingStatus(String processingStatus) {
this.processingStatus = processingStatus;
return this;
}
+ /** 设置转账状态;可空。 */
public Builder fundTransferStatus(String fundTransferStatus) {
this.fundTransferStatus = fundTransferStatus;
return this;
}
+ /** 设置结算单号;可空。 */
public Builder settlementId(String settlementId) {
this.settlementId = settlementId;
return this;
}
+ /** 设置结算时间;可空。 */
public Builder postedAt(PlatformTime postedAt) {
this.postedAt = postedAt;
return this;
}
+ /** 设置站点名称;可空。 */
public Builder marketplaceName(String marketplaceName) {
this.marketplaceName = marketplaceName;
return this;
}
+ /** 构建不可变交易明细;缺少必填字段时抛 {@link NullPointerException}。 */
public SettlementTransaction build() {
return new SettlementTransaction(this);
}
diff --git a/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java b/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java
index 5dbf7e4..beb5cc6 100644
--- a/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java
+++ b/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java
@@ -20,13 +20,29 @@ import java.security.NoSuchAlgorithmException;
*/
public final class CanonicalKeys {
+ /** 工具类,禁止实例化。 */
private CanonicalKeys() {
}
+ /**
+ * 业务主键:platform + omsStoreId + 平台实体 ID。
+ *
+ * 不含 provider;直连与聚合器必须落到同一个键。
+ *
+ * @throws IllegalArgumentException 任一参数为空白
+ */
public static String canonical(Platform platform, String omsStoreId, String platformEntityId) {
return platform.name() + ':' + require(omsStoreId, "omsStoreId") + ':' + require(platformEntityId, "platformEntityId");
}
+ /**
+ * 来源键:provider + platform + externalStoreId + 平台实体 ID。
+ *
+ * 用于原始报文、水位线、审计;不要用于业务实体 upsert。
+ *
+ * @param externalStoreId 平台店铺 ID / 领星 store_id,不是 OMS 的 storeId
+ * @throws IllegalArgumentException 任一字符串参数为空白
+ */
public static String source(ChannelProvider provider, Platform platform, String externalStoreId, String platformEntityId) {
return provider.name() + ':' + platform.name() + ':' + require(externalStoreId, "externalStoreId")
+ ':' + require(platformEntityId, "platformEntityId");
@@ -69,7 +85,6 @@ public final class CanonicalKeys {
return sha256Hex("DED|" + poNumber + '|' + invoiceNumber + '|' + type + '|'
+ amount + '|' + currency + '|' + period + '|' + reason);
}
-
/**
* 写操作业务幂等键:platform + omsStoreId + businessRef + action。
*
@@ -91,6 +106,7 @@ public final class CanonicalKeys {
+ ':' + require(operation, "operation") + ':' + require(providerRef, "providerRef");
}
+ /** SHA-256 十六进制摘要;用于各类指纹。 */
static String sha256Hex(String raw) {
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
@@ -106,6 +122,11 @@ public final class CanonicalKeys {
}
}
+ /**
+ * 去空白并校验非空。
+ *
+ * @throws IllegalArgumentException 值为 null 或空白
+ */
private static String require(String value, String name) {
if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
diff --git a/core/src/main/java/common/ecommerce/model/support/Money.java b/core/src/main/java/common/ecommerce/model/support/Money.java
index 0c28893..ab2c770 100644
--- a/core/src/main/java/common/ecommerce/model/support/Money.java
+++ b/core/src/main/java/common/ecommerce/model/support/Money.java
@@ -12,7 +12,10 @@ import java.util.Objects;
*/
public final class Money {
+ /** 金额,保留平台原始精度。 */
private final BigDecimal amount;
+
+ /** 币种,参与运算前的同币种校验。 */
private final Currency currency;
private Money(BigDecimal amount, Currency currency) {
@@ -20,40 +23,71 @@ public final class Money {
this.currency = Objects.requireNonNull(currency, "currency");
}
+ /**
+ * 由 {@link BigDecimal} 与币种代码构造。
+ *
+ * @throws IllegalArgumentException 币种代码非法
+ * @throws NullPointerException amount 为 null
+ */
public static Money of(BigDecimal amount, String currencyCode) {
return new Money(amount, Currency.getInstance(currencyCode));
}
+ /**
+ * 由十进制字符串构造,避免 double 精度问题。
+ *
+ * @throws NumberFormatException 金额字符串非法
+ * @throws IllegalArgumentException 币种代码非法
+ */
public static Money of(String amount, String currencyCode) {
return of(new BigDecimal(amount), currencyCode);
}
+ /** 指定币种的零值。 */
public static Money zero(String currencyCode) {
return of(BigDecimal.ZERO, currencyCode);
}
+ /** 金额原值,未做舍入。 */
public BigDecimal amount() {
return amount;
}
+ /** 币种。 */
public Currency currency() {
return currency;
}
+ /** ISO 币种代码,如 USD。 */
public String currencyCode() {
return currency.getCurrencyCode();
}
+ /**
+ * 相加,不做隐式舍入。
+ *
+ * @throws IllegalArgumentException 币种不同
+ */
public Money add(Money other) {
requireSameCurrency(other);
return new Money(amount.add(other.amount), currency);
}
+ /**
+ * 相减,不做隐式舍入。
+ *
+ * @throws IllegalArgumentException 币种不同
+ */
public Money subtract(Money other) {
requireSameCurrency(other);
return new Money(amount.subtract(other.amount), currency);
}
+ /**
+ * 乘以系数,不做隐式舍入。
+ *
+ * @param factor 乘数,不能为 null
+ */
public Money multiply(BigDecimal factor) {
return new Money(amount.multiply(factor), currency);
}
@@ -63,15 +97,27 @@ public final class Money {
return new Money(amount.setScale(currency.getDefaultFractionDigits(), RoundingMode.HALF_UP), currency);
}
+ /** 金额是否为负(退款、扣款等)。 */
public boolean isNegative() {
return amount.signum() < 0;
}
+ /**
+ * 按金额数值比较,忽略标度差异({@code 1.0} 与 {@code 1.00} 相等)。
+ *
+ * @throws IllegalArgumentException 币种不同
+ */
public int compareTo(Money other) {
requireSameCurrency(other);
return amount.compareTo(other.amount);
}
+ /**
+ * 校验同币种。
+ *
+ * @throws NullPointerException other 为 null
+ * @throws IllegalArgumentException 币种不同
+ */
private void requireSameCurrency(Money other) {
Objects.requireNonNull(other, "other");
if (!currency.equals(other.currency)) {
@@ -80,6 +126,7 @@ public final class Money {
}
}
+ /** 金额按数值比较、币种相同即相等(忽略标度差异)。 */
@Override
public boolean equals(Object o) {
if (this == o) {
@@ -92,11 +139,13 @@ public final class Money {
return amount.compareTo(that.amount) == 0 && currency.equals(that.currency);
}
+ /** 与 {@link #equals(Object)} 一致;先去尾零再哈希。 */
@Override
public int hashCode() {
return Objects.hash(amount.stripTrailingZeros(), currency);
}
+ /** 形如 {@code 12.34 USD}。 */
@Override
public String toString() {
return amount.toPlainString() + " " + currency.getCurrencyCode();
diff --git a/core/src/main/java/common/ecommerce/model/support/Page.java b/core/src/main/java/common/ecommerce/model/support/Page.java
index 4592c65..d96864f 100644
--- a/core/src/main/java/common/ecommerce/model/support/Page.java
+++ b/core/src/main/java/common/ecommerce/model/support/Page.java
@@ -11,8 +11,13 @@ import java.util.List;
*/
public final class Page {
+ /** 当前页条目;不可变。 */
private final List items;
+
+ /** 下一页游标;null 表示没有下一页。 */
private final String nextCursor;
+
+ /** 是否还有下一页;由 nextCursor 是否为 null/空推导,不能从 items 数量推断。 */
private final boolean hasMore;
private Page(List items, String nextCursor, boolean hasMore) {
@@ -21,31 +26,41 @@ public final class Page {
this.hasMore = hasMore;
}
+ /**
+ * 构造非末页。
+ *
+ * {@code nextCursor} 为 null 或空串时等价于 {@link #last(List)}。
+ */
public static Page of(List items, String nextCursor) {
return new Page(items, nextCursor, nextCursor != null && !nextCursor.isEmpty());
}
+ /** 构造末页:{@code nextCursor} 为 null。 */
public static Page last(List items) {
return new Page(items, null, false);
}
+ /** 空末页。 */
public static Page empty() {
return new Page(Collections.emptyList(), null, false);
}
+ /** 当前页条目;不可变。 */
public List items() {
return items;
}
- /** 下一页游标;null 表示结束。 */
+ /** 下一页游标;null 表示结束。不要用 items 数量推断是否还有下一页。 */
public String nextCursor() {
return nextCursor;
}
+ /** 是否还有下一页;等价于 {@code nextCursor() != null}。 */
public boolean hasMore() {
return hasMore;
}
+ /** 当前页条目数。 */
public int size() {
return items.size();
}
diff --git a/core/src/main/java/common/ecommerce/model/support/PlatformTime.java b/core/src/main/java/common/ecommerce/model/support/PlatformTime.java
index 54e965f..68a0d23 100644
--- a/core/src/main/java/common/ecommerce/model/support/PlatformTime.java
+++ b/core/src/main/java/common/ecommerce/model/support/PlatformTime.java
@@ -16,7 +16,10 @@ public final class PlatformTime {
/** 北京时间固定时区。 */
public static final ZoneId BEIJING_ZONE = ZoneId.of("Asia/Shanghai");
+ /** UTC 真值。 */
private final Instant utc;
+
+ /** 市场当地时区;只用于派生展示,不参与存储。 */
private final ZoneId marketplaceZone;
private PlatformTime(Instant utc, ZoneId marketplaceZone) {
@@ -24,15 +27,26 @@ public final class PlatformTime {
this.marketplaceZone = Objects.requireNonNull(marketplaceZone, "marketplaceZone");
}
+ /**
+ * 由 UTC 时刻与时区构造。
+ *
+ * @param marketplaceZone 市场时区,禁止传固定偏移量(夏令时会错)
+ */
public static PlatformTime of(Instant utc, ZoneId marketplaceZone) {
return new PlatformTime(utc, marketplaceZone);
}
+ /**
+ * 由 UTC 时刻与时区 ID 构造。
+ *
+ * @param marketplaceZone IANA 时区 ID,如 {@code America/Los_Angeles}
+ * @throws java.time.DateTimeException 时区 ID 非法
+ */
public static PlatformTime of(Instant utc, String marketplaceZone) {
return of(utc, ZoneId.of(marketplaceZone));
}
- /** 以当前 UTC 时刻构造。 */
+ /** 以当前 UTC 时刻构造;clock 由调用方注入,SDK 不私起时间源。 */
public static PlatformTime now(Clock clock, ZoneId marketplaceZone) {
return of(Instant.now(clock), marketplaceZone);
}
@@ -42,6 +56,7 @@ public final class PlatformTime {
return utc;
}
+ /** 市场时区。 */
public ZoneId marketplaceZone() {
return marketplaceZone;
}
@@ -61,6 +76,7 @@ public final class PlatformTime {
return new PlatformTime(utc.plus(duration), marketplaceZone);
}
+ /** UTC 时刻与时区都相同才相等。 */
@Override
public boolean equals(Object o) {
if (this == o) {
@@ -73,11 +89,13 @@ public final class PlatformTime {
return utc.equals(that.utc) && marketplaceZone.equals(that.marketplaceZone);
}
+ /** 与 {@link #equals(Object)} 一致。 */
@Override
public int hashCode() {
return Objects.hash(utc, marketplaceZone);
}
+ /** 形如 {@code 2026-01-01T00:00:00Z (America/Los_Angeles)}。 */
@Override
public String toString() {
return utc + " (" + marketplaceZone + ")";
diff --git a/core/src/main/java/common/ecommerce/sdk/AdapterFactory.java b/core/src/main/java/common/ecommerce/sdk/AdapterFactory.java
index c5db9f6..e855f7e 100644
--- a/core/src/main/java/common/ecommerce/sdk/AdapterFactory.java
+++ b/core/src/main/java/common/ecommerce/sdk/AdapterFactory.java
@@ -12,12 +12,23 @@ import java.util.EnumSet;
*/
public interface AdapterFactory {
+ /** 工厂标识,如 amazon-sc / lingxing;用于日志与重复注册定位。 */
String adapterId();
+ /** 该工厂产出的适配器所属接入通道。 */
ChannelProvider provider();
+ /** 该工厂覆盖的平台;create 出来的适配器应声明同一集合。 */
EnumSet platforms();
+ /**
+ * 创建适配器实例。
+ *
+ * 由 {@code ChannelSdk.Builder.build()} 在启动时调用一次;实现方自行装配
+ * 传输层、编解码、token 存储等依赖,SDK 不关心构造参数。
+ *
+ * @param config 测试/联调参数;生产传 {@link AdapterConfig#NONE}
+ */
PlatformAdapter create(AdapterConfig config);
/**
@@ -33,8 +44,10 @@ public interface AdapterFactory {
/** 不覆盖任何默认值,使用适配器内置端点。 */
public static final AdapterConfig NONE = new AdapterConfig(null);
+ /** 测试/联调用的端点覆盖;null 表示使用适配器内置端点。 */
private final String endpointBaseUrl;
+ /** 构造配置;端点只应由测试/联调代码传入。 */
public AdapterConfig(String endpointBaseUrl) {
this.endpointBaseUrl = endpointBaseUrl;
}
@@ -45,7 +58,9 @@ public interface AdapterFactory {
}
}
- /** 兜底:由平台推导默认 adapterId,便于日志定位。 */
+ /**
+ * 由平台推导默认 adapterId,如 {@code walmart_sc-lingxing},便于日志定位。
+ */
static String defaultAdapterId(AccountKey key) {
return key.platform().name().toLowerCase() + "-" + key.provider().name().toLowerCase();
}
diff --git a/core/src/main/java/common/ecommerce/sdk/CallSupport.java b/core/src/main/java/common/ecommerce/sdk/CallSupport.java
index b216216..b766cea 100644
--- a/core/src/main/java/common/ecommerce/sdk/CallSupport.java
+++ b/core/src/main/java/common/ecommerce/sdk/CallSupport.java
@@ -33,6 +33,9 @@ public final class CallSupport {
/** 结果数量不适用(单对象、写操作等)。 */
public static final int NO_COUNT = -1;
+ /**
+ * 门面埋点工具,禁止实例化。
+ */
private CallSupport() {
}
@@ -60,9 +63,14 @@ public final class CallSupport {
return map;
}
- /** 从返回值里取结果数量;不适用时返回 {@link #NO_COUNT}。 */
+ /**
+ * 结果数量提取器;不适用时返回 {@link #NO_COUNT}。
+ *
+ * @param 门面方法的返回类型
+ */
public interface ResultSize {
+ /** 返回结果条目数;不适用时返回 {@link CallSupport#NO_COUNT}。 */
int sizeOf(T result);
}
@@ -75,9 +83,16 @@ public final class CallSupport {
*/
public static final class ResultSummary {
+ /** 本次调用的结论:成功 / 部分成功 / 失败。 */
private final CallOutcome outcome;
+
+ /** 结果条目数;不适用时为 {@link #NO_COUNT}。 */
private final int resultCount;
+
+ /** 失败条目数;单对象失败时常用 1。 */
private final int failedCount;
+
+ /** 平台返回的业务码,可为 null。 */
private final String resultCode;
private ResultSummary(CallOutcome outcome, int resultCount, int failedCount, String resultCode) {
@@ -87,38 +102,54 @@ public final class CallSupport {
this.resultCode = resultCode;
}
+ /** 全部成功。 */
public static ResultSummary success(int resultCount) {
return new ResultSummary(CallOutcome.SUCCESS, resultCount, 0, null);
}
+ /** 部分成功;批处理里有失败条目时使用。 */
public static ResultSummary partial(int resultCount, int failedCount, String resultCode) {
return new ResultSummary(CallOutcome.PARTIAL, resultCount, failedCount, resultCode);
}
+ /** 整体失败;不会走成功路径,也不会被幂等层记为 SUCCEEDED。 */
public static ResultSummary failure(int resultCount, int failedCount, String resultCode) {
return new ResultSummary(CallOutcome.FAILURE, resultCount, failedCount, resultCode);
}
+ /** 结论。 */
public CallOutcome outcome() {
return outcome;
}
+ /** 结果条目数;不适用时为 {@link CallSupport#NO_COUNT}。 */
public int resultCount() {
return resultCount;
}
+ /** 失败条目数。 */
public int failedCount() {
return failedCount;
}
+ /** 平台业务码,可为 null。 */
public String resultCode() {
return resultCode;
}
}
- /** 从返回值里提取 {@link ResultSummary}。 */
+ /**
+ * 结果摘要提取器。
+ *
+ * @param 门面方法的返回类型
+ */
public interface ResultMapper {
+ /**
+ * 根据返回值生成摘要;返回 null 等价于 {@code SUCCESS + NO_COUNT}。
+ *
+ * 抛出运行时异常时同样兜底为 {@code SUCCESS + NO_COUNT},不影响业务返回值。
+ */
ResultSummary summarize(T result);
}
@@ -137,6 +168,7 @@ public final class CallSupport {
Supplier action) {
return observeSummary(observer, ctx, operation, params,
new ResultMapper() {
+ /** 只关心数量:null 结果或未提供提取器时记 NO_COUNT。 */
@Override
public ResultSummary summarize(T result) {
if (result == null || resultSize == null) {
@@ -151,6 +183,8 @@ public final class CallSupport {
/**
* 执行一次门面调用并记录日志(可区分成功 / 部分成功 / 失败)。
*
+ * 业务异常原样抛出;观察者异常吞掉并打 WARN。
+ *
* @param mapper 结果摘要提取器;抛异常时按 {@code SUCCESS + NO_COUNT} 兜底,
* 不影响业务返回值
*/
@@ -172,6 +206,7 @@ public final class CallSupport {
}
}
+ /** 摘要提取的兜底:mapper 为 null、返回 null 或抛异常时统一记成成功且无数量。 */
private static ResultSummary summarize(ResultMapper mapper, T result) {
if (mapper == null) {
return ResultSummary.success(NO_COUNT);
@@ -185,6 +220,9 @@ public final class CallSupport {
}
}
+ /**
+ * 组装 {@link CallRecord} 并回调观察者;回调失败只打 WARN,不影响业务。
+ */
private static void notifyObserver(CallObserver observer, ChannelContext ctx, String operation,
Map params, ResultSummary summary,
RuntimeException error,
diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java b/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java
index baa6501..beaef45 100644
--- a/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java
+++ b/core/src/main/java/common/ecommerce/sdk/ChannelConnection.java
@@ -38,6 +38,11 @@ public final class ChannelConnection {
.build();
}
+ /**
+ * 构造连接:基址去空白、去末尾斜杠,并把基址写回凭据副本。
+ *
+ * @throws IllegalArgumentException 基址为空
+ */
public static ChannelConnection of(String endpointBaseUrl, ChannelSecret secret) {
return new ChannelConnection(endpointBaseUrl, secret);
}
@@ -47,16 +52,23 @@ public final class ChannelConnection {
return endpointBaseUrl;
}
+ /** 凭据;已携带本次调用使用的端点,供 token 刷新回调使用。 */
public ChannelSecret secret() {
return secret;
}
+ /**
+ * 只保留基址与凭据指纹,可安全放进日志。
+ *
+ * 凭据本体(appSecret、clientSecret、refreshToken 等)不会出现在输出中。
+ */
@Override
public String toString() {
// 只打指纹与地址,凭据本体不出现在日志里
return "ChannelConnection{" + endpointBaseUrl + ", " + secret.fingerprint() + '}';
}
+ /** 去掉 URL 末尾所有斜杠;只处理字符串,不做 URL 合法性校验。 */
private static String trimTrailingSlash(String url) {
int end = url.length();
while (end > 0 && url.charAt(end - 1) == '/') {
diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelContext.java b/core/src/main/java/common/ecommerce/sdk/ChannelContext.java
index e11976d..20d6e34 100644
--- a/core/src/main/java/common/ecommerce/sdk/ChannelContext.java
+++ b/core/src/main/java/common/ecommerce/sdk/ChannelContext.java
@@ -16,10 +16,19 @@ import java.util.Objects;
*/
public final class ChannelContext {
+ /** 账户标识;构造时若未显式传入则取自账户。 */
private final AccountKey key;
+
+ /** 账户配置;{@link #ofKey} 构造时为 null。 */
private final ChannelAccount account;
+
+ /** 本次调用的连接信息;不联网的调用为 null。 */
private final ChannelConnection connection;
+
+ /** 本次调用的链路 ID。 */
private final String requestId;
+
+ /** 调用方注入的 UTC 时钟,用于耗时与时间窗计算。 */
private final Clock clock;
private ChannelContext(AccountKey key, ChannelAccount account, ChannelConnection connection,
@@ -31,6 +40,11 @@ public final class ChannelContext {
this.clock = Objects.requireNonNull(clock, "clock");
}
+ /**
+ * 完整上下文:账户 + 连接 + 链路 ID + 时钟。
+ *
+ * 会发起真实请求的调用必须用这个工厂;账户与连接都不能为 null。
+ */
public static ChannelContext of(ChannelAccount account, ChannelConnection connection,
String requestId, Clock clock) {
Objects.requireNonNull(account, "account");
@@ -80,14 +94,17 @@ public final class ChannelContext {
return account;
}
+ /** OMS 店铺 ID(业务归属),即使账户没查到也有值。 */
public String omsStoreId() {
return key.omsStoreId();
}
+ /** 电商平台;provider 只决定接入通道,不参与该维度。 */
public Platform platform() {
return key.platform();
}
+ /** 接入通道(直连 / 领星聚合等)。 */
public ChannelProvider provider() {
return key.provider();
}
diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
index c117e2e..18c57e2 100644
--- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
+++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
@@ -121,6 +121,7 @@ public final class ChannelSdk implements ProviderResolver {
IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS, callObserver);
}
+ /** 创建门面构建器。 */
public static Builder builder() {
return new Builder();
}
@@ -147,6 +148,7 @@ public final class ChannelSdk implements ProviderResolver {
() -> capabilitiesOf(key));
}
+ /** 能力矩阵的实际实现:账户与适配器都齐了才构造报告。 */
private CapabilityReport capabilitiesOf(AccountKey key) {
ChannelAccount account = requireAccount(key);
return new AdapterCapabilityReport(resolve(key), account);
@@ -254,6 +256,7 @@ public final class ChannelSdk implements ProviderResolver {
idempotencyGuard != null, clock.getClass().getSimpleName());
}
+ /** 启动日志用:观察者是否启用以及实现类名。 */
private String describeObserver() {
if (callObserver == CallObserver.NOOP) {
return "NOOP(no call log; set Builder.callObserver(...) to enable)";
@@ -359,7 +362,9 @@ public final class ChannelSdk implements ProviderResolver {
*/
private Supplier requestIdSupplier = DEFAULT_REQUEST_ID_SUPPLIER;
+ /** 缺省链路 ID 生成器:随机 UUID。 */
private static final Supplier DEFAULT_REQUEST_ID_SUPPLIER = new Supplier() {
+ /** 生成随机 UUID 作为链路 ID。 */
@Override
public String get() {
return UUID.randomUUID().toString();
diff --git a/core/src/main/java/common/ecommerce/sdk/ProviderResolver.java b/core/src/main/java/common/ecommerce/sdk/ProviderResolver.java
index d9a6b06..a0ff4c0 100644
--- a/core/src/main/java/common/ecommerce/sdk/ProviderResolver.java
+++ b/core/src/main/java/common/ecommerce/sdk/ProviderResolver.java
@@ -10,5 +10,10 @@ import common.ecommerce.model.account.AccountKey;
*/
public interface ProviderResolver {
+ /**
+ * 按 AccountKey 找到对应适配器。
+ *
+ * @throws IllegalStateException provider + platform 组合未注册适配器
+ */
PlatformAdapter resolve(AccountKey key);
}
diff --git a/core/src/main/java/common/ecommerce/spi/AccessToken.java b/core/src/main/java/common/ecommerce/spi/AccessToken.java
index 5d00ee1..305510a 100644
--- a/core/src/main/java/common/ecommerce/spi/AccessToken.java
+++ b/core/src/main/java/common/ecommerce/spi/AccessToken.java
@@ -5,12 +5,22 @@ import java.util.Objects;
/**
* 访问令牌。
+ *
+ * 由适配器通过 {@link TokenStore} 读写;令牌本体只应存在于内存与宿主的加密存储中,
+ * 日志只能使用 {@link #fingerprint()}。
*/
public final class AccessToken {
+ /** 令牌本体;必填。 */
private final String value;
+
+ /** 刷新令牌;无刷新机制的 provider 为 null。 */
private final String refreshToken;
+
+ /** 过期时刻(UTC);必填。 */
private final Instant expiresAt;
+
+ /** 令牌类型,默认 {@code Bearer}。 */
private final String tokenType;
private AccessToken(Builder b) {
@@ -20,22 +30,27 @@ public final class AccessToken {
this.tokenType = b.tokenType == null ? "Bearer" : b.tokenType;
}
+ /** 创建构建器。 */
public static Builder builder() {
return new Builder();
}
+ /** 令牌本体;不得直接写日志。 */
public String value() {
return value;
}
+ /** 刷新令牌,可为 null。 */
public String refreshToken() {
return refreshToken;
}
+ /** 过期时刻(UTC)。 */
public Instant expiresAt() {
return expiresAt;
}
+ /** 令牌类型,默认 {@code Bearer}。 */
public String tokenType() {
return tokenType;
}
@@ -50,33 +65,50 @@ public final class AccessToken {
return "token#" + Integer.toHexString(value.hashCode());
}
+ /** 令牌构建器。 */
public static final class Builder {
+ /** 令牌本体;必填。 */
private String value;
+
+ /** 刷新令牌,可为 null。 */
private String refreshToken;
+
+ /** 过期时刻(UTC);必填。 */
private Instant expiresAt;
+
+ /** 令牌类型;null 时构建为 {@code Bearer}。 */
private String tokenType;
+ /** 设置令牌本体。 */
public Builder value(String value) {
this.value = value;
return this;
}
+ /** 设置刷新令牌。 */
public Builder refreshToken(String refreshToken) {
this.refreshToken = refreshToken;
return this;
}
+ /** 设置过期时刻(UTC)。 */
public Builder expiresAt(Instant expiresAt) {
this.expiresAt = expiresAt;
return this;
}
+ /** 设置令牌类型;不设置时为 {@code Bearer}。 */
public Builder tokenType(String tokenType) {
this.tokenType = tokenType;
return this;
}
+ /**
+ * 构建令牌。
+ *
+ * @throws NullPointerException value 或 expiresAt 为 null
+ */
public AccessToken build() {
return new AccessToken(this);
}
diff --git a/core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java b/core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java
index 3b36b90..cb6848f 100644
--- a/core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java
+++ b/core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java
@@ -9,8 +9,20 @@ import java.util.Optional;
*/
public interface ChannelAccountRepository {
+ /**
+ * 按三维标识查账户。
+ *
+ * @param provider 接入通道名,如 {@code LINGXING}
+ * @param platform 平台名,如 {@code WALMART_SC}
+ * @param omsStoreId OMS 店铺 ID(不是平台店铺 ID)
+ * @return 找到的账户;未配置时返回 empty,SDK 会转成 IllegalStateException
+ */
Optional findByKey(String provider, String platform, String omsStoreId);
- /** 同一 omsStoreId 下所有 provider 账户。 */
+ /**
+ * 同一 omsStoreId 下所有 provider 账户。
+ *
+ * 用于展示「同一业务店铺有哪些接入通道」;没有时返回空列表。
+ */
java.util.List findByOmsStoreId(String omsStoreId);
}
diff --git a/core/src/main/java/common/ecommerce/spi/ChannelSecret.java b/core/src/main/java/common/ecommerce/spi/ChannelSecret.java
index 87bbde5..a7e4810 100644
--- a/core/src/main/java/common/ecommerce/spi/ChannelSecret.java
+++ b/core/src/main/java/common/ecommerce/spi/ChannelSecret.java
@@ -37,6 +37,7 @@ public final class ChannelSecret {
this.refreshToken = b.refreshToken;
}
+ /** 创建构建器。 */
public static Builder builder() {
return new Builder();
}
@@ -49,22 +50,27 @@ public final class ChannelSecret {
return endpointBaseUrl;
}
+ /** 应用标识;未使用该字段的 provider 为 null。 */
public String appKey() {
return appKey;
}
+ /** 应用密钥;未使用该字段的 provider 为 null。 */
public String appSecret() {
return appSecret;
}
+ /** OAuth 客户端 ID;未使用该字段的 provider 为 null。 */
public String clientId() {
return clientId;
}
+ /** OAuth 客户端密钥;未使用该字段的 provider 为 null。 */
public String clientSecret() {
return clientSecret;
}
+ /** 长期刷新令牌;未使用该字段的 provider 为 null。 */
public String refreshToken() {
return refreshToken;
}
@@ -75,13 +81,25 @@ public final class ChannelSecret {
return "secret#" + Integer.toHexString(seed.hashCode());
}
+ /** 凭证构建器。所有字段都可空,由 provider 按需取用。 */
public static final class Builder {
+ /** 目标基址;ChannelConnection 构造时会写回。 */
private String endpointBaseUrl;
+
+ /** 应用标识。 */
private String appKey;
+
+ /** 应用密钥。 */
private String appSecret;
+
+ /** OAuth 客户端 ID。 */
private String clientId;
+
+ /** OAuth 客户端密钥。 */
private String clientSecret;
+
+ /** 长期刷新令牌。 */
private String refreshToken;
/** 端点与凭据一起传入;TokenManager 刷新时需要它。 */
@@ -90,31 +108,37 @@ public final class ChannelSecret {
return this;
}
+ /** 设置应用标识(领星 appId)。 */
public Builder appKey(String appKey) {
this.appKey = appKey;
return this;
}
+ /** 设置应用密钥(领星 appSecret)。 */
public Builder appSecret(String appSecret) {
this.appSecret = appSecret;
return this;
}
+ /** 设置 OAuth 客户端 ID。 */
public Builder clientId(String clientId) {
this.clientId = clientId;
return this;
}
+ /** 设置 OAuth 客户端密钥。 */
public Builder clientSecret(String clientSecret) {
this.clientSecret = clientSecret;
return this;
}
+ /** 设置长期刷新令牌。 */
public Builder refreshToken(String refreshToken) {
this.refreshToken = refreshToken;
return this;
}
+ /** 构建凭证对象;不做必填校验,缺失字段留给 provider 在使用时判断。 */
public ChannelSecret build() {
return new ChannelSecret(this);
}
diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java b/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java
index 8a10d5c..7bc63a8 100644
--- a/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java
+++ b/core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java
@@ -13,14 +13,22 @@ package common.ecommerce.spi;
*/
public final class IdempotencyClaim {
+ /** 抢占结果。 */
public enum Outcome {
+ /** 抢占成功,可以执行。 */
ACQUIRED,
+ /** 已被其它调用抢占且未过期,不能执行。 */
IN_PROGRESS,
+ /** 已成功,直接回放结果。 */
SUCCEEDED,
+ /** 终态失败,需要人工介入。 */
FAILED_FINAL
}
+ /** 结果类型。 */
private final Outcome outcome;
+
+ /** 已有记录;ACQUIRED 时为 null。 */
private final IdempotencyRecord record;
private IdempotencyClaim(Outcome outcome, IdempotencyRecord record) {
@@ -33,10 +41,12 @@ public final class IdempotencyClaim {
return new IdempotencyClaim(Outcome.ACQUIRED, null);
}
+ /** 按指定结果构造;record 可为 null。 */
public static IdempotencyClaim of(Outcome outcome, IdempotencyRecord record) {
return new IdempotencyClaim(outcome, record);
}
+ /** 结果类型。 */
public Outcome outcome() {
return outcome;
}
@@ -46,10 +56,12 @@ public final class IdempotencyClaim {
return record;
}
+ /** 是否抢占成功。 */
public boolean acquired() {
return outcome == Outcome.ACQUIRED;
}
+ /** 结果类型与已有记录的可读形式,用于日志排查。 */
@Override
public String toString() {
return "IdempotencyClaim{" + outcome + (record == null ? "" : " " + record) + '}';
diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java b/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java
index c9b010d..3880409 100644
--- a/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java
+++ b/core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java
@@ -13,11 +13,22 @@ import java.util.Objects;
*/
public final class IdempotencyRecord {
+ /** 幂等键。 */
private final String key;
+
+ /** 当前状态。 */
private final IdempotencyStatus status;
+
+ /** 完成/抢占该动作的接入通道。 */
private final ChannelProvider provider;
+
+ /** 抢占方实例标识。 */
private final String owner;
+
+ /** 结果引用(订单号 / 包裹号等),可为 null。 */
private final String resultRef;
+
+ /** 最后更新时间(UTC)。 */
private final Instant updatedAt;
private IdempotencyRecord(String key, IdempotencyStatus status, ChannelProvider provider,
@@ -30,15 +41,22 @@ public final class IdempotencyRecord {
this.updatedAt = Objects.requireNonNull(updatedAt, "updatedAt");
}
+ /**
+ * 创建记录。
+ *
+ * @throws NullPointerException key、status 或 updatedAt 为 null
+ */
public static IdempotencyRecord of(String key, IdempotencyStatus status, ChannelProvider provider,
String owner, String resultRef, Instant updatedAt) {
return new IdempotencyRecord(key, status, provider, owner, resultRef, updatedAt);
}
+ /** 幂等键。 */
public String key() {
return key;
}
+ /** 当前状态。 */
public IdempotencyStatus status() {
return status;
}
@@ -48,6 +66,7 @@ public final class IdempotencyRecord {
return provider;
}
+ /** 抢占方实例标识。 */
public String owner() {
return owner;
}
@@ -57,10 +76,12 @@ public final class IdempotencyRecord {
return resultRef;
}
+ /** 最后更新时间(UTC)。 */
public Instant updatedAt() {
return updatedAt;
}
+ /** 键 / 状态 / 通道 / owner / 结果引用的可读形式;不含敏感数据。 */
@Override
public String toString() {
return "IdempotencyRecord{" + key + " " + status + " by " + provider + '/' + owner
diff --git a/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java b/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java
index 8bed7cf..60969fc 100644
--- a/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java
+++ b/core/src/main/java/common/ecommerce/spi/IdempotencyStore.java
@@ -16,19 +16,35 @@ public interface IdempotencyStore {
/**
* 抢占幂等键。
*
+ * 实现必须原子完成「查询 + 条件写入」,不能先查再写两步。
+ *
* @param key 幂等键(业务键或 provider 请求键)
* @param owner 抢占方实例标识
* @param provider 接入通道,写入记录用于识别跨 provider 重复
* @param now 当前时间(UTC)
* @param ttlSeconds 抢占后无结果的最长保留时间,过期视为可重新抢占
+ * @return 抢占结果;ACQUIRED 时 record 为 null 或历史记录
*/
IdempotencyClaim claim(String key, String owner, ChannelProvider provider, Instant now, long ttlSeconds);
- /** 执行成功,记录结果引用。只有当前 owner 可以写入。 */
+ /**
+ * 执行成功,记录结果引用。只有当前 owner 可以写入。
+ *
+ * @param resultRef 订单号 / 包裹号等外部引用,不保存完整业务结果
+ */
void complete(String key, String owner, String resultRef, Instant now);
- /** 执行失败;{@code retryable=false} 记为终态,不再自动重试。 */
+ /**
+ * 执行失败;{@code retryable=false} 记为终态,不再自动重试。
+ *
+ * 只有当前 owner 可以写入,避免过期 owner 覆盖新抢占者的结果。
+ */
void fail(String key, String owner, boolean retryable, Instant now);
+ /**
+ * 读取幂等记录。
+ *
+ * @return 记录;从未写入时为 empty
+ */
Optional get(String key);
}
diff --git a/core/src/main/java/common/ecommerce/spi/LockProvider.java b/core/src/main/java/common/ecommerce/spi/LockProvider.java
index f149e1a..34249ca 100644
--- a/core/src/main/java/common/ecommerce/spi/LockProvider.java
+++ b/core/src/main/java/common/ecommerce/spi/LockProvider.java
@@ -12,12 +12,14 @@ public interface LockProvider {
*
* @param key 锁键
* @param ttlSeconds 锁自动过期时间
- * @return 锁句柄;未获取到返回 empty
+ * @return 锁句柄;未获取到返回 empty。关闭句柄即释放锁,必须在 finally 中关闭
*/
Optional tryLock(String key, long ttlSeconds);
+ /** 锁句柄;实现需保证 close 幂等,并只释放自己持有的锁。 */
interface Lock extends AutoCloseable {
+ /** 释放锁;重复调用不应报错。 */
@Override
void close();
}
diff --git a/core/src/main/java/common/ecommerce/spi/SecretProvider.java b/core/src/main/java/common/ecommerce/spi/SecretProvider.java
index 8e4f6b4..49f6e42 100644
--- a/core/src/main/java/common/ecommerce/spi/SecretProvider.java
+++ b/core/src/main/java/common/ecommerce/spi/SecretProvider.java
@@ -8,7 +8,10 @@ package common.ecommerce.spi;
public interface SecretProvider {
/**
+ * 按引用取出凭证。
+ *
* @param credentialRef 形如 {@code kms://oms/lingxing/store-001}
+ * @return 凭证;引用不存在时返回 null 或抛异常,由实现自行约定
*/
ChannelSecret get(String credentialRef);
}
diff --git a/core/src/main/java/common/ecommerce/spi/Sink.java b/core/src/main/java/common/ecommerce/spi/Sink.java
index 3b45f4d..72348a3 100644
--- a/core/src/main/java/common/ecommerce/spi/Sink.java
+++ b/core/src/main/java/common/ecommerce/spi/Sink.java
@@ -12,7 +12,17 @@ import common.ecommerce.model.order.SalesOrder;
*/
public interface Sink {
+ /**
+ * 按 canonicalKey 写入一页销售订单。
+ *
+ * 空页也允许传入;实现必须幂等,重复同步不产生重复行。
+ */
void upsertSalesOrders(Page page);
+ /**
+ * 按 canonicalKey 写入一页商品。
+ *
+ * 空页也允许传入;实现必须幂等,重复同步不产生重复行。
+ */
void upsertProducts(Page page);
}
diff --git a/core/src/main/java/common/ecommerce/spi/SyncCursorStore.java b/core/src/main/java/common/ecommerce/spi/SyncCursorStore.java
index 5ca8efe..89edb79 100644
--- a/core/src/main/java/common/ecommerce/spi/SyncCursorStore.java
+++ b/core/src/main/java/common/ecommerce/spi/SyncCursorStore.java
@@ -11,8 +11,22 @@ import java.time.Instant;
*/
public interface SyncCursorStore {
- /** 返回 null 表示还没有水位线,需要首次全量建底。 */
+ /**
+ * 读取水位线。
+ *
+ * @param provider 接入通道,与 accountKey、stream 一起构成维度
+ * @param accountKey 宿主定义的账户标识
+ * @param stream 同步流名称,如 orders / products
+ * @return 水位线;null 表示还没有水位线,需要首次全量建底
+ */
Instant get(ChannelProvider provider, String accountKey, String stream);
+ /**
+ * 推进水位线。
+ *
+ * 只能在整个批次成功后调用;引擎只会写入更新的终点,实现按传入值覆盖即可。
+ *
+ * @param watermark 新水位线(UTC),不会为 null
+ */
void advance(ChannelProvider provider, String accountKey, String stream, Instant watermark);
}
diff --git a/core/src/main/java/common/ecommerce/spi/TokenStore.java b/core/src/main/java/common/ecommerce/spi/TokenStore.java
index ee0604f..5d85320 100644
--- a/core/src/main/java/common/ecommerce/spi/TokenStore.java
+++ b/core/src/main/java/common/ecommerce/spi/TokenStore.java
@@ -7,9 +7,21 @@ import java.util.Optional;
*/
public interface TokenStore {
+ /**
+ * 读取令牌。
+ *
+ * @param tokenKey 令牌键,由适配器按 provider + 账户 + 作用域生成
+ * @return 令牌;没有或已失效时返回 empty
+ */
Optional get(String tokenKey);
+ /**
+ * 写入/覆盖令牌。宿主必须加密存储,且不得把令牌写入日志。
+ */
void save(String tokenKey, AccessToken token);
+ /**
+ * 删除令牌(如刷新失败、账户解绑)。键不存在时视为成功。
+ */
void remove(String tokenKey);
}
diff --git a/core/src/main/java/common/ecommerce/sync/SyncEngine.java b/core/src/main/java/common/ecommerce/sync/SyncEngine.java
index 1027bcf..83bfcde 100644
--- a/core/src/main/java/common/ecommerce/sync/SyncEngine.java
+++ b/core/src/main/java/common/ecommerce/sync/SyncEngine.java
@@ -26,11 +26,18 @@ import java.util.function.BiFunction;
*/
public final class SyncEngine {
+ /** 本类自己的日志;引擎本身不配置日志目的地。 */
private static final Logger LOG = LoggerFactory.getLogger(SyncEngine.class);
+ /** 水位线存储,非 null;读写由宿主实现。 */
private final SyncCursorStore cursorStore;
+ /** 落库出口,非 null;按 canonicalKey upsert。 */
private final Sink sink;
+ /**
+ * @param cursorStore 水位线存储;不能为 null
+ * @param sink 领域对象落库出口;不能为 null
+ */
public SyncEngine(SyncCursorStore cursorStore, Sink sink) {
this.cursorStore = cursorStore;
this.sink = sink;
@@ -39,9 +46,15 @@ public final class SyncEngine {
/**
* 同步销售订单。
*
+ * 整批成功才推进水位线;任何一页抛异常都会直接冒出,
+ * {@code SyncResult} 不会返回,水位线保持原值。引擎不私起线程/定时器。
+ *
* @param spec 同步维度(provider + account + stream + overlap)
- * @param to 本次增量终点
- * @param fetch 拉一页的函数:(from, cursor) → page
+ * @param to 本次增量终点;会作为新水位线写入,需非 null
+ * @param fetch 拉一页的函数:(from, cursor) → page;首页 {@code cursor} 为 null
+ * @return 本次同步统计;成功路径恒为 {@code watermarkAdvanced=true}
+ * @throws IllegalStateException 账户/流还没有水位线(必须先跑一次全量建底)
+ * @throws RuntimeException {@code fetch} / {@code sink} 抛出的异常原样冒出
*/
public SyncResult syncSalesOrders(SyncSpec spec, Instant to,
BiFunction> fetch) {
diff --git a/core/src/main/java/common/ecommerce/sync/SyncResult.java b/core/src/main/java/common/ecommerce/sync/SyncResult.java
index 867122a..f7fb4d8 100644
--- a/core/src/main/java/common/ecommerce/sync/SyncResult.java
+++ b/core/src/main/java/common/ecommerce/sync/SyncResult.java
@@ -2,11 +2,17 @@ package common.ecommerce.sync;
/**
* 单次同步结果。
+ *
+ * 只有正常跑完的批次才会生成;同步中途抛异常时不会返回本对象,
+ * 水位线也不会推进。
*/
public final class SyncResult {
+ /** 本次拉取的页数(空批次为 0)。 */
private final int pages;
+ /** 本次经 Sink upsert 的条目总数(空批次为 0)。 */
private final int items;
+ /** 水位线是否已推进;整批成功为 true,另见 {@link #empty()}。 */
private final boolean watermarkAdvanced;
private SyncResult(int pages, int items, boolean watermarkAdvanced) {
@@ -15,18 +21,22 @@ public final class SyncResult {
this.watermarkAdvanced = watermarkAdvanced;
}
+ /** 本次同步统计:{@code watermarkAdvanced} 只有整批成功才应为 true。 */
public static SyncResult of(int pages, int items, boolean watermarkAdvanced) {
return new SyncResult(pages, items, watermarkAdvanced);
}
+ /** 空结果:0 页 0 条,且水位线未推进。 */
public static SyncResult empty() {
return new SyncResult(0, 0, false);
}
+ /** 拉取的页数。 */
public int pages() {
return pages;
}
+ /** 落库的条目数(首页为空时也是 0,不代表没拉取)。 */
public int items() {
return items;
}
@@ -36,6 +46,7 @@ public final class SyncResult {
return watermarkAdvanced;
}
+ /** 便于日志输出。 */
@Override
public String toString() {
return "SyncResult{pages=" + pages + ", items=" + items + ", watermarkAdvanced=" + watermarkAdvanced + '}';
diff --git a/core/src/main/java/common/ecommerce/sync/SyncSpec.java b/core/src/main/java/common/ecommerce/sync/SyncSpec.java
index 9b04f62..a6b30b7 100644
--- a/core/src/main/java/common/ecommerce/sync/SyncSpec.java
+++ b/core/src/main/java/common/ecommerce/sync/SyncSpec.java
@@ -15,9 +15,13 @@ public final class SyncSpec {
/** 商品流标识。 */
public static final String STREAM_PRODUCTS = "products";
+ /** 接入通道;与 accountKey、stream 一起构成水位线维度。 */
private final ChannelProvider provider;
+ /** 宿主侧账户标识;与 provider、stream 一起构成水位线维度。 */
private final String accountKey;
+ /** 流标识,如 {@link #STREAM_SALES_ORDERS}。 */
private final String stream;
+ /** 水位线回退窗口;非 null,通常 5~15 分钟。 */
private final Duration overlap;
private SyncSpec(ChannelProvider provider, String accountKey, String stream, Duration overlap) {
@@ -27,18 +31,25 @@ public final class SyncSpec {
this.overlap = overlap;
}
+ /**
+ * 构造同步配置;参数原样保存,不做校验,null 会在 {@link #from(Instant)} 或
+ * 调用 {@code SyncCursorStore} 时才暴露。
+ */
public static SyncSpec of(ChannelProvider provider, String accountKey, String stream, Duration overlap) {
return new SyncSpec(provider, accountKey, stream, overlap);
}
+ /** 接入通道。 */
public ChannelProvider provider() {
return provider;
}
+ /** 宿主侧账户标识。 */
public String accountKey() {
return accountKey;
}
+ /** 流标识。 */
public String stream() {
return stream;
}
@@ -49,9 +60,11 @@ public final class SyncSpec {
}
/**
- * 计算增量起点。
+ * 计算增量起点:{@code watermark - overlap}。
*
* 没有水位线时返回 null,由调用方走首次全量。
+ *
+ * @param watermark 上次成功同步的终点;null 表示尚未建底
*/
public Instant from(Instant watermark) {
return watermark == null ? null : watermark.minus(overlap);