Browse Source

fix(lingxing): 修正 listing 搜索参数名与时间窗,按真机实测对齐

用只读探针实测 2026-11 领星各平台 listing 接口(传不存在的 SKU 做对照),
发现三处会静默出错的问题:

- 沃尔玛 / eBay:camelCase 的 searchField 被平台静默忽略并返回整页,
  必须用 search_field / search_single_value;多值 search_values 同样无效,
  改为单值专用方法,传多值时抛 ValidationException
- Target:时间窗三字段必须同时出现且日期只接受 Y-m-d,单边或带时分秒都 400;
  改为补齐两端 + 日期格式,并用 listing_time_field=2(更新时间)
- Temu:时间窗跨度 31 天直接 500,改为按 30 天截断并补齐两端

搜索编码实测结论:沃尔玛 1/3、eBay 1/3、AliExpress 1/5、Temu/SHEIN/TikTok 9/8、
Target 1(=msku,2=item_id,4≈标题)、Amazon SC 字符串 seller_sku/sku;
Target 本地 SKU 在该 app 下恒为空,保持显式不支持。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
c33597fae9
  1. 9
      lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java
  2. 29
      lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchBody.java
  3. 31
      lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/product/LingxingProductSearchMapper.java
  4. 46
      lingxing/src/main/java/common/ecommerce/lingxing/platform/target/product/TargetProductSource.java
  5. 22
      lingxing/src/main/java/common/ecommerce/lingxing/platform/temu/product/TemuProductSource.java
  6. 9
      lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java

