diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java index c240ad0..98a6b0e 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java @@ -217,7 +217,7 @@ public final class EbayProductSource implements LingxingProductSource { return trimmed.isEmpty() ? null : trimmed; } - /** 统一 SKU 搜索 → ebay 的字段形态;未带搜索条件时什么也不做。 */ + /** 统一 SKU 搜索 → eBay 的字段形态;未带搜索条件时什么也不做。 */ private static void applySearch(java.util.Map body, ProductQuery query) { if (query == null || !query.hasSearch()) { @@ -225,11 +225,12 @@ public final class EbayProductSource implements LingxingProductSource { } try { Object fieldValue = LingxingProductSearchMapper.ebay(query.searchField()); - LingxingProductSearchBody.camelCase(body, query, fieldValue); + // 实测:camelCase 的 searchField 会被静默忽略并返回整页,必须用 snake_case; + // 多值 search_values 被忽略,只支持单值。 + LingxingProductSearchBody.snakeCaseSingle(body, query, fieldValue); } catch (UnsupportedOperationException e) { ChannelException.Builder b = ChannelException.builder() - .message("ebay listing does not support search field " - + query.searchField()) + .message("ebay listing does not support " + e.getMessage()) .operation("products.pull") .retryable(false); throw new ValidationException(b); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java index 5849f6b..cc349a7 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java @@ -7,11 +7,15 @@ import java.util.List; /** * 把统一的 SKU 搜索条件拼进领星请求体。 * - *

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

+ *

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

* */ @@ -23,7 +27,7 @@ public final class LingxingProductSearchBody { /** * camelCase 形态:searchField / searchSingleValue / searchValues。 * - *

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

+ *

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

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

用于 Target(领星 shopify 路径)。

+ *

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

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

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

+ *

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

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

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

+ *

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

* *

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

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

+ *

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

*/ public static Object target(ProductSearchField field) { if (field == ProductSearchField.PLATFORM_SKU) { return 1; } - throw new UnsupportedOperationException("target listing does not support local sku search yet"); + throw new UnsupportedOperationException("local sku search"); } /** 亚马逊 SC:字符串 "seller_sku" / "sku"。 */ diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java index aa335a8..521a6e2 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java @@ -39,13 +39,34 @@ import java.util.Map; * *

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

+ * + *

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

+ * + *

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

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

* *

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

+ * + *

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

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