Browse Source

feat(lingxing): 接入 eBay 在线商品

接口 /basicOpen/multiplatform/ebay/list(POST, qps 1, 上限 200):
- 响应是 data 数组(不是 data.list),总数在顶层 total
- 时间过滤精度 Y-m-d,查询类型取创建时间(1),区间超 31 天截断
- EbayListingDto 全字段 + 嵌套 product_auto_restock_response

映射要点:
- platformSku ← msku,为空串时回落 item_id(保证 canonicalKey 有值)
- listingId ← item_id
- status ← listing_status(1 在售,其余文档未列,归 UNKNOWN)
- rawStatus ← listing_status_name(中文,如「在售」)
- 接口不返回币种,price / currency 均为 null,原值在 attributes.price

其余字段全部进 attributes(变体属性、站点、销售类型、起拍价/一口价、
自动补货规则、所在地、处理时间等)。

Shopify 此前已接入,本次文档与其一致,无需改动。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
f3f7e08019
  1. 3
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java
  2. 4
      lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatforms.java
  3. 30
      lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/EbaySubPlatform.java
  4. 61
      lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayAutoRestockDto.java
  5. 123
      lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayListingDto.java
  6. 208
      lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java

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

@ -41,6 +41,9 @@ public enum LingxingApi { @@ -41,6 +41,9 @@ public enum LingxingApi {
/** Shopify 在线商品(变体维度)。POST,offset/length(上限 1000),返回 data.list。 */
LISTING_SHOPIFY("/basicOpen/multiplatform/shopify/variantList", 1),
/** eBay 在线商品。POST,offset/length(上限 200),返回 data 数组。 */
LISTING_EBAY("/basicOpen/multiplatform/ebay/list", 1),
/** 多平台订单列表;当前实现使用的跨平台接口。 */
ORDER_LIST("/pb/mp/order/v2/list", 10);

4
lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatforms.java

@ -38,7 +38,9 @@ public final class LingxingSubPlatforms { @@ -38,7 +38,9 @@ public final class LingxingSubPlatforms {
SHARED_TRANSPORT, SHARED_JSON));
register(map, new common.ecommerce.lingxing.platform.shopify.ShopifySubPlatform(
SHARED_TRANSPORT, SHARED_JSON));
// eBay、SHEIN… 落地后继续 register(...)
register(map, new common.ecommerce.lingxing.platform.ebay.EbaySubPlatform(
SHARED_TRANSPORT, SHARED_JSON));
// SHEIN… 落地后继续 register(...)
BY_PLATFORM = Collections.unmodifiableMap(map);
}

30
lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/EbaySubPlatform.java

@ -0,0 +1,30 @@ @@ -0,0 +1,30 @@
package common.ecommerce.lingxing.platform.ebay;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.lingxing.platform.LingxingSubPlatform;
import common.ecommerce.lingxing.platform.ebay.product.EbayProductSource;
import common.ecommerce.lingxing.platform.product.LingxingProductSource;
import common.ecommerce.model.Platform;
/**
* 领星 · eBay 子平台:只做能力组合。
*/
public final class EbaySubPlatform implements LingxingSubPlatform {
private final LingxingProductSource products;
public EbaySubPlatform(HttpTransport transport, JacksonJsonCodec json) {
this.products = new EbayProductSource();
}
@Override
public Platform platform() {
return Platform.EBAY;
}
@Override
public LingxingProductSource productSource() {
return products;
}
}

61
lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayAutoRestockDto.java

@ -0,0 +1,61 @@ @@ -0,0 +1,61 @@
package common.ecommerce.lingxing.platform.ebay.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/** eBay 自动补货规则({@code product_auto_restock_response})。 */
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class EbayAutoRestockDto {
/** 商品变体唯一 ID(雪花 ID)。 */
@JsonProperty("variantUniqueId")
private String variantUniqueId;
/** 补货类型:1 固定值 / 2 指定仓库。 */
@JsonProperty("type")
private Integer type;
/** 补货类型名。 */
@JsonProperty("typeName")
private String typeName;
/** 同步间隔:1 每30分钟 / 2 每1小时 / 3 每6小时 / 4 每12小时 / 5 每24小时。 */
@JsonProperty("syncIntervalTime")
private Integer syncIntervalTime;
/** 同步间隔名。 */
@JsonProperty("syncIntervalTimeName")
private String syncIntervalTimeName;
/** 是否自动补货:0 未设置 / 1 启用 / 2 停用。 */
@JsonProperty("autoRestock")
private Integer autoRestock;
/** 是否自动补货名。 */
@JsonProperty("autoRestockName")
private String autoRestockName;
/** 停用原因:1 手动 / 2 自动。 */
@JsonProperty("disableReason")
private Integer disableReason;
/** 停用原因名。 */
@JsonProperty("disableReasonName")
private String disableReasonName;
/** 自动停用具体原因。 */
@JsonProperty("autoDisableReason")
private String autoDisableReason;
/** 补货数量。 */
@JsonProperty("restockQuantity")
private String restockQuantity;
/** 补货仓库 ID。 */
@JsonProperty("restockWarehouseId")
private String restockWarehouseId;
}

123
lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayListingDto.java

@ -0,0 +1,123 @@ @@ -0,0 +1,123 @@
package common.ecommerce.lingxing.platform.ebay.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/**
* 领星 · eBay 在线商品({@code /basicOpen/multiplatform/ebay/list} 的 {@code data[]})。
*
* <p>注意:响应是 {@code data} 数组(不是 {@code data.list}),总数在顶层 {@code total}。</p>
*
* <p>{@code msku} 可能为空串;此时应回落到 {@code item_id} 作为商品标识。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class EbayListingDto {
/** 商品跳转链接。 */
@JsonProperty("item_url")
private String itemUrl;
/** 图片链接。 */
@JsonProperty("picture_url")
private String pictureUrl;
/** 商品 ID。 */
@JsonProperty("item_id")
private String itemId;
/** 平台侧 MSKU,可能为空串。 */
@JsonProperty("msku")
private String msku;
/** 变体属性,如 Black/Regular/S。 */
@JsonProperty("attribute")
private String attribute;
/** 标题。 */
@JsonProperty("title")
private String title;
/** 本地品名。 */
@JsonProperty("local_name")
private String localName;
/** 本地 SKU。 */
@JsonProperty("local_sku")
private String localSku;
/** 销售状态值。 */
@JsonProperty("listing_status")
private Integer listingStatus;
/** 销售状态名,如「在售」。 */
@JsonProperty("listing_status_name")
private String listingStatusName;
/** 店铺 id。 */
@JsonProperty("store_id")
private String storeId;
/** 店铺名称。 */
@JsonProperty("store_name")
private String storeName;
/** 站点 code,如 10003-US。 */
@JsonProperty("site_code")
private String siteCode;
/** 站点名称,如「美国」。 */
@JsonProperty("site_name")
private String siteName;
/** 销售类型:1 拍卖 / 2 固价 / 3 多属性。 */
@JsonProperty("listing_type")
private Integer listingType;
/** 销售类型名称。 */
@JsonProperty("listing_type_name")
private String listingTypeName;
/** 价格,接口不返回币种。 */
@JsonProperty("price")
private String price;
/** 起拍价。 */
@JsonProperty("start_price")
private String startPrice;
/** 一口价。 */
@JsonProperty("accept_price")
private String acceptPrice;
/** 库存。 */
@JsonProperty("quantity")
private Integer quantity;
/** 是否自动补货。 */
@JsonProperty("auto_restock")
private String autoRestock;
/** 自动补货规则详情。 */
@JsonProperty("product_auto_restock_response")
private EbayAutoRestockDto productAutoRestockResponse;
/** 物品所在地。 */
@JsonProperty("location")
private String location;
/** 处理时间。 */
@JsonProperty("dispatch_time_max")
private Integer dispatchTimeMax;
/** 创建时间,格式 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;
}

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

@ -0,0 +1,208 @@ @@ -0,0 +1,208 @@
package common.ecommerce.lingxing.platform.ebay.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.ebay.dto.EbayListingDto;
import common.ecommerce.lingxing.platform.product.LingxingProductSource;
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.LocalDate;
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.Map;
/**
* 领星 · eBay 在线商品。
*
* <p>接口 {@code /basicOpen/multiplatform/ebay/list}:POST,{@code offset}/{@code length}
* (上限 200),返回 {@code data} 数组;令牌桶容量 1。</p>
*
* <p>时间过滤精度为 {@code Y-m-d}(站点时间),区间不超过 31 天。</p>
*/
public final class EbayProductSource implements LingxingProductSource {
private static final int MAX_PAGE_SIZE = 200;
/** 查询时间类型:1 创建时间(默认)。 */
private static final int TIME_FIELD_CREATE = 1;
/** 接口要求时间区间不超过 31 天。 */
private static final int MAX_QUERY_DAYS = 31;
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
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 ? 20 : 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_EBAY, body, "products.pull");
HttpResponse resp = call.execute(req);
LingxingEnvelope envelope = call.envelope(resp, "products.pull");
List<EbayListingDto> dtos = call.json().listAt(envelope.body(), "data", EbayListingDto.class);
List<ProductListing> out = new ArrayList<ProductListing>(dtos.size());
for (EbayListingDto dto : dtos) {
out.add(toProductListing(dto, call));
}
int nextOffset = offset + dtos.size();
boolean hasMore = dtos.size() >= length
&& (envelope.total() < 0 || nextOffset < envelope.total());
return Page.of(out, hasMore ? String.valueOf(nextOffset) : null);
}
/** 日期精度 Y-m-d;区间超过 31 天时截断到最近 31 天。 */
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 (to == null) {
to = Instant.now();
}
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("listing_time_field", TIME_FIELD_CREATE);
body.put("listing_start_time", DATE.format(from.atZone(utc).toLocalDate()));
body.put("listing_end_time", DATE.format(to.atZone(utc).toLocalDate()));
}
/**
* 领星 eBay 商品 → 统一模型。
*
* <p>统一字段来源:</p>
* <ul>
* <li>platformSku ← {@code msku};<b>为空串时回落 {@code item_id}</b></li>
* <li>listingId ← {@code item_id}</li>
* <li>title ← {@code title}</li>
* <li>imageUrls ← {@code picture_url}</li>
* <li>status ← {@code listing_status}(1 在售)</li>
* <li>rawStatus ← {@code listing_status_name} 原值(中文)</li>
* <li>price ← {@code price};<b>接口不返回币种</b>,currency 为 null,price 也置空</li>
* <li>listedAt ← {@code listing_start_time}</li>
* <li>updatedAt ← 无(接口没有内容更新时间)</li>
* <li>attributes ← 其余全部原始字段</li>
* </ul>
*/
private ProductListing toProductListing(EbayListingDto dto, LingxingCall call) {
ZoneId zone = ZoneId.of(call.ctx().account().marketplaceZone());
String sku = firstNonBlank(dto.getMsku(), dto.getItemId());
return ProductListing.builder()
.platform(call.ctx().platform())
.omsStoreId(call.ctx().omsStoreId())
// msku 可能为空串,回落 item_id,保证 canonicalKey 有值
.platformSku(sku)
.listingId(trimToNull(dto.getItemId()))
.title(dto.getTitle())
.imageUrls(isBlank(dto.getPictureUrl())
? Collections.<String>emptyList()
: Collections.singletonList(dto.getPictureUrl().trim()))
.status(statusOf(dto.getListingStatus()))
.rawStatus(dto.getListingStatusName())
// eBay 接口不返回币种,无法构造 Money
.price(null)
.currency(null)
.listedAt(dateTime(dto.getListingStartTime(), zone))
.attributes(attributesOf(dto))
.sourceProvider(ChannelProvider.LINGXING)
.build();
}
/** eBay listing_status:1 在售。其余取值文档未列出,统一 UNKNOWN。 */
private static ProductStatus statusOf(Integer status) {
if (status == null) {
return ProductStatus.UNKNOWN;
}
if (status == 1) {
return ProductStatus.ACTIVE;
}
return ProductStatus.UNKNOWN;
}
private static Map<String, Object> attributesOf(EbayListingDto dto) {
Map<String, Object> attrs = new LinkedHashMap<String, Object>();
attrs.put("item_url", dto.getItemUrl());
attrs.put("attribute", dto.getAttribute());
attrs.put("local_sku", dto.getLocalSku());
attrs.put("local_name", dto.getLocalName());
attrs.put("store_id", dto.getStoreId());
attrs.put("store_name", dto.getStoreName());
attrs.put("site_code", dto.getSiteCode());
attrs.put("site_name", dto.getSiteName());
attrs.put("listing_type", dto.getListingType());
attrs.put("listing_type_name", dto.getListingTypeName());
attrs.put("price", dto.getPrice());
attrs.put("start_price", dto.getStartPrice());
attrs.put("accept_price", dto.getAcceptPrice());
attrs.put("quantity", dto.getQuantity());
attrs.put("auto_restock", dto.getAutoRestock());
attrs.put("product_auto_restock_response", dto.getProductAutoRestockResponse());
attrs.put("location", dto.getLocation());
attrs.put("dispatch_time_max", dto.getDispatchTimeMax());
attrs.put("listing_end_time", dto.getListingEndTime());
attrs.values().removeAll(Collections.singleton(null));
return attrs;
}
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 boolean isBlank(String v) {
return v == null || v.trim().isEmpty();
}
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;
}
}
Loading…
Cancel
Save