diff --git a/core/src/main/java/common/ecommerce/audit/CallOutcome.java b/core/src/main/java/common/ecommerce/audit/CallOutcome.java index 7b91771..b1e3f00 100644 --- a/core/src/main/java/common/ecommerce/audit/CallOutcome.java +++ b/core/src/main/java/common/ecommerce/audit/CallOutcome.java @@ -2,13 +2,20 @@ package common.ecommerce.audit; /** * 一次 SDK 调用的结果状态。 + * + *
只有 {@link #SUCCESS} 表示完整成功;批处理部分失败是 {@link #PARTIAL}, + * 不能当成功处理(例如幂等层会把成功当成业务动作已完成)。
*/ public enum CallOutcome { - /** 调用成功(适配器没有抛异常)。 */ + /** 调用成功(适配器没有抛异常,且没有失败明细)。 */ SUCCESS, - /** 批处理部分成功:有失败明细,但调用方拿到了结果。 */ + /** + * 批处理部分成功:有失败明细,但调用方仍拿到了结果(如审核发货部分单失败)。 + * + *不算 {@link #SUCCESS};需要逐条看 {@code failedCount} / {@code resultCode}。
+ */ PARTIAL, /** 调用失败(能力不支持、参数校验、平台返回错误、网络异常等)。 */ diff --git a/core/src/main/java/common/ecommerce/audit/CallRecord.java b/core/src/main/java/common/ecommerce/audit/CallRecord.java index 8bd5a12..85f3e3e 100644 --- a/core/src/main/java/common/ecommerce/audit/CallRecord.java +++ b/core/src/main/java/common/ecommerce/audit/CallRecord.java @@ -23,25 +23,44 @@ import java.util.Objects; */ public final class CallRecord { + /** 调用开始时间(UTC);构造时必填。 */ private final Instant occurredAt; + /** 我方链路 ID(可注入 traceId),可能为 null;不是平台工单号。 */ private final String requestId; + /** 接入通道;账户/适配器还没解析出来时可能为 null。 */ private final ChannelProvider provider; + /** 业务平台;账户/适配器还没解析出来时可能为 null。 */ private final Platform platform; + /** 宿主侧店铺 ID,业务主键的一部分;可能为 null。 */ private final String omsStoreId; + /** 渠道侧店铺 ID(领星 {@code store_id}、亚马逊 SC {@code sid});无账户信息时为 null。 */ private final String externalStoreId; + /** 门面操作名,必填,如 {@code salesOrders.pull}。 */ private final String operation; + /** 结论,必填;{@link CallOutcome#PARTIAL} 是批处理部分失败,不能当成功处理。 */ private final CallOutcome outcome; + /** 耗时(毫秒),非负;测试注入固定时钟时为 0。 */ private final long durationMillis; + /** 结果条数;不适用(写操作等)为 -1。 */ private final int resultCount; + /** 失败条数;仅批处理结果有值,其余为 -1。 */ private final int failedCount; + /** 平台业务结果码(如编辑订单 {@code 10000} / {@code 10001});无则为 null。 */ private final String resultCode; + /** 参数摘要,只读;永不为 null,缺省为空 Map。只放非敏感摘要。 */ private final Map这是我方生成的 ID;平台侧工单号是 {@link #platformRequestId()},两者不能混。
+ */ public String requestId() { return requestId; } + /** 接入通道;未解析出账户/适配器时为 null。 */ public ChannelProvider provider() { return provider; } + /** 业务平台;未解析出账户/适配器时为 null。 */ public Platform platform() { return platform; } @@ -122,6 +148,7 @@ public final class CallRecord { return operation; } + /** 结论;PARTIAL 表示批处理部分失败,不算 SUCCESS。 */ public CallOutcome outcome() { return outcome; } @@ -188,10 +215,12 @@ public final class CallRecord { return platformCode; } + /** 是否失败;只有 {@link CallOutcome#FAILURE} 为 true,PARTIAL 仍算拿到了结果。 */ public boolean failed() { return outcome == CallOutcome.FAILURE; } + /** 便于排查/日志输出;包含失败字段(成功时不带 error 段)。 */ @Override public String toString() { return "CallRecord{" + outcome @@ -214,92 +243,130 @@ public final class CallRecord { + '}'; } + /** 可变构建器;{@link #build()} 时复制参数 Map 并转为只读。 */ public static final class Builder { + /** 调用开始时间(UTC);默认 {@link Instant#EPOCH},正式埋点必须覆盖。 */ private Instant occurredAt = Instant.EPOCH; + /** 我方链路 ID;默认 null。 */ private String requestId; + /** 接入通道;默认 null。 */ private ChannelProvider provider; + /** 业务平台;默认 null。 */ private Platform platform; + /** 宿主侧店铺 ID;默认 null。 */ private String omsStoreId; + /** 渠道侧店铺 ID;默认 null。 */ private String externalStoreId; + /** 门面操作名;必填,默认 null。 */ private String operation; + /** 结论;默认 {@link CallOutcome#SUCCESS},失败路径务必显式设置。 */ private CallOutcome outcome = CallOutcome.SUCCESS; + /** 耗时(毫秒);默认 0。 */ private long durationMillis; + /** 结果条数;默认 -1(不适用)。 */ private int resultCount = -1; + /** 失败条数;默认 -1(不适用)。 */ private int failedCount = -1; + /** 平台业务结果码;默认 null。 */ private String resultCode; + /** 参数摘要;默认空 Map,{@link #params(Map)} 传 null 也归一为空 Map。 */ private Map不会自动把 outcome 改成 FAILURE,需调用方显式设置。
+ */ public Builder error(Throwable error) { if (error != null) { this.errorType = error.getClass().getName(); @@ -314,6 +381,7 @@ public final class CallRecord { return this; } + /** 构造不可变记录;occurredAt / operation / outcome 不能为 null。 */ public CallRecord build() { return new CallRecord(this); } diff --git a/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java index 5fb0040..fe1bf51 100644 --- a/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java +++ b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java @@ -29,13 +29,17 @@ import java.util.Objects; */ public final class Slf4jCallObserver implements CallObserver { + /** 本类的日志器;日志绑定由宿主提供,SDK 不引入实现。 */ private static final Logger LOG = LoggerFactory.getLogger(Slf4jCallObserver.class); /** 默认时间格式:24 小时制、精确到秒,例如 {@code 2026-11-05 08:00:00}。 */ public static final String DEFAULT_TIME_PATTERN = "yyyy-MM-dd HH:mm:ss"; + /** 日志展示时区,非 null。 */ private final ZoneId zone; + /** 时间格式串,非 null。 */ private final String pattern; + /** 由 {@link #pattern} + {@link #zone} 构建的格式化器,线程安全。 */ private final DateTimeFormatter formatter; /** 使用 JVM 默认时区与默认格式 {@value #DEFAULT_TIME_PATTERN}。 */ @@ -76,6 +80,12 @@ public final class Slf4jCallObserver implements CallObserver { return formatter.format(instant); } + /** + * 每次调用结束打一行日志。 + * + *{@link CallRecord#failed()} 为 true 打 WARN,否则打 INFO—— + * 因此 PARTIAL 也是 INFO,失败明细看行内的 {@code failed=}。
+ */ @Override public void onCall(CallRecord record) { if (record.failed()) { @@ -123,6 +133,7 @@ public final class Slf4jCallObserver implements CallObserver { + " error=" + record.errorType() + ": " + safe(record.errorMessage()); } + /** 拼公共维度字段:provider / platform / 两侧店铺 ID / 我方链路 ID。 */ private static String providerFields(CallRecord record) { return " provider=" + record.provider() + " platform=" + record.platform() @@ -131,6 +142,7 @@ public final class Slf4jCallObserver implements CallObserver { + " requestId=" + record.requestId(); } + /** 按当前时区与格式渲染时间。 */ private String at(Instant instant) { return format(instant); } diff --git a/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java b/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java index 1af635c..19345b5 100644 --- a/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java +++ b/core/src/main/java/common/ecommerce/capability/AdapterCapabilityReport.java @@ -13,10 +13,20 @@ import java.util.EnumSet; */ public final class AdapterCapabilityReport implements CapabilityReport { + /** 被查询的适配器。 */ private final PlatformAdapter adapter; + + /** 被查询的账户;聚合器据此细化能力。 */ private final ChannelAccount account; + + /** 构造时算好的支持能力集。 */ private final EnumSet只读,不触发真实 API。
+ */ public AdapterCapabilityReport(PlatformAdapter adapter, ChannelAccount account) { this.adapter = adapter; this.account = account; @@ -28,16 +38,19 @@ public final class AdapterCapabilityReport implements CapabilityReport { } } + /** 该账户是否支持某能力。 */ @Override public boolean supports(Capability capability) { return supported.contains(capability); } + /** 支持的能力集合(副本)。 */ @Override public EnumSet需要完整信息时用 {@link #builder()}。
+ */ public SubChannel(int platformCode, String externalStoreId, Platform platform, String name) { this(platformCode, externalStoreId, platform, name, null, null, null, null, null, null, null, null, java.util.Collections.返回 true 不代表出库成功,只代表平台已接收任务;结果用 {@link #results} 回查。
+ */ boolean submit(ChannelContext ctx, List返回 true 只表示任务已受理,最终结果要用 {@link #results(java.util.List)} 回查。
+ *
+ * @throws ChannelException.UnsupportedCapabilityException 未声明 MARK_SHIPPED 或未实现 OutboundCapable
+ */
public boolean submit(final List 全部失败时会抛 {@link PlatformBusinessException},避免幂等层误记为 SUCCEEDED。 直连适配器默认使用 {@link #capabilities()};聚合器按账户的子平台覆盖,
* 例如领星对 Walmart 支持标发、对 eBay 只支持订单。 适配器负责:ProductSearchField 到平台搜索编码的映射、时间窗解释、
+ * 游标透传。平台不支持某个过滤条件时必须显式报错,不能静默忽略。 全部失败时会抛 {@link PlatformBusinessException},避免幂等层误记为 SUCCEEDED。 抛出于:HTTP 401/403,或平台业务码表示 token/签名问题(如领星
+ * {@code 2001003}、{@code 2001006}、{@code 2001007}、{@code 3001002})。 是否可重试:本类不自动设置 {@code retryable},默认 false;
+ * 调用方应先刷新 token 再重跑一次,二次失败按不可重试处理。 平台错误、HTTP 错误、能力缺失、幂等冲突都归到本层;子类用于让调用方区分处理方式。
+ * 是否重试只看 {@link #retryable()},SDK 自身不做任何重试。 注意区分两个 ID:{@link #requestId()} 是我方链路 ID,
+ * {@link #platformRequestId()} 是平台工单号(如领星 {@code request_id})。 取值为 true 时只代表「宿主可以重跑」,不代表重跑一定安全;
+ * 写操作是否可重跑还要看幂等层裁决。 与 {@code CallRecord.retryable()}、{@code IdempotencyGuard} 的失败终态判定一致。 抛出于:适配器未实现对应 Capable 接口或未声明该 Capability。
+ * 不可重试({@code retryable=false})。 不自动跨 provider 重试,必须人工确认。 业务键(platform + omsStoreId + businessRef + action)不带 provider,
+ * 直连与聚合器共用;当记录显示已由别家完成时抛出。 是否可重试:不可重试({@code retryable=false}),不自动跨 provider 重试,
+ * 必须人工确认以哪条通道的结果为准。 抛出于:业务键处于 IN_PROGRESS(另一个实例正在执行同一动作)。 补充:真正的「已成功」场景不会走本异常,
+ * {@code IdempotencyGuard} 会直接回放并返回 {@code WriteResult.ALREADY_COMPLETED}。 是否可重试:不应立即重试;等对方完成或抢占 TTL 过期后再来,
+ * 届时会走回放而不是再次执行。构造时 {@code retryable} 默认 false。 抛出于:平台返回非 0 业务码但又不是限流/认证问题;或批处理全部失败
+ * (如审核发货 {@code successNum=0 && failNum>0})。 是否可重试:默认不可重试;只有明确知道错误码可重跑时,
+ * 调用方才应把 {@code retryable(true)} 传进 Builder。 抛出于:HTTP 429,或平台业务码表示限流(如领星 {@code 3001008})。 是否可重试:语义上可以,但必须等待 {@link #retryAfterMillis()};
+ * 本类构造时不会自动把 {@code retryable} 置为 true,SDK 也不自动重试。 抛出于:HTTP 5xx、连接失败、读写超时。 是否可重试:通常可以;构造时由适配器显式 {@code retryable(true)}
+ * (SDK 不自动重试)。超时属于「结果未知」,适配器应先回查再决定能否重跑。 抛出于:请求参数不合法、平台 4xx(401/403/429 除外),或响应字段无法映射。 是否可重试:不可重试,原样重跑只会再失败。 只处理非 ACQUIRED 的结果;ACQUIRED 走到这里属于实现缺陷,直接抛
+ * {@link IllegalStateException}。
不带 provider,直连与聚合器共用,保证同一业务动作只成功一次。
+ */ public String businessKey() { return CanonicalKeys.businessIdempotencyKey(platform, omsStoreId, businessRef, action); } - /** 单 provider 内的请求幂等键。 */ + /** + * 单 provider 内的请求幂等键: + * {@code provider + platform + externalStoreId + action + businessRef}。 + * + *只防单 provider 内的重复请求/重试,不能替代 {@link #businessKey()}。
+ */ public String providerKey() { return CanonicalKeys.providerRequestKey(provider, platform, externalStoreId, action, businessRef); } + /** 便于排查;不是业务键或 provider 键,不要拿去当幂等键用。 */ @Override public String toString() { return provider + ":" + platform + ":" + omsStoreId + ":" + action + ":" + businessRef; diff --git a/core/src/main/java/common/ecommerce/model/FulfillmentMode.java b/core/src/main/java/common/ecommerce/model/FulfillmentMode.java index 859d9a2..6973294 100644 --- a/core/src/main/java/common/ecommerce/model/FulfillmentMode.java +++ b/core/src/main/java/common/ecommerce/model/FulfillmentMode.java @@ -7,6 +7,6 @@ public enum FulfillmentMode { THIRD_PARTY_SHIP, /** C:1P 代发(VC DF / 沃尔玛 DSV) */ VENDOR_DF_SHIP, - /** D:1P Retail 供应商供货 */ + /** D:1P Retail 供应商供货(856 ASN) */ VENDOR_RETAIL_ASN } diff --git a/core/src/main/java/common/ecommerce/model/Platform.java b/core/src/main/java/common/ecommerce/model/Platform.java index b29c6f8..21c177d 100644 --- a/core/src/main/java/common/ecommerce/model/Platform.java +++ b/core/src/main/java/common/ecommerce/model/Platform.java @@ -24,8 +24,6 @@ public enum Platform { EBAY, /** SHEIN(首期经领星接入) */ SHEIN, - /** Shopify(领星 platform_code 10002)。 */ - SHOPIFY, /** AliExpress(首期经领星接入) */ ALIEXPRESS, /** Mirakl 市场 */ @@ -33,19 +31,23 @@ public enum Platform { /** * Target。 * - *领星侧没有独立的 Target 商品接口,商品走 Shopify 的 - * {@code /basicOpen/multiplatform/shopify/variantList}。
+ *领星侧没有独立的 Target 商品接口,商品走 + * {@code /basicOpen/multiplatform/shopify/variantList}(路径名是领星的历史命名)。
*/ TARGET, /** BestBuy。实测在领星 10034(Mirakl)下以 BSB-* 店铺出现。 */ BESTBUY, /** AEPH(领星 platform_code 10005 / 10031)。 */ AEPH, + /** Wayfair。 */ WAYFAIR, + /** Michaels。 */ MICHAELS, + /** Echo。 */ ECHO, + /** Losdlius。 */ LOSDLIUS, - /** 自定义平台 */ + /** 自定义平台:由适配器自行解释。 */ CUSTOM; /** 是否属于 1P(平台向供应商采购)语义。 */ diff --git a/core/src/main/java/common/ecommerce/model/account/AccountKey.java b/core/src/main/java/common/ecommerce/model/account/AccountKey.java index 1f27609..f66f628 100644 --- a/core/src/main/java/common/ecommerce/model/account/AccountKey.java +++ b/core/src/main/java/common/ecommerce/model/account/AccountKey.java @@ -14,8 +14,13 @@ import java.util.Objects; */ public final class AccountKey { + /** 接入通道(直连 / 领星聚合等)。 */ private final ChannelProvider provider; + + /** 电商平台。 */ private final Platform platform; + + /** OMS 店铺 ID(业务归属),不是平台店铺 ID。 */ private final String omsStoreId; private AccountKey(ChannelProvider provider, Platform platform, String omsStoreId) { @@ -27,22 +32,32 @@ public final class AccountKey { this.omsStoreId = omsStoreId.trim(); } + /** + * 创建账户标识。 + * + * @throws NullPointerException provider 或 platform 为 null + * @throws IllegalArgumentException omsStoreId 为空白 + */ public static AccountKey of(ChannelProvider provider, Platform platform, String omsStoreId) { return new AccountKey(provider, platform, omsStoreId); } + /** 接入通道。 */ public ChannelProvider provider() { return provider; } + /** 电商平台。 */ public Platform platform() { return platform; } + /** OMS 店铺 ID。 */ public String omsStoreId() { return omsStoreId; } + /** 三维字段全部相等才相等。 */ @Override public boolean equals(Object o) { if (this == o) { @@ -57,11 +72,13 @@ public final class AccountKey { && omsStoreId.equals(that.omsStoreId); } + /** 与 {@link #equals(Object)} 一致。 */ @Override public int hashCode() { return Objects.hash(provider, platform, omsStoreId); } + /** 形如 {@code LINGXING:WALMART_SC:store-001}。 */ @Override public String toString() { return provider + ":" + platform + ":" + omsStoreId; diff --git a/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java b/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java index 2efe426..3a6e971 100644 --- a/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java +++ b/core/src/main/java/common/ecommerce/model/account/ChannelAccount.java @@ -16,15 +16,34 @@ import java.util.Objects; */ public final class ChannelAccount { + /** 三维账户标识。 */ private final AccountKey key; + + /** 平台店铺 ID / 领星 store_id;不是 OMS 的 storeId。 */ private final String externalStoreId; + + /** 领星 platform_code;直连账户为 null。 */ private final Integer platformCode; + + /** 站点简称,如 na / eu;平台无关时可为 null。 */ private final String region; + + /** 市场 ID 列表;单市场平台可为空列表。 */ private final List平台侧的「售后单」往往是按订单聚合、按商品行拆分的(领星一份数据里带 - * {@code item_list})。统一模型按商品行展开:一行对应一个 - * {@link AfterSaleItem},避免下游再拆。
+ * {@code item_list})。统一模型按商品行展开:一行对应一个商品行 + * ({@link AfterSale} 本身),避免下游再拆。 * *唯一标识 {@link #afterSaleId()} 参与 upsert;必须是稳定的平台侧标识。
*/ public final class AfterSale { + /** 业务平台;必填,参与 canonicalKey。 */ private final Platform platform; + + /** 宿主(OMS)侧店铺标识;必填,参与 canonicalKey。与平台店铺 ID(externalStoreId)不是一回事。 */ private final String omsStoreId; + + /** + * 售后行唯一标识;必填,参与 upsert。 + * + *领星优先取 {@code md5_v2},其次 {@code item_identifier}, + * 再退化为 {@code 订单号|msku|after_time|row_index};{@code id} 不唯一,不可用。
+ */ private final String afterSaleId; + + /** 原始订单的平台订单号;领星取 {@code amazon_order_id},可空。 */ private final String channelOrderId; + + /** 归一化售后类型;构造时 null 会落为 {@link AfterSaleType#UNKNOWN},不会为 null。 */ private final AfterSaleType type; + + /** 平台原始售后类型值(领星中文标签「退款 / 退货 / 换货」或数字),保留原值便于排查;可空。 */ private final String rawType; + + /** 平台原始退货状态(领星 {@code return_status});可空。 */ private final String status; + + /** 售后原因(领星 {@code after_reason});可空。 */ private final String reason; + + /** 售后数量;平台未给时为 0。 */ private final int quantity; + + /** 平台侧 SKU;领星取行级 {@code msku},缺失回落订单级 msku;可空。可用于关联商品 canonicalKey。 */ private final String platformSku; + + /** 本地(ERP)SKU;领星 {@code local_sku},可空。 */ private final String localSku; + + /** 亚马逊 ASIN;领星行级优先、订单级回落,非亚马逊平台为 null。 */ private final String asin; + + /** 本行退款金额(Money);币种来自平台,缺失币种时整体为 null,不猜。 */ private final Money refundAmount; + + /** 本行退款花费 / 平台手续费(Money);没有或无法确定币种时为 null。 */ private final Money refundCost; + + /** 售后发生时间;领星行级 {@code after_time} 优先,缺失回落订单级 {@code deal_time};可空。 */ private final PlatformTime afterSaleTime; + + /** 本行数据更新时间;增量同步用它判断。领星 {@code data_update_time} 优先,回落 {@code gmt_modified};可空。 */ private final PlatformTime updatedAt; + + /** 退货授权号(RMA);领星 {@code rma_order_number},可空。 */ private final String rmaNumber; + + /** 退货运单承运商;领星 {@code carriers},可空。 */ private final String carrier; + + /** 退货运单号;领星 {@code waybill_number},可空。 */ private final String trackingNumber; + + /** 换货产生的新订单号;领星 {@code exchange_order_number},无换货时为 null。 */ private final String exchangeOrderId; + + /** 买家留言;可空。 */ private final String buyerNote; + + /** 未标准化的原始字段(金额明细、库存属性、多渠道标记等),键名与平台一致;不为 null,可能为空 Map。 */ private final Map包裹四项未同时设置、报关开关与明细不一致、或没有任何可改项时, + * 抛 {@link IllegalArgumentException}。
+ */ public OrderEditRequest build() { return new OrderEditRequest(this); } diff --git a/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java b/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java index 8de31a5..0abadce 100644 --- a/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java +++ b/core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java @@ -12,12 +12,18 @@ import java.util.List; */ public final class OrderEditResult { + /** 全部成功。 */ public static final String CODE_SUCCESS = "0"; + /** 全部失败。 */ public static final String CODE_ALL_FAILED = "10000"; + /** 部分成功。 */ public static final String CODE_PARTIAL = "10001"; + /** 平台业务码:{@link #CODE_SUCCESS} / {@link #CODE_ALL_FAILED} / {@link #CODE_PARTIAL}。 */ private final String code; + /** 平台返回的消息,原值。 */ private final String message; + /** 逐单失败明细(领星 {@code data.error_details[]}),不可变,永不为 null。 */ private final List领星取 {@code msku}(顺序 SKU),亚马逊取 {@code seller_sku}; + * 适配器在缺失时会回落到本地 SKU 或空串占位,因此可能为空串而不是 null。
+ */ private final String platformSku; + + /** 购买数量;0 表示平台未给或解析失败,非 null。 */ private final int quantity; + + /** 商品单价;平台未给时为 null。币种通常与订单总额一致。 */ private final Money unitPrice; + + /** 行税额;平台未给时为 null。 */ private final Money tax; + + /** 行优惠/折扣金额;平台未给时为 null。 */ private final Money discount; private OrderLine(Builder b) { @@ -25,73 +44,98 @@ public final class OrderLine { this.discount = b.discount; } + /** 创建 Builder。 */ public static Builder builder() { return new Builder(); } + /** 行标识;平台不提供时为 null,不适合作为稳定主键。 */ public String lineId() { return lineId; } + /** 平台侧 SKU(领星 msku / 亚马逊 seller_sku),可能为空串但不会为 null。 */ public String platformSku() { return platformSku; } + /** 购买数量;平台未给时为 0。 */ public int quantity() { return quantity; } + /** 商品单价;平台未给时为 null。 */ public Money unitPrice() { return unitPrice; } + /** 行税额;平台未给时为 null。 */ public Money tax() { return tax; } + /** 行优惠/折扣金额;平台未给时为 null。 */ public Money discount() { return discount; } public static final class Builder { + /** 行标识;可空,仅作展示。 */ private String lineId; + + /** 平台侧 SKU;必填。 */ private String platformSku; + + /** 购买数量;平台未给时保持 0。 */ private int quantity; + + /** 商品单价;可空。 */ private Money unitPrice; + + /** 行税额;可空。 */ private Money tax; + + /** 行优惠/折扣金额;可空。 */ private Money discount; + /** 设置行标识;可空。 */ public Builder lineId(String lineId) { this.lineId = lineId; return this; } + /** 设置平台侧 SKU;必填。 */ public Builder platformSku(String platformSku) { this.platformSku = platformSku; return this; } + /** 设置购买数量。 */ public Builder quantity(int quantity) { this.quantity = quantity; return this; } + /** 设置商品单价;可空。 */ public Builder unitPrice(Money unitPrice) { this.unitPrice = unitPrice; return this; } + /** 设置行税额;可空。 */ public Builder tax(Money tax) { this.tax = tax; return this; } + /** 设置行优惠/折扣金额;可空。 */ public Builder discount(Money discount) { this.discount = discount; return this; } + /** 构建明细行;缺 platformSku 时抛 {@link NullPointerException}。 */ public OrderLine build() { return new OrderLine(this); } diff --git a/core/src/main/java/common/ecommerce/model/order/SalesOrder.java b/core/src/main/java/common/ecommerce/model/order/SalesOrder.java index 2c3858c..edfbcd3 100644 --- a/core/src/main/java/common/ecommerce/model/order/SalesOrder.java +++ b/core/src/main/java/common/ecommerce/model/order/SalesOrder.java @@ -17,15 +17,40 @@ import java.util.Objects; */ public final class SalesOrder { + /** 宿主(OMS)侧店铺标识;必填,参与 canonicalKey。与平台店铺 ID(externalStoreId)不是一回事。 */ private final String omsStoreId; + + /** + * 平台订单号;必填,参与 canonicalKey,必须稳定。 + * + *领星多平台 / 亚马逊路由取 {@code platform_info[].platform_order_no},缺失时回落 + * {@code platform_order_name}、{@code global_order_no};领星 FBM 路由例外, + * 它就是领星系统单号 {@code order_number}。
+ */ private final String channelOrderId; + + /** 平台原始订单状态,未归一化,由宿主解释;领星为数字状态(1 同步中 … 9 平台发货),可空。 */ private final String status; + + /** 买家姓名,平台字段原样;多数领星订单接口不返回,此时为 null。 */ private final String buyerName; + + /** 收货国家代码(ISO 3166-1 alpha-2,如 US / DE);领星取 store_Country_code,可空。 */ private final String shipToCountryCode; + + /** 订单明细行;不可变列表。空列表可能表示该接口未返回商品行(如 FBM 列表),不代表订单无商品。 */ private final List领星优先取 {@code uniqueKey},其次 {@code md5},再退 {@code id};三者都没有时映射失败。
+ */ private final String transactionKey; + + /** 接入通道(直连 / 领星等);必填。 */ private final ChannelProvider sourceProvider; + + /** 来源账户标识;领星取店铺 {@code sid},可空。 */ private final String sourceAccountId; + + /** 平台订单号;领星取 {@code amazon_order_id},费用行可能没有订单号(如广告费),此时为 null。 */ private final String channelOrderId; + + /** 平台店铺名称;展示用,可空。 */ private final String storeName; + + /** 站点/国家代码(如 US / DE);可空。 */ private final String countryCode; + + /** 配送方式(如 FBA / FBM);平台原值,可空。 */ private final String fulfillment; + + /** 来源事件,如 Shipment / Refund / ServiceFee。 */ private final String eventType; + + /** 交易类型,如 Commission / Tax / Refund。 */ private final String transactionType; + + /** 平台侧卖家 SKU;可空。注意此处是 seller_sku,不是领星 msku。 */ private final String sellerSku; + + /** 本地(ERP)SKU;可空。 */ private final String localSku; + + /** 亚马逊 ASIN;可空。 */ private final String asin; + + /** 金额(BigDecimal + 币种);平台未给金额或币种时整体为 null,不猜币种。 */ private final Money amount; + + /** 数量;平台未给时为 0。 */ private final int quantity; + + /** 结算状态:Open / Closed / Reconciled。 */ private final String processingStatus; + + /** 转账状态:Succeeded / Processing / Failed / Unknown。 */ private final String fundTransferStatus; + + /** 结算单号;领星取 {@code settlement_id},缺失回落 {@code fid},可空。 */ private final String settlementId; + + /** 结算时间;平台未给可解析时间时为 null。同时带 UTC 与市场时区。 */ private final PlatformTime postedAt; + + /** 站点名称,如 Amazon.com;可空。 */ private final String marketplaceName; private SettlementTransaction(Builder b) { @@ -60,10 +103,12 @@ public final class SettlementTransaction { this.marketplaceName = b.marketplaceName; } + /** 创建 Builder。 */ public static Builder builder() { return new Builder(); } + /** 宿主(OMS)侧店铺标识。 */ public String omsStoreId() { return omsStoreId; } @@ -73,26 +118,32 @@ public final class SettlementTransaction { return transactionKey; } + /** 接入通道。 */ public ChannelProvider sourceProvider() { return sourceProvider; } + /** 来源账户标识;领星为店铺 sid,可空。 */ public String sourceAccountId() { return sourceAccountId; } + /** 平台订单号;无关联订单的费用行为 null。 */ public String channelOrderId() { return channelOrderId; } + /** 平台店铺名称;可空。 */ public String storeName() { return storeName; } + /** 站点/国家代码;可空。 */ public String countryCode() { return countryCode; } + /** 配送方式(FBA / FBM 等);可空。 */ public String fulfillment() { return fulfillment; } @@ -107,14 +158,17 @@ public final class SettlementTransaction { return transactionType; } + /** 平台侧卖家 SKU(seller_sku);可空。 */ public String sellerSku() { return sellerSku; } + /** 本地(ERP)SKU;可空。 */ public String localSku() { return localSku; } + /** 亚马逊 ASIN;可空。 */ public String asin() { return asin; } @@ -124,6 +178,7 @@ public final class SettlementTransaction { return amount; } + /** 数量;平台未给时为 0。 */ public int quantity() { return quantity; } @@ -138,6 +193,7 @@ public final class SettlementTransaction { return fundTransferStatus; } + /** 结算单号;可空。 */ public String settlementId() { return settlementId; } @@ -147,133 +203,194 @@ public final class SettlementTransaction { return postedAt; } + /** 站点名称;可空。 */ public String marketplaceName() { return marketplaceName; } public static final class Builder { + /** 宿主(OMS)侧店铺标识;必填。 */ private String omsStoreId; + + /** 交易明细唯一标识;必填且必须稳定。 */ private String transactionKey; + + /** 接入通道;必填。 */ private ChannelProvider sourceProvider; + + /** 来源账户标识;可空。 */ private String sourceAccountId; + + /** 平台订单号;可空。 */ private String channelOrderId; + + /** 平台店铺名称;可空。 */ private String storeName; + + /** 站点/国家代码;可空。 */ private String countryCode; + + /** 配送方式;可空。 */ private String fulfillment; + + /** 来源事件;可空。 */ private String eventType; + + /** 交易类型;可空。 */ private String transactionType; + + /** 平台侧卖家 SKU;可空。 */ private String sellerSku; + + /** 本地(ERP)SKU;可空。 */ private String localSku; + + /** 亚马逊 ASIN;可空。 */ private String asin; + + /** 金额;可空。 */ private Money amount; + + /** 数量;未设置时为 0。 */ private int quantity; + + /** 结算状态;可空。 */ private String processingStatus; + + /** 转账状态;可空。 */ private String fundTransferStatus; + + /** 结算单号;可空。 */ private String settlementId; + + /** 结算时间;可空。 */ private PlatformTime postedAt; + + /** 站点名称;可空。 */ private String marketplaceName; + /** 设置宿主(OMS)侧店铺标识;必填。 */ public Builder omsStoreId(String omsStoreId) { this.omsStoreId = omsStoreId; return this; } + /** 设置交易明细唯一标识;必填且必须稳定。 */ public Builder transactionKey(String transactionKey) { this.transactionKey = transactionKey; return this; } + /** 设置接入通道;必填。 */ public Builder sourceProvider(ChannelProvider sourceProvider) { this.sourceProvider = sourceProvider; return this; } + /** 设置来源账户标识;可空。 */ public Builder sourceAccountId(String sourceAccountId) { this.sourceAccountId = sourceAccountId; return this; } + /** 设置平台订单号;可空。 */ public Builder channelOrderId(String channelOrderId) { this.channelOrderId = channelOrderId; return this; } + /** 设置平台店铺名称;可空。 */ public Builder storeName(String storeName) { this.storeName = storeName; return this; } + /** 设置站点/国家代码;可空。 */ public Builder countryCode(String countryCode) { this.countryCode = countryCode; return this; } + /** 设置配送方式;可空。 */ public Builder fulfillment(String fulfillment) { this.fulfillment = fulfillment; return this; } + /** 设置来源事件;可空。 */ public Builder eventType(String eventType) { this.eventType = eventType; return this; } + /** 设置交易类型;可空。 */ public Builder transactionType(String transactionType) { this.transactionType = transactionType; return this; } + /** 设置平台侧卖家 SKU;可空。 */ public Builder sellerSku(String sellerSku) { this.sellerSku = sellerSku; return this; } + /** 设置本地(ERP)SKU;可空。 */ public Builder localSku(String localSku) { this.localSku = localSku; return this; } + /** 设置亚马逊 ASIN;可空。 */ public Builder asin(String asin) { this.asin = asin; return this; } + /** 设置金额;可空。 */ public Builder amount(Money amount) { this.amount = amount; return this; } + /** 设置数量。 */ public Builder quantity(int quantity) { this.quantity = quantity; return this; } + /** 设置结算状态;可空。 */ public Builder processingStatus(String processingStatus) { this.processingStatus = processingStatus; return this; } + /** 设置转账状态;可空。 */ public Builder fundTransferStatus(String fundTransferStatus) { this.fundTransferStatus = fundTransferStatus; return this; } + /** 设置结算单号;可空。 */ public Builder settlementId(String settlementId) { this.settlementId = settlementId; return this; } + /** 设置结算时间;可空。 */ public Builder postedAt(PlatformTime postedAt) { this.postedAt = postedAt; return this; } + /** 设置站点名称;可空。 */ public Builder marketplaceName(String marketplaceName) { this.marketplaceName = marketplaceName; return this; } + /** 构建不可变交易明细;缺少必填字段时抛 {@link NullPointerException}。 */ public SettlementTransaction build() { return new SettlementTransaction(this); } diff --git a/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java b/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java index 5dbf7e4..beb5cc6 100644 --- a/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java +++ b/core/src/main/java/common/ecommerce/model/support/CanonicalKeys.java @@ -20,13 +20,29 @@ import java.security.NoSuchAlgorithmException; */ public final class CanonicalKeys { + /** 工具类,禁止实例化。 */ private CanonicalKeys() { } + /** + * 业务主键:platform + omsStoreId + 平台实体 ID。 + * + *不含 provider;直连与聚合器必须落到同一个键。
+ * + * @throws IllegalArgumentException 任一参数为空白 + */ public static String canonical(Platform platform, String omsStoreId, String platformEntityId) { return platform.name() + ':' + require(omsStoreId, "omsStoreId") + ':' + require(platformEntityId, "platformEntityId"); } + /** + * 来源键:provider + platform + externalStoreId + 平台实体 ID。 + * + *用于原始报文、水位线、审计;不要用于业务实体 upsert。
+ * + * @param externalStoreId 平台店铺 ID / 领星 store_id,不是 OMS 的 storeId + * @throws IllegalArgumentException 任一字符串参数为空白 + */ public static String source(ChannelProvider provider, Platform platform, String externalStoreId, String platformEntityId) { return provider.name() + ':' + platform.name() + ':' + require(externalStoreId, "externalStoreId") + ':' + require(platformEntityId, "platformEntityId"); @@ -69,7 +85,6 @@ public final class CanonicalKeys { return sha256Hex("DED|" + poNumber + '|' + invoiceNumber + '|' + type + '|' + amount + '|' + currency + '|' + period + '|' + reason); } - /** * 写操作业务幂等键:platform + omsStoreId + businessRef + action。 * @@ -91,6 +106,7 @@ public final class CanonicalKeys { + ':' + require(operation, "operation") + ':' + require(providerRef, "providerRef"); } + /** SHA-256 十六进制摘要;用于各类指纹。 */ static String sha256Hex(String raw) { try { MessageDigest md = MessageDigest.getInstance("SHA-256"); @@ -106,6 +122,11 @@ public final class CanonicalKeys { } } + /** + * 去空白并校验非空。 + * + * @throws IllegalArgumentException 值为 null 或空白 + */ private static String require(String value, String name) { if (value == null || value.trim().isEmpty()) { throw new IllegalArgumentException(name + " must not be blank"); diff --git a/core/src/main/java/common/ecommerce/model/support/Money.java b/core/src/main/java/common/ecommerce/model/support/Money.java index 0c28893..ab2c770 100644 --- a/core/src/main/java/common/ecommerce/model/support/Money.java +++ b/core/src/main/java/common/ecommerce/model/support/Money.java @@ -12,7 +12,10 @@ import java.util.Objects; */ public final class Money { + /** 金额,保留平台原始精度。 */ private final BigDecimal amount; + + /** 币种,参与运算前的同币种校验。 */ private final Currency currency; private Money(BigDecimal amount, Currency currency) { @@ -20,40 +23,71 @@ public final class Money { this.currency = Objects.requireNonNull(currency, "currency"); } + /** + * 由 {@link BigDecimal} 与币种代码构造。 + * + * @throws IllegalArgumentException 币种代码非法 + * @throws NullPointerException amount 为 null + */ public static Money of(BigDecimal amount, String currencyCode) { return new Money(amount, Currency.getInstance(currencyCode)); } + /** + * 由十进制字符串构造,避免 double 精度问题。 + * + * @throws NumberFormatException 金额字符串非法 + * @throws IllegalArgumentException 币种代码非法 + */ public static Money of(String amount, String currencyCode) { return of(new BigDecimal(amount), currencyCode); } + /** 指定币种的零值。 */ public static Money zero(String currencyCode) { return of(BigDecimal.ZERO, currencyCode); } + /** 金额原值,未做舍入。 */ public BigDecimal amount() { return amount; } + /** 币种。 */ public Currency currency() { return currency; } + /** ISO 币种代码,如 USD。 */ public String currencyCode() { return currency.getCurrencyCode(); } + /** + * 相加,不做隐式舍入。 + * + * @throws IllegalArgumentException 币种不同 + */ public Money add(Money other) { requireSameCurrency(other); return new Money(amount.add(other.amount), currency); } + /** + * 相减,不做隐式舍入。 + * + * @throws IllegalArgumentException 币种不同 + */ public Money subtract(Money other) { requireSameCurrency(other); return new Money(amount.subtract(other.amount), currency); } + /** + * 乘以系数,不做隐式舍入。 + * + * @param factor 乘数,不能为 null + */ public Money multiply(BigDecimal factor) { return new Money(amount.multiply(factor), currency); } @@ -63,15 +97,27 @@ public final class Money { return new Money(amount.setScale(currency.getDefaultFractionDigits(), RoundingMode.HALF_UP), currency); } + /** 金额是否为负(退款、扣款等)。 */ public boolean isNegative() { return amount.signum() < 0; } + /** + * 按金额数值比较,忽略标度差异({@code 1.0} 与 {@code 1.00} 相等)。 + * + * @throws IllegalArgumentException 币种不同 + */ public int compareTo(Money other) { requireSameCurrency(other); return amount.compareTo(other.amount); } + /** + * 校验同币种。 + * + * @throws NullPointerException other 为 null + * @throws IllegalArgumentException 币种不同 + */ private void requireSameCurrency(Money other) { Objects.requireNonNull(other, "other"); if (!currency.equals(other.currency)) { @@ -80,6 +126,7 @@ public final class Money { } } + /** 金额按数值比较、币种相同即相等(忽略标度差异)。 */ @Override public boolean equals(Object o) { if (this == o) { @@ -92,11 +139,13 @@ public final class Money { return amount.compareTo(that.amount) == 0 && currency.equals(that.currency); } + /** 与 {@link #equals(Object)} 一致;先去尾零再哈希。 */ @Override public int hashCode() { return Objects.hash(amount.stripTrailingZeros(), currency); } + /** 形如 {@code 12.34 USD}。 */ @Override public String toString() { return amount.toPlainString() + " " + currency.getCurrencyCode(); diff --git a/core/src/main/java/common/ecommerce/model/support/Page.java b/core/src/main/java/common/ecommerce/model/support/Page.java index 4592c65..d96864f 100644 --- a/core/src/main/java/common/ecommerce/model/support/Page.java +++ b/core/src/main/java/common/ecommerce/model/support/Page.java @@ -11,8 +11,13 @@ import java.util.List; */ public final class Page{@code nextCursor} 为 null 或空串时等价于 {@link #last(List)}。
+ */
public static 由 {@code ChannelSdk.Builder.build()} 在启动时调用一次;实现方自行装配
+ * 传输层、编解码、token 存储等依赖,SDK 不关心构造参数。 抛出运行时异常时同样兜底为 {@code SUCCESS + NO_COUNT},不影响业务返回值。 业务异常原样抛出;观察者异常吞掉并打 WARN。 凭据本体(appSecret、clientSecret、refreshToken 等)不会出现在输出中。 会发起真实请求的调用必须用这个工厂;账户与连接都不能为 null。 由适配器通过 {@link TokenStore} 读写;令牌本体只应存在于内存与宿主的加密存储中,
+ * 日志只能使用 {@link #fingerprint()}。 用于展示「同一业务店铺有哪些接入通道」;没有时返回空列表。 实现必须原子完成「查询 + 条件写入」,不能先查再写两步。 只有当前 owner 可以写入,避免过期 owner 覆盖新抢占者的结果。 空页也允许传入;实现必须幂等,重复同步不产生重复行。 空页也允许传入;实现必须幂等,重复同步不产生重复行。 只能在整个批次成功后调用;引擎只会写入更新的终点,实现按传入值覆盖即可。 整批成功才推进水位线;任何一页抛异常都会直接冒出,
+ * {@code SyncResult} 不会返回,水位线保持原值。引擎不私起线程/定时器。 只有正常跑完的批次才会生成;同步中途抛异常时不会返回本对象,
+ * 水位线也不会推进。 没有水位线时返回 null,由调用方走首次全量。 Target / BestBuy / AEPH / Michaels / ECHO / LOS-DLI-US 在领星侧没有独立平台码
* (多为自定义平台或共用 Mirakl)。业务平台以账户的 {@code AccountKey.platform} 为准,
* 本方法只用于从响应行反推。Target 没有独立的领星商品接口,
- * 它的商品走 Shopify 的 {@code /basicOpen/multiplatform/shopify/variantList}。 各平台字段名与形态不同: 字段名按实测区分(2026-11,见 {@code ListingParamProbeTest}): 用于 Temu、SHEIN、TikTok、AliExpress、沃尔玛、eBay。 用于 Temu、SHEIN、TikTok、AliExpress(单值与多值均实测生效)。 用于 Shopify、Target。 用于沃尔玛、eBay、Target:参数名必须是 snake_case,且只支持单值。
+ * 传多值时抛 {@link UnsupportedOperationException},由各 Source 翻译成
+ * {@code ValidationException},避免静默返回整页。 同一个语义在不同平台下的取值完全不同: 同一个语义在不同平台下的取值完全不同(2026-11 全部实测,
+ * 方法见 {@code ListingParamProbeTest}:用真实 msku 回查 + 用不存在的值做对照): 取值来源:领星文档(2026-10 摘录)+ AliExpress 实测(2026-11)。
- * 未实测的平台按文档写,联调时用 {@code SearchFieldProbeTest} 逐个核对。 注意:沃尔玛 / eBay 用 camelCase 时平台不报错但静默忽略搜索条件,
+ * 所以参数名必须与上表一致,见 {@link LingxingProductSearchBody}。 用「按平台命名的方法」而不是「按 platform_code 查表」:每个 Source 只服务一个平台,
* 直接调自己那一个方法即可;AliExpress 的 platform_code 尚未确认,也不影响调用。
@@ -62,16 +63,16 @@ public final class LingxingProductSearchMapper {
}
/**
- * Shopify / Target:1 = msku。
+ * Target:1 = msku(实测)。
*
- * 本地 SKU 的编码文档未给出,实测样本 {@code local_sku} 也为空,
- * 暂时返回 null 表示不支持;联调时用探针确认后再补。 该 app 下 {@code local_sku} 恒为空(翻 200 行全空),没有可对应的本地 SKU 编码,
+ * 因此对 {@link ProductSearchField#LOCAL_SKU} 显式抛异常,不静默退化为平台 SKU 查询。 文档字段是 snake_case;这里用 camelCase 的 Java 字段 + {@code @JsonProperty} 映射。 Shopify 按变体(variant)返回,{@code msku} 是平台侧 SKU。 接口 {@code /basicOpen/multiplatform/shopify/variantList}:POST,{@code offset}/{@code length}
- * (上限 1000),返回 {@code data.list};令牌桶容量 1。 统一字段来源: 领星文档没有给出 Target 的独立 platform_code(多见于自定义平台或 Mirakl)。
* 订单与店铺都按账户的 platform_code 查询多平台接口,不按平台码反推。 Target 没有独立的商品接口,商品走 Shopify 的
- * {@code /basicOpen/multiplatform/shopify/variantList},因此复用
- * {@link ShopifyProductSource}。 Target 没有独立的商品接口,商品走领星的
+ * {@code /basicOpen/multiplatform/shopify/variantList}(路径名是领星的历史命名,
+ * 与业务平台无关),由 {@link TargetProductSource} 实现。 {@code store_ids} 是非必填项:文档未标必填,不传时返回该 app 下所有店铺的商品。
* 这里按账户的 {@code externalStoreId} 过滤,避免把其它店铺的商品混进同一个 omsStoreId。 时间窗(实测):{@code listing_time_field} + {@code listing_start_time} +
+ * {@code listing_end_time} 必须三者同时填或同时不填;日期精度 {@code Y-m-d},
+ * 不支持 {@code HH:mm:ss} 与 epoch;单边窗口返回 400。实测窗口跨度 1 年内均可用。 搜索(实测):{@code search_field=1} 对应 {@code msku},
+ * {@code search_field=2} 对应 {@code item_id},{@code search_field=4} 对应标题(模糊);
+ * 多值 {@code search_values} 返回 400,只支持单值。该 app 下 {@code local_sku} 恒为空,
+ * 本地 SKU 搜索无编码可用,显式不支持。 本实现固定走 offset 分页({@code useCursor=false}),游标以 offset 字符串表示。 时间窗(实测):{@code updateStartTime}/{@code updateEndTime} 均为
+ * {@code yyyy-MM-dd HH:mm:ss},跨度不能超过 30 天,超过返回 500;单边填写同样返回 500。
+ * 因此这里两端必须同时给出:缺终点取当前时间,缺起点取终点前 30 天。 用 {@link RecordingTransport} 替掉网络,走真实的 {@link LingxingAdapter},
+ * 验证「门面 → 子平台 → Source」这条链路:能力检查、请求路径、SKU 搜索参数、
+ * 统一模型映射和调用日志。 Target 的本地 SKU 搜索编码尚未确认,传了必须显式失败。 实测:时间窗三字段必须同时出现且只接受 {@code Y-m-d};多值搜索返回 400;
+ * {@code local_sku} 在该 app 下恒为空,本地 SKU 搜索显式不支持。 默认跳过;用 {@code -Dlingxing.probe=true} 显式开启。只做查询。 默认跳过;用 {@code -Dlingxing.probe=true} 显式开启。 只做查询。会打印请求体(截断)与统一模型的关键字段,
+ * 便于对照接口文档核对分页、日期、SKU 搜索三项参数。
*
* code 实测店铺 Platform
- * 10001 AMZ-* AMAZON_SC
- * 10002 SPF-* SHOPIFY
+ * 10003 EBA-* EBAY
* 10003 EBA-* EBAY
* 10005 / 10031 AEP-* / AEPH-* AEPH
* 10008 WMT-* WALMART_SC
@@ -105,7 +104,7 @@ public final class LingxingConstants {
* 10010 WAY-* WAYFAIR
- *
*/
@@ -23,7 +27,7 @@ public final class LingxingProductSearchBody {
/**
* camelCase 形态:searchField / searchSingleValue / searchValues。
*
- *
- * 平台 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 不支持搜索
*
*
- *
- *
- */
- 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.