From f3f7e080191b5183dab4f600786e036d47e22670 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 3 Nov 2026 13:50:29 +0800 Subject: [PATCH] =?UTF-8?q?feat(lingxing):=20=E6=8E=A5=E5=85=A5=20eBay=20?= =?UTF-8?q?=E5=9C=A8=E7=BA=BF=E5=95=86=E5=93=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 接口 /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 --- .../common/ecommerce/lingxing/LingxingApi.java | 3 + .../lingxing/platform/LingxingSubPlatforms.java | 4 +- .../lingxing/platform/ebay/EbaySubPlatform.java | 30 +++ .../platform/ebay/dto/EbayAutoRestockDto.java | 61 ++++++ .../lingxing/platform/ebay/dto/EbayListingDto.java | 123 ++++++++++++ .../platform/ebay/product/EbayProductSource.java | 208 +++++++++++++++++++++ 6 files changed, 428 insertions(+), 1 deletion(-) create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/EbaySubPlatform.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayAutoRestockDto.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayListingDto.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java index 90e05bd..4572f17 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java @@ -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); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatforms.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatforms.java index e6c028f..c4d681f 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatforms.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatforms.java @@ -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); } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/EbaySubPlatform.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/EbaySubPlatform.java new file mode 100644 index 0000000..9a46c47 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/EbaySubPlatform.java @@ -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; + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayAutoRestockDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayAutoRestockDto.java new file mode 100644 index 0000000..947d71a --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayAutoRestockDto.java @@ -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; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayListingDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayListingDto.java new file mode 100644 index 0000000..e91e35e --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/dto/EbayListingDto.java @@ -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[]})。 + * + *

注意:响应是 {@code data} 数组(不是 {@code data.list}),总数在顶层 {@code total}。

+ * + *

{@code msku} 可能为空串;此时应回落到 {@code item_id} 作为商品标识。

+ */ +@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; +} 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 new file mode 100644 index 0000000..4ee31fc --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/ebay/product/EbayProductSource.java @@ -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 在线商品。 + * + *

接口 {@code /basicOpen/multiplatform/ebay/list}:POST,{@code offset}/{@code length} + * (上限 200),返回 {@code data} 数组;令牌桶容量 1。

+ * + *

时间过滤精度为 {@code Y-m-d}(站点时间),区间不超过 31 天。

+ */ +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 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 body = new LinkedHashMap(); + 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 dtos = call.json().listAt(envelope.body(), "data", EbayListingDto.class); + List out = new ArrayList(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 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 商品 → 统一模型。 + * + *

统一字段来源:

+ *
    + *
  • platformSku ← {@code msku};为空串时回落 {@code item_id}
  • + *
  • listingId ← {@code item_id}
  • + *
  • title ← {@code title}
  • + *
  • imageUrls ← {@code picture_url}
  • + *
  • status ← {@code listing_status}(1 在售)
  • + *
  • rawStatus ← {@code listing_status_name} 原值(中文)
  • + *
  • price ← {@code price};接口不返回币种,currency 为 null,price 也置空
  • + *
  • listedAt ← {@code listing_start_time}
  • + *
  • updatedAt ← 无(接口没有内容更新时间)
  • + *
  • attributes ← 其余全部原始字段
  • + *
+ */ + 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.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 attributesOf(EbayListingDto dto) { + Map attrs = new LinkedHashMap(); + 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; + } +}