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 b29c6f8..21c177d 100644 --- a/core/src/main/java/common/ecommerce/model/Platform.java +++ b/core/src/main/java/common/ecommerce/model/Platform.java @@ -24,8 +24,6 @@ public enum Platform { EBAY, /** SHEIN(首期经领星接入) */ SHEIN, - /** Shopify(领星 platform_code 10002)。 */ - SHOPIFY, /** AliExpress(首期经领星接入) */ ALIEXPRESS, /** Mirakl 市场 */ @@ -33,19 +31,23 @@ public enum Platform { /** * Target。 * - *

领星侧没有独立的 Target 商品接口,商品走 Shopify 的 - * {@code /basicOpen/multiplatform/shopify/variantList}。

+ *

领星侧没有独立的 Target 商品接口,商品走 + * {@code /basicOpen/multiplatform/shopify/variantList}(路径名是领星的历史命名)。

*/ TARGET, /** BestBuy。实测在领星 10034(Mirakl)下以 BSB-* 店铺出现。 */ 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 206027b..c414946 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -122,6 +122,7 @@ public final class ChannelSdk implements ProviderResolver { IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS, callObserver); } + /** 创建门面构建器。 */ public static Builder builder() { return new Builder(); } @@ -148,6 +149,7 @@ public final class ChannelSdk implements ProviderResolver { () -> capabilitiesOf(key)); } + /** 能力矩阵的实际实现:账户与适配器都齐了才构造报告。 */ private CapabilityReport capabilitiesOf(AccountKey key) { ChannelAccount account = requireAccount(key); return new AdapterCapabilityReport(resolve(key), account); @@ -267,6 +269,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)"; @@ -372,7 +375,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); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java index 5fae28d..ff1ba5e 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java @@ -51,7 +51,8 @@ public enum LingxingApi { LISTING_TEMU("/basicOpen/multiplatform/temu/list", 1), /** - * 在线商品(变体维度),Shopify(10002)与 Target 共用此接口。 + * 在线商品(变体维度),Target 使用此接口; + * 路径里的 shopify 是领星的历史命名,与业务平台无关。 * POST,offset/length(上限 1000),返回 data.list。 */ LISTING_SHOPIFY("/basicOpen/multiplatform/shopify/variantList", 1), diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java index 0fea109..5c3420f 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java @@ -82,8 +82,7 @@ public final class LingxingConstants { * * * - * - * + * * * * @@ -105,7 +104,7 @@ public final class LingxingConstants { *

Target / BestBuy / AEPH / Michaels / ECHO / LOS-DLI-US 在领星侧没有独立平台码 * (多为自定义平台或共用 Mirakl)。业务平台以账户的 {@code AccountKey.platform} 为准, * 本方法只用于从响应行反推。Target 没有独立的领星商品接口, - * 它的商品走 Shopify 的 {@code /basicOpen/multiplatform/shopify/variantList}。

+ * 它的商品走 {@code /basicOpen/multiplatform/shopify/variantList}(领星的历史路径命名)。

