Browse Source

Merge remote-tracking branch 'origin/feature/supplier-lingxing' into feature/supplier-lingxing

feature/supplier-lingxing
lml 2 weeks ago
parent
commit
0a126986ce
  1. 11
      core/src/main/java/common/ecommerce/audit/CallOutcome.java
  2. 70
      core/src/main/java/common/ecommerce/audit/CallRecord.java
  3. 12
      core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java
  4. 16
      core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java
  5. 6
      core/src/main/java/common/ecommerce/capability/AfterSaleCapable.java
  6. 15
      core/src/main/java/common/ecommerce/capability/AfterSales.java
  7. 68
      core/src/main/java/common/ecommerce/capability/AggregatorCapable.java
  8. 7
      core/src/main/java/common/ecommerce/capability/CapabilityReport.java
  9. 6
      core/src/main/java/common/ecommerce/capability/OrderEditCapable.java
  10. 12
      core/src/main/java/common/ecommerce/capability/OutboundCapable.java
  11. 6
      core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java
  12. 47
      core/src/main/java/common/ecommerce/capability/Outbounds.java
  13. 7
      core/src/main/java/common/ecommerce/capability/PlatformAdapter.java
  14. 15
      core/src/main/java/common/ecommerce/capability/ProductCapable.java
  15. 20
      core/src/main/java/common/ecommerce/capability/Products.java
  16. 14
      core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java
  17. 30
      core/src/main/java/common/ecommerce/capability/SalesOrders.java
  18. 5
      core/src/main/java/common/ecommerce/capability/SettlementCapable.java
  19. 15
      core/src/main/java/common/ecommerce/capability/Settlements.java
  20. 6
      core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java
  21. 6
      core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java
  22. 8
      core/src/main/java/common/ecommerce/error/AuthException.java
  23. 70
      core/src/main/java/common/ecommerce/error/ChannelException.java
  24. 12
      core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java
  25. 21
      core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java
  26. 7
      core/src/main/java/common/ecommerce/error/PlatformBusinessException.java
  27. 11
      core/src/main/java/common/ecommerce/error/RateLimitException.java
  28. 6
      core/src/main/java/common/ecommerce/error/TransientException.java
  29. 6
      core/src/main/java/common/ecommerce/error/ValidationException.java
  30. 43
      core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java
  31. 4
      core/src/main/java/common/ecommerce/idempotency/WriteAudit.java
  32. 13
      core/src/main/java/common/ecommerce/idempotency/WriteResult.java
  33. 28
      core/src/main/java/common/ecommerce/idempotency/WriteScope.java
  34. 2
      core/src/main/java/common/ecommerce/model/FulfillmentMode.java
  35. 12
      core/src/main/java/common/ecommerce/model/Platform.java
  36. 17
      core/src/main/java/common/ecommerce/model/account/AccountKey.java
  37. 65
      core/src/main/java/common/ecommerce/model/account/ChannelAccount.java
  38. 156
      core/src/main/java/common/ecommerce/model/aftersale/AfterSale.java
  39. 39
      core/src/main/java/common/ecommerce/model/aftersale/AfterSaleQuery.java
  40. 2
      core/src/main/java/common/ecommerce/model/aftersale/AfterSaleType.java
  41. 41
      core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java
  42. 11
      core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java
  43. 42
      core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java
  44. 22
      core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java
  45. 128
      core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java
  46. 27
      core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java
  47. 48
      core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java
  48. 59
      core/src/main/java/common/ecommerce/model/fulfillment/OutboundPackage.java
  49. 14
      core/src/main/java/common/ecommerce/model/fulfillment/OutboundResult.java
  50. 24
      core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java
  51. 39
      core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java
  52. 44
      core/src/main/java/common/ecommerce/model/order/OrderLine.java
  53. 66
      core/src/main/java/common/ecommerce/model/order/SalesOrder.java
  54. 6
      core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java
  55. 63
      core/src/main/java/common/ecommerce/model/product/ProductListing.java
  56. 32
      core/src/main/java/common/ecommerce/model/product/ProductQuery.java
  57. 10
      core/src/main/java/common/ecommerce/model/product/ProductRef.java
  58. 6
      core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java
  59. 61
      core/src/main/java/common/ecommerce/model/settlement/SettlementQuery.java
  60. 117
      core/src/main/java/common/ecommerce/model/settlement/SettlementTransaction.java
  61. 23
      core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java
  62. 49
      core/src/main/java/common/ecommerce/model/support/Money.java
  63. 17
      core/src/main/java/common/ecommerce/model/support/Page.java
  64. 20
      core/src/main/java/common/ecommerce/model/support/PlatformTime.java
  65. 17
      core/src/main/java/common/ecommerce/sdk/AdapterFactory.java
  66. 42
      core/src/main/java/common/ecommerce/sdk/CallSupport.java
  67. 12
      core/src/main/java/common/ecommerce/sdk/ChannelConnection.java
  68. 17
      core/src/main/java/common/ecommerce/sdk/ChannelContext.java
  69. 5
      core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
  70. 5
      core/src/main/java/common/ecommerce/sdk/ProviderResolver.java
  71. 32
      core/src/main/java/common/ecommerce/spi/AccessToken.java
  72. 14
      core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java
  73. 24
      core/src/main/java/common/ecommerce/spi/ChannelSecret.java
  74. 12
      core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java
  75. 21
      core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java
  76. 20
      core/src/main/java/common/ecommerce/spi/IdempotencyStore.java
  77. 4
      core/src/main/java/common/ecommerce/spi/LockProvider.java
  78. 3
      core/src/main/java/common/ecommerce/spi/SecretProvider.java
  79. 10
      core/src/main/java/common/ecommerce/spi/Sink.java
  80. 16
      core/src/main/java/common/ecommerce/spi/SyncCursorStore.java
  81. 12
      core/src/main/java/common/ecommerce/spi/TokenStore.java
  82. 17
      core/src/main/java/common/ecommerce/sync/SyncEngine.java
  83. 11
      core/src/main/java/common/ecommerce/sync/SyncResult.java
  84. 15
      core/src/main/java/common/ecommerce/sync/SyncSpec.java
  85. 3
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java
  86. 8
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java
  87. 2
      lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java
  88. 2
      lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatformDefaults.java
  89. 9
      lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java
  90. 29
      lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java
  91. 35
      lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchMapper.java
  92. 58
      lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/ShopifySubPlatform.java
  93. 166
      lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyListingDto.java
  94. 49
      lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyLocationDto.java
  95. 272
      lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/product/ShopifyProductSource.java
  96. 10
      lingxing/src/main/java/common/ecommerce/lingxing/platform/target/TargetSubPlatform.java
  97. 48
      lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java
  98. 22
      lingxing/src/main/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSource.java
  99. 9
      lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java
  100. 164
      lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingSdkListingCallTest.java
  101. Some files were not shown because too many files have changed in this diff Show More

11
core/src/main/java/common/ecommerce/audit/CallOutcome.java

