diff --git a/core/src/main/java/common/ecommerce/audit/CallOutcome.java b/core/src/main/java/common/ecommerce/audit/CallOutcome.java index 7b91771..b1e3f00 100644 --- a/core/src/main/java/common/ecommerce/audit/CallOutcome.java +++ b/core/src/main/java/common/ecommerce/audit/CallOutcome.java @@ -2,13 +2,20 @@ package common.ecommerce.audit; /** * 一次 SDK 调用的结果状态。 + * + *

只有 {@link #SUCCESS} 表示完整成功;批处理部分失败是 {@link #PARTIAL}, + * 不能当成功处理(例如幂等层会把成功当成业务动作已完成)。

*/ public enum CallOutcome { - /** 调用成功(适配器没有抛异常)。 */ + /** 调用成功(适配器没有抛异常,且没有失败明细)。 */ SUCCESS, - /** 批处理部分成功:有失败明细,但调用方拿到了结果。 */ + /** + * 批处理部分成功:有失败明细,但调用方仍拿到了结果(如审核发货部分单失败)。 + * + *

不算 {@link #SUCCESS};需要逐条看 {@code failedCount} / {@code resultCode}。

+ */ PARTIAL, /** 调用失败(能力不支持、参数校验、平台返回错误、网络异常等)。 */ diff --git a/core/src/main/java/common/ecommerce/audit/CallRecord.java b/core/src/main/java/common/ecommerce/audit/CallRecord.java index 8bd5a12..85f3e3e 100644 --- a/core/src/main/java/common/ecommerce/audit/CallRecord.java +++ b/core/src/main/java/common/ecommerce/audit/CallRecord.java @@ -23,25 +23,44 @@ import java.util.Objects; */ public final class CallRecord { + /** 调用开始时间(UTC);构造时必填。 */ private final Instant occurredAt; + /** 我方链路 ID(可注入 traceId),可能为 null;不是平台工单号。 */ private final String requestId; + /** 接入通道;账户/适配器还没解析出来时可能为 null。 */ private final ChannelProvider provider; + /** 业务平台;账户/适配器还没解析出来时可能为 null。 */ private final Platform platform; + /** 宿主侧店铺 ID,业务主键的一部分;可能为 null。 */ private final String omsStoreId; + /** 渠道侧店铺 ID(领星 {@code store_id}、亚马逊 SC {@code sid});无账户信息时为 null。 */ private final String externalStoreId; + /** 门面操作名,必填,如 {@code salesOrders.pull}。 */ private final String operation; + /** 结论,必填;{@link CallOutcome#PARTIAL} 是批处理部分失败,不能当成功处理。 */ private final CallOutcome outcome; + /** 耗时(毫秒),非负;测试注入固定时钟时为 0。 */ private final long durationMillis; + /** 结果条数;不适用(写操作等)为 -1。 */ private final int resultCount; + /** 失败条数;仅批处理结果有值,其余为 -1。 */ private final int failedCount; + /** 平台业务结果码(如编辑订单 {@code 10000} / {@code 10001});无则为 null。 */ private final String resultCode; + /** 参数摘要,只读;永不为 null,缺省为空 Map。只放非敏感摘要。 */ private final Map params; + /** 失败异常的全限定类名;成功为 null。 */ private final String errorType; + /** 失败异常的消息;成功或异常无 message 时为 null。 */ private final String errorMessage; + /** 是否值得重试;仅失败异常是 {@code ChannelException} 时有值,其余为 null。SDK 不重试。 */ private final Boolean retryable; + /** 平台工单号(如领星响应体 {@code request_id});与 {@link #requestId()} 是两回事,无则 null。 */ private final String platformRequestId; + /** 平台业务码 / HTTP 状态码;仅失败异常是 {@code ChannelException} 时有值。 */ private final String platformCode; + /** 由 Builder 装配;必填字段已校验,其余字段可能为 null。 */ private CallRecord(Builder b) { this.occurredAt = Objects.requireNonNull(b.occurredAt, "occurredAt"); this.requestId = b.requestId; @@ -64,6 +83,7 @@ public final class CallRecord { this.platformCode = b.platformCode; } + /** 新建 Builder;只填排查所需字段,缺省值见各 setter 注释。 */ public static Builder builder() { return new Builder(); } @@ -94,15 +114,21 @@ public final class CallRecord { return finishedAt().atZone(Objects.requireNonNull(zone, "zone")); } - /** 链路 ID,与 HTTP 层日志、平台 request_id 关联用。 */ + /** + * 链路 ID,与 HTTP 层日志关联用。 + * + *

这是我方生成的 ID;平台侧工单号是 {@link #platformRequestId()},两者不能混。

+ */ public String requestId() { return requestId; } + /** 接入通道;未解析出账户/适配器时为 null。 */ public ChannelProvider provider() { return provider; } + /** 业务平台;未解析出账户/适配器时为 null。 */ public Platform platform() { return platform; } @@ -122,6 +148,7 @@ public final class CallRecord { return operation; } + /** 结论;PARTIAL 表示批处理部分失败,不算 SUCCESS。 */ public CallOutcome outcome() { return outcome; } @@ -188,10 +215,12 @@ public final class CallRecord { return platformCode; } + /** 是否失败;只有 {@link CallOutcome#FAILURE} 为 true,PARTIAL 仍算拿到了结果。 */ public boolean failed() { return outcome == CallOutcome.FAILURE; } + /** 便于排查/日志输出;包含失败字段(成功时不带 error 段)。 */ @Override public String toString() { return "CallRecord{" + outcome @@ -214,92 +243,130 @@ public final class CallRecord { + '}'; } + /** 可变构建器;{@link #build()} 时复制参数 Map 并转为只读。 */ public static final class Builder { + /** 调用开始时间(UTC);默认 {@link Instant#EPOCH},正式埋点必须覆盖。 */ private Instant occurredAt = Instant.EPOCH; + /** 我方链路 ID;默认 null。 */ private String requestId; + /** 接入通道;默认 null。 */ private ChannelProvider provider; + /** 业务平台;默认 null。 */ private Platform platform; + /** 宿主侧店铺 ID;默认 null。 */ private String omsStoreId; + /** 渠道侧店铺 ID;默认 null。 */ private String externalStoreId; + /** 门面操作名;必填,默认 null。 */ private String operation; + /** 结论;默认 {@link CallOutcome#SUCCESS},失败路径务必显式设置。 */ private CallOutcome outcome = CallOutcome.SUCCESS; + /** 耗时(毫秒);默认 0。 */ private long durationMillis; + /** 结果条数;默认 -1(不适用)。 */ private int resultCount = -1; + /** 失败条数;默认 -1(不适用)。 */ private int failedCount = -1; + /** 平台业务结果码;默认 null。 */ private String resultCode; + /** 参数摘要;默认空 Map,{@link #params(Map)} 传 null 也归一为空 Map。 */ private Map params = Collections.emptyMap(); + /** 失败异常类名;由 {@link #error(Throwable)} 填充。 */ private String errorType; + /** 失败异常消息;由 {@link #error(Throwable)} 填充。 */ private String errorMessage; + /** 是否值得重试;仅由 {@link #error(Throwable)} 从 {@code ChannelException} 提取。 */ private Boolean retryable; + /** 平台工单号;仅由 {@link #error(Throwable)} 从 {@code ChannelException} 提取。 */ private String platformRequestId; + /** 平台业务码;仅由 {@link #error(Throwable)} 从 {@code ChannelException} 提取。 */ private String platformCode; + /** 调用开始时间(UTC);必填。 */ public Builder occurredAt(Instant occurredAt) { this.occurredAt = occurredAt; return this; } + /** 我方链路 ID,不是平台 {@code request_id}。 */ public Builder requestId(String requestId) { this.requestId = requestId; return this; } + /** 接入通道。 */ public Builder provider(ChannelProvider provider) { this.provider = provider; return this; } + /** 业务平台。 */ public Builder platform(Platform platform) { this.platform = platform; return this; } + /** 宿主侧店铺 ID。 */ public Builder omsStoreId(String omsStoreId) { this.omsStoreId = omsStoreId; return this; } + /** 渠道侧店铺 ID。 */ public Builder externalStoreId(String externalStoreId) { this.externalStoreId = externalStoreId; return this; } + /** 门面操作名,如 {@code outbounds.review};必填。 */ public Builder operation(String operation) { this.operation = operation; return this; } + /** 结论;批处理部分失败用 {@link CallOutcome#PARTIAL},不要记 SUCCESS。 */ public Builder outcome(CallOutcome outcome) { this.outcome = outcome; return this; } + /** 耗时(毫秒),应非负。 */ public Builder durationMillis(long durationMillis) { this.durationMillis = durationMillis; return this; } + /** 结果条数;不适用时传 -1 或保持默认。 */ public Builder resultCount(int resultCount) { this.resultCount = resultCount; return this; } + /** 失败条数;仅批处理适用,其余保持 -1。 */ public Builder failedCount(int failedCount) { this.failedCount = failedCount; return this; } + /** 平台业务结果码。 */ public Builder resultCode(String resultCode) { this.resultCode = resultCode; return this; } + /** 参数摘要;null 归一为空 Map,调用方仍须保证不放敏感信息。 */ public Builder params(Map params) { this.params = params == null ? Collections.emptyMap() : params; return this; } + /** + * 从异常填充失败字段:类名、消息;若为 {@code ChannelException} + * 还提取 {@code retryable} / {@code platformRequestId} / {@code platformCode}。 + * + *

不会自动把 outcome 改成 FAILURE,需调用方显式设置。

+ */ public Builder error(Throwable error) { if (error != null) { this.errorType = error.getClass().getName(); @@ -314,6 +381,7 @@ public final class CallRecord { return this; } + /** 构造不可变记录;occurredAt / operation / outcome 不能为 null。 */ public CallRecord build() { return new CallRecord(this); } diff --git a/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java index 5fb0040..fe1bf51 100644 --- a/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java +++ b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java @@ -29,13 +29,17 @@ import java.util.Objects; */ public final class Slf4jCallObserver implements CallObserver { + /** 本类的日志器;日志绑定由宿主提供,SDK 不引入实现。 */ private static final Logger LOG = LoggerFactory.getLogger(Slf4jCallObserver.class); /** 默认时间格式:24 小时制、精确到秒,例如 {@code 2026-11-05 08:00:00}。 */ public static final String DEFAULT_TIME_PATTERN = "yyyy-MM-dd HH:mm:ss"; + /** 日志展示时区,非 null。 */ private final ZoneId zone; + /** 时间格式串,非 null。 */ private final String pattern; + /** 由 {@link #pattern} + {@link #zone} 构建的格式化器,线程安全。 */ private final DateTimeFormatter formatter; /** 使用 JVM 默认时区与默认格式 {@value #DEFAULT_TIME_PATTERN}。 */ @@ -76,6 +80,12 @@ public final class Slf4jCallObserver implements CallObserver { return formatter.format(instant); } + /** + * 每次调用结束打一行日志。 + * + *

{@link CallRecord#failed()} 为 true 打 WARN,否则打 INFO—— + * 因此 PARTIAL 也是 INFO,失败明细看行内的 {@code failed=}。

+ */ @Override public void onCall(CallRecord record) { if (record.failed()) { @@ -123,6 +133,7 @@ public final class Slf4jCallObserver implements CallObserver { + " error=" + record.errorType() + ": " + safe(record.errorMessage()); } + /** 拼公共维度字段:provider / platform / 两侧店铺 ID / 我方链路 ID。 */ private static String providerFields(CallRecord record) { return " provider=" + record.provider() + " platform=" + record.platform() @@ -131,6 +142,7 @@ public final class Slf4jCallObserver implements CallObserver { + " requestId=" + record.requestId(); } + /** 按当前时区与格式渲染时间。 */ private String at(Instant instant) { return format(instant); } diff --git a/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java b/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java index 1af635c..19345b5 100644 --- a/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java +++ b/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java @@ -13,10 +13,20 @@ import java.util.EnumSet; */ public final class AdapterCapabilityReport implements CapabilityReport { + /** 被查询的适配器。 */ private final PlatformAdapter adapter; + + /** 被查询的账户;聚合器据此细化能力。 */ private final ChannelAccount account; + + /** 构造时算好的支持能力集。 */ private final EnumSet supported; + /** + * 遍历 {@link Capability} 全集,逐项询问适配器。 + * + *

只读,不触发真实 API。

+ */ public AdapterCapabilityReport(PlatformAdapter adapter, ChannelAccount account) { this.adapter = adapter; this.account = account; @@ -28,16 +38,19 @@ public final class AdapterCapabilityReport implements CapabilityReport { } } + /** 该账户是否支持某能力。 */ @Override public boolean supports(Capability capability) { return supported.contains(capability); } + /** 支持的能力集合(副本)。 */ @Override public EnumSet supported() { return EnumSet.copyOf(supported); } + /** 不支持的能力集合(全集差集)。 */ @Override public EnumSet unsupported() { EnumSet all = EnumSet.allOf(Capability.class); @@ -45,14 +58,17 @@ public final class AdapterCapabilityReport implements CapabilityReport { return all; } + /** 被查询的适配器。 */ public PlatformAdapter adapter() { return adapter; } + /** 被查询的账户。 */ public ChannelAccount account() { return account; } + /** 适配器 ID + 店铺 ID + 支持能力,便于日志定位。 */ @Override public String toString() { return "Capabilities[" + adapter.adapterId() + "/" + account.omsStoreId() + "] supported=" + supported; diff --git a/core/src/main/java/common/ecommerce/capability/AfterSaleCapable.java b/core/src/main/java/common/ecommerce/capability/AfterSaleCapable.java index a79c9d7..76d360a 100644 --- a/core/src/main/java/common/ecommerce/capability/AfterSaleCapable.java +++ b/core/src/main/java/common/ecommerce/capability/AfterSaleCapable.java @@ -15,6 +15,10 @@ import common.ecommerce.sdk.ChannelContext; */ public interface AfterSaleCapable extends PlatformAdapter { - /** 分页拉取售后订单;统一模型按商品行展开。 */ + /** + * 分页拉取售后订单;统一模型按商品行展开。 + * + * @return 当前页;{@link Page#nextCursor()} 为 null 表示没有下一页 + */ Page pull(ChannelContext ctx, AfterSaleQuery query); } diff --git a/core/src/main/java/common/ecommerce/capability/AfterSales.java b/core/src/main/java/common/ecommerce/capability/AfterSales.java index 0bff26e..32febf1 100644 --- a/core/src/main/java/common/ecommerce/capability/AfterSales.java +++ b/core/src/main/java/common/ecommerce/capability/AfterSales.java @@ -15,15 +15,24 @@ import common.ecommerce.sdk.ChannelContext; */ public final class AfterSales { + /** 实际执行拉取的适配器。 */ private final PlatformAdapter adapter; + + /** 账户配置,用于按账户细化能力检查。 */ private final ChannelAccount account; + + /** 本次调用上下文(端点、凭据、链路 ID、时钟)。 */ private final ChannelContext ctx; + + /** 调用观察者,默认空实现。 */ private final CallObserver observer; + /** 不记录调用日志的构造方式。 */ public AfterSales(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) { this(adapter, account, ctx, CallObserver.NOOP); } + /** 标准构造;observer 为 null 时退化为空实现。 */ public AfterSales(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx, CallObserver observer) { this.adapter = adapter; @@ -41,6 +50,11 @@ public final class AfterSales { return new AfterSales(adapter, account, ctx.withRequestId(requestId), observer); } + /** + * 拉取一页售后订单(按商品行展开)。 + * + * @throws ChannelException.UnsupportedCapabilityException 未声明 RETURNS 或未实现 AfterSaleCapable + */ public Page pull(final AfterSaleQuery query) { return CallSupport.observe(observer, ctx, "afterSales.pull", CallSupport.params( @@ -58,6 +72,7 @@ public final class AfterSales { }); } + /** 能力双检:账户级能力声明 + 接口实现,缺一即拒绝。 */ private void requireAfterSaleCapable() { if (!adapter.supports(account, Capability.RETURNS) || !(adapter instanceof AfterSaleCapable)) { throw new ChannelException.UnsupportedCapabilityException(Capability.RETURNS); diff --git a/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java b/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java index ae7d5af..efc61a1 100644 --- a/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java +++ b/core/src/main/java/common/ecommerce/capability/AggregatorCapable.java @@ -27,7 +27,6 @@ public interface AggregatorCapable extends PlatformAdapter { /** 聚合器通过子平台的 platform_code 细化能力。 */ @Override boolean supports(ChannelAccount account, Capability capability); - /** * 子店铺信息。 * @@ -38,9 +37,16 @@ public interface AggregatorCapable extends PlatformAdapter { */ final class SubChannel { + /** 聚合器内部平台编码,如领星 platform_code;直连账户引申为 0。 */ private final int platformCode; + + /** 平台店铺 ID / 领星 store_id;不是 OMS 的 storeId。 */ private final String externalStoreId; + + /** 该子店铺对应的业务平台。 */ private final Platform platform; + + /** 店铺显示名。 */ private final String name; /** 平台卖家 ID:领星 SC 的 {@code seller_id}、VC 的 {@code seller_id}。 */ @@ -62,12 +68,18 @@ public interface AggregatorCapable extends PlatformAdapter { /** 平台特有字段。 */ private final java.util.Map attributes; + /** + * 构造只含路由字段的子店铺信息;平台特有字段为 null。 + * + *

需要完整信息时用 {@link #builder()}。

+ */ public SubChannel(int platformCode, String externalStoreId, Platform platform, String name) { this(platformCode, externalStoreId, platform, name, null, null, null, null, null, null, null, null, java.util.Collections.emptyMap()); } + /** 全字段构造;attributes 为 null 会抛 NPE,请用 Builder。 */ private SubChannel(int platformCode, String externalStoreId, Platform platform, String name, String sellerId, String accountName, Integer status, String region, String regionName, String country, @@ -89,145 +101,199 @@ public interface AggregatorCapable extends PlatformAdapter { new java.util.LinkedHashMap(attributes)); } + /** 创建子店铺构建器。 */ public static Builder builder() { return new Builder(); } + /** 聚合器内部平台编码。 */ public int platformCode() { return platformCode; } + /** 平台店铺 ID / 领星 store_id;不是 OMS 的 storeId。 */ public String externalStoreId() { return externalStoreId; } + /** 该子店铺对应的业务平台。 */ public Platform platform() { return platform; } + /** 店铺显示名。 */ public String name() { return name; } + /** 平台卖家 ID,可为 null。 */ public String sellerId() { return sellerId; } + /** 账号名,可为 null。 */ public String accountName() { return accountName; } + /** 店铺授权状态原值,可为 null。 */ public Integer status() { return status; } + /** 站点简称,可为 null。 */ public String region() { return region; } + /** 站点名称,可为 null。 */ public String regionName() { return regionName; } + /** 商城所在国家名称,可为 null。 */ public String country() { return country; } + /** 市场 ID,可为 null。 */ public String marketplaceId() { return marketplaceId; } + /** 站点数字 ID,可为 null。 */ public Integer marketplaceNum() { return marketplaceNum; } + /** 平台特有字段;不可变,缺省为空 Map。 */ public java.util.Map attributes() { return attributes; } + /** 子店铺构建器。 */ public static final class Builder { + /** 聚合器内部平台编码。 */ private int platformCode; + + /** 平台店铺 ID / 领星 store_id。 */ private String externalStoreId; + + /** 该子店铺对应的业务平台。 */ private Platform platform; + + /** 店铺显示名。 */ private String name; + + /** 平台卖家 ID。 */ private String sellerId; + + /** 账号名。 */ private String accountName; + + /** 店铺授权状态原值。 */ private Integer status; + + /** 站点简称。 */ private String region; + + /** 站点名称。 */ private String regionName; + + /** 商城所在国家名称。 */ private String country; + + /** 市场 ID。 */ private String marketplaceId; + + /** 站点数字 ID。 */ private Integer marketplaceNum; + + /** 平台特有字段;null 表示空 Map。 */ private java.util.Map attributes = java.util.Collections.emptyMap(); + /** 设置聚合器内部平台编码。 */ public Builder platformCode(int platformCode) { this.platformCode = platformCode; return this; } + /** 设置平台店铺 ID / 领星 store_id。 */ public Builder externalStoreId(String externalStoreId) { this.externalStoreId = externalStoreId; return this; } + /** 设置该子店铺对应的业务平台。 */ public Builder platform(Platform platform) { this.platform = platform; return this; } + /** 设置店铺显示名。 */ public Builder name(String name) { this.name = name; return this; } + /** 设置平台卖家 ID。 */ public Builder sellerId(String sellerId) { this.sellerId = sellerId; return this; } + /** 设置账号名。 */ public Builder accountName(String accountName) { this.accountName = accountName; return this; } + /** 设置店铺授权状态原值。 */ public Builder status(Integer status) { this.status = status; return this; } + /** 设置站点简称。 */ public Builder region(String region) { this.region = region; return this; } + /** 设置站点名称。 */ public Builder regionName(String regionName) { this.regionName = regionName; return this; } + /** 设置商城所在国家名称。 */ public Builder country(String country) { this.country = country; return this; } + /** 设置市场 ID。 */ public Builder marketplaceId(String marketplaceId) { this.marketplaceId = marketplaceId; return this; } + /** 设置站点数字 ID。 */ public Builder marketplaceNum(Integer marketplaceNum) { this.marketplaceNum = marketplaceNum; return this; } + /** 设置平台特有字段;null 视为空 Map。 */ public Builder attributes(java.util.Map attributes) { this.attributes = attributes == null ? java.util.Collections.emptyMap() : attributes; return this; } + /** 构建子店铺信息;必填字段不做校验,由调用方保证。 */ public SubChannel build() { return new SubChannel(platformCode, externalStoreId, platform, name, sellerId, accountName, status, region, regionName, country, diff --git a/core/src/main/java/common/ecommerce/capability/CapabilityReport.java b/core/src/main/java/common/ecommerce/capability/CapabilityReport.java index 46d212a..e394250 100644 --- a/core/src/main/java/common/ecommerce/capability/CapabilityReport.java +++ b/core/src/main/java/common/ecommerce/capability/CapabilityReport.java @@ -11,9 +11,16 @@ import java.util.EnumSet; */ public interface CapabilityReport { + /** + * 该账户是否支持某能力。 + * + * @param capability 待检查能力,null 返回 false + */ boolean supports(Capability capability); + /** 支持的能力集合(副本,调用方可安全修改)。 */ EnumSet supported(); + /** 不支持的能力集合(副本),即 {@link Capability} 全集的差集。 */ EnumSet unsupported(); } diff --git a/core/src/main/java/common/ecommerce/capability/OrderEditCapable.java b/core/src/main/java/common/ecommerce/capability/OrderEditCapable.java index 9ce7c53..0740a86 100644 --- a/core/src/main/java/common/ecommerce/capability/OrderEditCapable.java +++ b/core/src/main/java/common/ecommerce/capability/OrderEditCapable.java @@ -18,6 +18,10 @@ import java.util.List; */ public interface OrderEditCapable extends PlatformAdapter { - /** 批量编辑订单;平台按单返回失败原因。 */ + /** + * 批量编辑订单;平台按单返回失败原因。 + * + * @return 逐单结果;全部失败时由门面转成 PlatformBusinessException + */ OrderEditResult edit(ChannelContext ctx, List requests); } diff --git a/core/src/main/java/common/ecommerce/capability/OutboundCapable.java b/core/src/main/java/common/ecommerce/capability/OutboundCapable.java index d122df5..eca0a30 100644 --- a/core/src/main/java/common/ecommerce/capability/OutboundCapable.java +++ b/core/src/main/java/common/ecommerce/capability/OutboundCapable.java @@ -17,9 +17,17 @@ import java.util.List; */ public interface OutboundCapable extends PlatformAdapter { - /** 提交出库任务;返回是否受理。 */ + /** + * 提交出库任务;返回是否受理。 + * + *

返回 true 不代表出库成功,只代表平台已接收任务;结果用 {@link #results} 回查。

+ */ boolean submit(ChannelContext ctx, List packages); - /** 按系统单号查询出库结果。 */ + /** + * 按系统单号查询出库结果。 + * + * @return 每个系统单号的当前状态;平台未返回的单号不出现在结果中 + */ OutboundResult results(ChannelContext ctx, List globalOrderNos); } diff --git a/core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java b/core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java index c8ac327..bc2b3e1 100644 --- a/core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java +++ b/core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java @@ -13,6 +13,10 @@ import common.ecommerce.sdk.ChannelContext; */ public interface OutboundOrderCapable extends PlatformAdapter { - /** 分页拉取销售出库单。 */ + /** + * 分页拉取销售出库单。 + * + * @return 当前页;{@link Page#nextCursor()} 为 null 表示没有下一页 + */ Page pull(ChannelContext ctx, OutboundOrderQuery query); } diff --git a/core/src/main/java/common/ecommerce/capability/Outbounds.java b/core/src/main/java/common/ecommerce/capability/Outbounds.java index 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 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);