From 2a046d4e9e8e3036481097dbd6bd0c080d42da72 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 3 Nov 2026 10:41:44 +0800 Subject: [PATCH] =?UTF-8?q?feat(lingxing):=20=E6=B2=83=E5=B0=94=E7=8E=9B?= =?UTF-8?q?=E5=9C=A8=E7=BA=BF=E5=95=86=E5=93=81=EF=BC=9B=E5=BA=97=E9=93=BA?= =?UTF-8?q?=E5=88=97=E8=A1=A8=E4=B8=8D=E5=86=8D=E6=8C=89=E7=8A=B6=E6=80=81?= =?UTF-8?q?=E8=BF=87=E6=BB=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 沃尔玛商品(/basicOpen/multiplatform/walmart/list, POST, qps 1, 上限 200): - WalmartListingDto:34 个字段全覆盖(文档标注均为必填) - WalmartProductSource:store_ids 传数组;时间窗按 Y-m-d,字段类型取更新时间(2), 超 31 天截断;响应在 data.list - 映射:msku→platformSku、item_id→listingId、gtin/upc→gtin、picture_url→imageUrls、 status_name 按名称归一、price + currency_icon 反推币种、 offer_start_date→listedAt、listing_start_time→updatedAt - 其余字段全部进 attributes - WalmartSubPlatform 注册 productSource 店铺列表: - 移除 SC / VC 的 status != 1 过滤,SDK 只转发 - 调用方按 SubChannel.status() 自行决定可用性 Co-Authored-By: Claude --- .../common/ecommerce/lingxing/LingxingApi.java | 3 + .../amazon/sc/shop/AmazonScShopSource.java | 7 +- .../amazon/vc/shop/AmazonVcShopSource.java | 8 +- .../platform/walmart/WalmartSubPlatform.java | 9 + .../platform/walmart/dto/WalmartListingDto.java | 160 ++++++++++++ .../walmart/product/WalmartProductSource.java | 267 +++++++++++++++++++++ 6 files changed, 445 insertions(+), 9 deletions(-) create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/dto/WalmartListingDto.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java index 002d23a..2c081b2 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java @@ -32,6 +32,9 @@ public enum LingxingApi { /** 亚马逊 VC Listing 列表。POST,offset/length 分页(上限 200)。 */ LISTING_AMAZON_VC("/basicOpen/listingManage/vcListing/pageList", 1), + /** 沃尔玛在线商品。POST,offset/length 分页(上限 200),返回 data.list。 */ + LISTING_WALMART("/basicOpen/multiplatform/walmart/list", 1), + /** 多平台订单列表;当前实现使用的跨平台接口。 */ ORDER_LIST("/pb/mp/order/v2/list", 10); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/shop/AmazonScShopSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/shop/AmazonScShopSource.java index a1368f6..549cb75 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/shop/AmazonScShopSource.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/shop/AmazonScShopSource.java @@ -21,15 +21,14 @@ import java.util.Map; * *

接口 {@code /erp/sc/data/seller/lists} 是 GET、非分页,一次返回企业下全部已授权 SC 店铺。 * 令牌桶容量 1,按「账户 + path」限流。

+ * + *

SDK 只做转发,不按状态过滤;调用方按 {@link SubChannel#status()} 自行决定用哪些。

*/ public final class AmazonScShopSource implements LingxingShopSource { /** 领星侧 Amazon SC 的 platform_code。 */ private static final int AMAZON_SC_PLATFORM_CODE = 10001; - /** 店铺状态:1 = 正常同步。 */ - private static final int STATUS_ACTIVE = 1; - @Override public List shops(LingxingCall call) { HttpRequest req = call.get(LingxingApi.SHOP_LIST_AMAZON_SC, "shops.list"); @@ -39,7 +38,7 @@ public final class AmazonScShopSource implements LingxingShopSource { List shops = call.json().listAt(envelope.body(), "data", AmazonScShopDto.class); List out = new ArrayList(shops.size()); for (AmazonScShopDto shop : shops) { - if (shop.getSid() == null || shop.getStatus() == null || shop.getStatus() != STATUS_ACTIVE) { + if (shop.getSid() == null) { continue; } // platformCode 取领星侧 Amazon SC 的平台码 10001;externalStoreId 用领星店铺 id(sid) diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/shop/AmazonVcShopSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/shop/AmazonVcShopSource.java index 2272da1..30693d5 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/shop/AmazonVcShopSource.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/shop/AmazonVcShopSource.java @@ -21,15 +21,14 @@ import java.util.Map; * *

接口 {@code /basicOpen/platformAuth/vcSeller/pageList}:POST,{@code offset}/{@code length} * 分页,{@code length} 上限 200,令牌桶容量 1。

+ * + *

SDK 只做转发,不按状态过滤;调用方按 {@link SubChannel#status()} 自行决定用哪些。

*/ public final class AmazonVcShopSource implements LingxingShopSource { /** 领星侧 Amazon VC 的 platform_code。 */ private static final int AMAZON_VC_PLATFORM_CODE = 10035; - /** 店铺授权服务状态:1 = 正常同步。 */ - private static final int STATUS_ACTIVE = 1; - private static final int MAX_PAGE_SIZE = 200; @Override @@ -47,8 +46,7 @@ public final class AmazonVcShopSource implements LingxingShopSource { List page = call.json().listAt(envelope.body(), "data", AmazonVcShopDto.class); for (AmazonVcShopDto shop : page) { - if (shop.getVcStoreId() == null || shop.getStatus() == null - || shop.getStatus() != STATUS_ACTIVE) { + if (shop.getVcStoreId() == null) { continue; } out.add(SubChannel.builder() diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java index 1ae0d52..09cb58e 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java @@ -4,7 +4,9 @@ import common.ecommerce.http.HttpTransport; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.lingxing.platform.LingxingSubPlatform; import common.ecommerce.lingxing.platform.order.LingxingOrderSource; +import common.ecommerce.lingxing.platform.product.LingxingProductSource; import common.ecommerce.lingxing.platform.walmart.order.WalmartOrderSource; +import common.ecommerce.lingxing.platform.walmart.product.WalmartProductSource; import common.ecommerce.model.Platform; /** @@ -13,9 +15,11 @@ import common.ecommerce.model.Platform; public final class WalmartSubPlatform implements LingxingSubPlatform { private final LingxingOrderSource orders; + private final LingxingProductSource products; public WalmartSubPlatform(HttpTransport transport, JacksonJsonCodec json) { this.orders = new WalmartOrderSource(transport, json); + this.products = new WalmartProductSource(); } @Override @@ -27,4 +31,9 @@ public final class WalmartSubPlatform implements LingxingSubPlatform { public LingxingOrderSource orderSource() { return orders; } + + @Override + public LingxingProductSource productSource() { + return products; + } } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/dto/WalmartListingDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/dto/WalmartListingDto.java new file mode 100644 index 0000000..4466b55 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/dto/WalmartListingDto.java @@ -0,0 +1,160 @@ +package common.ecommerce.lingxing.platform.walmart.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** + * 领星 · 沃尔玛在线商品({@code /basicOpen/multiplatform/walmart/list} 的 {@code data.list[]})。 + * + *

字段名以官方文档为准。注意响应外层是 {@code data.list},不是 {@code data}。

+ * + *

SKU 语义:{@code msku} 是平台侧 MSKU,{@code local_sku} 是领星本地 SKU, + * 对齐时应优先用 {@code msku}。

+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class WalmartListingDto { + + /** 平台商品 ID。 */ + @JsonProperty("item_id") + private String itemId; + + /** 商品跳转链接。 */ + @JsonProperty("item_url") + private String itemUrl; + + /** 图片链接。 */ + @JsonProperty("picture_url") + private String pictureUrl; + + /** 平台 SKU(MSKU),参与 canonicalKey。 */ + @JsonProperty("msku") + private String msku; + + /** 标题。 */ + @JsonProperty("title") + private String title; + + /** 本地品名。 */ + @JsonProperty("local_name") + private String localName; + + /** 本地 SKU。 */ + @JsonProperty("local_sku") + private String localSku; + + /** 状态名:PUBLISHED / READY TO PUBLISH / IN PROGRESS / UNPUBLISHED / STAGE / SYSTEM PROBLEM。 */ + @JsonProperty("status_name") + private String statusName; + + /** 店铺 ID。 */ + @JsonProperty("store_id") + private String storeId; + + /** 店铺名。 */ + @JsonProperty("store_name") + private String storeName; + + /** 货币符号,注意不是 ISO 代码。 */ + @JsonProperty("currency_icon") + private String currencyIcon; + + /** 价格。 */ + @JsonProperty("price") + private String price; + + /** 非 WFS 可售数量。 */ + @JsonProperty("available_quantity") + private Integer availableQuantity; + + /** WFS 可售数量。 */ + @JsonProperty("wfs_available_quantity") + private Integer wfsAvailableQuantity; + + /** Buy Box 价格。 */ + @JsonProperty("buy_box_price") + private String buyBoxPrice; + + /** Buy Box 运费。 */ + @JsonProperty("buy_box_shipping_price") + private String buyBoxShippingPrice; + + /** GTIN。 */ + @JsonProperty("gtin") + private String gtin; + + /** UPC。 */ + @JsonProperty("upc") + private String upc; + + /** 商品税号。 */ + @JsonProperty("product_tax_code") + private String productTaxCode; + + /** 销售开始时间,格式 Y-m-d H:i:s。 */ + @JsonProperty("offer_start_date") + private String offerStartDate; + + /** 销售结束时间,格式 Y-m-d H:i:s。 */ + @JsonProperty("offer_end_date") + private String offerEndDate; + + /** 评论数。 */ + @JsonProperty("review_count") + private String reviewCount; + + /** 评分。 */ + @JsonProperty("average_rating") + private String averageRating; + + /** 品牌。 */ + @JsonProperty("brand") + private String brand; + + /** 发货方式:0 WFS Eligible / 1 Walmart Fulfilled / 2 Seller Fulfilled。 */ + @JsonProperty("fulfillment_type") + private Integer fulfillmentType; + + /** 发货方式名称。 */ + @JsonProperty("fulfillment_type_name") + private String fulfillmentTypeName; + + /** 竞品价格。 */ + @JsonProperty("competitor_price") + private String competitorPrice; + + /** 竞品运费。 */ + @JsonProperty("competitor_ship_price") + private String competitorShipPrice; + + /** 创建时间,格式 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; + + /** 变体唯一 ID。 */ + @JsonProperty("variant_unique_id") + private String variantUniqueId; + + /** 库存调整后的值。 */ + @JsonProperty("quantityAdjustAfter") + private String quantityAdjustAfter; + + /** 库存调整前的值。 */ + @JsonProperty("quantityAdjustBefore") + private String quantityAdjustBefore; + + /** 库存调整操作人 ID。 */ + @JsonProperty("quantityUserId") + private String quantityUserId; + + /** 库存调整操作人名称。 */ + @JsonProperty("quantityUserIdName") + private String quantityUserIdName; +} 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 new file mode 100644 index 0000000..91240d2 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java @@ -0,0 +1,267 @@ +package common.ecommerce.lingxing.platform.walmart.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.product.LingxingProductSource; +import common.ecommerce.lingxing.platform.walmart.dto.WalmartListingDto; +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 java.time.Instant; +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.time.ZoneId; +import java.util.ArrayList; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Locale; +import java.util.Map; + +/** + * 领星 · 沃尔玛在线商品。 + * + *

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

+ * + *

时间过滤:{@code listing_time_field} 选创建(1)/更新(2),日期精度为 {@code Y-m-d}, + * 区间不超过 31 天。

+ */ +public final class WalmartProductSource implements LingxingProductSource { + + private static final int MAX_PAGE_SIZE = 200; + + /** 搜索时间类型:按更新时间。 */ + private static final int TIME_FIELD_UPDATE = 2; + + /** 接口要求时间区间不超过 31 天。 */ + private static final int MAX_QUERY_DAYS = 31; + + /** 创建/更新时间是 Y-m-d H:i:s。 */ + private static final java.time.format.DateTimeFormatter DATE_TIME = + java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + /** 销量开始/结束是 Y-m-d。 */ + private static final java.time.format.DateTimeFormatter DATE = + java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd"); + + @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_WALMART, body, "products.pull"); + HttpResponse resp = call.execute(req); + LingxingEnvelope envelope = call.envelope(resp, "products.pull"); + + List dtos = call.json().listAt(envelope.body(), "data.list", WalmartListingDto.class); + List out = new ArrayList(dtos.size()); + for (WalmartListingDto 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; + } + if (to == null) { + to = Instant.now(); + } + if (from == null) { + from = to.minus(java.time.Duration.ofDays(MAX_QUERY_DAYS)); + } else if (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_UPDATE); + body.put("listing_start_time", DATE.format(from.atZone(ZoneId.of("UTC")).toLocalDate())); + body.put("listing_end_time", DATE.format(to.atZone(ZoneId.of("UTC")).toLocalDate())); + } + + /** + * 领星沃尔玛商品 → 统一模型。 + * + *

统一字段来源:

+ *
    + *
  • platformSku ← {@code msku}
  • + *
  • listingId ← {@code item_id}
  • + *
  • gtin ← {@code gtin},缺失时用 {@code upc}
  • + *
  • title ← {@code title}
  • + *
  • imageUrls ← {@code picture_url}(单张)
  • + *
  • status ← {@code status_name}(PUBLISHED / ... 字符串)
  • + *
  • rawStatus ← {@code status_name} 原值
  • + *
  • price ← {@code price};currency 由 {@code currency_icon} 反推
  • + *
  • listedAt ← {@code offer_start_date}(销售开始时间)
  • + *
  • updatedAt ← {@code listing_start_time}(接口只给创建时间,没有内容更新时间)
  • + *
  • attributes ← 其余全部原始字段
  • + *
+ */ + private ProductListing toProductListing(WalmartListingDto dto, LingxingCall call) { + ZoneId zone = ZoneId.of(call.ctx().account().marketplaceZone()); + String currency = currencyOf(dto.getCurrencyIcon()); + String gtin = firstNonBlank(dto.getGtin(), dto.getUpc()); + + return ProductListing.builder() + .platform(call.ctx().platform()) + .omsStoreId(call.ctx().omsStoreId()) + .platformSku(dto.getMsku()) + .listingId(trimToNull(dto.getItemId())) + .gtin(gtin) + .title(dto.getTitle()) + .imageUrls(dto.getPictureUrl() == null + ? Collections.emptyList() + : Collections.singletonList(dto.getPictureUrl())) + .status(statusOf(dto.getStatusName())) + .rawStatus(dto.getStatusName()) + .price(moneyOrNull(dto.getPrice(), currency)) + .currency(currency) + .listedAt(dateTime(dto.getOfferStartDate(), zone, false)) + .updatedAt(dateTime(dto.getListingStartTime(), zone, false)) + .attributes(attributesOf(dto)) + .sourceProvider(ChannelProvider.LINGXING) + .build(); + } + + /** 沃尔玛状态是字符串,按名称归一。 */ + private static ProductStatus statusOf(String statusName) { + if (statusName == null) { + return ProductStatus.UNKNOWN; + } + String s = statusName.trim().toUpperCase(Locale.ROOT); + if ("PUBLISHED".equals(s)) { + return ProductStatus.ACTIVE; + } + if ("UNPUBLISHED".equals(s) || "STAGE".equals(s) + || "READY TO PUBLISH".equals(s) || "IN PROGRESS".equals(s)) { + return ProductStatus.INACTIVE; + } + if ("SYSTEM PROBLEM".equals(s)) { + return ProductStatus.UNKNOWN; + } + return ProductStatus.UNKNOWN; + } + + private static Map attributesOf(WalmartListingDto dto) { + Map attrs = new LinkedHashMap(); + attrs.put("item_url", dto.getItemUrl()); + 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("currency_icon", dto.getCurrencyIcon()); + attrs.put("available_quantity", dto.getAvailableQuantity()); + attrs.put("wfs_available_quantity", dto.getWfsAvailableQuantity()); + attrs.put("buy_box_price", dto.getBuyBoxPrice()); + attrs.put("buy_box_shipping_price", dto.getBuyBoxShippingPrice()); + attrs.put("upc", dto.getUpc()); + attrs.put("product_tax_code", dto.getProductTaxCode()); + attrs.put("offer_end_date", dto.getOfferEndDate()); + attrs.put("review_count", dto.getReviewCount()); + attrs.put("average_rating", dto.getAverageRating()); + attrs.put("brand", dto.getBrand()); + attrs.put("fulfillment_type", dto.getFulfillmentType()); + attrs.put("fulfillment_type_name", dto.getFulfillmentTypeName()); + attrs.put("competitor_price", dto.getCompetitorPrice()); + attrs.put("competitor_ship_price", dto.getCompetitorShipPrice()); + attrs.put("listing_end_time", dto.getListingEndTime()); + attrs.put("variant_unique_id", dto.getVariantUniqueId()); + attrs.put("quantityAdjustAfter", dto.getQuantityAdjustAfter()); + attrs.put("quantityAdjustBefore", dto.getQuantityAdjustBefore()); + attrs.put("quantityUserId", dto.getQuantityUserId()); + attrs.put("quantityUserIdName", dto.getQuantityUserIdName()); + attrs.values().removeAll(Collections.singleton(null)); + return attrs; + } + + /** + * 货币符号 → ISO 代码。无法识别时返回 null,不猜。 + */ + private static String currencyOf(String icon) { + if (icon == null) { + return null; + } + String s = icon.trim(); + if ("$".equals(s) || "US$".equals(s)) { + return "USD"; + } + if ("€".equals(s)) { + return "EUR"; + } + if ("£".equals(s)) { + return "GBP"; + } + if ("C$".equals(s) || "CA$".equals(s)) { + return "CAD"; + } + if ("MXN".equals(s) || "MX$".equals(s)) { + return "MXN"; + } + return null; + } + + private static common.ecommerce.model.support.PlatformTime dateTime(String raw, ZoneId zone, + boolean dateOnly) { + if (raw == null || raw.trim().isEmpty()) { + return null; + } + try { + String value = raw.trim(); + Instant utc = dateOnly + ? LocalDate.parse(value, DATE).atStartOfDay(zone).toInstant() + : LocalDateTime.parse(value, DATE_TIME).atZone(zone).toInstant(); + return common.ecommerce.model.support.PlatformTime.of(utc, zone); + } catch (RuntimeException e) { + return null; + } + } + + private static Money moneyOrNull(String value, String currency) { + if (value == null || value.trim().isEmpty() || currency == null) { + return null; + } + try { + return Money.of(value.trim(), currency); + } catch (RuntimeException e) { + return null; + } + } + + 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; + } +}