*/ public static Platform toPlatform(Integer platformCode) { if (platformCode == null) { @@ -115,7 +114,8 @@ public final class LingxingConstants { case 10001: return Platform.AMAZON_SC; case 10002: - return Platform.SHOPIFY; + // 领星侧 10002 的店铺(SPF-*)在统一模型里暂无对应平台 + return Platform.CUSTOM; case 10003: return Platform.EBAY; case 10005: diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java index e801fe6..8e31060 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java @@ -169,7 +169,7 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @Override public Set platforms() { return EnumSet.of(Platform.AMAZON_SC, Platform.AMAZON_VC, Platform.WALMART_SC, Platform.TIKTOK, - Platform.TEMU, Platform.EBAY, Platform.SHEIN, Platform.SHOPIFY, + Platform.TEMU, Platform.EBAY, Platform.SHEIN, Platform.ALIEXPRESS, Platform.MIRAKL, Platform.WAYFAIR, Platform.TARGET, Platform.BESTBUY, Platform.AEPH, Platform.MICHAELS, Platform.ECHO, Platform.LOSDLIUS, diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatformDefaults.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatformDefaults.java index b1a0dae..07e9b1a 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatformDefaults.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatformDefaults.java @@ -14,7 +14,6 @@ import common.ecommerce.lingxing.platform.losdlius.LosDliUsSubPlatform; import common.ecommerce.lingxing.platform.michaels.MichaelsSubPlatform; import common.ecommerce.lingxing.platform.mirakl.MiraklSubPlatform; import common.ecommerce.lingxing.platform.shein.SheinSubPlatform; -import common.ecommerce.lingxing.platform.shopify.ShopifySubPlatform; import common.ecommerce.lingxing.platform.target.TargetSubPlatform; import common.ecommerce.lingxing.platform.temu.TemuSubPlatform; import common.ecommerce.lingxing.platform.tiktok.TiktokSubPlatform; @@ -40,7 +39,6 @@ public final class LingxingSubPlatformDefaults { .register(new WalmartSubPlatform(transport, json)) .register(new TemuSubPlatform(transport, json)) .register(new SheinSubPlatform(transport, json)) - .register(new ShopifySubPlatform(transport, json)) .register(new EbaySubPlatform(transport, json)) .register(new AliexpressSubPlatform(transport, json)) .register(new TiktokSubPlatform(transport, json)) diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java index c240ad0..98a6b0e 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java @@ -217,7 +217,7 @@ public final class EbayProductSource implements LingxingProductSource { return trimmed.isEmpty() ? null : trimmed; } - /** 统一 SKU 搜索 → ebay 的字段形态;未带搜索条件时什么也不做。 */ + /** 统一 SKU 搜索 → eBay 的字段形态;未带搜索条件时什么也不做。 */ private static void applySearch(java.util.Map body, ProductQuery query) { if (query == null || !query.hasSearch()) { @@ -225,11 +225,12 @@ public final class EbayProductSource implements LingxingProductSource { } try { Object fieldValue = LingxingProductSearchMapper.ebay(query.searchField()); - LingxingProductSearchBody.camelCase(body, query, fieldValue); + // 实测:camelCase 的 searchField 会被静默忽略并返回整页,必须用 snake_case; + // 多值 search_values 被忽略,只支持单值。 + LingxingProductSearchBody.snakeCaseSingle(body, query, fieldValue); } catch (UnsupportedOperationException e) { ChannelException.Builder b = ChannelException.builder() - .message("ebay listing does not support search field " - + query.searchField()) + .message("ebay listing does not support " + e.getMessage()) .operation("products.pull") .retryable(false); throw new ValidationException(b); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java index 617b877..cc349a7 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java @@ -7,11 +7,15 @@ import java.util.List; /** * 把统一的 SKU 搜索条件拼进领星请求体。 * - *

各平台字段名与形态不同:

+ *

字段名按实测区分(2026-11,见 {@code ListingParamProbeTest}):

*
    - *
  • 沃尔玛 / eBay / Temu / SHEIN / TikTok / AliExpress:{@code searchField}(数字) - * + {@code searchSingleValue}(单值模糊)+ {@code searchValues}(多值精确)
  • - *
  • Shopify / Target:{@code search_field} + {@code search_single_value} + {@code search_values}
  • + *
  • Temu / SHEIN / TikTok / AliExpress:{@code searchField}(数字) + * + {@code searchSingleValue}(单值)+ {@code searchValues}(多值,均支持)
  • + *
  • 沃尔玛 / eBay:{@code search_field} + {@code search_single_value}(snake_case)。 + * 写成 camelCase 不会报错,但搜索条件被静默忽略、返回整页; + * 多值 {@code search_values} 同样被忽略或报 400,因此只支持单值。
  • + *
  • Target(走领星 shopify 路径):{@code search_field} + {@code search_single_value}; + * 多值 {@code search_values} 返回 400,只支持单值。
  • *
  • 亚马逊 SC:{@code search_field}(字符串)+ {@code search_value}(数组)+ {@code exact_search}
  • *
*/ @@ -23,7 +27,7 @@ public final class LingxingProductSearchBody { /** * camelCase 形态:searchField / searchSingleValue / searchValues。 * - *

用于 Temu、SHEIN、TikTok、AliExpress、沃尔玛、eBay。

+ *

用于 Temu、SHEIN、TikTok、AliExpress(单值与多值均实测生效)。

*/ public static void camelCase(java.util.Map body, ProductQuery query, Object fieldValue) { if (query == null || !query.hasSearch()) { @@ -34,16 +38,23 @@ public final class LingxingProductSearchBody { } /** - * snake_case 形态:search_field / search_single_value / search_values。 + * snake_case 单值形态:search_field / search_single_value。 * - *

用于 Shopify、Target。

+ *

用于沃尔玛、eBay、Target:参数名必须是 snake_case,且只支持单值。 + * 传多值时抛 {@link UnsupportedOperationException},由各 Source 翻译成 + * {@code ValidationException},避免静默返回整页。

*/ - public static void snakeCase(java.util.Map body, ProductQuery query, Object fieldValue) { + public static void snakeCaseSingle(java.util.Map body, ProductQuery query, + Object fieldValue) { if (query == null || !query.hasSearch()) { return; } + if (!query.searchValues().isEmpty()) { + throw new UnsupportedOperationException( + "multi-value search is not supported by this listing API"); + } body.put("search_field", fieldValue); - applyValue(body, query, "search_single_value", "search_values"); + body.put("search_single_value", query.searchValue()); } /** diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchMapper.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchMapper.java index 7b74522..830dda9 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchMapper.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchMapper.java @@ -5,22 +5,23 @@ import common.ecommerce.model.product.ProductSearchField; /** * 领星侧各平台的「搜索维度 → 平台枚举值」映射。 * - *

同一个语义在不同平台下的取值完全不同:

+ *

同一个语义在不同平台下的取值完全不同(2026-11 全部实测, + * 方法见 {@code ListingParamProbeTest}:用真实 msku 回查 + 用不存在的值做对照):

*
- *              平台 SKU        本地 SKU
- * 沃尔玛         1               3
- * eBay           1               3
- * AliExpress     1               5      ← 实测:文档写 3,但 3 查不到
- * Temu           9               8
- * SHEIN          9               8
- * TikTok         9               8
- * Shopify/Target 1               待核对(样本 local_sku 为空)
- * 亚马逊 SC      "seller_sku"    "sku"   ← 字符串,不是数字
+ *              平台 SKU        本地 SKU      参数名
+ * 沃尔玛         1               3           snake_case,多值不支持
+ * eBay           1               3           snake_case,多值不支持
+ * AliExpress     1               5           camelCase,多值支持
+ * Temu           9               8           camelCase,多值支持
+ * SHEIN          9               8           camelCase,多值支持
+ * TikTok         9               8           camelCase,多值支持
+ * Target         1(=msku)      不支持      snake_case,多值不支持
+ * 亚马逊 SC      "seller_sku"    "sku"       字符串,不是数字
  * 亚马逊 VC      不支持搜索
  * 
* - *

取值来源:领星文档(2026-10 摘录)+ AliExpress 实测(2026-11)。 - * 未实测的平台按文档写,联调时用 {@code SearchFieldProbeTest} 逐个核对。

+ *

注意:沃尔玛 / eBay 用 camelCase 时平台不报错但静默忽略搜索条件, + * 所以参数名必须与上表一致,见 {@link LingxingProductSearchBody}。

* *

用「按平台命名的方法」而不是「按 platform_code 查表」:每个 Source 只服务一个平台, * 直接调自己那一个方法即可;AliExpress 的 platform_code 尚未确认,也不影响调用。 @@ -62,16 +63,16 @@ public final class LingxingProductSearchMapper { } /** - * Shopify / Target:1 = msku。 + * Target:1 = msku(实测)。 * - *

本地 SKU 的编码文档未给出,实测样本 {@code local_sku} 也为空, - * 暂时返回 null 表示不支持;联调时用探针确认后再补。

+ *

该 app 下 {@code local_sku} 恒为空(翻 200 行全空),没有可对应的本地 SKU 编码, + * 因此对 {@link ProductSearchField#LOCAL_SKU} 显式抛异常,不静默退化为平台 SKU 查询。

*/ - public static Object shopify(ProductSearchField field) { + public static Object target(ProductSearchField field) { if (field == ProductSearchField.PLATFORM_SKU) { return 1; } - throw new UnsupportedOperationException("shopify/target listing does not support local sku search yet"); + throw new UnsupportedOperationException("local sku search"); } /** 亚马逊 SC:字符串 "seller_sku" / "sku"。 */ diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/ShopifySubPlatform.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/ShopifySubPlatform.java deleted file mode 100644 index 93a0cc0..0000000 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/ShopifySubPlatform.java +++ /dev/null @@ -1,58 +0,0 @@ -package common.ecommerce.lingxing.platform.shopify; - -import common.ecommerce.http.HttpTransport; -import common.ecommerce.http.JacksonJsonCodec; -import common.ecommerce.lingxing.platform.LingxingSubPlatform; -import common.ecommerce.lingxing.platform.LingxingOrderSource; -import common.ecommerce.lingxing.platform.LingxingProductSource; -import common.ecommerce.lingxing.platform.LingxingShopSource; -import common.ecommerce.lingxing.platform.multiplatform.order.MultiPlatformOrderSource; -import common.ecommerce.lingxing.platform.multiplatform.outbound.MultiPlatformOutboundSource; -import common.ecommerce.lingxing.platform.multiplatform.shop.MultiPlatformShopSource; -import common.ecommerce.lingxing.platform.LingxingOutboundSource; -import common.ecommerce.lingxing.platform.shopify.product.ShopifyProductSource; -import common.ecommerce.model.Platform; - -/** - * 领星 · Shopify 子平台:只做能力组合。 - */ -public final class ShopifySubPlatform implements LingxingSubPlatform { - - /** 快速出库是多平台通用接口,各子平台共用。 */ - private static final MultiPlatformOutboundSource OUTBOUND = new MultiPlatformOutboundSource(); - - private final LingxingOrderSource orders; - private final LingxingProductSource products; - private final LingxingShopSource shops; - - public ShopifySubPlatform(HttpTransport transport, JacksonJsonCodec json) { - this.orders = new MultiPlatformOrderSource(transport, json); - this.products = new ShopifyProductSource(); - this.shops = new MultiPlatformShopSource(Platform.SHOPIFY); - } - - @Override - public Platform platform() { - return Platform.SHOPIFY; - } - - @Override - public LingxingOrderSource orderSource() { - return orders; - } - - @Override - public LingxingProductSource productSource() { - return products; - } - - @Override - public LingxingShopSource shopSource() { - return shops; - } - - @Override - public LingxingOutboundSource outboundSource() { - return OUTBOUND; - } -} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyListingDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyListingDto.java deleted file mode 100644 index d1db7e4..0000000 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyListingDto.java +++ /dev/null @@ -1,166 +0,0 @@ -package common.ecommerce.lingxing.platform.shopify.dto; - -import com.fasterxml.jackson.annotation.JsonIgnoreProperties; -import com.fasterxml.jackson.annotation.JsonProperty; -import lombok.Getter; -import lombok.Setter; - -import java.util.ArrayList; -import java.util.List; - -/** - * 领星 · Shopify 在线商品({@code /basicOpen/multiplatform/shopify/variantList} 的 {@code data.list[]})。 - * - *

文档字段是 snake_case;这里用 camelCase 的 Java 字段 + {@code @JsonProperty} 映射。

- * - *

Shopify 按变体(variant)返回,{@code msku} 是平台侧 SKU。

- */ -@Getter -@Setter -@JsonIgnoreProperties(ignoreUnknown = true) -public class ShopifyListingDto { - - /** 商品 ID。 */ - @JsonProperty("item_id") - private String itemId; - - /** 商品链接。 */ - @JsonProperty("item_url") - private String itemUrl; - - /** 产品 uid。 */ - @JsonProperty("product_unique_id") - private String productUniqueId; - - /** 子体 uid。 */ - @JsonProperty("variant_unique_id") - private String variantUniqueId; - - /** 企业 ID。 */ - @JsonProperty("company_id") - private String companyId; - - /** 父图链接。 */ - @JsonProperty("parent_picture_url") - private String parentPictureUrl; - - /** 图片链接。 */ - @JsonProperty("picture_url") - private String pictureUrl; - - /** 父 MSKU。 */ - @JsonProperty("parent_msku") - private String parentMsku; - - /** 平台侧 MSKU,参与 canonicalKey。 */ - @JsonProperty("msku") - private String msku; - - /** 母体属性,如 Size/Color。 */ - @JsonProperty("parent_attribute") - private String parentAttribute; - - /** 变体属性,如 42 / red。 */ - @JsonProperty("attribute") - private String attribute; - - /** 标题。 */ - @JsonProperty("title") - private String title; - - /** 本地 SKU。 */ - @JsonProperty("local_sku") - private String localSku; - - /** 本地商品 id。 */ - @JsonProperty("pid") - private String pid; - - /** 本地品名。 */ - @JsonProperty("local_name") - private String localName; - - /** 店铺 id。 */ - @JsonProperty("store_id") - private String storeId; - - /** 店铺名称。 */ - @JsonProperty("store_name") - private String storeName; - - /** 售价。 */ - @JsonProperty("price") - private String price; - - /** 库存。 */ - @JsonProperty("quantity") - private String quantity; - - /** 货币符号,如 ¥。 */ - @JsonProperty("currency_icon") - private String currencyIcon; - - /** 是否有子体。 */ - @JsonProperty("has_variant") - private Boolean hasVariant; - - /** 开始时间,Y-m-d H:i:s。 */ - @JsonProperty("listing_start_time") - private String listingStartTime; - - /** 结束时间,Y-m-d H:i:s。 */ - @JsonProperty("listing_end_time") - private String listingEndTime; - - /** 商品状态:1 active,2 draft,3 archived,4 deleted。 */ - @JsonProperty("status") - private Integer status; - - /** 商品状态名。 */ - @JsonProperty("status_name") - private String statusName; - - /** 库存策略:1 不跟踪,2 缺货停止销售,3 缺货继续销售。 */ - @JsonProperty("inventory_policy") - private Integer inventoryPolicy; - - /** 库存策略名。 */ - @JsonProperty("inventory_policy_name") - private String inventoryPolicyName; - - /** 商品分类 ID。 */ - @JsonProperty("type_id") - private String typeId; - - /** 商品分类名。 */ - @JsonProperty("type_name") - private String typeName; - - /** 是否需要运输。 */ - @JsonProperty("requires_shipping") - private Boolean requiresShipping; - - /** 是否要征税。 */ - @JsonProperty("taxable") - private Boolean taxable; - - /** 最小重量。 */ - @JsonProperty("min_weight") - private Integer minWeight; - - /** 最大重量。 */ - @JsonProperty("max_weight") - private Integer maxWeight; - - /** 重量单位。 */ - @JsonProperty("weight_unit") - private String weightUnit; - - /** 重量。 */ - @JsonProperty("weight") - private String weight; - - /** 各仓位信息。 */ - @JsonProperty("location_infos") - private List locationInfos = new ArrayList(); -} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyLocationDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyLocationDto.java deleted file mode 100644 index b94f00c..0000000 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyLocationDto.java +++ /dev/null @@ -1,49 +0,0 @@ -package common.ecommerce.lingxing.platform.shopify.dto; - -import com.fasterxml.jackson.annotation.JsonIgnoreProperties; -import com.fasterxml.jackson.annotation.JsonProperty; -import lombok.Getter; -import lombok.Setter; - -/** Shopify 商品仓位信息({@code location_infos[]})。 */ -@Getter -@Setter -@JsonIgnoreProperties(ignoreUnknown = true) -public class ShopifyLocationDto { - - /** 仓位 id。 */ - @JsonProperty("location_id") - private String locationId; - - /** 仓位名称。 */ - @JsonProperty("location_name") - private String locationName; - - /** 该仓位库存。 */ - @JsonProperty("location_quantity") - private String locationQuantity; - - /** 库存调整后的值。 */ - @JsonProperty("quantity_adjust_after") - private String quantityAdjustAfter; - - /** 库存调整前的值。 */ - @JsonProperty("quantity_adjust_before") - private String quantityAdjustBefore; - - /** 库存调整操作人 id。 */ - @JsonProperty("quantity_user_id") - private String quantityUserId; - - /** 库存调整操作人名字。 */ - @JsonProperty("quantity_user_id_name") - private String quantityUserIdName; - - /** 库存队列类型。 */ - @JsonProperty("quantity_queue_type") - private Integer quantityQueueType; - - /** 库存队列状态。 */ - @JsonProperty("quantity_queue_status") - private String quantityQueueStatus; -} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/product/ShopifyProductSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/product/ShopifyProductSource.java deleted file mode 100644 index 745c443..0000000 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/product/ShopifyProductSource.java +++ /dev/null @@ -1,272 +0,0 @@ -package common.ecommerce.lingxing.platform.shopify.product; - -import common.ecommerce.http.HttpRequest; -import common.ecommerce.http.HttpResponse; -import common.ecommerce.lingxing.LingxingApi; -import common.ecommerce.lingxing.http.LingxingEnvelope; -import common.ecommerce.lingxing.platform.LingxingCall; -import common.ecommerce.lingxing.platform.LingxingProductSource; -import common.ecommerce.lingxing.platform.shopify.dto.ShopifyListingDto; -import common.ecommerce.model.ChannelProvider; -import common.ecommerce.model.product.ProductListing; -import common.ecommerce.model.product.ProductQuery; -import common.ecommerce.model.product.ProductStatus; -import common.ecommerce.model.support.Money; -import common.ecommerce.model.support.Page; -import common.ecommerce.model.support.PlatformTime; - -import java.time.Instant; -import java.time.LocalDateTime; -import java.time.ZoneId; -import java.time.format.DateTimeFormatter; -import java.util.ArrayList; -import java.util.Collections; -import java.util.LinkedHashMap; -import java.util.List; -import java.util.Locale; -import java.util.Map; - -/** - * 领星 · Shopify 在线商品(变体维度)。 - * - *

接口 {@code /basicOpen/multiplatform/shopify/variantList}:POST,{@code offset}/{@code length} - * (上限 1000),返回 {@code data.list};令牌桶容量 1。

- */ -public final class ShopifyProductSource implements LingxingProductSource { - - private static final int MAX_PAGE_SIZE = 1000; - - /** 时间字段格式,文档未给出示例值格式,按 Y-m-d H:i:s 发送。 */ - private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); - @Override - public Page products(LingxingCall call, ProductQuery query) { - int length = Math.min(query.pageSize() <= 0 ? 100 : query.pageSize(), MAX_PAGE_SIZE); - int offset = query.cursor() == null ? 0 : Integer.parseInt(query.cursor()); - - Map body = new LinkedHashMap(); - body.put("offset", offset); - body.put("length", length); - body.put("store_ids", Collections.singletonList(call.ctx().account().externalStoreId())); - applyTimeWindow(body, query); - - HttpRequest req = call.signed(LingxingApi.LISTING_SHOPIFY, body, "products.pull"); - HttpResponse resp = call.execute(req); - LingxingEnvelope envelope = call.envelope(resp, "products.pull"); - - List dtos = call.json().listAt(envelope.body(), "data.list", ShopifyListingDto.class); - List out = new ArrayList(dtos.size()); - for (ShopifyListingDto dto : dtos) { - out.add(toProductListing(dto, call)); - } - - int total = totalOf(call, envelope.body()); - int nextOffset = offset + dtos.size(); - boolean hasMore = dtos.size() >= length && (total < 0 || nextOffset < total); - return Page.of(out, hasMore ? String.valueOf(nextOffset) : null); - } - - /** 时间窗:按 UTC 发送,未给终点时不发终点。 */ - private static void applyTimeWindow(Map body, ProductQuery query) { - Instant from = query.updatedAfter(); - Instant to = query.updatedBefore(); - if (from == null && to == null) { - return; - } - ZoneId utc = ZoneId.of("UTC"); - if (from != null) { - body.put("listing_start_time", DATE_TIME.format(from.atZone(utc))); - } - if (to != null) { - body.put("listing_end_time", DATE_TIME.format(to.atZone(utc))); - } - } - - /** 总数取 data.count;没有时用顶层 total;都没有返回 -1。 */ - private static int totalOf(LingxingCall call, String body) { - String raw = call.json().stringAt(body, "data.count"); - if (raw == null) { - raw = call.json().stringAt(body, "total"); - } - if (raw == null) { - return -1; - } - try { - return Integer.parseInt(raw.trim()); - } catch (NumberFormatException e) { - return -1; - } - } - - /** - * 领星 Shopify 商品 → 统一模型。 - * - *

统一字段来源:

- *
    - *
  • platformSku ← {@code msku}
  • - *
  • listingId ← {@code product_unique_id}
  • - *
  • gtin ← 无
  • - *
  • title ← {@code title}
  • - *
  • imageUrls ← {@code picture_url},为空时用 {@code parent_picture_url}
  • - *
  • status ← {@code status}(1 active / 2 draft / 3 archived / 4 deleted)
  • - *
  • rawStatus ← {@code status_name} 原值
  • - *
  • price ← {@code price};currency 由 {@code currency_icon} 反推
  • - *
  • listedAt ← {@code listing_start_time}
  • - *
  • updatedAt ← 无(接口没有内容更新时间)
  • - *
  • attributes ← 其余全部原始字段
  • - *
- */ - private ProductListing toProductListing(ShopifyListingDto dto, LingxingCall call) { - ZoneId zone = ZoneId.of(call.ctx().account().marketplaceZone()); - String currency = currencyOf(dto.getCurrencyIcon()); - String image = firstNonBlank(dto.getPictureUrl(), dto.getParentPictureUrl()); - - return ProductListing.builder() - .platform(call.ctx().platform()) - .omsStoreId(call.ctx().omsStoreId()) - .platformSku(dto.getMsku()) - .listingId(trimToNull(dto.getProductUniqueId())) - .title(dto.getTitle()) - .imageUrls(image == null - ? Collections.emptyList() - : Collections.singletonList(image)) - .status(statusOf(dto)) - .rawStatus(dto.getStatusName()) - .price(moneyOrNull(dto.getPrice(), currency)) - .currency(currency) - .listedAt(dateTime(dto.getListingStartTime(), zone)) - .attributes(attributesOf(dto)) - .sourceProvider(ChannelProvider.LINGXING) - .build(); - } - - /** Shopify:1 active / 2 draft / 3 archived / 4 deleted。 */ - private static ProductStatus statusOf(ShopifyListingDto dto) { - if (dto.getStatus() == null) { - String name = dto.getStatusName(); - if (name != null) { - String s = name.trim().toUpperCase(Locale.ROOT); - if ("ACTIVE".equals(s)) { - return ProductStatus.ACTIVE; - } - if ("DELETED".equals(s)) { - return ProductStatus.DELETED; - } - if ("DRAFT".equals(s) || "ARCHIVED".equals(s)) { - return ProductStatus.INACTIVE; - } - } - return ProductStatus.UNKNOWN; - } - switch (dto.getStatus()) { - case 1: - return ProductStatus.ACTIVE; - case 2: - case 3: - return ProductStatus.INACTIVE; - case 4: - return ProductStatus.DELETED; - default: - return ProductStatus.UNKNOWN; - } - } - - private static Map attributesOf(ShopifyListingDto dto) { - Map attrs = new LinkedHashMap(); - attrs.put("item_id", dto.getItemId()); - attrs.put("item_url", dto.getItemUrl()); - attrs.put("variant_unique_id", dto.getVariantUniqueId()); - attrs.put("company_id", dto.getCompanyId()); - attrs.put("parent_picture_url", dto.getParentPictureUrl()); - attrs.put("parent_msku", dto.getParentMsku()); - attrs.put("parent_attribute", dto.getParentAttribute()); - attrs.put("attribute", dto.getAttribute()); - attrs.put("local_sku", dto.getLocalSku()); - attrs.put("pid", dto.getPid()); - attrs.put("local_name", dto.getLocalName()); - attrs.put("store_id", dto.getStoreId()); - attrs.put("store_name", dto.getStoreName()); - attrs.put("quantity", dto.getQuantity()); - attrs.put("currency_icon", dto.getCurrencyIcon()); - attrs.put("has_variant", dto.getHasVariant()); - attrs.put("listing_end_time", dto.getListingEndTime()); - attrs.put("inventory_policy", dto.getInventoryPolicy()); - attrs.put("inventory_policy_name", dto.getInventoryPolicyName()); - attrs.put("type_id", dto.getTypeId()); - attrs.put("type_name", dto.getTypeName()); - attrs.put("requires_shipping", dto.getRequiresShipping()); - attrs.put("taxable", dto.getTaxable()); - attrs.put("min_weight", dto.getMinWeight()); - attrs.put("max_weight", dto.getMaxWeight()); - attrs.put("weight", dto.getWeight()); - attrs.put("weight_unit", dto.getWeightUnit()); - attrs.put("location_infos", dto.getLocationInfos()); - attrs.values().removeAll(Collections.singleton(null)); - return attrs; - } - - /** 货币符号 → ISO;约定 ¥ 符号视为日元,人民币以 ISO 代码 CNY 返回。 */ - private static String currencyOf(String icon) { - if (icon == null) { - return null; - } - String s = icon.trim(); - if ("$".equals(s) || "US$".equals(s)) { - return "USD"; - } - if ("€".equals(s)) { - return "EUR"; - } - if ("£".equals(s)) { - return "GBP"; - } - if ("¥".equals(s) || "¥".equals(s)) { - // 约定:¥ 符号按日元处理;人民币由平台以 ISO 代码 CNY 返回 - return "JPY"; - } - if ("CNY".equalsIgnoreCase(s) || "RMB".equalsIgnoreCase(s)) { - return "CNY"; - } - return null; - } - - private static PlatformTime dateTime(String raw, ZoneId zone) { - if (raw == null || raw.trim().isEmpty()) { - return null; - } - try { - Instant utc = LocalDateTime.parse(raw.trim(), DATE_TIME).atZone(zone).toInstant(); - return PlatformTime.of(utc, zone); - } catch (RuntimeException e) { - return null; - } - } - - private static Money moneyOrNull(String value, String currency) { - if (value == null || value.trim().isEmpty() || currency == null) { - return null; - } - try { - return Money.of(value.trim(), currency); - } catch (RuntimeException e) { - return null; - } - } - - private static String firstNonBlank(String... values) { - for (String v : values) { - String trimmed = trimToNull(v); - if (trimmed != null) { - return trimmed; - } - } - return null; - } - - private static String trimToNull(String v) { - if (v == null) { - return null; - } - String trimmed = v.trim(); - return trimmed.isEmpty() ? null : trimmed; - } -} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/TargetSubPlatform.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/TargetSubPlatform.java index 45db669..103cbf2 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/TargetSubPlatform.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/TargetSubPlatform.java @@ -10,7 +10,7 @@ import common.ecommerce.lingxing.platform.LingxingSubPlatform; import common.ecommerce.lingxing.platform.multiplatform.order.MultiPlatformOrderSource; import common.ecommerce.lingxing.platform.multiplatform.outbound.MultiPlatformOutboundSource; import common.ecommerce.lingxing.platform.multiplatform.shop.MultiPlatformShopSource; -import common.ecommerce.lingxing.platform.shopify.product.ShopifyProductSource; +import common.ecommerce.lingxing.platform.target.product.TargetProductSource; import common.ecommerce.model.Platform; /** @@ -19,9 +19,9 @@ import common.ecommerce.model.Platform; *

领星文档没有给出 Target 的独立 platform_code(多见于自定义平台或 Mirakl)。 * 订单与店铺都按账户的 platform_code 查询多平台接口,不按平台码反推。

* - *

Target 没有独立的商品接口,商品走 Shopify 的 - * {@code /basicOpen/multiplatform/shopify/variantList},因此复用 - * {@link ShopifyProductSource}。

+ *

Target 没有独立的商品接口,商品走领星的 + * {@code /basicOpen/multiplatform/shopify/variantList}(路径名是领星的历史命名, + * 与业务平台无关),由 {@link TargetProductSource} 实现。

*/ public final class TargetSubPlatform implements LingxingSubPlatform { @@ -34,7 +34,7 @@ public final class TargetSubPlatform implements LingxingSubPlatform { public TargetSubPlatform(HttpTransport transport, JacksonJsonCodec json) { this.orders = new MultiPlatformOrderSource(transport, json); - this.products = new ShopifyProductSource(); + this.products = new TargetProductSource(); this.shops = new MultiPlatformShopSource(Platform.TARGET); } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java index ab4986f..521a6e2 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java @@ -39,13 +39,34 @@ import java.util.Map; * *

{@code store_ids} 是非必填项:文档未标必填,不传时返回该 app 下所有店铺的商品。 * 这里按账户的 {@code externalStoreId} 过滤,避免把其它店铺的商品混进同一个 omsStoreId。

+ * + *

时间窗(实测):{@code listing_time_field} + {@code listing_start_time} + + * {@code listing_end_time} 必须三者同时填或同时不填;日期精度 {@code Y-m-d}, + * 不支持 {@code HH:mm:ss} 与 epoch;单边窗口返回 400。实测窗口跨度 1 年内均可用。

+ * + *

搜索(实测):{@code search_field=1} 对应 {@code msku}, + * {@code search_field=2} 对应 {@code item_id},{@code search_field=4} 对应标题(模糊); + * 多值 {@code search_values} 返回 400,只支持单值。该 app 下 {@code local_sku} 恒为空, + * 本地 SKU 搜索无编码可用,显式不支持。

*/ public final class TargetProductSource implements LingxingProductSource { private static final int MAX_PAGE_SIZE = 1000; - /** 时间字段格式,文档未给出示例值格式,按 Y-m-d H:i:s 发送。 */ + /** + * 时间字段取值:1 创建时间、2 更新时间。用 2 才符合 + * {@link common.ecommerce.model.product.ProductQuery#updatedAfter()} 的语义。 + */ + private static final int TIME_FIELD_UPDATE = 2; + + /** 时间字段只接受 Y-m-d。 */ + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + + /** 响应里的 listing_start_time / listing_end_time 带时分秒。 */ private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + /** 只给终点时向前补的默认窗口。 */ + private static final int DEFAULT_QUERY_DAYS = 30; @Override public Page products(LingxingCall call, ProductQuery query) { int length = Math.min(query.pageSize() <= 0 ? 100 : query.pageSize(), MAX_PAGE_SIZE); @@ -80,7 +101,10 @@ public final class TargetProductSource implements LingxingProductSource { return Page.of(out, hasMore ? String.valueOf(nextOffset) : null); } - /** 时间窗:按 UTC 发送,未给终点时不发终点。 */ + /** + * 时间窗:三个字段必须同时出现,日期精度 Y-m-d(按 UTC 取日期)。 + * 只传了一边时补齐另一边:起点缺失取终点前 30 天,终点缺失取当前时间。 + */ private static void applyTimeWindow(Map body, ProductQuery query) { Instant from = query.updatedAfter(); Instant to = query.updatedBefore(); @@ -88,12 +112,15 @@ public final class TargetProductSource implements LingxingProductSource { return; } ZoneId utc = ZoneId.of("UTC"); - if (from != null) { - body.put("listing_start_time", DATE_TIME.format(from.atZone(utc))); + if (to == null) { + to = Instant.now(); } - if (to != null) { - body.put("listing_end_time", DATE_TIME.format(to.atZone(utc))); + if (from == null) { + from = to.minus(java.time.Duration.ofDays(DEFAULT_QUERY_DAYS)); } + body.put("listing_time_field", TIME_FIELD_UPDATE); + body.put("listing_start_time", DATE.format(from.atZone(utc).toLocalDate())); + body.put("listing_end_time", DATE.format(to.atZone(utc).toLocalDate())); } /** 总数取 data.count;没有时用顶层 total;都没有返回 -1。 */ @@ -286,18 +313,19 @@ public final class TargetProductSource implements LingxingProductSource { } /** 统一 SKU 搜索 → shopify/target 的字段形态;未带搜索条件时什么也不做。 */ + /** 统一 SKU 搜索 → Target 的字段形态;未带搜索条件时什么也不做。 */ private static void applySearch(java.util.Map body, ProductQuery query) { if (query == null || !query.hasSearch()) { return; } try { - Object fieldValue = LingxingProductSearchMapper.shopify(query.searchField()); - LingxingProductSearchBody.snakeCase(body, query, fieldValue); + Object fieldValue = LingxingProductSearchMapper.target(query.searchField()); + // 实测:多值 search_values 返回 400,只支持单值。 + LingxingProductSearchBody.snakeCaseSingle(body, query, fieldValue); } catch (UnsupportedOperationException e) { ChannelException.Builder b = ChannelException.builder() - .message("shopify/target listing does not support search field " - + query.searchField()) + .message("target listing does not support " + e.getMessage()) .operation("products.pull") .retryable(false); throw new ValidationException(b); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSource.java index 4b784d1..662d793 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSource.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSource.java @@ -34,11 +34,18 @@ import java.util.Map; * (上限 1000)或 {@code cursorId} 游标分页,返回 {@code data.list};令牌桶容量 1。

* *

本实现固定走 offset 分页({@code useCursor=false}),游标以 offset 字符串表示。

+ * + *

时间窗(实测):{@code updateStartTime}/{@code updateEndTime} 均为 + * {@code yyyy-MM-dd HH:mm:ss},跨度不能超过 30 天,超过返回 500;单边填写同样返回 500。 + * 因此这里两端必须同时给出:缺终点取当前时间,缺起点取终点前 30 天。

*/ public final class TemuProductSource implements LingxingProductSource { private static final int MAX_PAGE_SIZE = 1000; + /** 接口要求时间区间不超过 30 天(第 31 天返回 500)。 */ + private static final int MAX_QUERY_DAYS = 30; + /** 更新时间区间格式。 */ private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); @Override @@ -77,7 +84,10 @@ public final class TemuProductSource implements LingxingProductSource { return Page.of(out, hasMore ? String.valueOf(nextOffset) : null); } - /** 时间窗:接口精度到秒,未说明时区,统一按 UTC 发送。 */ + /** + * 时间窗:两端必须同时给。跨度超过 30 天时截断到最近 30 天; + * 只给一端时补齐另一端(终点缺失取当前时间)。 + */ private static void applyTimeWindow(Map body, ProductQuery query) { Instant from = query.updatedAfter(); Instant to = query.updatedBefore(); @@ -85,12 +95,14 @@ public final class TemuProductSource implements LingxingProductSource { return; } ZoneId utc = ZoneId.of("UTC"); - if (from != null) { - body.put("updateStartTime", DATE_TIME.format(from.atZone(utc))); + if (to == null) { + to = Instant.now(); } - if (to != null) { - body.put("updateEndTime", DATE_TIME.format(to.atZone(utc))); + if (from == null || java.time.Duration.between(from, to).toDays() > MAX_QUERY_DAYS) { + from = to.minus(java.time.Duration.ofDays(MAX_QUERY_DAYS)); } + body.put("updateStartTime", DATE_TIME.format(from.atZone(utc))); + body.put("updateEndTime", DATE_TIME.format(to.atZone(utc))); } /** 总数取 data.count;没有时返回 -1。 */ diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java index 15f9168..8de972d 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java @@ -292,7 +292,7 @@ public final class WalmartProductSource implements LingxingProductSource { return trimmed.isEmpty() ? null : trimmed; } - /** 统一 SKU 搜索 → walmart 的字段形态;未带搜索条件时什么也不做。 */ + /** 统一 SKU 搜索 → 沃尔玛的字段形态;未带搜索条件时什么也不做。 */ private static void applySearch(java.util.Map body, ProductQuery query) { if (query == null || !query.hasSearch()) { @@ -300,11 +300,12 @@ public final class WalmartProductSource implements LingxingProductSource { } try { Object fieldValue = LingxingProductSearchMapper.walmart(query.searchField()); - LingxingProductSearchBody.camelCase(body, query, fieldValue); + // 实测:camelCase 的 searchField 会被静默忽略并返回整页,必须用 snake_case; + // 多值 search_values 同样被忽略,只支持单值。 + LingxingProductSearchBody.snakeCaseSingle(body, query, fieldValue); } catch (UnsupportedOperationException e) { ChannelException.Builder b = ChannelException.builder() - .message("walmart listing does not support search field " - + query.searchField()) + .message("walmart listing does not support " + e.getMessage()) .operation("products.pull") .retryable(false); throw new ValidationException(b); diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingSdkListingCallTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingSdkListingCallTest.java new file mode 100644 index 0000000..5c0edae --- /dev/null +++ b/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingSdkListingCallTest.java @@ -0,0 +1,164 @@ +package common.ecommerce.lingxing.adapter; + +import common.ecommerce.audit.CallObserver; +import common.ecommerce.audit.CallOutcome; +import common.ecommerce.audit.CallRecord; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.lingxing.LingxingApi; +import common.ecommerce.lingxing.support.LingxingTestSupport; +import common.ecommerce.model.Platform; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.product.ProductListing; +import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.product.ProductSearchField; +import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.ChannelConnection; +import common.ecommerce.sdk.ChannelSdk; +import common.ecommerce.spi.ChannelSecret; +import common.ecommerce.testkit.InMemoryAccounts; +import common.ecommerce.testkit.InMemoryLockProvider; +import common.ecommerce.testkit.InMemoryTokenStore; +import common.ecommerce.testkit.RecordingTransport; +import common.ecommerce.testkit.Responses; +import org.junit.jupiter.api.Test; + +import java.util.ArrayList; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 从 {@link ChannelSdk} 门面调用领星 listing 的端到端测试。 + * + *

用 {@link RecordingTransport} 替掉网络,走真实的 {@link LingxingAdapter}, + * 验证「门面 → 子平台 → Source」这条链路:能力检查、请求路径、SKU 搜索参数、 + * 统一模型映射和调用日志。

+ */ +class LingxingSdkListingCallTest { + + /** 沃尔玛的商品页;响应里 total 在顶层,data 是数组。 */ + private static final String WALMART_JSON = + "{\"code\":0,\"message\":\"success\",\"total\":1,\"data\":[{" + + "\"item_id\":\"wal-1\",\"msku\":\"WM-MSKU-1\",\"title\":\"Walmart Item\"," + + "\"local_sku\":\"WM-LOCAL-1\",\"status_name\":\"PUBLISHED\"," + + "\"store_id\":\"store-1\",\"currency_icon\":\"$\",\"price\":\"19.99\"}]}"; + + /** Target 的商品页;响应结构是 data.list。 */ + private static final String TARGET_JSON = + "{\"code\":0,\"message\":\"success\",\"data\":{\"count\":1,\"list\":[{" + + "\"product_unique_id\":\"prod-1\",\"msku\":\"TGT-MSKU-1\",\"title\":\"Target Item\"," + + "\"local_sku\":\"\",\"store_id\":\"store-1\",\"price\":\"9.99\"," + + "\"currency_icon\":\"$\",\"status\":1,\"status_name\":\"active\"}]}}"; + + private static final class CollectingObserver implements CallObserver { + + private final List records = new ArrayList(); + + @Override + public void onCall(CallRecord record) { + records.add(record); + } + } + + private static ChannelSdk sdk(RecordingTransport transport, ChannelAccount account, + CallObserver observer) { + LingxingAdapter adapter = new LingxingAdapter( + transport, new JacksonJsonCodec(), + new InMemoryTokenStore(), new InMemoryLockProvider(), + LingxingTestSupport.CLOCK); + return ChannelSdk.builder() + .accountRepository(new InMemoryAccounts().put(account)) + .clock(LingxingTestSupport.CLOCK) + .register(adapter) + .callObserver(observer) + .build(); + } + + private static ChannelConnection connection() { + return ChannelConnection.of(LingxingTestSupport.ENDPOINT, + ChannelSecret.builder() + .appKey(LingxingTestSupport.APP_KEY) + .appSecret(LingxingTestSupport.APP_SECRET) + .build()); + } + + @Test + void pullsWalmartListingThroughFacade() { + RecordingTransport transport = RecordingTransport.create() + .route(LingxingApi.LISTING_WALMART.path(), r -> Responses.ok(WALMART_JSON)); + ChannelAccount account = LingxingTestSupport.account(Platform.WALMART_SC, 10008, "store-1"); + CollectingObserver observer = new CollectingObserver(); + + Page page = sdk(transport, account, observer) + .products(account.key(), connection()) + .pull(ProductQuery.builder() + .pageSize(10) + .searchField(ProductSearchField.PLATFORM_SKU) + .searchValue("WM-MSKU-1") + .build()); + + assertEquals(1, page.size()); + ProductListing p = page.items().get(0); + assertEquals(Platform.WALMART_SC, p.platform()); + assertEquals("WM-MSKU-1", p.platformSku()); + // omsStoreId 是宿主的店铺标识(这里取 AccountKey 的 storeId),不是领星 store_id + assertEquals(account.omsStoreId(), p.omsStoreId()); + assertEquals("PUBLISHED", p.rawStatus()); + + // 实测:搜索参数必须是 snake_case,否则平台静默忽略 + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"search_field\":1"), body); + assertTrue(body.contains("\"search_single_value\":\"WM-MSKU-1\""), body); + assertFalse(body.contains("searchField"), body); + + // 门面审计记录:operation / 平台 / store / 条数 + assertEquals(1, observer.records.size()); + CallRecord record = observer.records.get(0); + assertEquals("products.pull", record.operation()); + assertEquals(CallOutcome.SUCCESS, record.outcome()); + assertEquals(Platform.WALMART_SC, record.platform()); + assertEquals("store-1", record.externalStoreId()); + assertEquals(1, record.resultCount()); + } + + @Test + void pullsTargetListingThroughFacade() { + RecordingTransport transport = RecordingTransport.create() + .route(LingxingApi.LISTING_SHOPIFY.path(), r -> Responses.ok(TARGET_JSON)); + ChannelAccount account = LingxingTestSupport.account(Platform.TARGET, 0, "store-1"); + + Page page = sdk(transport, account, CallObserver.NOOP) + .products(account.key(), connection()) + .pull(ProductQuery.builder() + .pageSize(5) + .updatedAfter(java.time.Instant.parse("2026-10-01T00:00:00Z")) + .updatedBefore(java.time.Instant.parse("2026-10-08T00:00:00Z")) + .build()); + + assertEquals(1, page.size()); + assertEquals("TGT-MSKU-1", page.items().get(0).platformSku()); + assertEquals("prod-1", page.items().get(0).listingId()); + + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"store_ids\":[\"store-1\"]"), body); + assertTrue(body.contains("\"listing_time_field\":2"), body); + assertTrue(body.contains("\"listing_start_time\":\"2026-10-01\""), body); + assertTrue(body.contains("\"listing_end_time\":\"2026-10-08\""), body); + } + + @Test + void capabilityReportIncludesProductPerSubPlatform() { + RecordingTransport transport = RecordingTransport.create(); + ChannelAccount account = LingxingTestSupport.account(Platform.TARGET, 0, "store-1"); + + // Target 有商品能力;没有商品接口的长尾平台(如 Mirakl)没有 + assertTrue(sdk(transport, account, CallObserver.NOOP) + .capabilities(account.key()).supports(common.ecommerce.model.Capability.PRODUCT)); + + ChannelAccount mirakl = LingxingTestSupport.account(Platform.MIRAKL, 10034, "store-1"); + assertFalse(sdk(transport, mirakl, CallObserver.NOOP) + .capabilities(mirakl.key()).supports(common.ecommerce.model.Capability.PRODUCT)); + } +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSourceTest.java index 62e6cd1..c0953b0 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSourceTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSourceTest.java @@ -1,5 +1,6 @@ package common.ecommerce.lingxing.platform.ebay.product; +import common.ecommerce.error.ValidationException; import common.ecommerce.lingxing.LingxingApi; import common.ecommerce.model.Platform; import common.ecommerce.model.product.ProductListing; @@ -15,10 +16,12 @@ import java.time.Instant; import static common.ecommerce.lingxing.support.LingxingTestSupport.account; import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyContains; +import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyNotContains; import static common.ecommerce.lingxing.support.LingxingTestSupport.call; import static common.ecommerce.lingxing.support.LingxingTestSupport.lastBody; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; /** eBay 在线商品:请求构造 + 响应映射。 */ class EbayProductSourceTest { @@ -40,8 +43,32 @@ class EbayProductSourceTest { String body = lastBody(transport); assertBodyContains(body, "\"store_ids\":[\"1106\"]"); assertBodyContains(body, "\"listing_time_field\":1"); - assertBodyContains(body, "\"searchField\":1"); - assertBodyContains(body, "\"searchSingleValue\":\"EBAY-MSKU-1\""); + // 实测:camelCase 会被静默忽略,必须用 snake_case + assertBodyContains(body, "\"search_field\":1"); + assertBodyContains(body, "\"search_single_value\":\"EBAY-MSKU-1\""); + assertBodyNotContains(body, "searchField"); + } + + @Test + void localSkuSearchUsesField3() { + new EbayProductSource().products(call(transport, account(Platform.EBAY, 10003, "1106")), + ProductQuery.builder() + .searchField(ProductSearchField.LOCAL_SKU) + .searchValue("EBAY-LOCAL-1") + .build()); + + assertBodyContains(lastBody(transport), "\"search_field\":3"); + } + + @Test + void multiValueSearchUnsupportedFailsLoudly() { + assertThrows(ValidationException.class, + () -> new EbayProductSource().products( + call(transport, account(Platform.EBAY, 10003, "1106")), + ProductQuery.builder() + .searchField(ProductSearchField.PLATFORM_SKU) + .searchValues(java.util.Arrays.asList("A", "B")) + .build())); } @Test diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/shein/product/SheinProductSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/shein/product/SheinProductSourceTest.java index f337302..8239b5f 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/shein/product/SheinProductSourceTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/shein/product/SheinProductSourceTest.java @@ -42,6 +42,17 @@ class SheinProductSourceTest { } @Test + void localSkuSearchUsesField8() { + // 实测:9 = msku,8 = 本地 sku + new SheinProductSource().products(call(transport, account(Platform.SHEIN, 10028, "1105")), + ProductQuery.builder() + .searchField(ProductSearchField.LOCAL_SKU) + .searchValue("SHEIN-LOCAL-1") + .build()); + assertBodyContains(lastBody(transport), "\"searchField\":8"); + } + + @Test void mapsResponseWithSalePrice() { ProductListing p = new SheinProductSource().products( call(transport, account(Platform.SHEIN, 10028, "1105")), diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/target/product/TargetProductSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/target/product/TargetProductSourceTest.java index bb9334a..a4b7fd6 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/target/product/TargetProductSourceTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/target/product/TargetProductSourceTest.java @@ -13,6 +13,7 @@ import org.junit.jupiter.api.Test; import static common.ecommerce.lingxing.support.LingxingTestSupport.account; import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyContains; +import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyNotContains; import static common.ecommerce.lingxing.support.LingxingTestSupport.call; import static common.ecommerce.lingxing.support.LingxingTestSupport.lastBody; import static org.junit.jupiter.api.Assertions.assertEquals; @@ -21,7 +22,8 @@ import static org.junit.jupiter.api.Assertions.assertThrows; /** * Target 在线商品:走 Shopify 的 variantList 接口。 * - *

Target 的本地 SKU 搜索编码尚未确认,传了必须显式失败。

+ *

实测:时间窗三字段必须同时出现且只接受 {@code Y-m-d};多值搜索返回 400; + * {@code local_sku} 在该 app 下恒为空,本地 SKU 搜索显式不支持。

*/ class TargetProductSourceTest { @@ -44,6 +46,36 @@ class TargetProductSourceTest { } @Test + void timeWindowSendsAllThreeFieldsWithDateOnly() { + new TargetProductSource().products(call(transport, account(Platform.TARGET, 10017, "1106")), + ProductQuery.builder() + .updatedAfter(java.time.Instant.parse("2026-10-01T00:00:00Z")) + .updatedBefore(java.time.Instant.parse("2026-10-08T00:00:00Z")) + .build()); + + String body = lastBody(transport); + // 实测:缺 listing_time_field 或日期带时分秒都会 400 + assertBodyContains(body, "\"listing_time_field\":2"); + assertBodyContains(body, "\"listing_start_time\":\"2026-10-01\""); + assertBodyContains(body, "\"listing_end_time\":\"2026-10-08\""); + assertBodyNotContains(body, "00:00:00"); + } + + @Test + void singleSidedWindowFillsBothEnds() { + new TargetProductSource().products(call(transport, account(Platform.TARGET, 10017, "1106")), + ProductQuery.builder() + .updatedAfter(java.time.Instant.parse("2026-10-01T00:00:00Z")) + .build()); + + String body = lastBody(transport); + // 实测:只传一端返回 400,所以必须补齐另一端 + assertBodyContains(body, "\"listing_time_field\":2"); + assertBodyContains(body, "\"listing_start_time\":\"2026-10-01\""); + assertBodyContains(body, "\"listing_end_time\":\""); + } + + @Test void localSkuSearchUnsupportedFailsLoudly() { assertThrows(common.ecommerce.error.ValidationException.class, () -> new TargetProductSource().products( @@ -55,6 +87,17 @@ class TargetProductSourceTest { } @Test + void multiValueSearchUnsupportedFailsLoudly() { + assertThrows(common.ecommerce.error.ValidationException.class, + () -> new TargetProductSource().products( + call(transport, account(Platform.TARGET, 10017, "1106")), + ProductQuery.builder() + .searchField(ProductSearchField.PLATFORM_SKU) + .searchValues(java.util.Arrays.asList("A", "B")) + .build())); + } + + @Test void mapsResponse() { ProductListing p = new TargetProductSource().products( call(transport, account(Platform.TARGET, 10017, "1106")), diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSourceTest.java index 88321a7..7488ffa 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSourceTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSourceTest.java @@ -52,6 +52,33 @@ class TemuProductSourceTest { } @Test + void timeWindowIsCappedAt30Days() { + // 实测:跨度 31 天直接返回 500,必须截断 + new TemuProductSource().products(call(transport, account(Platform.TEMU, 10024, "1105")), + ProductQuery.builder() + .updatedAfter(java.time.Instant.parse("2026-09-01T00:00:00Z")) + .updatedBefore(java.time.Instant.parse("2026-11-06T00:00:00Z")) + .build()); + + String body = lastBody(transport); + assertBodyContains(body, "\"updateEndTime\":\"2026-11-06 00:00:00\""); + assertBodyContains(body, "\"updateStartTime\":\"2026-10-07 00:00:00\""); + } + + @Test + void singleSidedWindowFillsBothEnds() { + // 实测:只传一端返回 500,必须两端同时给 + new TemuProductSource().products(call(transport, account(Platform.TEMU, 10024, "1105")), + ProductQuery.builder() + .updatedAfter(java.time.Instant.parse("2026-10-30T00:00:00Z")) + .build()); + + String body = lastBody(transport); + assertBodyContains(body, "\"updateStartTime\":\"2026-10-30 00:00:00\""); + assertBodyContains(body, "\"updateEndTime\":\""); + } + + @Test void mapsResponseToUnifiedModel() { ProductListing p = new TemuProductSource().products( call(transport, account(Platform.TEMU, 10024, "1105")), diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/tiktok/product/TiktokProductSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/tiktok/product/TiktokProductSourceTest.java index 14dd72f..c0e0e99 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/tiktok/product/TiktokProductSourceTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/tiktok/product/TiktokProductSourceTest.java @@ -4,6 +4,7 @@ import common.ecommerce.lingxing.LingxingApi; import common.ecommerce.model.Platform; import common.ecommerce.model.product.ProductListing; import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.product.ProductSearchField; import common.ecommerce.model.product.ProductStatus; import common.ecommerce.testkit.JsonFixture; import common.ecommerce.testkit.RecordingTransport; @@ -34,6 +35,25 @@ class TiktokProductSourceTest { } @Test + void searchUsesField9ForPlatformSkuAnd8ForLocalSku() { + // 实测:9 = msku,8 = 本地 sku,单值/多值都生效 + new TiktokProductSource().products(call(transport, account(Platform.TIKTOK, 10011, "1104")), + ProductQuery.builder() + .searchField(ProductSearchField.PLATFORM_SKU) + .searchValue("TT-MSKU-1") + .build()); + assertBodyContains(lastBody(transport), "\"searchField\":9"); + + new TiktokProductSource().products(call(transport, account(Platform.TIKTOK, 10011, "1104")), + ProductQuery.builder() + .searchField(ProductSearchField.LOCAL_SKU) + .searchValues(java.util.Arrays.asList("L-1", "L-2")) + .build()); + assertBodyContains(lastBody(transport), "\"searchField\":8"); + assertBodyContains(lastBody(transport), "\"searchValues\":[\"L-1\",\"L-2\"]"); + } + + @Test void mapsPlatformStatusString() { ProductListing p = new TiktokProductSource().products( call(transport, account(Platform.TIKTOK, 10011, "1104")), diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSourceTest.java index 72497e3..68a5720 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSourceTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSourceTest.java @@ -1,5 +1,6 @@ package common.ecommerce.lingxing.platform.walmart.product; +import common.ecommerce.error.ValidationException; import common.ecommerce.lingxing.LingxingApi; import common.ecommerce.model.Platform; import common.ecommerce.model.product.ProductListing; @@ -17,12 +18,14 @@ import java.time.Instant; import static common.ecommerce.lingxing.support.LingxingTestSupport.ENDPOINT; import static common.ecommerce.lingxing.support.LingxingTestSupport.account; import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyContains; +import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyNotContains; import static common.ecommerce.lingxing.support.LingxingTestSupport.assertUrlStartsWith; import static common.ecommerce.lingxing.support.LingxingTestSupport.call; import static common.ecommerce.lingxing.support.LingxingTestSupport.lastBody; import static common.ecommerce.lingxing.support.LingxingTestSupport.lastUrl; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; /** 沃尔玛在线商品:请求构造 + 响应映射。 */ class WalmartProductSourceTest { @@ -49,8 +52,11 @@ class WalmartProductSourceTest { assertBodyContains(body, "\"length\":50"); assertBodyContains(body, "\"listing_time_field\":2"); assertBodyContains(body, "\"listing_start_time\":\"2026-10-01\""); - assertBodyContains(body, "\"searchField\":1"); - assertBodyContains(body, "\"searchSingleValue\":\"WM-MSKU-1\""); + // 实测:camelCase 会被静默忽略,必须用 snake_case + assertBodyContains(body, "\"search_field\":1"); + assertBodyContains(body, "\"search_single_value\":\"WM-MSKU-1\""); + assertBodyNotContains(body, "searchField"); + assertBodyNotContains(body, "searchSingleValue"); } @Test @@ -61,7 +67,19 @@ class WalmartProductSourceTest { .searchValue("WM-LOCAL-1") .build()); - assertBodyContains(lastBody(transport), "\"searchField\":3"); + assertBodyContains(lastBody(transport), "\"search_field\":3"); + } + + @Test + void multiValueSearchUnsupportedFailsLoudly() { + // 实测:search_values 被平台忽略并返回整页,宁可报错也不静默返回全量 + assertThrows(ValidationException.class, + () -> new WalmartProductSource().products( + call(transport, account(Platform.WALMART_SC, 10008, "1108")), + ProductQuery.builder() + .searchField(ProductSearchField.PLATFORM_SKU) + .searchValues(java.util.Arrays.asList("A", "B")) + .build())); } @Test diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/probe/ListingParamProbeTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/probe/ListingParamProbeTest.java new file mode 100644 index 0000000..1b2ec66 --- /dev/null +++ b/lingxing/src/test/java/common/ecommerce/lingxing/probe/ListingParamProbeTest.java @@ -0,0 +1,165 @@ +package common.ecommerce.lingxing.probe; + +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.HttpTransport; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.lingxing.LingxingApi; +import common.ecommerce.lingxing.LingxingConstants; +import common.ecommerce.lingxing.auth.LingxingTokenClient; +import common.ecommerce.lingxing.http.LingxingEnvelope; +import common.ecommerce.lingxing.http.LingxingRateLimiter; +import common.ecommerce.lingxing.http.LingxingRequestFactory; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; +import common.ecommerce.model.account.AccountKey; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.sdk.ChannelConnection; +import common.ecommerce.sdk.ChannelContext; +import common.ecommerce.spi.AccessToken; +import common.ecommerce.spi.ChannelSecret; +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.databind.JsonNode; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledIfSystemProperty; + +import java.time.Clock; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.Map; + +/** + * 只读探针(收尾第三轮):Target 时间窗上限与单边窗口。 + * + *

默认跳过;用 {@code -Dlingxing.probe=true} 显式开启。只做查询。

+ */ +@EnabledIfSystemProperty(named = "lingxing.probe", matches = "true") +class ListingParamProbeTest { + + // 真实凭据不入库:本地跑探针时用 -Dlingxing.probe.appKey=... -Dlingxing.probe.appSecret=... + private static final String APP_KEY = System.getProperty("lingxing.probe.appKey", ""); + private static final String APP_SECRET = System.getProperty("lingxing.probe.appSecret", ""); + private static final String BASE_URL = LingxingConstants.PRODUCTION_BASE_URL; + + private static final JacksonJsonCodec JSON = new JacksonJsonCodec(); + private final HttpTransport transport = new OkHttpTransport("common-ecommerce-param-probe"); + + private static final String TARGET_STORE = "110593321260223488"; + private static final String TEMU_STORE = "110544498784182784"; + + @Test + void targetWindowLimits() { + requireCredentials(); + LingxingCall call = call(Platform.TARGET, 0, TARGET_STORE); + System.out.println("\n===== TARGET 时间窗上限 ====="); + for (int days : new int[]{30, 31, 60, 90, 180, 365}) { + Map body = base(); + body.put("listing_time_field", 2); + body.put("listing_start_time", minusDays(days)); + body.put("listing_end_time", "2026-11-06"); + probe(call, LingxingApi.LISTING_SHOPIFY, days + " 天", body); + } + System.out.println("\n===== TARGET 单边窗口(field=2)====="); + Map startOnly = base(); + startOnly.put("listing_time_field", 2); + startOnly.put("listing_start_time", "2026-10-01"); + probe(call, LingxingApi.LISTING_SHOPIFY, "只 start", startOnly); + + Map endOnly = base(); + endOnly.put("listing_time_field", 2); + endOnly.put("listing_end_time", "2026-11-06"); + probe(call, LingxingApi.LISTING_SHOPIFY, "只 end", endOnly); + + System.out.println("\n===== TARGET time_field 取值 ====="); + for (int field : new int[]{1, 2, 3}) { + Map body = base(); + body.put("listing_time_field", field); + body.put("listing_start_time", "2021-01-01"); + body.put("listing_end_time", "2023-12-31"); + probe(call, LingxingApi.LISTING_SHOPIFY, "field=" + field + " 2021-2023", body); + } + } + + @Test + void temuWindowBoundary() { + requireCredentials(); + LingxingCall call = call(Platform.TEMU, 10024, TEMU_STORE); + System.out.println("\n===== TEMU 窗口边界(数据时间未知,只看是否报错)====="); + for (int days : new int[]{1, 7, 30}) { + Map body = new LinkedHashMap(); + body.put("offset", 0); + body.put("length", 3); + body.put("useCursor", Boolean.FALSE); + body.put("storeIds", Collections.singletonList(TEMU_STORE)); + body.put("updateStartTime", minusDays(days) + " 00:00:00"); + body.put("updateEndTime", "2026-11-06 00:00:00"); + probe(call, LingxingApi.LISTING_TEMU, days + " 天", body); + } + } + + // ---------------------------------------------------------------- 工具 + + private static Map base() { + Map body = new LinkedHashMap(); + body.put("offset", 0); + body.put("length", 10); + body.put("store_ids", Collections.singletonList(TARGET_STORE)); + return body; + } + + private static String minusDays(int days) { + return java.time.LocalDate.parse("2026-11-06").minusDays(days).toString(); + } + + /** 没有真实凭据时跳过,避免本地/CI 默认跑真机。 */ + private static void requireCredentials() { + org.junit.jupiter.api.Assumptions.assumeTrue( + !APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(), + "未提供 -Dlingxing.probe.appKey / -Dlingxing.probe.appSecret,跳过探针"); + } + + private void probe(LingxingCall call, LingxingApi api, String label, Map body) { + try { + HttpRequest req = call.signed(api, body, "probe.param"); + HttpResponse resp = call.execute(req); + LingxingEnvelope env = call.envelope(resp, "probe.param"); + JsonNode root = JSON.mapper().readTree(env.body()); + JsonNode data = root == null ? null : root.get("data"); + int items = 0; + if (data != null) { + items = data.isArray() ? data.size() : data.path("list").size(); + } + System.out.println(" [" + label + "] items=" + items); + } catch (JsonProcessingException e) { + System.out.println(" [" + label + "] 解析失败"); + } catch (RuntimeException e) { + System.out.println(" [" + label + "] 失败: " + shortMsg(e)); + } + } + + private static String shortMsg(RuntimeException e) { + String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage(); + return msg.length() <= 150 ? msg : msg.substring(0, 150); + } + + private LingxingCall call(Platform platform, int code, String storeId) { + ChannelAccount account = ChannelAccount.builder() + .key(AccountKey.of(ChannelProvider.LINGXING, platform, "oms-probe")) + .externalStoreId(storeId == null || storeId.isEmpty() ? "probe" : storeId) + .platformCode(code == 0 ? null : code) + .credentialRef("probe") + .marketplaceZone("America/Los_Angeles") + .currency("USD") + .build(); + Clock clock = Clock.systemUTC(); + ChannelSecret secret = ChannelSecret.builder().appKey(APP_KEY).appSecret(APP_SECRET).build(); + ChannelConnection conn = ChannelConnection.of(BASE_URL, secret); + ChannelContext ctx = ChannelContext.of(account, conn, "probe-" + System.currentTimeMillis(), clock); + AccessToken token = new LingxingTokenClient(transport, JSON, clock) + .fetch(BASE_URL, APP_KEY, APP_SECRET); + return new LingxingCall(ctx, token, new LingxingRequestFactory(JSON, clock), + new LingxingRateLimiter(), JSON, transport); + } +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/probe/ListingSmokeProbeTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/probe/ListingSmokeProbeTest.java new file mode 100644 index 0000000..d2968a4 --- /dev/null +++ b/lingxing/src/test/java/common/ecommerce/lingxing/probe/ListingSmokeProbeTest.java @@ -0,0 +1,217 @@ +package common.ecommerce.lingxing.probe; + +import common.ecommerce.capability.AggregatorCapable.SubChannel; +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.HttpTransport; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.lingxing.LingxingConstants; +import common.ecommerce.lingxing.adapter.LingxingAdapter; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; +import common.ecommerce.model.account.AccountKey; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.product.ProductListing; +import common.ecommerce.model.product.ProductQuery; +import common.ecommerce.model.product.ProductSearchField; +import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.ChannelConnection; +import common.ecommerce.sdk.ChannelContext; +import common.ecommerce.sdk.ChannelSdk; +import common.ecommerce.spi.ChannelSecret; +import common.ecommerce.testkit.InMemoryAccounts; +import common.ecommerce.testkit.InMemoryLockProvider; +import common.ecommerce.testkit.InMemoryTokenStore; +import org.junit.jupiter.api.Assumptions; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledIfSystemProperty; + +import java.time.Clock; +import java.time.Instant; +import java.util.ArrayList; +import java.util.List; + +/** + * 只读冒烟:从 {@link ChannelSdk} 门面逐个平台拉一页 listing,核对出入参。 + * + *

默认跳过;用 {@code -Dlingxing.probe=true} 显式开启。

+ * + *

只做查询。会打印请求体(截断)与统一模型的关键字段, + * 便于对照接口文档核对分页、日期、SKU 搜索三项参数。

+ */ +@EnabledIfSystemProperty(named = "lingxing.probe", matches = "true") +class ListingSmokeProbeTest { + + // 真实凭据不入库:本地跑探针时用 -Dlingxing.probe.appKey=... -Dlingxing.probe.appSecret=... + private static final String APP_KEY = System.getProperty("lingxing.probe.appKey", ""); + private static final String APP_SECRET = System.getProperty("lingxing.probe.appSecret", ""); + private static final String BASE_URL = LingxingConstants.PRODUCTION_BASE_URL; + + private static final JacksonJsonCodec JSON = new JacksonJsonCodec(); + private final LoggingTransport transport = new LoggingTransport(new OkHttpTransport("common-ecommerce-listing-probe")); + private final InMemoryTokenStore tokens = new InMemoryTokenStore(); + + /** 平台 → 实测店铺 id,取自 ShopListProbeTest 的输出。 */ + private static final Object[][] TARGETS = { + {Platform.AMAZON_SC, 10001, "127524991355697152", "AMZ-TOY-US"}, + {Platform.AMAZON_VC, 10035, "134543850419473408", "AMZ-CL-US"}, + {Platform.WALMART_SC, 10008, "110528861382225920", "WMT-CYB-US"}, + {Platform.EBAY, 10003, "110627593325390848", "EBA-STE-US"}, + {Platform.TIKTOK, 10011, "110541661459314688", "TTK-STE"}, + {Platform.TEMU, 10024, "110544498784182784", "TEMU OFFICE DIRECT"}, + {Platform.SHEIN, 10028, "110541676737748480", "SHE-JCK-US"}, + {Platform.ALIEXPRESS, 0, "", "全部阿里店铺(接口不需要 store)"}, + // shopify/variantList 下真正有商品的是 SPF-BM(10002),Target DVS 是空店 + {Platform.TARGET, 0, "110593321260223488", "SPF-BM"}, + }; + + /** + * 列表页不传时间窗:部分平台的数据很久没更新(Temu 最近更新时间早于窗口), + * 传窄窗口会得到 0 条,看不出字段映射。时间窗参数另行核对,见 {@link ListingParamProbeTest}。 + */ + @Test + void pullOnePagePerPlatform() { + Assumptions.assumeTrue(!APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(), + "未提供 -Dlingxing.probe.appKey / -Dlingxing.probe.appSecret,跳过探针"); + ChannelSdk sdk = sdk(); + + for (Object[] row : TARGETS) { + Platform platform = (Platform) row[0]; + int code = (Integer) row[1]; + String storeId = (String) row[2]; + String label = (String) row[3]; + System.out.println("\n================ " + platform + " / " + label + " ================"); + + ChannelAccount account = account(platform, code, storeId); + AccountKey key = account.key(); + ChannelConnection conn = connection(); + + try { + sdk.capabilities(key); + Page page = sdk.products(key, conn).pull(ProductQuery.builder() + .pageSize(3) + .build()); + System.out.println("[result] items=" + page.size() + " nextCursor=" + page.nextCursor()); + for (ProductListing p : page.items()) { + System.out.println(" platformSku=" + p.platformSku() + + " localSku=" + localSkuOf(p) + + " listingId=" + p.listingId() + + " status=" + p.status() + + " title=" + shorten(p.title()) + + " listedAt=" + p.listedAt() + + " updatedAt=" + p.updatedAt()); + } + + // 用样本回查平台 SKU + 本地 SKU,核对 search 条件 + if (!page.items().isEmpty()) { + ProductListing sample = page.items().get(0); + probeSearch(sdk, key, conn, platform, ProductSearchField.PLATFORM_SKU, sample.platformSku()); + String localSku = localSkuOf(sample); + if (localSku != null && !localSku.isEmpty()) { + probeSearch(sdk, key, conn, platform, ProductSearchField.LOCAL_SKU, localSku); + } else { + System.out.println(" [search] 本地 SKU 为空,跳过 LOCAL_SKU 回查"); + } + } + } catch (RuntimeException e) { + System.out.println("[ERROR] " + e.getClass().getSimpleName() + ": " + e.getMessage()); + } + } + } + + private void probeSearch(ChannelSdk sdk, AccountKey key, ChannelConnection conn, + Platform platform, ProductSearchField field, String value) { + try { + Page got = sdk.products(key, conn).pull(ProductQuery.builder() + .searchField(field) + .searchValue(value) + .pageSize(3) + .build()); + System.out.println(" [search] " + field + "=" + value + " → items=" + got.size()); + } catch (RuntimeException e) { + String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage(); + System.out.println(" [search] " + field + "=" + value + " → 失败:" + shorten(msg)); + } + } + + /** 统一模型没有 localSku 字段,从 attributes 里取原始值。 */ + private static String localSkuOf(ProductListing p) { + Object v = p.attributes().get("local_sku"); + return v == null ? null : String.valueOf(v); + } + + private ChannelSdk sdk() { + ChannelAccount[] accounts = new ChannelAccount[TARGETS.length]; + InMemoryAccounts repo = new InMemoryAccounts(); + for (int i = 0; i < TARGETS.length; i++) { + Object[] row = TARGETS[i]; + accounts[i] = account((Platform) row[0], (Integer) row[1], (String) row[2]); + repo.put(accounts[i]); + } + LingxingAdapter adapter = new LingxingAdapter(transport, JSON, tokens, + new InMemoryLockProvider(), Clock.systemUTC()); + return ChannelSdk.builder() + .accountRepository(repo) + .clock(Clock.systemUTC()) + .register(adapter) + .build(); + } + + private static ChannelAccount account(Platform platform, int code, String storeId) { + return ChannelAccount.builder() + .key(AccountKey.of(ChannelProvider.LINGXING, platform, + "oms-" + platform.name().toLowerCase())) + .externalStoreId(storeId == null || storeId.trim().isEmpty() ? "probe" : storeId) + .platformCode(code == 0 ? null : code) + .credentialRef("probe") + .marketplaceZone("America/Los_Angeles") + .currency("USD") + .build(); + } + + private static ChannelConnection connection() { + return ChannelConnection.of(BASE_URL, ChannelSecret.builder() + .appKey(APP_KEY).appSecret(APP_SECRET).build()); + } + + private static String shorten(String s) { + if (s == null) { + return "null"; + } + return s.length() <= 40 ? s : s.substring(0, 40) + "…"; + } + + /** 打印请求/响应(截断),只读排查用。 */ + static final class LoggingTransport implements HttpTransport { + + private static final int MAX_BODY = 1200; + + private final HttpTransport delegate; + + LoggingTransport(HttpTransport delegate) { + this.delegate = delegate; + } + + @Override + public HttpResponse execute(HttpRequest request) { + System.out.println(" --> " + request.method() + " " + pathOf(request.url())); + System.out.println(" body " + truncate(request.body())); + HttpResponse response = delegate.execute(request); + System.out.println(" <-- " + response.statusCode() + " " + truncate(response.body())); + return response; + } + + private static String pathOf(String url) { + int i = url.indexOf('/', url.indexOf("://") + 3); + return i < 0 ? url : url.substring(i); + } + + private static String truncate(String body) { + if (body == null) { + return "null"; + } + return body.length() <= MAX_BODY ? body : body.substring(0, MAX_BODY) + "...(" + body.length() + " chars)"; + } + } +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/probe/SearchFieldProbeTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/probe/SearchFieldProbeTest.java index a9f1e79..956e52c 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/probe/SearchFieldProbeTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/probe/SearchFieldProbeTest.java @@ -35,9 +35,11 @@ import java.util.Map; * *

只做查询,不创建、不修改任何数据。

* - *

用法:填好下面四个常量后运行

+ *

用法:通过系统属性提供凭据后运行(凭据不入库)

*
- * mvn -pl lingxing test -Dtest=SearchFieldProbeTest -DfailIfNoTests=false
+ * mvn -pl lingxing test -Dtest=SearchFieldProbeTest -DfailIfNoTests=false \
+ *     -Dlingxing.probe=true \
+ *     -Dlingxing.probe.appKey=你的appId -Dlingxing.probe.appSecret=你的appSecret
  * 
* *

输出会告诉你:对同一个 SKU 值,哪个 searchField 编码能命中; @@ -48,8 +50,9 @@ import java.util.Map; class SearchFieldProbeTest { // ==================== 填写这里 ==================== - private static final String APP_KEY = "ak_MWoHJz2tcIwKF"; - private static final String APP_SECRET = "YOUkd5efWJSK71jLvDyz+g=="; + // 真实凭据不入库:本地跑探针时用 -Dlingxing.probe.appKey=... -Dlingxing.probe.appSecret=... + private static final String APP_KEY = System.getProperty("lingxing.probe.appKey", ""); + private static final String APP_SECRET = System.getProperty("lingxing.probe.appSecret", ""); /** AliExpress 探针开关:该接口不需要店铺 id,只要 app 下有阿里商品就能查。 */ private static final boolean PROBE_ALIEXPRESS = true; @@ -58,7 +61,7 @@ class SearchFieldProbeTest { * Target 店铺的 storeId。可选——文档里 store_ids 不是必填项, * 不填就查该 app 下全部店铺的商品。 */ - private static final String TARGET_STORE_ID = "110593321260223488"; + private static final String TARGET_STORE_ID = ""; /** AliExpress 的领星 platform_code(待实测确认;该码不影响商品接口调用)。 */ private static final int ALIEXPRESS_PLATFORM_CODE = 0; @@ -117,15 +120,18 @@ class SearchFieldProbeTest { Map probe = new LinkedHashMap(); List> sample = queryShopify(call, probe, 2); if (sample.isEmpty()) { - throw new AssertionError("店铺没有商品,无法做样本;换个有商品的 store_id"); + System.out.println("[target] 样本为空,原始响应在 LoggingTransport 输出中;" + + "store_ids=" + (TARGET_STORE_ID.isEmpty() ? "未传" : TARGET_STORE_ID)); + return; } String sampleMsku = str(sample.get(0).get("msku")); String sampleSku = str(sample.get(0).get("local_sku")); System.out.println("[target] 样本 msku=" + sampleMsku + " local_sku=" + sampleSku); for (int field = 1; field <= 9; field++) { - int hitByMsku = countBySearch(call, field, sampleMsku, 10, true); - int hitBySku = countBySearch(call, field, sampleSku, 10, true); + // 平台可能对某些编码直接返回参数错误:单独接住,继续试下一个 + String hitByMsku = safeCount(call, field, sampleMsku, true); + String hitBySku = safeCount(call, field, sampleSku, true); System.out.println("[target] search_field=" + field + " 用msku查命中=" + hitByMsku + " 用local_sku查命中=" + hitBySku); @@ -187,6 +193,19 @@ class SearchFieldProbeTest { return queryShopify(call, body, length, null, null); } + /** 单个编码查询失败时返回错误摘要,不中断整轮探针。 */ + private String safeCount(LingxingCall call, int field, String value, boolean target) { + if (value == null || value.isEmpty()) { + return "样本为空"; + } + try { + return String.valueOf(countBySearch(call, field, value, 10, target)); + } catch (RuntimeException e) { + String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage(); + return "失败:" + msg; + } + } + private int countBySearch(LingxingCall call, int field, String value, int length, boolean shopify) { if (value == null || value.isEmpty()) { return -1; @@ -221,8 +240,8 @@ class SearchFieldProbeTest { // ---------------------------------------------------------------- 公共设施 private void requireConfigured() { - Assumptions.assumeTrue(!APP_KEY.startsWith("在这里填") && !APP_SECRET.startsWith("在这里填"), - "请先填写 APP_KEY / APP_SECRET"); + Assumptions.assumeTrue(!APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(), + "未提供 -Dlingxing.probe.appKey / -Dlingxing.probe.appSecret,跳过探针"); } private static void skipIfBlank(String value, String name) { diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/probe/ShopListProbeTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/probe/ShopListProbeTest.java index c94977a..def6211 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/probe/ShopListProbeTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/probe/ShopListProbeTest.java @@ -41,9 +41,11 @@ import java.util.TreeMap; * *

只做查询,不创建、不修改数据。

* - *

用法:填好 APP_KEY / APP_SECRET,然后

+ *

用法:通过系统属性提供凭据后运行(凭据不入库),然后

*
- * mvn -pl lingxing test -Dtest=ShopListProbeTest -DfailIfNoTests=false
+ * mvn -pl lingxing test -Dtest=ShopListProbeTest -DfailIfNoTests=false \
+ *     -Dlingxing.probe=true \
+ *     -Dlingxing.probe.appKey=你的appId -Dlingxing.probe.appSecret=你的appSecret
  * 
* *

输出会按 platform_code 分组,形如:

@@ -60,8 +62,9 @@ import java.util.TreeMap; class ShopListProbeTest { // ==================== 填写这里 ==================== - private static final String APP_KEY = "ak_MWoHJz2tcIwKF"; - private static final String APP_SECRET = "YOUkd5efWJSK71jLvDyz+g=="; + // 真实凭据不入库:本地跑探针时用 -Dlingxing.probe.appKey=... -Dlingxing.probe.appSecret=... + private static final String APP_KEY = System.getProperty("lingxing.probe.appKey", ""); + private static final String APP_SECRET = System.getProperty("lingxing.probe.appSecret", ""); /** 可选:只查某个 platform_code 的店铺。留空查全部。 */ private static final Integer ONLY_PLATFORM_CODE = null; @@ -197,8 +200,8 @@ class ShopListProbeTest { // ---------------------------------------------------------------- 公共设施 private void requireConfigured() { - Assumptions.assumeTrue(!APP_KEY.startsWith("在这里填") && !APP_SECRET.startsWith("在这里填"), - "请先填写 APP_KEY / APP_SECRET"); + Assumptions.assumeTrue(!APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(), + "未提供 -Dlingxing.probe.appKey / -Dlingxing.probe.appSecret,跳过探针"); } private LingxingCall call(ChannelAccount account) {
code实测店铺Platform
10001AMZ-*AMAZON_SC
10002SPF-*SHOPIFY
10003EBA-*EBAY
10003EBA-*EBAY
10005 / 10031AEP-* / AEPH-*AEPH
10008WMT-*WALMART_SC
10010WAY-*WAYFAIR