9
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; return trimmed.isEmpty() ? null : trimmed;
} }
/** 统一 SKU 搜索 → ebay 的字段形态;未带搜索条件时什么也不做。 */ /** 统一 SKU 搜索 → eBay 的字段形态;未带搜索条件时什么也不做。 */
private static void applySearch(java.util.Map<String, Object> body, private static void applySearch(java.util.Map<String, Object> body,
ProductQuery query) { ProductQuery query) {
if (query == null || !query.hasSearch()) { if (query == null || !query.hasSearch()) {
@ -225,11 +225,12 @@ public final class EbayProductSource implements LingxingProductSource {
} }
try { try {
Object fieldValue = LingxingProductSearchMapper.ebay(query.searchField()); 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) { } catch (UnsupportedOperationException e) {
ChannelException.Builder b = ChannelException.builder() ChannelException.Builder b = ChannelException.builder()
.message("ebay listing does not support search field " .message("ebay listing does not support " + e.getMessage())
+ query.searchField())
.operation("products.pull") .operation("products.pull")
.retryable(false); .retryable(false);
throw new ValidationException(b); 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;
/** /**
* 把统一的 SKU 搜索条件拼进领星请求体。 * 把统一的 SKU 搜索条件拼进领星请求体。
* *
* <p>各平台字段名与形态不同:</p> * <p>字段名按<b>实测</b>区分(2026-11,见 {@code ListingParamProbeTest}):</p>
* <ul> * <ul>
* <li>沃尔玛 / eBay / Temu / SHEIN / TikTok / AliExpress:{@code searchField}(数字) * <li>Temu / SHEIN / TikTok / AliExpress:{@code searchField}(数字)
* + {@code searchSingleValue}(单值模糊)+ {@code searchValues}(多值精确)</li> * + {@code searchSingleValue}(单值)+ {@code searchValues}(多值,均支持)</li>
* <li>Target(走领星 shopify 路径):{@code search_field} + {@code search_single_value} + {@code search_values}</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> * <li>亚马逊 SC:{@code search_field}(字符串)+ {@code search_value}(数组)+ {@code exact_search}</li>
* </ul> * </ul>
*/ */
@ -23,7 +27,7 @@ public final class LingxingProductSearchBody {
/** /**
* camelCase 形态:searchField / searchSingleValue / searchValues。 * 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) { public static void camelCase(java.util.Map<String, Object> body, ProductQuery query, Object fieldValue) {
if (query == null || !query.hasSearch()) { 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。
* *
* <p>用于 Target(领星 shopify 路径)。</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()) { if (query == null || !query.hasSearch()) {
return; return;
} }
if (!query.searchValues().isEmpty()) {
throw new UnsupportedOperationException(
"multi-value search is not supported by this listing API");
}
body.put("search_field", fieldValue); body.put("search_field", fieldValue);
applyValue(body, query, "search_single_value", "search_values"); body.put("search_single_value", query.searchValue());
} }
/** /**

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

@ -5,22 +5,23 @@ import common.ecommerce.model.product.ProductSearchField;
/** /**
* 领星侧各平台的「搜索维度 → 平台枚举值」映射。 * 领星侧各平台的「搜索维度 → 平台枚举值」映射。
* *
* <p>同一个语义在不同平台下的取值完全不同:</p> * <p>同一个语义在不同平台下的取值完全不同(<b>2026-11 全部实测</b>,
* 方法见 {@code ListingParamProbeTest}:用真实 msku 回查 + 用不存在的值做对照):</p>
* <pre> * <pre>
* 平台 SKU 本地 SKU * 平台 SKU 本地 SKU 参数名
* 沃尔玛 1 3 * 沃尔玛 1 3 snake_case,多值不支持
* eBay 1 3 * eBay 1 3 snake_case,多值不支持
* AliExpress 1 5 ← 实测:文档写 3,但 3 查不到 * AliExpress 1 5 camelCase,多值支持
* Temu 9 8 * Temu 9 8 camelCase,多值支持
* SHEIN 9 8 * SHEIN 9 8 camelCase,多值支持
* TikTok 9 8 * TikTok 9 8 camelCase,多值支持
* Target 1 待核对(样本 local_sku 为空) * Target 1(=msku) 不支持 snake_case,多值不支持
* 亚马逊 SC "seller_sku" "sku" ← 字符串,不是数字 * 亚马逊 SC "seller_sku" "sku" 字符串,不是数字
* 亚马逊 VC 不支持搜索 * 亚马逊 VC 不支持搜索
* </pre> * </pre>
* *
* <p>取值来源:领星文档(2026-10 摘录)+ AliExpress 实测(2026-11)。 * <p>注意:沃尔玛 / eBay 用 camelCase 时平台<b>不报错但静默忽略</b>搜索条件,
* 未实测的平台按文档写,联调时用 {@code SearchFieldProbeTest} 逐个核对。</p> * 所以参数名必须与上表一致,见 {@link LingxingProductSearchBody}。</p>
* *
* <p>用「按平台命名的方法」而不是「按 platform_code 查表」:每个 Source 只服务一个平台, * <p>用「按平台命名的方法」而不是「按 platform_code 查表」:每个 Source 只服务一个平台,
* 直接调自己那一个方法即可;AliExpress 的 platform_code 尚未确认,也不影响调用。 * 直接调自己那一个方法即可;AliExpress 的 platform_code 尚未确认,也不影响调用。
@ -64,14 +65,14 @@ public final class LingxingProductSearchMapper {
/** /**
* Target:1 = msku(实测)。 * Target:1 = msku(实测)。
* *
* <p>本地 SKU 的编码文档未给出,实测样本 {@code local_sku} 也为空, * <p>该 app 下 {@code local_sku} 恒为空(翻 200 行全空),没有可对应的本地 SKU 编码,
* 暂时抛异常表示不支持;联调时用探针确认后再补。</p> * 因此对 {@link ProductSearchField#LOCAL_SKU} 显式抛异常,不静默退化为平台 SKU 查询。</p>
*/ */
public static Object target(ProductSearchField field) { public static Object target(ProductSearchField field) {
if (field == ProductSearchField.PLATFORM_SKU) { if (field == ProductSearchField.PLATFORM_SKU) {
return 1; return 1;
} }
throw new UnsupportedOperationException("target listing does not support local sku search yet"); throw new UnsupportedOperationException("local sku search");
} }
/** 亚马逊 SC:字符串 "seller_sku" / "sku"。 */ /** 亚马逊 SC:字符串 "seller_sku" / "sku"。 */

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

@ -39,13 +39,34 @@ import java.util.Map;
* *
* <p>{@code store_ids} 是<b>非必填</b>项:文档未标必填,不传时返回该 app 下所有店铺的商品。 * <p>{@code store_ids} 是<b>非必填</b>项:文档未标必填,不传时返回该 app 下所有店铺的商品。
* 这里按账户的 {@code externalStoreId} 过滤,避免把其它店铺的商品混进同一个 omsStoreId。</p> * 这里按账户的 {@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 { public final class TargetProductSource implements LingxingProductSource {
private static final int MAX_PAGE_SIZE = 1000; 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 DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
/** 只给终点时向前补的默认窗口。 */
private static final int DEFAULT_QUERY_DAYS = 30;
@Override @Override
public Page<ProductListing> products(LingxingCall call, ProductQuery query) { public Page<ProductListing> products(LingxingCall call, ProductQuery query) {
int length = Math.min(query.pageSize() <= 0 ? 100 : query.pageSize(), MAX_PAGE_SIZE); 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); 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) { private static void applyTimeWindow(Map<String, Object> body, ProductQuery query) {
Instant from = query.updatedAfter(); Instant from = query.updatedAfter();
Instant to = query.updatedBefore(); Instant to = query.updatedBefore();
@ -88,12 +112,15 @@ public final class TargetProductSource implements LingxingProductSource {
return; return;
} }
ZoneId utc = ZoneId.of("UTC"); ZoneId utc = ZoneId.of("UTC");
if (from != null) { if (to == null) {
body.put("listing_start_time", DATE_TIME.format(from.atZone(utc))); to = Instant.now();
} }
if (to != null) { if (from == null) {
body.put("listing_end_time", DATE_TIME.format(to.atZone(utc))); 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。 */ /** 总数取 data.count;没有时用顶层 total;都没有返回 -1。 */
@ -286,6 +313,7 @@ public final class TargetProductSource implements LingxingProductSource {
} }
/** 统一 SKU 搜索 → shopify/target 的字段形态;未带搜索条件时什么也不做。 */ /** 统一 SKU 搜索 → shopify/target 的字段形态;未带搜索条件时什么也不做。 */
/** 统一 SKU 搜索 → Target 的字段形态;未带搜索条件时什么也不做。 */
private static void applySearch(java.util.Map<String, Object> body, private static void applySearch(java.util.Map<String, Object> body,
ProductQuery query) { ProductQuery query) {
if (query == null || !query.hasSearch()) { if (query == null || !query.hasSearch()) {
@ -293,11 +321,11 @@ public final class TargetProductSource implements LingxingProductSource {
} }
try { try {
Object fieldValue = LingxingProductSearchMapper.target(query.searchField()); Object fieldValue = LingxingProductSearchMapper.target(query.searchField());
LingxingProductSearchBody.snakeCase(body, query, fieldValue); // 实测:多值 search_values 返回 400,只支持单值。
LingxingProductSearchBody.snakeCaseSingle(body, query, fieldValue);
} catch (UnsupportedOperationException e) { } catch (UnsupportedOperationException e) {
ChannelException.Builder b = ChannelException.builder() ChannelException.Builder b = ChannelException.builder()
.message("target listing does not support search field " .message("target listing does not support " + e.getMessage())
+ query.searchField())
.operation("products.pull") .operation("products.pull")
.retryable(false); .retryable(false);
throw new ValidationException(b); 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;
* (上限 1000)或 {@code cursorId} 游标分页,返回 {@code data.list};令牌桶容量 1。</p> * (上限 1000)或 {@code cursorId} 游标分页,返回 {@code data.list};令牌桶容量 1。</p>
* *
* <p>本实现固定走 offset 分页({@code useCursor=false}),游标以 offset 字符串表示。</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 { public final class TemuProductSource implements LingxingProductSource {
private static final int MAX_PAGE_SIZE = 1000; 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"); private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
@Override @Override
@ -77,7 +84,10 @@ public final class TemuProductSource implements LingxingProductSource {
return Page.of(out, hasMore ? String.valueOf(nextOffset) : null); return Page.of(out, hasMore ? String.valueOf(nextOffset) : null);
} }
/** 时间窗:接口精度到秒,未说明时区,统一按 UTC 发送。 */ /**
* 时间窗:两端必须同时给。跨度超过 30 天时截断到最近 30 天;
* 只给一端时补齐另一端(终点缺失取当前时间)。
*/
private static void applyTimeWindow(Map<String, Object> body, ProductQuery query) { private static void applyTimeWindow(Map<String, Object> body, ProductQuery query) {
Instant from = query.updatedAfter(); Instant from = query.updatedAfter();
Instant to = query.updatedBefore(); Instant to = query.updatedBefore();
@ -85,12 +95,14 @@ public final class TemuProductSource implements LingxingProductSource {
return; return;
} }
ZoneId utc = ZoneId.of("UTC"); ZoneId utc = ZoneId.of("UTC");
if (from != null) { if (to == null) {
body.put("updateStartTime", DATE_TIME.format(from.atZone(utc))); to = Instant.now();
} }
if (to != null) { if (from == null || java.time.Duration.between(from, to).toDays() > MAX_QUERY_DAYS) {
body.put("updateEndTime", DATE_TIME.format(to.atZone(utc))); 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。 */ /** 总数取 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 {
return trimmed.isEmpty() ? null : trimmed; return trimmed.isEmpty() ? null : trimmed;
} }
/** 统一 SKU 搜索 → walmart 的字段形态;未带搜索条件时什么也不做。 */ /** 统一 SKU 搜索 → 沃尔玛的字段形态;未带搜索条件时什么也不做。 */
private static void applySearch(java.util.Map<String, Object> body, private static void applySearch(java.util.Map<String, Object> body,
ProductQuery query) { ProductQuery query) {
if (query == null || !query.hasSearch()) { if (query == null || !query.hasSearch()) {
@ -300,11 +300,12 @@ public final class WalmartProductSource implements LingxingProductSource {
} }
try { try {
Object fieldValue = LingxingProductSearchMapper.walmart(query.searchField()); 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) { } catch (UnsupportedOperationException e) {
ChannelException.Builder b = ChannelException.builder() ChannelException.Builder b = ChannelException.builder()
.message("walmart listing does not support search field " .message("walmart listing does not support " + e.getMessage())
+ query.searchField())
.operation("products.pull") .operation("products.pull")
.retryable(false); .retryable(false);
throw new ValidationException(b); throw new ValidationException(b);

Loading…
Cancel
Save