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}):
*
- * - 沃尔玛 / eBay / Temu / SHEIN / TikTok / AliExpress:{@code searchField}(数字)
- * + {@code searchSingleValue}(单值模糊)+ {@code searchValues}(多值精确)
- * - Target(走领星 shopify 路径):{@code search_field} + {@code search_single_value} + {@code search_values}
+ * - Temu / SHEIN / TikTok / AliExpress:{@code searchField}(数字)
+ * + {@code searchSingleValue}(单值)+ {@code searchValues}(多值,均支持)
+ * - 沃尔玛 / eBay:{@code search_field} + {@code search_single_value}(snake_case)。
+ * 写成 camelCase 不会报错,但搜索条件被静默忽略、返回整页;
+ * 多值 {@code search_values} 同样被忽略或报 400,因此只支持单值。
+ * - Target(走领星 shopify 路径):{@code search_field} + {@code search_single_value};
+ * 多值 {@code search_values} 返回 400,只支持单值。
* - 亚马逊 SC:{@code search_field}(字符串)+ {@code search_value}(数组)+ {@code exact_search}
*
*/
@@ -23,7 +27,7 @@ public final class LingxingProductSearchBody {
/**
* camelCase 形态:searchField / searchSingleValue / searchValues。
*
- * 用于 Temu、SHEIN、TikTok、AliExpress、沃尔玛、eBay。
+ * 用于 Temu、SHEIN、TikTok、AliExpress(单值与多值均实测生效)。
*/
public static void camelCase(java.util.Map body, ProductQuery query, Object fieldValue) {
if (query == null || !query.hasSearch()) {
@@ -34,16 +38,23 @@ public final class LingxingProductSearchBody {
}
/**
- * snake_case 形态:search_field / search_single_value / search_values。
+ * snake_case 单值形态:search_field / search_single_value。
*
- * 用于 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);