@ -2,13 +2,20 @@ package common.ecommerce.audit; @@ -2,13 +2,20 @@ package common.ecommerce.audit;
/**
* 一次 SDK 调用的结果状态。
*
* <p>只有 {@link #SUCCESS} 表示完整成功;批处理部分失败是 {@link #PARTIAL},
* <b>不能</b>当成功处理(例如幂等层会把成功当成业务动作已完成)。</p>
*/
public enum CallOutcome {
/** 调用成功(适配器没有抛异常)。 */
/** 调用成功(适配器没有抛异常,且没有失败明细)。 */
SUCCESS,
/** 批处理部分成功:有失败明细,但调用方拿到了结果。 */
/**
* 批处理部分成功:有失败明细,但调用方仍拿到了结果(如审核发货部分单失败)。
*
* <p>不算 {@link #SUCCESS};需要逐条看 {@code failedCount} / {@code resultCode}。</p>
*/
PARTIAL,
/** 调用失败(能力不支持、参数校验、平台返回错误、网络异常等)。 */

70
core/src/main/java/common/ecommerce/audit/CallRecord.java

@ -23,25 +23,44 @@ import java.util.Objects; @@ -23,25 +23,44 @@ import java.util.Objects;
*/
public final class CallRecord {
/** 调用开始时间(UTC);构造时必填。 */
private final Instant occurredAt;
/** <b>我方</b>链路 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<String, Object> 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 { @@ -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 { @@ -94,15 +114,21 @@ public final class CallRecord {
return finishedAt().atZone(Objects.requireNonNull(zone, "zone"));
}
/** 链路 ID,与 HTTP 层日志、平台 request_id 关联用。 */
/**
* 链路 ID,与 HTTP 层日志关联用。
*
* <p>这是我方生成的 ID;平台侧工单号是 {@link #platformRequestId()},两者不能混。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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<String, Object> 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<String, Object> params) {
this.params = params == null ? Collections.<String, Object>emptyMap() : params;
return this;
}
/**
* 从异常填充失败字段:类名、消息;若为 {@code ChannelException}
* 还提取 {@code retryable} / {@code platformRequestId} / {@code platformCode}。
*
* <p>不会自动把 outcome 改成 FAILURE,需调用方显式设置。</p>
*/
public Builder error(Throwable error) {
if (error != null) {
this.errorType = error.getClass().getName();
@ -314,6 +381,7 @@ public final class CallRecord { @@ -314,6 +381,7 @@ public final class CallRecord {
return this;
}
/** 构造不可变记录;occurredAt / operation / outcome 不能为 null。 */
public CallRecord build() {
return new CallRecord(this);
}

12
core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java

@ -29,13 +29,17 @@ import java.util.Objects; @@ -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 { @@ -76,6 +80,12 @@ public final class Slf4jCallObserver implements CallObserver {
return formatter.format(instant);
}
/**
* 每次调用结束打一行日志。
*
* <p>{@link CallRecord#failed()} 为 true 打 WARN,否则打 INFO——
* 因此 PARTIAL 也是 INFO,失败明细看行内的 {@code failed=}。</p>
*/
@Override
public void onCall(CallRecord record) {
if (record.failed()) {
@ -123,6 +133,7 @@ public final class Slf4jCallObserver implements CallObserver { @@ -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 { @@ -131,6 +142,7 @@ public final class Slf4jCallObserver implements CallObserver {
+ " requestId=" + record.requestId();
}
/** 按当前时区与格式渲染时间。 */
private String at(Instant instant) {
return format(instant);
}

16
core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java

@ -13,10 +13,20 @@ import java.util.EnumSet; @@ -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<Capability> supported;
/**
* 遍历 {@link Capability} 全集,逐项询问适配器。
*
* <p>只读,不触发真实 API。</p>
*/
public AdapterCapabilityReport(PlatformAdapter adapter, ChannelAccount account) {
this.adapter = adapter;
this.account = account;
@ -28,16 +38,19 @@ public final class AdapterCapabilityReport implements CapabilityReport { @@ -28,16 +38,19 @@ public final class AdapterCapabilityReport implements CapabilityReport {
}
}
/** 该账户是否支持某能力。 */
@Override
public boolean supports(Capability capability) {
return supported.contains(capability);
}
/** 支持的能力集合(副本)。 */
@Override
public EnumSet<Capability> supported() {
return EnumSet.copyOf(supported);
}
/** 不支持的能力集合(全集差集)。 */
@Override
public EnumSet<Capability> unsupported() {
EnumSet<Capability> all = EnumSet.allOf(Capability.class);
@ -45,14 +58,17 @@ public final class AdapterCapabilityReport implements CapabilityReport { @@ -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;

6
core/src/main/java/common/ecommerce/capability/AfterSaleCapable.java

@ -15,6 +15,10 @@ import common.ecommerce.sdk.ChannelContext; @@ -15,6 +15,10 @@ import common.ecommerce.sdk.ChannelContext;
*/
public interface AfterSaleCapable extends PlatformAdapter {
/** 分页拉取售后订单;统一模型按<b>商品行</b>展开。 */
/**
* 分页拉取售后订单;统一模型按<b>商品行</b>展开。
*
* @return 当前页;{@link Page#nextCursor()} 为 null 表示没有下一页
*/
Page<AfterSale> pull(ChannelContext ctx, AfterSaleQuery query);
}

15
core/src/main/java/common/ecommerce/capability/AfterSales.java

@ -15,15 +15,24 @@ import common.ecommerce.sdk.ChannelContext; @@ -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 { @@ -41,6 +50,11 @@ public final class AfterSales {
return new AfterSales(adapter, account, ctx.withRequestId(requestId), observer);
}
/**
* 拉取一页售后订单(按商品行展开)。
*
* @throws ChannelException.UnsupportedCapabilityException 未声明 RETURNS 或未实现 AfterSaleCapable
*/
public Page<AfterSale> pull(final AfterSaleQuery query) {
return CallSupport.observe(observer, ctx, "afterSales.pull",
CallSupport.params(
@ -58,6 +72,7 @@ public final class AfterSales { @@ -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);

68
core/src/main/java/common/ecommerce/capability/AggregatorCapable.java

@ -27,7 +27,6 @@ public interface AggregatorCapable extends PlatformAdapter { @@ -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 { @@ -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 { @@ -62,12 +68,18 @@ public interface AggregatorCapable extends PlatformAdapter {
/** 平台特有字段。 */
private final java.util.Map<String, Object> attributes;
/**
* 构造只含路由字段的子店铺信息;平台特有字段为 null。
*
* <p>需要完整信息时用 {@link #builder()}。</p>
*/
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.<String, Object>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 { @@ -89,145 +101,199 @@ public interface AggregatorCapable extends PlatformAdapter {
new java.util.LinkedHashMap<String, Object>(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<String, Object> 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<String, Object> 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<String, Object> attributes) {
this.attributes = attributes == null
? java.util.Collections.<String, Object>emptyMap() : attributes;
return this;
}
/** 构建子店铺信息;必填字段不做校验,由调用方保证。 */
public SubChannel build() {
return new SubChannel(platformCode, externalStoreId, platform, name,
sellerId, accountName, status, region, regionName, country,

7
core/src/main/java/common/ecommerce/capability/CapabilityReport.java

@ -11,9 +11,16 @@ import java.util.EnumSet; @@ -11,9 +11,16 @@ import java.util.EnumSet;
*/
public interface CapabilityReport {
/**
* 该账户是否支持某能力。
*
* @param capability 待检查能力,null 返回 false
*/
boolean supports(Capability capability);
/** 支持的能力集合(副本,调用方可安全修改)。 */
EnumSet<Capability> supported();
/** 不支持的能力集合(副本),即 {@link Capability} 全集的差集。 */
EnumSet<Capability> unsupported();
}

6
core/src/main/java/common/ecommerce/capability/OrderEditCapable.java

@ -18,6 +18,10 @@ import java.util.List; @@ -18,6 +18,10 @@ import java.util.List;
*/
public interface OrderEditCapable extends PlatformAdapter {
/** 批量编辑订单;平台按单返回失败原因。 */
/**
* 批量编辑订单;平台按单返回失败原因。
*
* @return 逐单结果;全部失败时由门面转成 PlatformBusinessException
*/
OrderEditResult edit(ChannelContext ctx, List<OrderEditRequest> requests);
}

12
core/src/main/java/common/ecommerce/capability/OutboundCapable.java

@ -17,9 +17,17 @@ import java.util.List; @@ -17,9 +17,17 @@ import java.util.List;
*/
public interface OutboundCapable extends PlatformAdapter {
/** 提交出库任务;返回是否受理。 */
/**
* 提交出库任务;返回是否受理。
*
* <p>返回 true 不代表出库成功,只代表平台已接收任务;结果用 {@link #results} 回查。</p>
*/
boolean submit(ChannelContext ctx, List<OutboundPackage> packages);
/** 按系统单号查询出库结果。 */
/**
* 按系统单号查询出库结果。
*
* @return 每个系统单号的当前状态;平台未返回的单号不出现在结果中
*/
OutboundResult results(ChannelContext ctx, List<String> globalOrderNos);
}

6
core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java

@ -13,6 +13,10 @@ import common.ecommerce.sdk.ChannelContext; @@ -13,6 +13,10 @@ import common.ecommerce.sdk.ChannelContext;
*/
public interface OutboundOrderCapable extends PlatformAdapter {
/** 分页拉取销售出库单。 */
/**
* 分页拉取销售出库单。
*
* @return 当前页;{@link Page#nextCursor()} 为 null 表示没有下一页
*/
Page<OutboundOrder> pull(ChannelContext ctx, OutboundOrderQuery query);
}

47
core/src/main/java/common/ecommerce/capability/Outbounds.java

@ -26,15 +26,24 @@ import java.util.List; @@ -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 { @@ -52,6 +61,13 @@ public final class Outbounds {
return new Outbounds(adapter, account, ctx.withRequestId(requestId), observer);
}
/**
* 提交快速出库(写操作,调用方需包在 {@code sdk.writes()} 里)。
*
* <p>返回 true 只表示任务已受理,最终结果要用 {@link #results(java.util.List)} 回查。
*
* @throws ChannelException.UnsupportedCapabilityException 未声明 MARK_SHIPPED 或未实现 OutboundCapable
*/
public boolean submit(final List<OutboundPackage> packages) {
return CallSupport.observeSummary(observer, ctx, "outbounds.submit",
CallSupport.params("packageCount", packages == null ? 0 : packages.size()),
@ -64,6 +80,11 @@ public final class Outbounds { @@ -64,6 +80,11 @@ public final class Outbounds {
});
}
/**
* 按系统单号查询快速出库结果。
*
* @throws ChannelException.UnsupportedCapabilityException 未声明 MARK_SHIPPED 或未实现 OutboundCapable
*/
public OutboundResult results(final List<String> globalOrderNos) {
return CallSupport.observe(observer, ctx, "outbounds.results",
CallSupport.params("orderCount", globalOrderNos == null ? 0 : globalOrderNos.size()),
@ -74,7 +95,12 @@ public final class Outbounds { @@ -74,7 +95,12 @@ public final class Outbounds {
});
}
/** 销售出库单列表。 */
/**
* 销售出库单列表。
*
* @throws ChannelException.UnsupportedCapabilityException
* 未声明 OUTBOUND_ORDER 或未实现 OutboundOrderCapable
*/
public Page<OutboundOrder> pull(final OutboundOrderQuery query) {
return CallSupport.observe(observer, ctx, "outbounds.pull",
CallSupport.params(
@ -93,7 +119,11 @@ public final class Outbounds { @@ -93,7 +119,11 @@ public final class Outbounds {
});
}
/** 销售出库单物流面单。 */
/**
* 销售出库单物流面单。
*
* @throws ChannelException.UnsupportedCapabilityException 未声明 LABEL 或未实现 ShippingLabelCapable
*/
public List<ShippingLabel> labels(final LabelQuery query) {
return CallSupport.observe(observer, ctx, "outbounds.labels",
CallSupport.params(
@ -106,7 +136,14 @@ public final class Outbounds { @@ -106,7 +136,14 @@ public final class Outbounds {
});
}
/** 审核发货(写操作,调用方需包在 {@code sdk.writes()} 里)。 */
/**
* 审核发货(写操作,调用方需包在 {@code sdk.writes()} 里)。
*
* <p>全部失败时会抛 {@link PlatformBusinessException},避免幂等层误记为 SUCCEEDED。</p>
*
* @throws ChannelException.UnsupportedCapabilityException
* 未声明 SHIPMENT_REVIEW 或未实现 ShipmentReviewCapable
*/
public ShipmentReviewResult review(final List<String> globalOrderNos) {
return CallSupport.observeSummary(observer, ctx, "outbounds.review",
CallSupport.params("orderCount", globalOrderNos == null ? 0 : globalOrderNos.size()),
@ -131,6 +168,7 @@ public final class Outbounds { @@ -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 { @@ -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 { @@ -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);

7
core/src/main/java/common/ecommerce/capability/PlatformAdapter.java

@ -16,12 +16,13 @@ public interface PlatformAdapter { @@ -16,12 +16,13 @@ public interface PlatformAdapter {
/** 适配器标识,如 amazon-sc / lingxing。 */
String adapterId();
/** 该适配器所属接入通道;provider 与 platform 是两个维度,不要混用。 */
ChannelProvider provider();
/** 该适配器覆盖的平台。 */
Set<Platform> platforms();
/** 适配器能力并集。 */
/** 适配器能力并集;聚合器在未看账户时的粗粒度声明。 */
EnumSet<Capability> capabilities();
/**
@ -29,6 +30,10 @@ public interface PlatformAdapter { @@ -29,6 +30,10 @@ public interface PlatformAdapter {
*
* <p>直连适配器默认使用 {@link #capabilities()};聚合器按账户的子平台覆盖,
* 例如领星对 Walmart 支持标发、对 eBay 只支持订单。</p>
*
* @param account 账户配置;聚合器据此读取 platformCode / externalStoreId
* @param capability 待检查能力
* @return 该账户是否支持该能力
*/
default boolean supports(ChannelAccount account, Capability capability) {
return capabilities().contains(capability);

15
core/src/main/java/common/ecommerce/capability/ProductCapable.java

@ -16,10 +16,25 @@ public interface ProductCapable extends PlatformAdapter { @@ -16,10 +16,25 @@ public interface ProductCapable extends PlatformAdapter {
/** 适配器声明自己支持哪一种同步策略。 */
ProductSyncStrategy syncStrategy();
/**
* 分页拉取商品 / Listing。
*
* <p>适配器负责:ProductSearchField 到平台搜索编码的映射、时间窗解释、
* 游标透传。平台不支持某个过滤条件时必须显式报错,不能静默忽略。</p>
*
* @return 当前页;{@link Page#nextCursor()} 为 null 表示没有下一页
*/
Page<ProductListing> 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;
}

20
core/src/main/java/common/ecommerce/capability/Products.java

@ -14,15 +14,24 @@ import common.ecommerce.sdk.ChannelContext; @@ -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 { @@ -40,6 +49,11 @@ public final class Products {
return new Products(adapter, account, ctx.withRequestId(requestId), observer);
}
/**
* 拉取一页商品。
*
* @throws ChannelException.UnsupportedCapabilityException 适配器未声明 PRODUCT 或未实现 ProductCapable
*/
public Page<ProductListing> pull(final ProductQuery query) {
return CallSupport.observe(observer, ctx, "products.pull",
CallSupport.params(
@ -57,6 +71,11 @@ public final class Products { @@ -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 { @@ -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);

14
core/src/main/java/common/ecommerce/capability/SalesOrderCapable.java

@ -17,14 +17,24 @@ import common.ecommerce.sdk.ChannelContext; @@ -17,14 +17,24 @@ import common.ecommerce.sdk.ChannelContext;
*/
public interface SalesOrderCapable extends PlatformAdapter {
/** 分页拉取。时间窗与游标由适配器解释。 */
/**
* 分页拉取。时间窗与游标由适配器解释。
*
* @return 当前页;{@link Page#nextCursor()} 为 null 表示没有下一页
*/
Page<SalesOrder> 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)) {

30
core/src/main/java/common/ecommerce/capability/SalesOrders.java

@ -24,15 +24,24 @@ import java.util.List; @@ -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 { @@ -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<SalesOrder> pull(final SalesOrderQuery query) {
return CallSupport.observe(observer, ctx, "salesOrders.pull",
CallSupport.params(
@ -64,6 +78,11 @@ public final class SalesOrders { @@ -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 { @@ -74,7 +93,13 @@ public final class SalesOrders {
});
}
/** 批量编辑订单(写操作,调用方需包在 {@code sdk.writes()} 里)。 */
/**
* 批量编辑订单(写操作,调用方需包在 {@code sdk.writes()} 里)。
*
* <p>全部失败时会抛 {@link PlatformBusinessException},避免幂等层误记为 SUCCEEDED。</p>
*
* @throws ChannelException.UnsupportedCapabilityException 适配器未声明 ORDER_EDIT 或未实现 OrderEditCapable
*/
public OrderEditResult edit(final List<OrderEditRequest> requests) {
return CallSupport.observeSummary(observer, ctx, "salesOrders.edit",
CallSupport.params("requestCount", requests == null ? 0 : requests.size()),
@ -101,6 +126,7 @@ public final class SalesOrders { @@ -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 { @@ -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 { @@ -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);

5
core/src/main/java/common/ecommerce/capability/SettlementCapable.java

@ -13,5 +13,10 @@ import common.ecommerce.sdk.ChannelContext; @@ -13,5 +13,10 @@ import common.ecommerce.sdk.ChannelContext;
*/
public interface SettlementCapable extends PlatformAdapter {
/**
* 分页拉取结算交易明细。
*
* @return 当前页;平台按结算周期或修改时间解释查询条件
*/
Page<SettlementTransaction> pull(ChannelContext ctx, SettlementQuery query);
}

15
core/src/main/java/common/ecommerce/capability/Settlements.java

@ -15,15 +15,24 @@ import common.ecommerce.sdk.ChannelContext; @@ -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 { @@ -41,6 +50,11 @@ public final class Settlements {
return new Settlements(adapter, account, ctx.withRequestId(requestId), observer);
}
/**
* 拉取一页结算交易明细。
*
* @throws ChannelException.UnsupportedCapabilityException 未声明 BILLING 或未实现 SettlementCapable
*/
public Page<SettlementTransaction> pull(final SettlementQuery query) {
return CallSupport.observe(observer, ctx, "settlements.pull",
CallSupport.params(
@ -61,6 +75,7 @@ public final class Settlements { @@ -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);

6
core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java

@ -14,6 +14,10 @@ import java.util.List; @@ -14,6 +14,10 @@ import java.util.List;
*/
public interface ShipmentReviewCapable extends PlatformAdapter {
/** 按系统单号批量审核发货;逐单返回成功或失败原因。 */
/**
* 按系统单号批量审核发货;逐单返回成功或失败原因。
*
* @return 逐单结果;全部失败时由门面转成 PlatformBusinessException
*/
ShipmentReviewResult review(ChannelContext ctx, List<String> globalOrderNos);
}

6
core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java

@ -13,6 +13,10 @@ import java.util.List; @@ -13,6 +13,10 @@ import java.util.List;
*/
public interface ShippingLabelCapable extends PlatformAdapter {
/** 按销售出库单号或系统单号批量取面单。 */
/**
* 按销售出库单号或系统单号批量取面单。
*
* @return 面单列表;查不到时为 null 或空列表,由适配器约定
*/
List<ShippingLabel> labels(ChannelContext ctx, LabelQuery query);
}

8
core/src/main/java/common/ecommerce/error/AuthException.java

@ -2,15 +2,23 @@ package common.ecommerce.error; @@ -2,15 +2,23 @@ package common.ecommerce.error;
/**
* 认证失败:401/403、token 失效。刷新后重试一次;仍失败则告警并停用账户。
*
* <p>抛出于:HTTP 401/403,或平台业务码表示 token/签名问题(如领星
* {@code 2001003}、{@code 2001006}、{@code 2001007}、{@code 3001002})。</p>
*
* <p><b>是否可重试</b>:本类不自动设置 {@code retryable},默认 false;
* 调用方应先刷新 token 再重跑一次,二次失败按不可重试处理。</p>
*/
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);
}

70
core/src/main/java/common/ecommerce/error/ChannelException.java

@ -5,21 +5,46 @@ import common.ecommerce.model.Platform; @@ -5,21 +5,46 @@ import common.ecommerce.model.Platform;
/**
* 统一异常基类。适配器把平台错误映射到这里;{@code rawResponse} 必须已脱敏。
*
* <p>平台错误、HTTP 错误、能力缺失、幂等冲突都归到本层;子类用于让调用方区分处理方式。
* 是否重试只看 {@link #retryable()},<b>SDK 自身不做任何重试</b>。</p>
*
* <p>注意区分两个 ID:{@link #requestId()} 是我方链路 ID,
* {@link #platformRequestId()} 是平台工单号(如领星 {@code request_id})。</p>
*/
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 本身不重试。
*
* <p>取值为 true 时只代表「宿主可以重跑」,不代表重跑一定安全;
* 写操作是否可重跑还要看幂等层裁决。</p>
*/
private final boolean retryable;
/** 已脱敏的原始响应片段;没有或不便保存时为 null。<b>绝不能放密钥</b>。 */
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 { @@ -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;
}
/** <b>我方</b>链路 ID,用于串本地日志;平台工单号见 {@link #platformRequestId()}。 */
public String requestId() {
return requestId;
}
/** 平台业务码 / HTTP 状态码;无则为 null。 */
public String platformCode() {
return platformCode;
}
@ -71,57 +103,81 @@ public class ChannelException extends RuntimeException { @@ -71,57 +103,81 @@ public class ChannelException extends RuntimeException {
return platformRequestId;
}
/**
* 是否值得重试;由适配器显式设置,SDK 本身不重试。
*
* <p>与 {@code CallRecord.retryable()}、{@code IdempotencyGuard} 的失败终态判定一致。</p>
*/
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;
}
/** <b>我方</b>链路 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 { @@ -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 或人工兜底。
*
* <p>抛出于:适配器未实现对应 Capable 接口或未声明该 Capability。
* 不可重试({@code retryable=false})。</p>
*/
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 { @@ -166,6 +233,7 @@ public class ChannelException extends RuntimeException {
this.capability = capability;
}
/** 被拒绝的能力。 */
public Capability capability() {
return capability;
}

12
core/src/main/java/common/ecommerce/error/CrossProviderConflictException.java

@ -3,19 +3,29 @@ package common.ecommerce.error; @@ -3,19 +3,29 @@ package common.ecommerce.error;
/**
* 跨 provider 冲突:同一业务动作已由另一个 provider 完成。
*
* <p>不自动跨 provider 重试,必须人工确认。</p>
* <p>业务键(platform + omsStoreId + businessRef + action)不带 provider,
* 直连与聚合器共用;当记录显示已由别家完成时抛出。</p>
*
* <p><b>是否可重试</b>:不可重试({@code retryable=false}),不自动跨 provider 重试,
* 必须人工确认以哪条通道的结果为准。</p>
*/
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;
}

21
core/src/main/java/common/ecommerce/error/IdempotencyConflictException.java

@ -1,17 +1,36 @@ @@ -1,17 +1,36 @@
package common.ecommerce.error;
/** 写操作幂等冲突:重复写。返回已完成结果,不视为失败。 */
/**
* 写操作幂等冲突:重复写。返回已完成结果,不视为失败。
*
* <p>抛出于:业务键处于 IN_PROGRESS(另一个实例正在执行同一动作)。</p>
*
* <p><b>补充</b>:真正的「已成功」场景不会走本异常,
* {@code IdempotencyGuard} 会直接回放并返回 {@code WriteResult.ALREADY_COMPLETED}。</p>
*
* <p><b>是否可重试</b>:不应立即重试;等对方完成或抢占 TTL 过期后再来,
* 届时会走回放而不是再次执行。构造时 {@code retryable} 默认 false。</p>
*/
public class IdempotencyConflictException extends ChannelException {
private static final long serialVersionUID = 1L;
/**
* 冲突的幂等键。注意实际填的是<b>业务键</b>(跨 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;
}

7
core/src/main/java/common/ecommerce/error/PlatformBusinessException.java

@ -2,11 +2,18 @@ package common.ecommerce.error; @@ -2,11 +2,18 @@ package common.ecommerce.error;
/**
* 平台业务错误码。是否重试视错误码而定,保留 code/message/raw。
*
* <p>抛出于:平台返回非 0 业务码但又不是限流/认证问题;或批处理全部失败
* (如审核发货 {@code successNum=0 && failNum>0})。</p>
*
* <p><b>是否可重试</b>:默认不可重试;只有明确知道错误码可重跑时,
* 调用方才应把 {@code retryable(true)} 传进 Builder。</p>
*/
public class PlatformBusinessException extends ChannelException {
private static final long serialVersionUID = 1L;
/** @param b 异常字段构造器 */
public PlatformBusinessException(Builder b) {
super(b, null);
}

11
core/src/main/java/common/ecommerce/error/RateLimitException.java

@ -2,18 +2,29 @@ package common.ecommerce.error; @@ -2,18 +2,29 @@ package common.ecommerce.error;
/**
* 限流:429。遵守 Retry-After 并退避。
*
* <p>抛出于:HTTP 429,或平台业务码表示限流(如领星 {@code 3001008})。</p>
*
* <p><b>是否可重试</b>:语义上可以,但必须等待 {@link #retryAfterMillis()};
* 本类构造时不会自动把 {@code retryable} 置为 true,SDK 也不自动重试。</p>
*/
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;
}

6
core/src/main/java/common/ecommerce/error/TransientException.java

@ -2,11 +2,17 @@ package common.ecommerce.error; @@ -2,11 +2,17 @@ package common.ecommerce.error;
/**
* 瞬时错误:5xx / 网络 / 超时。退避加抖动后重试,超过上限进入补偿队列。
*
* <p>抛出于:HTTP 5xx、连接失败、读写超时。</p>
*
* <p><b>是否可重试</b>:通常可以;构造时由适配器显式 {@code retryable(true)}
* (SDK 不自动重试)。超时属于「结果未知」,适配器应先回查再决定能否重跑。</p>
*/
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);
}

6
core/src/main/java/common/ecommerce/error/ValidationException.java

@ -2,15 +2,21 @@ package common.ecommerce.error; @@ -2,15 +2,21 @@ package common.ecommerce.error;
/**
* 参数或映射错误:4xx。不重试,保留原始报文由人工修正映射。
*
* <p>抛出于:请求参数不合法、平台 4xx(401/403/429 除外),或响应字段无法映射。</p>
*
* <p><b>是否可重试</b>:不可重试,原样重跑只会再失败。</p>
*/
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);
}

43
core/src/main/java/common/ecommerce/idempotency/IdempotencyGuard.java

@ -58,18 +58,38 @@ import java.util.function.Supplier; @@ -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 { @@ -96,6 +116,10 @@ public final class IdempotencyGuard {
* @param action 平台写操作;抛 {@link ChannelException} 时按其 {@code retryable()} 决定是否可重试。
* <b>业务失败必须抛异常</b>,返回「失败结果」会被记成已成功
* @param resultRef 从执行结果中提取结果引用(订单号 / 包裹号等),可为 null
* @return 本次执行或回放的结果;回放时 {@code value()} 为 null
* @throws IdempotencyConflictException 业务键处于 IN_PROGRESS
* @throws CrossProviderConflictException 已由另一个 provider 完成
* @throws ChannelException 业务键 FAILED_FINAL,或 {@code action} 自己抛出
*/
public <T> WriteResult<T> execute(WriteScope scope, Supplier<T> action, Function<? super T, String> resultRef) {
Objects.requireNonNull(scope, "scope");
@ -151,6 +175,12 @@ public final class IdempotencyGuard { @@ -151,6 +175,12 @@ public final class IdempotencyGuard {
// ---------------------------------------------------------------- internals
/**
* 业务键或 provider 键未抢到时的统一裁决:回放、并发冲突或终态失败。
*
* <p>只处理非 ACQUIRED 的结果;ACQUIRED 走到这里属于实现缺陷,直接抛
* {@link IllegalStateException}。</p>
*/
private <T> WriteResult<T> handleNotAcquired(WriteScope scope, IdempotencyClaim claim,
String businessKey, String providerKey) {
IdempotencyRecord record = claim.record();
@ -187,6 +217,10 @@ public final class IdempotencyGuard { @@ -187,6 +217,10 @@ public final class IdempotencyGuard {
}
}
/**
* 回放已成功的结果;若原完成方是另一个 provider,则改抛
* {@link CrossProviderConflictException}(不自动跨 provider 重试)。
*/
private <T> WriteResult<T> replay(WriteScope scope, IdempotencyRecord record,
String businessKey, String providerKey,
WriteAudit.Stage stage) {
@ -219,16 +253,21 @@ public final class IdempotencyGuard { @@ -219,16 +253,21 @@ public final class IdempotencyGuard {
return e instanceof ChannelException && ((ChannelException) e).retryable();
}
/** 本实例标识。 */
public String owner() {
return owner;
}
/** 只读查询,供运维排查。 */
/**
* 按业务键查询当前幂等记录,只读查询,供运维排查。
*
* @return 无记录时为空 Optional
*/
public Optional<IdempotencyRecord> status(WriteScope scope) {
return store.get(scope.businessKey());
}
/** 该状态是否可安全重跑。 */
/** 该状态是否可安全重跑;只有 FAILED_RETRYABLE 返回 true。 */
public static boolean isRetryableStatus(IdempotencyStatus status) {
return status == IdempotencyStatus.FAILED_RETRYABLE;
}

4
core/src/main/java/common/ecommerce/idempotency/WriteAudit.java

@ -23,6 +23,7 @@ import java.util.Map; @@ -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 { @@ -32,6 +33,7 @@ final class WriteAudit {
*/
static final String OPERATION_PREFIX = "writes.";
/** 工具类,不实例化。 */
private WriteAudit() {
}
@ -52,6 +54,8 @@ final class WriteAudit { @@ -52,6 +54,8 @@ final class WriteAudit {
* 只有「观察者自身抛异常」才允许被吞掉。</p>
*
* @param observer 观察者;null 等价于 NOOP
* @param clock 取审计时间用的时钟;null 时 {@link Instant#now(Clock)} 会抛 NPE
* (属于调用方缺陷,不吞)
* @param scope 标识维度
* @param outcome 结论
* @param stage 守卫阶段

13
core/src/main/java/common/ecommerce/idempotency/WriteResult.java

@ -15,10 +15,15 @@ public final class WriteResult<T> { @@ -15,10 +15,15 @@ public final class WriteResult<T> {
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<T> { @@ -29,6 +34,7 @@ public final class WriteResult<T> {
this.providerKey = providerKey;
}
/** 本次真正调用了平台并成功。 */
public static <T> WriteResult<T> executed(T value, String resultRef, String businessKey, String providerKey) {
return new WriteResult<T>(Outcome.EXECUTED, value, resultRef, businessKey, providerKey);
}
@ -38,6 +44,7 @@ public final class WriteResult<T> { @@ -38,6 +44,7 @@ public final class WriteResult<T> {
return new WriteResult<T>(Outcome.ALREADY_COMPLETED, null, resultRef, businessKey, providerKey);
}
/** 执行结论。 */
public Outcome outcome() {
return outcome;
}
@ -47,23 +54,27 @@ public final class WriteResult<T> { @@ -47,23 +54,27 @@ public final class WriteResult<T> {
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) + '}';

28
core/src/main/java/common/ecommerce/idempotency/WriteScope.java

@ -18,11 +18,17 @@ import java.util.Objects; @@ -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 { @@ -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};
* <b>不得使用金额</b>
*/
@ -44,40 +52,56 @@ public final class WriteScope { @@ -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}。
*
* <p>不带 provider,直连与聚合器共用,保证同一业务动作只成功一次。</p>
*/
public String businessKey() {
return CanonicalKeys.businessIdempotencyKey(platform, omsStoreId, businessRef, action);
}
/** 单 provider 内的请求幂等键。 */
/**
* 单 provider 内的请求幂等键:
* {@code provider + platform + externalStoreId + action + businessRef}。
*
* <p>只防单 provider 内的重复请求/重试,不能替代 {@link #businessKey()}。</p>
*/
public String providerKey() {
return CanonicalKeys.providerRequestKey(provider, platform, externalStoreId, action, businessRef);
}
/** 便于排查;<b>不是</b>业务键或 provider 键,不要拿去当幂等键用。 */
@Override
public String toString() {
return provider + ":" + platform + ":" + omsStoreId + ":" + action + ":" + businessRef;

2
core/src/main/java/common/ecommerce/model/FulfillmentMode.java

@ -7,6 +7,6 @@ public enum FulfillmentMode { @@ -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
}

12
core/src/main/java/common/ecommerce/model/Platform.java

@ -24,8 +24,6 @@ public enum Platform { @@ -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 { @@ -33,19 +31,23 @@ public enum Platform {
/**
* Target。
*
* <p>领星侧没有独立的 Target 商品接口,商品走 Shopify 的
* {@code /basicOpen/multiplatform/shopify/variantList}。</p>
* <p>领星侧没有独立的 Target 商品接口,商品走
* {@code /basicOpen/multiplatform/shopify/variantList}(路径名是领星的历史命名)。</p>
*/
TARGET,
/** BestBuy。实测在领星 10034(Mirakl)下以 BSB-* 店铺出现。 */
BESTBUY,
/** AEPH(领星 platform_code 10005 / 10031)。 */
AEPH,
/** Wayfair。 */
WAYFAIR,
/** Michaels。 */
MICHAELS,
/** Echo。 */
ECHO,
/** Losdlius。 */
LOSDLIUS,
/** 自定义平台 */
/** 自定义平台:由适配器自行解释。 */
CUSTOM;
/** 是否属于 1P(平台向供应商采购)语义。 */

17
core/src/main/java/common/ecommerce/model/account/AccountKey.java

@ -14,8 +14,13 @@ import java.util.Objects; @@ -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 { @@ -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 { @@ -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;

65
core/src/main/java/common/ecommerce/model/account/ChannelAccount.java

@ -16,15 +16,34 @@ import java.util.Objects; @@ -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<String> 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 { @@ -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 { @@ -70,10 +94,12 @@ public final class ChannelAccount {
return platformCode;
}
/** 站点简称,如 na / eu;平台无关时可为 null。 */
public String region() {
return region;
}
/** 市场 ID 列表;不可变,单市场平台为空列表。 */
public List<String> marketplaceIds() {
return marketplaceIds;
}
@ -88,81 +114,120 @@ public final class ChannelAccount { @@ -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<String> 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<String> marketplaceIds) {
this.marketplaceIds = marketplaceIds == null ? Collections.<String>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);
}

156
core/src/main/java/common/ecommerce/model/aftersale/AfterSale.java

@ -16,35 +16,85 @@ import java.util.Objects; @@ -16,35 +16,85 @@ import java.util.Objects;
* 统一售后单(一行 = 一个售后商品行)。
*
* <p>平台侧的「售后单」往往是<b>按订单聚合、按商品行拆分</b>的(领星一份数据里带
* {@code item_list})。统一模型按<b>商品行</b>展开:一行对应一个
* {@link AfterSaleItem},避免下游再拆。</p>
* {@code item_list})。统一模型按<b>商品行</b>展开:一行对应一个商品行
* ({@link AfterSale} 本身),避免下游再拆。</p>
*
* <p>唯一标识 {@link #afterSaleId()} 参与 upsert;必须是稳定的平台侧标识。</p>
*/
public final class AfterSale {
/** 业务平台;必填,参与 canonicalKey。 */
private final Platform platform;
/** 宿主(OMS)侧店铺标识;必填,参与 canonicalKey。与平台店铺 ID(externalStoreId)不是一回事。 */
private final String omsStoreId;
/**
* 售后行唯一标识;必填,参与 upsert。
*
* <p>领星优先取 {@code md5_v2},其次 {@code item_identifier},
* 再退化为 {@code 订单号|msku|after_time|row_index};{@code id} 不唯一,不可用。</p>
*/
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<String, Object> attributes;
/** 接入通道(直连 / 领星等);必填,不参与 canonicalKey。 */
private final ChannelProvider sourceProvider;
private AfterSale(Builder b) {
@ -73,14 +123,17 @@ public final class AfterSale { @@ -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 { @@ -95,6 +148,7 @@ public final class AfterSale {
return channelOrderId;
}
/** 归一化售后类型;不会为 null。 */
public AfterSaleType type() {
return type;
}
@ -109,6 +163,7 @@ public final class AfterSale { @@ -109,6 +163,7 @@ public final class AfterSale {
return status;
}
/** 售后原因;无则为 null。 */
public String reason() {
return reason;
}
@ -123,10 +178,12 @@ public final class AfterSale { @@ -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 { @@ -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 { @@ -169,6 +228,7 @@ public final class AfterSale {
return exchangeOrderId;
}
/** 买家留言;无则为 null。 */
public String buyerNote() {
return buyerNote;
}
@ -178,63 +238,155 @@ public final class AfterSale { @@ -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<String, Object> 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<String, Object> v) {
this.attributes = v == null ? Collections.<String, Object>emptyMap() : v;
return this;
}
/** 设置接入通道;必填。 */
public Builder sourceProvider(ChannelProvider v) { this.sourceProvider = v; return this; }
/** 构建不可变售后行;缺少必填字段时抛 {@link NullPointerException}。 */
public AfterSale build() {
return new AfterSale(this);
}

39
core/src/main/java/common/ecommerce/model/aftersale/AfterSaleQuery.java

@ -15,12 +15,25 @@ import java.util.Objects; @@ -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<AfterSaleType> types;
/** 按平台订单号过滤(领星 {@code amazon_order_id_list});空列表表示不过滤,单次最多 50 个。 */
private final List<String> 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 { @@ -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 { @@ -50,6 +64,7 @@ public final class AfterSaleQuery {
return endDate;
}
/** 时间窗按哪个字段过滤;不会为 null。 */
public DateType dateType() {
return dateType;
}
@ -64,14 +79,17 @@ public final class AfterSaleQuery { @@ -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 { @@ -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<AfterSaleType> types = Collections.emptyList();
/** 平台订单号过滤;默认空列表表示不过滤。 */
private List<String> 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<AfterSaleType> types) {
this.types = types == null ? Collections.<AfterSaleType>emptyList() : types;
return this;
}
/** 设置平台订单号过滤;null 等价于空列表(不过滤)。 */
public Builder channelOrderIds(List<String> channelOrderIds) {
this.channelOrderIds = channelOrderIds == null
? Collections.<String>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);
}

2
core/src/main/java/common/ecommerce/model/aftersale/AfterSaleType.java

@ -14,6 +14,6 @@ public enum AfterSaleType { @@ -14,6 +14,6 @@ public enum AfterSaleType {
RETURN,
/** 换货。 */
EXCHANGE,
/** 无法识别;原值见 {@link AfterSaleItem#rawAfterType()}。 */
/** 无法识别;原值见 {@link AfterSale#rawType()}。 */
UNKNOWN
}

41
core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java

@ -13,15 +13,25 @@ import java.util.List; @@ -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<String> specialAttributes;
private DeclaredItem(Builder b) {
@ -38,6 +48,7 @@ public final class DeclaredItem { @@ -38,6 +48,7 @@ public final class DeclaredItem {
new ArrayList<String>(b.specialAttributes));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@ -52,10 +63,12 @@ public final class DeclaredItem { @@ -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 { @@ -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 { @@ -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 { @@ -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<String> 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<String> specialAttributes) {
this.specialAttributes = specialAttributes == null
? Collections.<String>emptyList() : specialAttributes;
return this;
}
/** 以可变参数设置特殊属性编码;null 视为空列表。 */
public Builder specialAttributes(String... specialAttributes) {
List<String> values = new ArrayList<String>();
if (specialAttributes != null) {
@ -191,6 +231,7 @@ public final class DeclaredItem { @@ -191,6 +231,7 @@ public final class DeclaredItem {
return this;
}
/** 构建报关明细;必填项缺失或非正数时抛 {@link IllegalArgumentException}。 */
public DeclaredItem build() {
return new DeclaredItem(this);
}

11
core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java

@ -12,7 +12,9 @@ import java.util.List; @@ -12,7 +12,9 @@ import java.util.List;
*/
public final class LabelQuery {
/** 销售出库单号列表(领星 {@code wo_number_arr}),与 {@link #orderNumbers} 二选一。 */
private final List<String> woNumbers;
/** 领星系统单号列表(领星 {@code order_number_arr}),与 {@link #woNumbers} 二选一。 */
private final List<String> orderNumbers;
private LabelQuery(Builder b) {
@ -20,6 +22,7 @@ public final class LabelQuery { @@ -20,6 +22,7 @@ public final class LabelQuery {
this.orderNumbers = Collections.unmodifiableList(new ArrayList<String>(b.orderNumbers));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@ -34,16 +37,21 @@ public final class LabelQuery { @@ -34,16 +37,21 @@ public final class LabelQuery {
return orderNumbers;
}
/** {@link LabelQuery} 构建器;构建时不校验,二选一由适配器在调用时显式检查。 */
public static final class Builder {
/** 销售出库单号;默认空列表,setter 传 null 也归一为空列表。 */
private List<String> woNumbers = Collections.emptyList();
/** 领星系统单号;默认空列表,setter 传 null 也归一为空列表。 */
private List<String> orderNumbers = Collections.emptyList();
/** 设置销售出库单号列表;null 视为空列表。 */
public Builder woNumbers(List<String> woNumbers) {
this.woNumbers = woNumbers == null ? Collections.<String>emptyList() : woNumbers;
return this;
}
/** 以可变参数设置销售出库单号;null 视为空列表。 */
public Builder woNumbers(String... woNumbers) {
List<String> values = new ArrayList<String>();
if (woNumbers != null) {
@ -53,11 +61,13 @@ public final class LabelQuery { @@ -53,11 +61,13 @@ public final class LabelQuery {
return this;
}
/** 设置领星系统单号列表;null 视为空列表。 */
public Builder orderNumbers(List<String> orderNumbers) {
this.orderNumbers = orderNumbers == null ? Collections.<String>emptyList() : orderNumbers;
return this;
}
/** 以可变参数设置领星系统单号;null 视为空列表。 */
public Builder orderNumbers(String... orderNumbers) {
List<String> values = new ArrayList<String>();
if (orderNumbers != null) {
@ -67,6 +77,7 @@ public final class LabelQuery { @@ -67,6 +77,7 @@ public final class LabelQuery {
return this;
}
/** 构建查询条件;是否二选一由适配器在调用时校验。 */
public LabelQuery build() {
return new LabelQuery(this);
}

42
core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java

@ -20,14 +20,23 @@ import java.util.List; @@ -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<DeclaredItem> declaredItems;
private OrderEditRequest(Builder b) {
@ -68,6 +77,7 @@ public final class OrderEditRequest { @@ -68,6 +77,7 @@ public final class OrderEditRequest {
}
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@ -107,10 +117,12 @@ public final class OrderEditRequest { @@ -107,10 +117,12 @@ public final class OrderEditRequest {
return packageWeight;
}
/** 是否修改报关信息。 */
public boolean modifyDeclared() {
return modifyDeclared;
}
/** 报关明细,不可变列表;未开启报关时为空列表。 */
public List<DeclaredItem> declaredItems() {
return declaredItems;
}
@ -122,84 +134,108 @@ public final class OrderEditRequest { @@ -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<DeclaredItem> 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<DeclaredItem> declaredItems) {
this.declaredItems = declaredItems == null
? Collections.<DeclaredItem>emptyList() : declaredItems;
return this;
}
/** 以可变参数设置报关明细;null 视为空列表。 */
public Builder declaredItems(DeclaredItem... declaredItems) {
List<DeclaredItem> values = new ArrayList<DeclaredItem>();
if (declaredItems != null) {
@ -209,6 +245,12 @@ public final class OrderEditRequest { @@ -209,6 +245,12 @@ public final class OrderEditRequest {
return this;
}
/**
* 构建请求。
*
* <p>包裹四项未同时设置、报关开关与明细不一致、或没有任何可改项时,
* 抛 {@link IllegalArgumentException}。</p>
*/
public OrderEditRequest build() {
return new OrderEditRequest(this);
}

22
core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java

@ -12,12 +12,18 @@ import java.util.List; @@ -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<Failure> failures;
private OrderEditResult(Builder b) {
@ -26,6 +32,7 @@ public final class OrderEditResult { @@ -26,6 +32,7 @@ public final class OrderEditResult {
this.failures = Collections.unmodifiableList(new ArrayList<Failure>(b.failures));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
@ -35,10 +42,12 @@ public final class OrderEditResult { @@ -35,10 +42,12 @@ public final class OrderEditResult {
return code;
}
/** 平台返回的消息。 */
public String message() {
return message;
}
/** 逐单失败明细,不可变列表。 */
public List<Failure> failures() {
return failures;
}
@ -51,44 +60,57 @@ public final class OrderEditResult { @@ -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<Failure> 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<Failure> failures) {
this.failures = failures == null ? Collections.<Failure>emptyList() : failures;
return this;
}
/** 构建结果。 */
public OrderEditResult build() {
return new OrderEditResult(this);
}

128
core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java

@ -21,40 +21,75 @@ import java.util.Objects; @@ -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<String> 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<OutboundOrderLine> lines;
private OutboundOrder(Builder b) {
@ -95,18 +130,22 @@ public final class OutboundOrder { @@ -95,18 +130,22 @@ public final class OutboundOrder {
this.lines = Collections.unmodifiableList(new ArrayList<OutboundOrderLine>(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 { @@ -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 { @@ -158,6 +200,7 @@ public final class OutboundOrder {
return status;
}
/** 出库单状态名称。 */
public String statusName() {
return statusName;
}
@ -167,34 +210,42 @@ public final class OutboundOrder { @@ -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 { @@ -204,6 +255,7 @@ public final class OutboundOrder {
return orderAmount;
}
/** 目的国家/地区代码。 */
public String targetCountry() {
return targetCountry;
}
@ -223,6 +275,7 @@ public final class OutboundOrder { @@ -223,6 +275,7 @@ public final class OutboundOrder {
return packageFeeWeight;
}
/** 包裹重量单位。 */
public String packageWeightUnit() {
return packageWeightUnit;
}
@ -232,10 +285,12 @@ public final class OutboundOrder { @@ -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 { @@ -250,224 +305,297 @@ public final class OutboundOrder {
return purchasedAt;
}
/** 商品行,不可变列表。 */
public List<OutboundOrderLine> 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<String> 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<OutboundOrderLine> 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<String> platformOrderNos) {
this.platformOrderNos = platformOrderNos == null
? Collections.<String>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<OutboundOrderLine> lines) {
this.lines = lines == null ? Collections.<OutboundOrderLine>emptyList() : lines;
return this;
}
/** 构建出库单;{@code omsStoreId}/{@code sourceProvider}/{@code woNumber} 为 null 时抛 NPE。 */
public OutboundOrder build() {
return new OutboundOrder(this);
}

27
core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java

@ -12,12 +12,19 @@ import java.util.Objects; @@ -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 { @@ -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 { @@ -39,6 +47,7 @@ public final class OutboundOrderLine {
return lineId;
}
/** 领星商品 id。 */
public String productId() {
return productId;
}
@ -53,10 +62,12 @@ public final class OutboundOrderLine { @@ -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 { @@ -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);
}

48
core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java

@ -22,16 +22,27 @@ public final class OutboundOrderQuery { @@ -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<String> sids;
/** 出库单状态过滤(领星 {@code status_arr}),含义见 {@link OutboundOrder#status()}。 */
private final List<Integer> statuses;
/** 物流下单状态过滤(领星 {@code logistics_status_arr})。 */
private final List<Integer> logisticsStatuses;
/** 平台订单号过滤(领星 {@code platform_order_no_arr})。 */
private final List<String> platformOrderNos;
/** 领星系统单号过滤(领星 {@code order_number_arr})。 */
private final List<String> orderNumbers;
/** 销售出库单号过滤(领星 {@code wo_number_arr})。 */
private final List<String> 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 { @@ -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 { @@ -86,26 +98,32 @@ public final class OutboundOrderQuery {
return logisticsStatuses;
}
/** 平台订单号过滤。 */
public List<String> platformOrderNos() {
return platformOrderNos;
}
/** 领星系统单号过滤。 */
public List<String> orderNumbers() {
return orderNumbers;
}
/** 销售出库单号过滤。 */
public List<String> 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 { @@ -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<String> sids = Collections.emptyList();
/** 出库单状态过滤;默认空列表。 */
private List<Integer> statuses = Collections.emptyList();
/** 物流下单状态过滤;默认空列表。 */
private List<Integer> logisticsStatuses = Collections.emptyList();
/** 平台订单号过滤;默认空列表。 */
private List<String> platformOrderNos = Collections.emptyList();
/** 领星系统单号过滤;默认空列表。 */
private List<String> orderNumbers = Collections.emptyList();
/** 销售出库单号过滤;默认空列表。 */
private List<String> 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<String> sids) {
this.sids = sids == null ? Collections.<String>emptyList() : sids;
return this;
}
/** 以可变参数设置店铺 id 过滤;null 视为空列表。 */
public Builder sids(String... sids) {
List<String> values = new ArrayList<String>();
if (sids != null) {
@ -164,11 +199,13 @@ public final class OutboundOrderQuery { @@ -164,11 +199,13 @@ public final class OutboundOrderQuery {
return this;
}
/** 设置出库单状态过滤;null 视为空列表。 */
public Builder statuses(List<Integer> statuses) {
this.statuses = statuses == null ? Collections.<Integer>emptyList() : statuses;
return this;
}
/** 以可变参数设置出库单状态过滤;null 视为空列表。 */
public Builder statuses(Integer... statuses) {
List<Integer> values = new ArrayList<Integer>();
if (statuses != null) {
@ -178,12 +215,14 @@ public final class OutboundOrderQuery { @@ -178,12 +215,14 @@ public final class OutboundOrderQuery {
return this;
}
/** 设置物流下单状态过滤;null 视为空列表。 */
public Builder logisticsStatuses(List<Integer> logisticsStatuses) {
this.logisticsStatuses = logisticsStatuses == null
? Collections.<Integer>emptyList() : logisticsStatuses;
return this;
}
/** 以可变参数设置物流下单状态过滤;null 视为空列表。 */
public Builder logisticsStatuses(Integer... logisticsStatuses) {
List<Integer> values = new ArrayList<Integer>();
if (logisticsStatuses != null) {
@ -193,12 +232,14 @@ public final class OutboundOrderQuery { @@ -193,12 +232,14 @@ public final class OutboundOrderQuery {
return this;
}
/** 设置平台订单号过滤;null 视为空列表。 */
public Builder platformOrderNos(List<String> platformOrderNos) {
this.platformOrderNos = platformOrderNos == null
? Collections.<String>emptyList() : platformOrderNos;
return this;
}
/** 以可变参数设置平台订单号过滤;null 视为空列表。 */
public Builder platformOrderNos(String... platformOrderNos) {
List<String> values = new ArrayList<String>();
if (platformOrderNos != null) {
@ -208,11 +249,13 @@ public final class OutboundOrderQuery { @@ -208,11 +249,13 @@ public final class OutboundOrderQuery {
return this;
}
/** 设置领星系统单号过滤;null 视为空列表。 */
public Builder orderNumbers(List<String> orderNumbers) {
this.orderNumbers = orderNumbers == null ? Collections.<String>emptyList() : orderNumbers;
return this;
}
/** 以可变参数设置领星系统单号过滤;null 视为空列表。 */
public Builder orderNumbers(String... orderNumbers) {
List<String> values = new ArrayList<String>();
if (orderNumbers != null) {
@ -222,11 +265,13 @@ public final class OutboundOrderQuery { @@ -222,11 +265,13 @@ public final class OutboundOrderQuery {
return this;
}
/** 设置销售出库单号过滤;null 视为空列表。 */
public Builder woNumbers(List<String> woNumbers) {
this.woNumbers = woNumbers == null ? Collections.<String>emptyList() : woNumbers;
return this;
}
/** 以可变参数设置销售出库单号过滤;null 视为空列表。 */
public Builder woNumbers(String... woNumbers) {
List<String> values = new ArrayList<String>();
if (woNumbers != null) {
@ -236,16 +281,19 @@ public final class OutboundOrderQuery { @@ -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);
}

59
core/src/main/java/common/ecommerce/model/fulfillment/OutboundPackage.java

@ -11,19 +11,33 @@ import java.util.Objects; @@ -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 { @@ -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);
}

14
core/src/main/java/common/ecommerce/model/fulfillment/OutboundResult.java

@ -9,7 +9,9 @@ import java.util.List; @@ -9,7 +9,9 @@ import java.util.List;
*/
public final class OutboundResult {
/** 出库成功组(领星 {@code data.success[]}),不可变,永不为 null。 */
private final List<Success> success;
/** 出库失败组(领星 {@code data.failure[]}),不可变,永不为 null。 */
private final List<Failure> failure;
private OutboundResult(List<Success> success, List<Failure> failure) {
@ -17,24 +19,31 @@ public final class OutboundResult { @@ -17,24 +19,31 @@ public final class OutboundResult {
this.failure = Collections.unmodifiableList(new ArrayList<Failure>(failure));
}
/** 构造结果;两个列表都会被复制为不可变列表。 */
public static OutboundResult of(List<Success> success, List<Failure> failure) {
return new OutboundResult(success, failure);
}
/** 出库成功组。 */
public List<Success> success() { return success; }
/** 出库失败组。 */
public List<Failure> 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 { @@ -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; }
}
}

24
core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java

@ -12,9 +12,13 @@ import java.util.List; @@ -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<String> successGlobalOrderNos;
/** 失败明细列表,不可变,永不为 null。 */
private final List<Failure> failures;
private ShipmentReviewResult(Builder b) {
@ -25,22 +29,27 @@ public final class ShipmentReviewResult { @@ -25,22 +29,27 @@ public final class ShipmentReviewResult {
this.failures = Collections.unmodifiableList(new ArrayList<Failure>(b.failures));
}
/** 新建构建器。 */
public static Builder builder() {
return new Builder();
}
/** 成功单数。 */
public int successNum() {
return successNum;
}
/** 失败单数。 */
public int failNum() {
return failNum;
}
/** 成功单的领星系统单号列表。 */
public List<String> successGlobalOrderNos() {
return successGlobalOrderNos;
}
/** 失败明细列表。 */
public List<Failure> failures() {
return failures;
}
@ -53,51 +62,66 @@ public final class ShipmentReviewResult { @@ -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<String> successGlobalOrderNos = Collections.emptyList();
/** 失败明细;默认空列表,setter 传 null 也归一为空列表。 */
private List<Failure> 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<String> successGlobalOrderNos) {
this.successGlobalOrderNos = successGlobalOrderNos == null
? Collections.<String>emptyList() : successGlobalOrderNos;
return this;
}
/** 设置失败明细;null 视为空列表。 */
public Builder failures(List<Failure> failures) {
this.failures = failures == null ? Collections.<Failure>emptyList() : failures;
return this;
}
/** 构建结果。 */
public ShipmentReviewResult build() {
return new ShipmentReviewResult(this);
}

39
core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java

@ -12,15 +12,25 @@ import java.util.Objects; @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

44
core/src/main/java/common/ecommerce/model/order/OrderLine.java

@ -9,11 +9,30 @@ import java.util.Objects; @@ -9,11 +9,30 @@ import java.util.Objects;
*/
public final class OrderLine {
/**
* 行标识,仅作展示/追溯;平台侧不一定稳定(如亚马逊 {@code order_item_id} 可能变更),
* 不要当 upsert 主键。平台不提供时为 null。
*/
private final String lineId;
/**
* 平台侧 SKU;必填,可关联商品 canonicalKey。
*
* <p>领星取 {@code msku}(顺序 SKU),亚马逊取 {@code seller_sku};
* 适配器在缺失时会回落到本地 SKU 或空串占位,因此可能为空串而不是 null。</p>
*/
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 { @@ -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);
}

66
core/src/main/java/common/ecommerce/model/order/SalesOrder.java

@ -17,15 +17,40 @@ import java.util.Objects; @@ -17,15 +17,40 @@ import java.util.Objects;
*/
public final class SalesOrder {
/** 宿主(OMS)侧店铺标识;必填,参与 canonicalKey。与平台店铺 ID(externalStoreId)不是一回事。 */
private final String omsStoreId;
/**
* 平台订单号;必填,参与 canonicalKey,必须稳定。
*
* <p>领星多平台 / 亚马逊路由取 {@code platform_info[].platform_order_no},缺失时回落
* {@code platform_order_name}、{@code global_order_no};领星 FBM 路由例外,
* 它就是领星系统单号 {@code order_number}。</p>
*/
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<OrderLine> 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 { @@ -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<OrderLine> 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<OrderLine> 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<OrderLine> lines) {
this.lines = lines == null ? Collections.<OrderLine>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);
}

6
core/src/main/java/common/ecommerce/model/order/SalesOrderRef.java

@ -12,6 +12,7 @@ import java.util.Objects; @@ -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 { @@ -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 + '}';

63
core/src/main/java/common/ecommerce/model/product/ProductListing.java

@ -27,7 +27,9 @@ public final class ProductListing { @@ -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 { @@ -42,7 +44,9 @@ public final class ProductListing {
// ---------------------------------------------------------------- 内容
/** 商品标题。 */
private final String title;
/** 图片 URL 列表;不可变,可能为空列表。 */
private final List<String> imageUrls;
/** 平台原始属性(尺寸、变体、排名等未标准化字段),键为渠道字段名。 */
private final java.util.Map<String, Object> attributes;
@ -64,6 +68,7 @@ public final class ProductListing { @@ -64,6 +68,7 @@ public final class ProductListing {
// ---------------------------------------------------------------- 来源
/** 该数据来自哪条接入通道;用于排查,不参与业务主键。 */
private final ChannelProvider sourceProvider;
private ProductListing(Builder b) {
@ -86,188 +91,246 @@ public final class ProductListing { @@ -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<String> imageUrls() {
return imageUrls;
}
/** 平台原始属性;不可变。 */
public java.util.Map<String, Object> 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<String> imageUrls = Collections.emptyList();
/** 平台原始属性;null 视为空 Map。 */
private java.util.Map<String, Object> 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<String> imageUrls) {
this.imageUrls = imageUrls == null ? Collections.<String>emptyList() : imageUrls;
return this;
}
/** 设置平台原始属性;null 视为空 Map。 */
public Builder attributes(java.util.Map<String, Object> attributes) {
this.attributes = attributes == null
? Collections.<String, Object>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);
}

32
core/src/main/java/common/ecommerce/model/product/ProductQuery.java

@ -21,12 +21,19 @@ import java.util.Objects; @@ -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<String> searchValues;
private ProductQuery(Builder b) {
@ -45,22 +52,27 @@ public final class ProductQuery { @@ -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 { @@ -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 { @@ -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<String> 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 { @@ -138,12 +163,17 @@ public final class ProductQuery {
return this;
}
/** 多个精确搜索;与 {@link #searchValue(String)} 互斥。 */
/** 多个精确搜索;与 {@link #searchValue(String)} 互斥,null 视为空列表。 */
public Builder searchValues(List<String> searchValues) {
this.searchValues = searchValues == null ? Collections.<String>emptyList() : searchValues;
return this;
}
/**
* 构建查询。
*
* @throws IllegalArgumentException 只给了搜索值没给 searchField,或模糊/精确同时设置
*/
public ProductQuery build() {
return new ProductQuery(this);
}

10
core/src/main/java/common/ecommerce/model/product/ProductRef.java

@ -7,6 +7,7 @@ import java.util.Objects; @@ -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 { @@ -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 + '}';

6
core/src/main/java/common/ecommerce/model/product/ProductSyncStrategy.java

@ -3,10 +3,10 @@ package common.ecommerce.model.product; @@ -3,10 +3,10 @@ package common.ecommerce.model.product;
/** 商品同步策略,适配器声明自己支持哪一种。 */
public enum ProductSyncStrategy {
/** 时间窗增量 */
/** 时间窗增量:按更新时间区间拉取,适合有稳定 updated_at 的平台。 */
INCREMENTAL_TIME_WINDOW,
/** 全量拉取 + 差异比对 */
/** 全量拉取 + 差异比对:平台不提供可靠增量时的退路,开销大。 */
FULL_PULL_DIFF,
/** 报告 / 文件 */
/** 报告 / 文件:平台异步生成文件,适配器需自行轮询并下载。 */
REPORT
}

61
core/src/main/java/common/ecommerce/model/settlement/SettlementQuery.java

@ -14,15 +14,40 @@ import java.util.List; @@ -14,15 +14,40 @@ import java.util.List;
*/
public final class SettlementQuery {
/**
* 结算时间起(含);按平台站点日期({@link LocalDate}),对应领星 {@code startDate}。
* 与 {@link #settledBefore} 组成<b>双闭区间</b>,跨度上限 7 天(含首尾)。
*/
private final LocalDate settledAfter;
/** 结算时间止(含);对应领星 {@code endDate};可空,与 {@link #settledAfter} 语义见上。 */
private final LocalDate settledBefore;
/**
* 修改时间起(含);对应领星 {@code gmtModifiedStart},按<b>北京时间</b>格式化后发送。
* 可空,但需与结算窗口或 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<String> 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 { @@ -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 { @@ -77,18 +103,22 @@ public final class SettlementQuery {
return searchField;
}
/** 精确搜索值列表;空列表表示不使用搜索值。 */
public List<String> 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 { @@ -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<String> 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<String> searchValues) {
this.searchValues = searchValues == null
? Collections.<String>emptyList() : searchValues;
return this;
}
/** 以可变参数设置精确搜索值;null 或空数组等价于空列表。 */
public Builder searchValues(String... searchValues) {
List<String> values = new ArrayList<String>();
if (searchValues != null) {
@ -166,16 +224,19 @@ public final class SettlementQuery { @@ -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);
}

117
core/src/main/java/common/ecommerce/model/settlement/SettlementTransaction.java

@ -16,25 +16,68 @@ import java.util.Objects; @@ -16,25 +16,68 @@ import java.util.Objects;
*/
public final class SettlementTransaction {
/** 宿主(OMS)侧店铺标识;必填,取账户上的 omsStoreId。 */
private final String omsStoreId;
/**
* 交易明细唯一标识;必填,重复同步按它 upsert。
*
* <p>领星优先取 {@code uniqueKey},其次 {@code md5},再退 {@code id};三者都没有时映射失败。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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 { @@ -124,6 +178,7 @@ public final class SettlementTransaction {
return amount;
}
/** 数量;平台未给时为 0。 */
public int quantity() {
return quantity;
}
@ -138,6 +193,7 @@ public final class SettlementTransaction { @@ -138,6 +193,7 @@ public final class SettlementTransaction {
return fundTransferStatus;
}
/** 结算单号;可空。 */
public String settlementId() {
return settlementId;
}
@ -147,133 +203,194 @@ public final class SettlementTransaction { @@ -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);
}

23
core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java

@ -20,13 +20,29 @@ import java.security.NoSuchAlgorithmException; @@ -20,13 +20,29 @@ import java.security.NoSuchAlgorithmException;
*/
public final class CanonicalKeys {
/** 工具类,禁止实例化。 */
private CanonicalKeys() {
}
/**
* 业务主键:platform + omsStoreId + 平台实体 ID。
*
* <p>不含 provider;直连与聚合器必须落到同一个键。</p>
*
* @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。
*
* <p>用于原始报文、水位线、审计;不要用于业务实体 upsert。</p>
*
* @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 { @@ -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 { @@ -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 { @@ -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");

49
core/src/main/java/common/ecommerce/model/support/Money.java

@ -12,7 +12,10 @@ import java.util.Objects; @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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();

17
core/src/main/java/common/ecommerce/model/support/Page.java

@ -11,8 +11,13 @@ import java.util.List; @@ -11,8 +11,13 @@ import java.util.List;
*/
public final class Page<T> {
/** 当前页条目;不可变。 */
private final List<T> items;
/** 下一页游标;null 表示没有下一页。 */
private final String nextCursor;
/** 是否还有下一页;由 nextCursor 是否为 null/空推导,不能从 items 数量推断。 */
private final boolean hasMore;
private Page(List<T> items, String nextCursor, boolean hasMore) {
@ -21,31 +26,41 @@ public final class Page<T> { @@ -21,31 +26,41 @@ public final class Page<T> {
this.hasMore = hasMore;
}
/**
* 构造非末页。
*
* <p>{@code nextCursor} 为 null 或空串时等价于 {@link #last(List)}。
*/
public static <T> Page<T> of(List<T> items, String nextCursor) {
return new Page<T>(items, nextCursor, nextCursor != null && !nextCursor.isEmpty());
}
/** 构造末页:{@code nextCursor} 为 null。 */
public static <T> Page<T> last(List<T> items) {
return new Page<T>(items, null, false);
}
/** 空末页。 */
public static <T> Page<T> empty() {
return new Page<T>(Collections.<T>emptyList(), null, false);
}
/** 当前页条目;不可变。 */
public List<T> 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();
}

20
core/src/main/java/common/ecommerce/model/support/PlatformTime.java

@ -16,7 +16,10 @@ public final class PlatformTime { @@ -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 { @@ -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 { @@ -42,6 +56,7 @@ public final class PlatformTime {
return utc;
}
/** 市场时区。 */
public ZoneId marketplaceZone() {
return marketplaceZone;
}
@ -61,6 +76,7 @@ public final class PlatformTime { @@ -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 { @@ -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 + ")";

17
core/src/main/java/common/ecommerce/sdk/AdapterFactory.java

@ -12,12 +12,23 @@ import java.util.EnumSet; @@ -12,12 +12,23 @@ import java.util.EnumSet;
*/
public interface AdapterFactory {
/** 工厂标识,如 amazon-sc / lingxing;用于日志与重复注册定位。 */
String adapterId();
/** 该工厂产出的适配器所属接入通道。 */
ChannelProvider provider();
/** 该工厂覆盖的平台;create 出来的适配器应声明同一集合。 */
EnumSet<Platform> platforms();
/**
* 创建适配器实例。
*
* <p>由 {@code ChannelSdk.Builder.build()} 在启动时调用一次;实现方自行装配
* 传输层、编解码、token 存储等依赖,SDK 不关心构造参数。</p>
*
* @param config 测试/联调参数;生产传 {@link AdapterConfig#NONE}
*/
PlatformAdapter create(AdapterConfig config);
/**
@ -33,8 +44,10 @@ public interface AdapterFactory { @@ -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 { @@ -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();
}

42
core/src/main/java/common/ecommerce/sdk/CallSupport.java

@ -33,6 +33,9 @@ public final class CallSupport { @@ -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 { @@ -60,9 +63,14 @@ public final class CallSupport {
return map;
}
/** 从返回值里取结果数量;不适用时返回 {@link #NO_COUNT}。 */
/**
* 结果数量提取器;不适用时返回 {@link #NO_COUNT}。
*
* @param <T> 门面方法的返回类型
*/
public interface ResultSize<T> {
/** 返回结果条目数;不适用时返回 {@link CallSupport#NO_COUNT}。 */
int sizeOf(T result);
}
@ -75,9 +83,16 @@ public final class CallSupport { @@ -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 { @@ -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 <T> 门面方法的返回类型
*/
public interface ResultMapper<T> {
/**
* 根据返回值生成摘要;返回 null 等价于 {@code SUCCESS + NO_COUNT}。
*
* <p>抛出运行时异常时同样兜底为 {@code SUCCESS + NO_COUNT},不影响业务返回值。</p>
*/
ResultSummary summarize(T result);
}
@ -137,6 +168,7 @@ public final class CallSupport { @@ -137,6 +168,7 @@ public final class CallSupport {
Supplier<T> action) {
return observeSummary(observer, ctx, operation, params,
new ResultMapper<T>() {
/** 只关心数量:null 结果或未提供提取器时记 NO_COUNT。 */
@Override
public ResultSummary summarize(T result) {
if (result == null || resultSize == null) {
@ -151,6 +183,8 @@ public final class CallSupport { @@ -151,6 +183,8 @@ public final class CallSupport {
/**
* 执行一次门面调用并记录日志(可区分成功 / 部分成功 / 失败)。
*
* <p>业务异常原样抛出;观察者异常吞掉并打 WARN。</p>
*
* @param mapper 结果摘要提取器;抛异常时按 {@code SUCCESS + NO_COUNT} 兜底,
* 不影响业务返回值
*/
@ -172,6 +206,7 @@ public final class CallSupport { @@ -172,6 +206,7 @@ public final class CallSupport {
}
}
/** 摘要提取的兜底:mapper 为 null、返回 null 或抛异常时统一记成成功且无数量。 */
private static <T> ResultSummary summarize(ResultMapper<T> mapper, T result) {
if (mapper == null) {
return ResultSummary.success(NO_COUNT);
@ -185,6 +220,9 @@ public final class CallSupport { @@ -185,6 +220,9 @@ public final class CallSupport {
}
}
/**
* 组装 {@link CallRecord} 并回调观察者;回调失败只打 WARN,不影响业务。
*/
private static void notifyObserver(CallObserver observer, ChannelContext ctx, String operation,
Map<String, Object> params, ResultSummary summary,
RuntimeException error,

12
core/src/main/java/common/ecommerce/sdk/ChannelConnection.java

@ -38,6 +38,11 @@ public final class ChannelConnection { @@ -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 { @@ -47,16 +52,23 @@ public final class ChannelConnection {
return endpointBaseUrl;
}
/** 凭据;已携带本次调用使用的端点,供 token 刷新回调使用。 */
public ChannelSecret secret() {
return secret;
}
/**
* 只保留基址与凭据指纹,可安全放进日志。
*
* <p>凭据本体(appSecret、clientSecret、refreshToken 等)不会出现在输出中。</p>
*/
@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) == '/') {

17
core/src/main/java/common/ecommerce/sdk/ChannelContext.java

@ -16,10 +16,19 @@ import java.util.Objects; @@ -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 { @@ -31,6 +40,11 @@ public final class ChannelContext {
this.clock = Objects.requireNonNull(clock, "clock");
}
/**
* 完整上下文:账户 + 连接 + 链路 ID + 时钟。
*
* <p>会发起真实请求的调用必须用这个工厂;账户与连接都不能为 null。</p>
*/
public static ChannelContext of(ChannelAccount account, ChannelConnection connection,
String requestId, Clock clock) {
Objects.requireNonNull(account, "account");
@ -80,14 +94,17 @@ public final class ChannelContext { @@ -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();
}

5
core/src/main/java/common/ecommerce/sdk/ChannelSdk.java

@ -122,6 +122,7 @@ public final class ChannelSdk implements ProviderResolver { @@ -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 { @@ -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 { @@ -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 { @@ -372,7 +375,9 @@ public final class ChannelSdk implements ProviderResolver {
*/
private Supplier<String> requestIdSupplier = DEFAULT_REQUEST_ID_SUPPLIER;
/** 缺省链路 ID 生成器:随机 UUID。 */
private static final Supplier<String> DEFAULT_REQUEST_ID_SUPPLIER = new Supplier<String>() {
/** 生成随机 UUID 作为链路 ID。 */
@Override
public String get() {
return UUID.randomUUID().toString();

5
core/src/main/java/common/ecommerce/sdk/ProviderResolver.java

@ -10,5 +10,10 @@ import common.ecommerce.model.account.AccountKey; @@ -10,5 +10,10 @@ import common.ecommerce.model.account.AccountKey;
*/
public interface ProviderResolver {
/**
* 按 AccountKey 找到对应适配器。
*
* @throws IllegalStateException provider + platform 组合未注册适配器
*/
PlatformAdapter resolve(AccountKey key);
}

32
core/src/main/java/common/ecommerce/spi/AccessToken.java

@ -5,12 +5,22 @@ import java.util.Objects; @@ -5,12 +5,22 @@ import java.util.Objects;
/**
* 访问令牌。
*
* <p>由适配器通过 {@link TokenStore} 读写;令牌本体只应存在于内存与宿主的加密存储中,
* 日志只能使用 {@link #fingerprint()}。</p>
*/
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 { @@ -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 { @@ -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);
}

14
core/src/main/java/common/ecommerce/spi/ChannelAccountRepository.java

@ -9,8 +9,20 @@ import java.util.Optional; @@ -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<ChannelAccount> findByKey(String provider, String platform, String omsStoreId);
/** 同一 omsStoreId 下所有 provider 账户。 */
/**
* 同一 omsStoreId 下所有 provider 账户。
*
* <p>用于展示「同一业务店铺有哪些接入通道」;没有时返回空列表。</p>
*/
java.util.List<ChannelAccount> findByOmsStoreId(String omsStoreId);
}

24
core/src/main/java/common/ecommerce/spi/ChannelSecret.java

@ -37,6 +37,7 @@ public final class ChannelSecret { @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

12
core/src/main/java/common/ecommerce/spi/IdempotencyClaim.java

@ -13,14 +13,22 @@ package common.ecommerce.spi; @@ -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 { @@ -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 { @@ -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) + '}';

21
core/src/main/java/common/ecommerce/spi/IdempotencyRecord.java

@ -13,11 +13,22 @@ import java.util.Objects; @@ -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 { @@ -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 { @@ -48,6 +66,7 @@ public final class IdempotencyRecord {
return provider;
}
/** 抢占方实例标识。 */
public String owner() {
return owner;
}
@ -57,10 +76,12 @@ public final class IdempotencyRecord { @@ -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

20
core/src/main/java/common/ecommerce/spi/IdempotencyStore.java

@ -16,19 +16,35 @@ public interface IdempotencyStore { @@ -16,19 +16,35 @@ public interface IdempotencyStore {
/**
* 抢占幂等键。
*
* <p>实现必须原子完成「查询 + 条件写入」,不能先查再写两步。</p>
*
* @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} 记为终态,不再自动重试。
*
* <p>只有当前 owner 可以写入,避免过期 owner 覆盖新抢占者的结果。</p>
*/
void fail(String key, String owner, boolean retryable, Instant now);
/**
* 读取幂等记录。
*
* @return 记录;从未写入时为 empty
*/
Optional<IdempotencyRecord> get(String key);
}

4
core/src/main/java/common/ecommerce/spi/LockProvider.java

@ -12,12 +12,14 @@ public interface LockProvider { @@ -12,12 +12,14 @@ public interface LockProvider {
*
* @param key 锁键
* @param ttlSeconds 锁自动过期时间
* @return 锁句柄;未获取到返回 empty
* @return 锁句柄;未获取到返回 empty。关闭句柄即释放锁,必须在 finally 中关闭
*/
Optional<Lock> tryLock(String key, long ttlSeconds);
/** 锁句柄;实现需保证 close 幂等,并只释放自己持有的锁。 */
interface Lock extends AutoCloseable {
/** 释放锁;重复调用不应报错。 */
@Override
void close();
}

3
core/src/main/java/common/ecommerce/spi/SecretProvider.java

@ -8,7 +8,10 @@ package common.ecommerce.spi; @@ -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);
}

10
core/src/main/java/common/ecommerce/spi/Sink.java

@ -12,7 +12,17 @@ import common.ecommerce.model.order.SalesOrder; @@ -12,7 +12,17 @@ import common.ecommerce.model.order.SalesOrder;
*/
public interface Sink {
/**
* 按 canonicalKey 写入一页销售订单。
*
* <p>空页也允许传入;实现必须幂等,重复同步不产生重复行。</p>
*/
void upsertSalesOrders(Page<SalesOrder> page);
/**
* 按 canonicalKey 写入一页商品。
*
* <p>空页也允许传入;实现必须幂等,重复同步不产生重复行。</p>
*/
void upsertProducts(Page<ProductListing> page);
}

16
core/src/main/java/common/ecommerce/spi/SyncCursorStore.java

@ -11,8 +11,22 @@ import java.time.Instant; @@ -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);
/**
* 推进水位线。
*
* <p>只能在整个批次成功后调用;引擎只会写入更新的终点,实现按传入值覆盖即可。</p>
*
* @param watermark 新水位线(UTC),不会为 null
*/
void advance(ChannelProvider provider, String accountKey, String stream, Instant watermark);
}

12
core/src/main/java/common/ecommerce/spi/TokenStore.java

@ -7,9 +7,21 @@ import java.util.Optional; @@ -7,9 +7,21 @@ import java.util.Optional;
*/
public interface TokenStore {
/**
* 读取令牌。
*
* @param tokenKey 令牌键,由适配器按 provider + 账户 + 作用域生成
* @return 令牌;没有或已失效时返回 empty
*/
Optional<AccessToken> get(String tokenKey);
/**
* 写入/覆盖令牌。宿主必须加密存储,且不得把令牌写入日志。
*/
void save(String tokenKey, AccessToken token);
/**
* 删除令牌(如刷新失败、账户解绑)。键不存在时视为成功。
*/
void remove(String tokenKey);
}

17
core/src/main/java/common/ecommerce/sync/SyncEngine.java

@ -26,11 +26,18 @@ import java.util.function.BiFunction; @@ -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 { @@ -39,9 +46,15 @@ public final class SyncEngine {
/**
* 同步销售订单。
*
* <p>整批成功才推进水位线;任何一页抛异常都会直接冒出,
* {@code SyncResult} 不会返回,水位线保持原值。引擎不私起线程/定时器。</p>
*
* @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<Instant, String, Page<SalesOrder>> fetch) {

11
core/src/main/java/common/ecommerce/sync/SyncResult.java

@ -2,11 +2,17 @@ package common.ecommerce.sync; @@ -2,11 +2,17 @@ package common.ecommerce.sync;
/**
* 单次同步结果。
*
* <p>只有正常跑完的批次才会生成;同步中途抛异常时不会返回本对象,
* 水位线也不会推进。</p>
*/
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 { @@ -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 { @@ -36,6 +46,7 @@ public final class SyncResult {
return watermarkAdvanced;
}
/** 便于日志输出。 */
@Override
public String toString() {
return "SyncResult{pages=" + pages + ", items=" + items + ", watermarkAdvanced=" + watermarkAdvanced + '}';

15
core/src/main/java/common/ecommerce/sync/SyncSpec.java

@ -15,9 +15,13 @@ public final class SyncSpec { @@ -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 { @@ -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 { @@ -49,9 +60,11 @@ public final class SyncSpec {
}
/**
* 计算增量起点。
* 计算增量起点:{@code watermark - overlap}。
*
* <p>没有水位线时返回 null,由调用方走首次全量。</p>
*
* @param watermark 上次成功同步的终点;null 表示尚未建底
*/
public Instant from(Instant watermark) {
return watermark == null ? null : watermark.minus(overlap);

3
lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java

@ -51,7 +51,8 @@ public enum LingxingApi { @@ -51,7 +51,8 @@ public enum LingxingApi {
LISTING_TEMU("/basicOpen/multiplatform/temu/list", 1),
/**
* 在线商品(变体维度),<b>Shopify(10002)与 Target 共用此接口</b>。
* 在线商品(变体维度),<b>Target 使用此接口</b>;
* 路径里的 shopify 是领星的历史命名,与业务平台无关。
* POST,offset/length(上限 1000),返回 data.list。
*/
LISTING_SHOPIFY("/basicOpen/multiplatform/shopify/variantList", 1),

8
lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java

@ -82,8 +82,7 @@ public final class LingxingConstants { @@ -82,8 +82,7 @@ public final class LingxingConstants {
* <table summary="platform_code 实测对照">
* <tr><th>code</th><th>实测店铺</th><th>Platform</th></tr>
* <tr><td>10001</td><td>AMZ-*</td><td>AMAZON_SC</td></tr>
* <tr><td>10002</td><td>SPF-*</td><td>SHOPIFY</td></tr>
* <tr><td>10003</td><td>EBA-*</td><td>EBAY</td></tr>
* <tr><td>10003</td><td>EBA-*</td><td>EBAY</td></tr>
* <tr><td>10005 / 10031</td><td>AEP-* / AEPH-*</td><td>AEPH</td></tr>
* <tr><td>10008</td><td>WMT-*</td><td>WALMART_SC</td></tr>
* <tr><td>10010</td><td>WAY-*</td><td>WAYFAIR</td></tr>
@ -105,7 +104,7 @@ public final class LingxingConstants { @@ -105,7 +104,7 @@ public final class LingxingConstants {
* <p>Target / BestBuy / AEPH / Michaels / ECHO / LOS-DLI-US 在领星侧没有独立平台码
* (多为自定义平台或共用 Mirakl)。<b>业务平台以账户的 {@code AccountKey.platform} 为准,
* 本方法只用于从响应行反推</b>。Target 没有独立的领星商品接口,
* 它的商品走 Shopify 的 {@code /basicOpen/multiplatform/shopify/variantList}。</p>
* 它的商品走 {@code /basicOpen/multiplatform/shopify/variantList}(领星的历史路径命名)。</p>
*/
public static Platform toPlatform(Integer platformCode) {
if (platformCode == null) {
@ -115,7 +114,8 @@ public final class LingxingConstants { @@ -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:

2
lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java

@ -169,7 +169,7 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -169,7 +169,7 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
@Override
public Set<Platform> 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,

2
lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatformDefaults.java

@ -14,7 +14,6 @@ import common.ecommerce.lingxing.platform.losdlius.LosDliUsSubPlatform; @@ -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 { @@ -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))

9
lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java

@ -217,7 +217,7 @@ public final class EbayProductSource implements LingxingProductSource { @@ -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<String, Object> body,
ProductQuery query) {
if (query == null || !query.hasSearch()) {
@ -225,11 +225,12 @@ public final class EbayProductSource implements LingxingProductSource { @@ -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);

29
lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java

@ -7,11 +7,15 @@ import java.util.List; @@ -7,11 +7,15 @@ import java.util.List;
/**
* 把统一的 SKU 搜索条件拼进领星请求体。
*
* <p>各平台字段名与形态不同:</p>
* <p>字段名按<b>实测</b>区分(2026-11,见 {@code ListingParamProbeTest}):</p>
* <ul>
* <li>沃尔玛 / eBay / Temu / SHEIN / TikTok / AliExpress:{@code searchField}(数字)
* + {@code searchSingleValue}(单值模糊)+ {@code searchValues}(多值精确)</li>
* <li>Shopify / Target:{@code search_field} + {@code search_single_value} + {@code search_values}</li>
* <li>Temu / SHEIN / TikTok / AliExpress:{@code searchField}(数字)
* + {@code searchSingleValue}(单值)+ {@code searchValues}(多值,均支持)</li>
* <li>沃尔玛 / eBay:{@code search_field} + {@code search_single_value}(<b>snake_case</b>)。
* 写成 camelCase 不会报错,但搜索条件被静默忽略、返回整页;
* 多值 {@code search_values} 同样被忽略或报 400,因此只支持单值。</li>
* <li>Target(走领星 shopify 路径):{@code search_field} + {@code search_single_value};
* 多值 {@code search_values} 返回 400,只支持单值。</li>
* <li>亚马逊 SC:{@code search_field}(字符串)+ {@code search_value}(数组)+ {@code exact_search}</li>
* </ul>
*/
@ -23,7 +27,7 @@ public final class LingxingProductSearchBody { @@ -23,7 +27,7 @@ public final class LingxingProductSearchBody {
/**
* camelCase 形态:searchField / searchSingleValue / searchValues。
*
* <p>用于 Temu、SHEIN、TikTok、AliExpress、沃尔玛、eBay。</p>
* <p>用于 Temu、SHEIN、TikTok、AliExpress(单值与多值均实测生效)。</p>
*/
public static void camelCase(java.util.Map<String, Object> body, ProductQuery query, Object fieldValue) {
if (query == null || !query.hasSearch()) {
@ -34,16 +38,23 @@ public final class LingxingProductSearchBody { @@ -34,16 +38,23 @@ public final class LingxingProductSearchBody {
}
/**
* snake_case 形态:search_field / search_single_value / search_values。
* snake_case 单值形态:search_field / search_single_value。
*
* <p>用于 Shopify、Target。</p>
* <p>用于沃尔玛、eBay、Target:参数名必须是 snake_case,且只支持单值。
* 传多值时抛 {@link UnsupportedOperationException},由各 Source 翻译成
* {@code ValidationException},避免静默返回整页。</p>
*/
public static void snakeCase(java.util.Map<String, Object> body, ProductQuery query, Object fieldValue) {
public static void snakeCaseSingle(java.util.Map<String, Object> 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());
}
/**

35
lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchMapper.java

@ -5,22 +5,23 @@ import common.ecommerce.model.product.ProductSearchField; @@ -5,22 +5,23 @@ import common.ecommerce.model.product.ProductSearchField;
/**
* 领星侧各平台的「搜索维度 → 平台枚举值」映射。
*
* <p>同一个语义在不同平台下的取值完全不同:</p>
* <p>同一个语义在不同平台下的取值完全不同(<b>2026-11 全部实测</b>,
* 方法见 {@code ListingParamProbeTest}:用真实 msku 回查 + 用不存在的值做对照):</p>
* <pre>
* 平台 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 不支持搜索
* </pre>
*
* <p>取值来源:领星文档(2026-10 摘录)+ AliExpress 实测(2026-11)。
* 未实测的平台按文档写,联调时用 {@code SearchFieldProbeTest} 逐个核对。</p>
* <p>注意:沃尔玛 / eBay 用 camelCase 时平台<b>不报错但静默忽略</b>搜索条件,
* 所以参数名必须与上表一致,见 {@link LingxingProductSearchBody}。</p>
*
* <p>用「按平台命名的方法」而不是「按 platform_code 查表」:每个 Source 只服务一个平台,
* 直接调自己那一个方法即可;AliExpress 的 platform_code 尚未确认,也不影响调用。
@ -62,16 +63,16 @@ public final class LingxingProductSearchMapper { @@ -62,16 +63,16 @@ public final class LingxingProductSearchMapper {
}
/**
* Shopify / Target:1 = msku。
* Target:1 = msku(实测)。
*
* <p>本地 SKU 的编码文档未给出,实测样本 {@code local_sku} 也为空,
* 暂时返回 null 表示不支持;联调时用探针确认后再补。</p>
* <p>该 app 下 {@code local_sku} 恒为空(翻 200 行全空),没有可对应的本地 SKU 编码,
* 因此对 {@link ProductSearchField#LOCAL_SKU} 显式抛异常,不静默退化为平台 SKU 查询。</p>
*/
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"。 */

58
lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/ShopifySubPlatform.java

@ -1,58 +0,0 @@ @@ -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;
}
}

166
lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyListingDto.java

@ -1,166 +0,0 @@ @@ -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[]})。
*
* <p>文档字段是 snake_case;这里用 camelCase 的 Java 字段 + {@code @JsonProperty} 映射。</p>
*
* <p>Shopify 按<b>变体(variant)</b>返回,{@code msku} 是平台侧 SKU。</p>
*/
@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<ShopifyLocationDto> locationInfos = new ArrayList<ShopifyLocationDto>();
}

49
lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/dto/ShopifyLocationDto.java

@ -1,49 +0,0 @@ @@ -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;
}

272
lingxing/src/main/java/common/ecommerce/lingxing/platform/shopify/product/ShopifyProductSource.java

@ -1,272 +0,0 @@ @@ -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 在线商品(变体维度)。
*
* <p>接口 {@code /basicOpen/multiplatform/shopify/variantList}:POST,{@code offset}/{@code length}
* (上限 1000),返回 {@code data.list};令牌桶容量 1。</p>
*/
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<ProductListing> 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<String, Object> body = new LinkedHashMap<String, Object>();
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<ShopifyListingDto> dtos = call.json().listAt(envelope.body(), "data.list", ShopifyListingDto.class);
List<ProductListing> out = new ArrayList<ProductListing>(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<String, Object> 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 商品 → 统一模型。
*
* <p>统一字段来源:</p>
* <ul>
* <li>platformSku ← {@code msku}</li>
* <li>listingId ← {@code product_unique_id}</li>
* <li>gtin ← 无</li>
* <li>title ← {@code title}</li>
* <li>imageUrls ← {@code picture_url},为空时用 {@code parent_picture_url}</li>
* <li>status ← {@code status}(1 active / 2 draft / 3 archived / 4 deleted)</li>
* <li>rawStatus ← {@code status_name} 原值</li>
* <li>price ← {@code price};currency 由 {@code currency_icon} 反推</li>
* <li>listedAt ← {@code listing_start_time}</li>
* <li>updatedAt ← 无(接口没有内容更新时间)</li>
* <li>attributes ← 其余全部原始字段</li>
* </ul>
*/
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.<String>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<String, Object> attributesOf(ShopifyListingDto dto) {
Map<String, Object> attrs = new LinkedHashMap<String, Object>();
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;
}
}

10
lingxing/src/main/java/common/ecommerce/lingxing/platform/target/TargetSubPlatform.java

@ -10,7 +10,7 @@ import common.ecommerce.lingxing.platform.LingxingSubPlatform; @@ -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; @@ -19,9 +19,9 @@ import common.ecommerce.model.Platform;
* <p>领星文档没有给出 Target 的独立 platform_code(多见于自定义平台或 Mirakl)。
* 订单与店铺都按<b>账户</b>的 platform_code 查询多平台接口,不按平台码反推。</p>
*
* <p>Target 没有独立的商品接口,商品走 Shopify 的
* {@code /basicOpen/multiplatform/shopify/variantList},因此复用
* {@link ShopifyProductSource}。</p>
* <p>Target 没有独立的商品接口,商品走领星的
* {@code /basicOpen/multiplatform/shopify/variantList}(路径名是领星的历史命名,
* 与业务平台无关),由 {@link TargetProductSource} 实现。</p>
*/
public final class TargetSubPlatform implements LingxingSubPlatform {
@ -34,7 +34,7 @@ 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);
}

48
lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java

@ -39,13 +39,34 @@ import java.util.Map; @@ -39,13 +39,34 @@ import java.util.Map;
*
* <p>{@code store_ids} 是<b>非必填</b>项:文档未标必填,不传时返回该 app 下所有店铺的商品。
* 这里按账户的 {@code externalStoreId} 过滤,避免把其它店铺的商品混进同一个 omsStoreId。</p>
*
* <p><b>时间窗(实测)</b>:{@code listing_time_field} + {@code listing_start_time} +
* {@code listing_end_time} 必须三者同时填或同时不填;日期精度 {@code Y-m-d},
* 不支持 {@code HH:mm:ss} 与 epoch;单边窗口返回 400。实测窗口跨度 1 年内均可用。</p>
*
* <p><b>搜索(实测)</b>:{@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 搜索无编码可用,显式不支持。</p>
*/
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<ProductListing> 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 { @@ -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<String, Object> body, ProductQuery query) {
Instant from = query.updatedAfter();
Instant to = query.updatedBefore();
@ -88,12 +112,15 @@ public final class TargetProductSource implements LingxingProductSource { @@ -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 { @@ -286,18 +313,19 @@ public final class TargetProductSource implements LingxingProductSource {
}
/** 统一 SKU 搜索 → shopify/target 的字段形态;未带搜索条件时什么也不做。 */
/** 统一 SKU 搜索 → Target 的字段形态;未带搜索条件时什么也不做。 */
private static void applySearch(java.util.Map<String, Object> 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);

22
lingxing/src/main/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSource.java

@ -34,11 +34,18 @@ import java.util.Map; @@ -34,11 +34,18 @@ import java.util.Map;
* (上限 1000)或 {@code cursorId} 游标分页,返回 {@code data.list};令牌桶容量 1。</p>
*
* <p>本实现固定走 offset 分页({@code useCursor=false}),游标以 offset 字符串表示。</p>
*
* <p><b>时间窗(实测)</b>:{@code updateStartTime}/{@code updateEndTime} 均为
* {@code yyyy-MM-dd HH:mm:ss},跨度不能超过 30 天,超过返回 500;单边填写同样返回 500。
* 因此这里两端必须同时给出:缺终点取当前时间,缺起点取终点前 30 天。</p>
*/
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 { @@ -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<String, Object> body, ProductQuery query) {
Instant from = query.updatedAfter();
Instant to = query.updatedBefore();
@ -85,12 +95,14 @@ public final class TemuProductSource implements LingxingProductSource { @@ -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。 */

9
lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java

@ -292,7 +292,7 @@ public final class WalmartProductSource implements LingxingProductSource { @@ -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<String, Object> body,
ProductQuery query) {
if (query == null || !query.hasSearch()) {
@ -300,11 +300,12 @@ public final class WalmartProductSource implements LingxingProductSource { @@ -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);

164
lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingSdkListingCallTest.java

@ -0,0 +1,164 @@ @@ -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 的端到端测试。
*
* <p>用 {@link RecordingTransport} 替掉网络,走真实的 {@link LingxingAdapter},
* 验证「门面 → 子平台 → Source」这条链路:能力检查、请求路径、SKU 搜索参数、
* 统一模型映射和调用日志。</p>
*/
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<CallRecord> records = new ArrayList<CallRecord>();
@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<ProductListing> 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<ProductListing> 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));
}
}

Some files were not shown because too many files have changed in this diff Show More

Loading…
Cancel
Save