From e940945174c71202ab406e3daf9b8b0b5261ae3c Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Tue, 3 Nov 2026 10:16:29 +0800
Subject: [PATCH] =?UTF-8?q?feat(product):=20ProductListing=20=E6=89=A9?=
=?UTF-8?q?=E5=85=85=E6=A0=87=E5=87=86=E5=AD=97=E6=AE=B5=EF=BC=8CSC/VC=20?=
=?UTF-8?q?=E5=85=A8=E5=AD=97=E6=AE=B5=E6=98=A0=E5=B0=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
统一模型新增(都有注释说明对应哪个平台字段):
- platform:业务平台,落库时不必再反查账户
- listingId / asin / parentAsin / gtin:平台商品标识
- attributes:未标准化的原始字段(本地 SKU、库存、费用、排名、尺寸等)
- status 改为枚举 ProductStatus(ACTIVE/INACTIVE/DELETED/UNKNOWN),
rawStatus 保留平台原值
SC 映射:seller_sku / listing_id / asin / item_name / small_image_url /
status+is_delete / price+currency_code / on_sale_time / listing_update_date,
其余 40+ 字段进 attributes。
VC 映射:msku / asin / parent_asin / upc|ean / item_name / small_min_image_url /
status / price,其余进 attributes。
VC 只给货币符号不给 ISO 代码,按符号反推,反推不出时 currency 与 price 都为 null;
¥ 因人民币与日元无法区分,一律返回 null。
Co-Authored-By: Claude
---
.../ecommerce/model/product/ProductListing.java | 172 ++++++++++++++++++-
.../ecommerce/model/product/ProductStatus.java | 20 +++
.../platform/amazon/sc/dto/AmazonScListingDto.java | 183 +++++++++++++++++++++
.../amazon/sc/product/AmazonScProductSource.java | 149 +++++++++++++++--
.../platform/amazon/vc/dto/AmazonVcListingDto.java | 51 ++++++
.../amazon/vc/product/AmazonVcProductSource.java | 160 ++++++++++++++++--
.../ecommerce/testkit/FakeDirectAdapter.java | 5 +-
7 files changed, 707 insertions(+), 33 deletions(-)
create mode 100644 core/src/main/java/common/ecommerce/model/product/ProductStatus.java
diff --git a/core/src/main/java/common/ecommerce/model/product/ProductListing.java b/core/src/main/java/common/ecommerce/model/product/ProductListing.java
index af6e14d..1f445d1 100644
--- a/core/src/main/java/common/ecommerce/model/product/ProductListing.java
+++ b/core/src/main/java/common/ecommerce/model/product/ProductListing.java
@@ -1,6 +1,8 @@
package common.ecommerce.model.product;
import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.model.Platform;
+import common.ecommerce.model.support.Money;
import common.ecommerce.model.support.PlatformTime;
import java.util.ArrayList;
@@ -10,31 +12,90 @@ import java.util.Objects;
/**
* 统一商品 / Listing。
+ *
+ * 各渠道字段名不同、含义相同的部分,全部在此收敛为标准字段;
+ * 平台原始值另存于 {@code raw*} 字段,便于排查与后续扩展。
+ *
+ * 字段分三组:
+ *
+ * - 标识:platform / omsStoreId / platformSku / listingId / asin …
+ * - 内容:title / description / imageUrls / attributes
+ * - 状态与价格:status / rawStatus / price / currency
+ *
*/
public final class ProductListing {
+ // ---------------------------------------------------------------- 标识
+
+ private final Platform platform;
private final String omsStoreId;
+ /** 平台侧 SKU,参与 canonicalKey。领星 SC 取 seller_sku,VC 取 msku。 */
private final String platformSku;
+ /** 平台自身的 Listing 标识;亚马逊 SC 是 listing_id,VC 无,可空。 */
+ private final String listingId;
+ /** 平台商品编码;亚马逊是 ASIN。 */
+ private final String asin;
+ /** 父商品编码;亚马逊是父 ASIN,变体商品才有。 */
+ private final String parentAsin;
+ /** 全球贸易项目代码,如 UPC / EAN / GTIN。 */
+ private final String gtin;
+
+ // ---------------------------------------------------------------- 内容
+
private final String title;
private final List imageUrls;
- private final String status;
+ /** 平台原始属性(尺寸、变体、排名等未标准化字段),键为渠道字段名。 */
+ private final java.util.Map attributes;
+
+ // ---------------------------------------------------------------- 状态与价格
+
+ /** 归一化状态。 */
+ private final ProductStatus status;
+ /** 平台原始状态值,如 "1"、"-1"、"Active"。 */
+ private final String rawStatus;
+ /** 平台价格;币种见 {@link #currency()}。 */
+ private final Money price;
+ /** 币种代码,如 USD;平台不给时为 null。 */
+ private final String currency;
+ /** 开售时间;平台不提供时为 null。 */
+ private final PlatformTime listedAt;
+ /** 内容最后更新时间;平台不提供时为 null。 */
private final PlatformTime updatedAt;
+
+ // ---------------------------------------------------------------- 来源
+
private final ChannelProvider sourceProvider;
private ProductListing(Builder b) {
+ this.platform = Objects.requireNonNull(b.platform, "platform");
this.omsStoreId = Objects.requireNonNull(b.omsStoreId, "omsStoreId");
this.platformSku = Objects.requireNonNull(b.platformSku, "platformSku");
+ this.listingId = b.listingId;
+ this.asin = b.asin;
+ this.parentAsin = b.parentAsin;
+ this.gtin = b.gtin;
this.title = b.title;
this.imageUrls = Collections.unmodifiableList(new ArrayList(b.imageUrls));
- this.status = b.status;
+ this.attributes = Collections.unmodifiableMap(new java.util.LinkedHashMap(b.attributes));
+ this.status = b.status == null ? ProductStatus.UNKNOWN : b.status;
+ this.rawStatus = b.rawStatus;
+ this.price = b.price;
+ this.currency = b.currency;
+ this.listedAt = b.listedAt;
this.updatedAt = b.updatedAt;
- this.sourceProvider = b.sourceProvider;
+ this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider");
}
public static Builder builder() {
return new Builder();
}
+ // ---------------------------------------------------------------- getters
+
+ public Platform platform() {
+ return platform;
+ }
+
public String omsStoreId() {
return omsStoreId;
}
@@ -43,6 +104,22 @@ public final class ProductListing {
return platformSku;
}
+ public String listingId() {
+ return listingId;
+ }
+
+ public String asin() {
+ return asin;
+ }
+
+ public String parentAsin() {
+ return parentAsin;
+ }
+
+ public String gtin() {
+ return gtin;
+ }
+
public String title() {
return title;
}
@@ -51,10 +128,30 @@ public final class ProductListing {
return imageUrls;
}
- public String status() {
+ public java.util.Map attributes() {
+ return attributes;
+ }
+
+ public ProductStatus status() {
return status;
}
+ public String rawStatus() {
+ return rawStatus;
+ }
+
+ public Money price() {
+ return price;
+ }
+
+ public String currency() {
+ return currency;
+ }
+
+ public PlatformTime listedAt() {
+ return listedAt;
+ }
+
public PlatformTime updatedAt() {
return updatedAt;
}
@@ -63,16 +160,33 @@ public final class ProductListing {
return sourceProvider;
}
+ // ---------------------------------------------------------------- builder
+
public static final class Builder {
+ private Platform platform;
private String omsStoreId;
private String platformSku;
+ private String listingId;
+ private String asin;
+ private String parentAsin;
+ private String gtin;
private String title;
private List imageUrls = Collections.emptyList();
- private String status;
+ private java.util.Map attributes = Collections.emptyMap();
+ private ProductStatus status;
+ private String rawStatus;
+ private Money price;
+ private String currency;
+ private PlatformTime listedAt;
private PlatformTime updatedAt;
private ChannelProvider sourceProvider;
+ public Builder platform(Platform platform) {
+ this.platform = platform;
+ return this;
+ }
+
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
@@ -83,6 +197,26 @@ public final class ProductListing {
return this;
}
+ public Builder listingId(String listingId) {
+ this.listingId = listingId;
+ return this;
+ }
+
+ public Builder asin(String asin) {
+ this.asin = asin;
+ return this;
+ }
+
+ public Builder parentAsin(String parentAsin) {
+ this.parentAsin = parentAsin;
+ return this;
+ }
+
+ public Builder gtin(String gtin) {
+ this.gtin = gtin;
+ return this;
+ }
+
public Builder title(String title) {
this.title = title;
return this;
@@ -93,11 +227,37 @@ public final class ProductListing {
return this;
}
- public Builder status(String status) {
+ public Builder attributes(java.util.Map attributes) {
+ this.attributes = attributes == null
+ ? Collections.emptyMap() : attributes;
+ return this;
+ }
+
+ public Builder status(ProductStatus status) {
this.status = status;
return this;
}
+ public Builder rawStatus(String rawStatus) {
+ this.rawStatus = rawStatus;
+ return this;
+ }
+
+ public Builder price(Money price) {
+ this.price = price;
+ return this;
+ }
+
+ public Builder currency(String currency) {
+ this.currency = currency;
+ return this;
+ }
+
+ public Builder listedAt(PlatformTime listedAt) {
+ this.listedAt = listedAt;
+ return this;
+ }
+
public Builder updatedAt(PlatformTime updatedAt) {
this.updatedAt = updatedAt;
return this;
diff --git a/core/src/main/java/common/ecommerce/model/product/ProductStatus.java b/core/src/main/java/common/ecommerce/model/product/ProductStatus.java
new file mode 100644
index 0000000..94eea66
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/model/product/ProductStatus.java
@@ -0,0 +1,20 @@
+package common.ecommerce.model.product;
+
+/**
+ * 统一商品状态。
+ *
+ * 各渠道原始状态值不同(领星亚马逊 SC 是 0/1,VC 是 -1/0/1,其它平台可能是字符串),
+ * 由各自的 Mapper 归一到这里;无法识别时用 {@link #UNKNOWN},并保留原值在
+ * {@link ProductListing#rawStatus()}。
+ */
+public enum ProductStatus {
+
+ /** 在售。 */
+ ACTIVE,
+ /** 停售。 */
+ INACTIVE,
+ /** 已删除。 */
+ DELETED,
+ /** 无法识别;原值见 {@code rawStatus}。 */
+ UNKNOWN
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/dto/AmazonScListingDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/dto/AmazonScListingDto.java
index 8cbebff..1b5ac59 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/dto/AmazonScListingDto.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/dto/AmazonScListingDto.java
@@ -5,6 +5,9 @@ import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
+import java.util.ArrayList;
+import java.util.List;
+
/**
* 领星 · 亚马逊 SC Listing({@code /erp/sc/data/mws/listing} 的 {@code data[]})。
*
@@ -70,4 +73,184 @@ public class AmazonScListingDto {
/** 商城所在国家。 */
@JsonProperty("marketplace")
private String marketplace;
+
+ /** 亚马逊定义的 Listing id,可能为空。 */
+ @JsonProperty("listing_id")
+ private String listingId;
+
+ /** FNSKU。 */
+ @JsonProperty("fnsku")
+ private String fnsku;
+
+ /** 本地产品 SKU。 */
+ @JsonProperty("local_sku")
+ private String localSku;
+
+ /** 本地品名。 */
+ @JsonProperty("local_name")
+ private String localName;
+
+ /** 备注。 */
+ @JsonProperty("remark")
+ private String remark;
+
+ /** List Price。 */
+ @JsonProperty("list_price")
+ private String listPrice;
+
+ /** 含促销、运费、积分的总价。 */
+ @JsonProperty("landed_price")
+ private String landedPrice;
+
+ /** 优惠价。 */
+ @JsonProperty("listing_price")
+ private String listingPrice;
+
+ /** 运费。 */
+ @JsonProperty("shipping")
+ private String shipping;
+
+ /** 积分(日本站才有)。 */
+ @JsonProperty("points")
+ private String points;
+
+ /** FBM 库存。 */
+ @JsonProperty("quantity")
+ private Integer quantity;
+
+ /** FBA 可售。 */
+ @JsonProperty("afn_fulfillable_quantity")
+ private Integer afnFulfillableQuantity;
+
+ /** FBA 不可售。 */
+ @JsonProperty("afn_unsellable_quantity")
+ private Integer afnUnsellableQuantity;
+
+ /** 待调仓。 */
+ @JsonProperty("reserved_fc_transfers")
+ private Integer reservedFcTransfers;
+
+ /** 调仓中。 */
+ @JsonProperty("reserved_fc_processing")
+ private Integer reservedFcProcessing;
+
+ /** 待发货。 */
+ @JsonProperty("reserved_customerorders")
+ private Integer reservedCustomerorders;
+
+ /** 在途。 */
+ @JsonProperty("afn_inbound_shipped_quantity")
+ private Integer afnInboundShippedQuantity;
+
+ /** 计划入库。 */
+ @JsonProperty("afn_inbound_working_quantity")
+ private Integer afnInboundWorkingQuantity;
+
+ /** 入库中。 */
+ @JsonProperty("afn_inbound_receiving_quantity")
+ private Integer afnInboundReceivingQuantity;
+
+ /** 预计 FBA 费(API 口径)。 */
+ @JsonProperty("fba_fee")
+ private String fbaFee;
+
+ /** FBA 费更新时间(API 口径)。 */
+ @JsonProperty("fba_fee_update_time")
+ private String fbaFeeUpdateTime;
+
+ /** 预计 FBA 费(报表口径)。 */
+ @JsonProperty("report_fba_fee")
+ private String reportFbaFee;
+
+ /** FBA 费更新时间(报表口径)。 */
+ @JsonProperty("report_fba_fee_update_time")
+ private String reportFbaFeeUpdateTime;
+
+ /** 平台费(报表口径)。 */
+ @JsonProperty("estimated_referral_fee")
+ private String estimatedReferralFee;
+
+ /** 平台费率,形如 15.0%,无法计算时为空串。 */
+ @JsonProperty("estimated_referral_fee_rate")
+ private String estimatedReferralFeeRate;
+
+ /** 品牌。 */
+ @JsonProperty("seller_brand")
+ private String sellerBrand;
+
+ /** 排名类别(已废弃,用 seller_category_new)。 */
+ @JsonProperty("seller_category")
+ private String sellerCategory;
+
+ /** 排名类别(新)。 */
+ @JsonProperty("seller_category_new")
+ private List
*
- * 注意:该接口不支持按时间窗过滤,只能全量翻页后由调用方比对。
+ * 注意:该接口不支持按时间窗过滤,{@code ProductQuery.updatedAfter/Before} 会被忽略。
*/
public final class AmazonVcProductSource implements LingxingProductSource {
private static final int MAX_PAGE_SIZE = 200;
- /** on_sale_time 是 Y-m-d 日期。 */
+ /** 只有日期的字段,如 on_sale_time。 */
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
@Override
@@ -67,35 +68,168 @@ public final class AmazonVcProductSource implements LingxingProductSource {
return Page.of(out, hasMore ? String.valueOf(nextOffset) : null);
}
+ /**
+ * 领星 VC Listing → 统一模型。
+ *
+ * 统一字段的来源:
+ *
+ * - platformSku ← {@code msku}(平台侧 SKU)
+ * - asin / parentAsin ← {@code asin} / {@code parent_asin}
+ * - gtin ← {@code upc},缺失时用 {@code ean}
+ * - listingId ← 无(VC 接口不返回 listing_id)
+ * - title ← {@code item_name}
+ * - imageUrls ← {@code small_min_image_url}(单张)
+ * - status ← {@code status}(-1 删除 / 0 停售 / 1 在售)
+ * - rawStatus ← 原始 {@code status} 值
+ * - price / currency ← {@code price} / {@code price_currency_icon} 反推(见下)
+ * - listedAt ← {@code on_sale_time}(仅日期,按市场当地零点)
+ * - updatedAt ← 无(VC 接口没有内容更新时间,返回 null)
+ * - attributes ← 其余全部原始字段
+ *
+ *
+ * 币种说明:VC 只给货币符号({@code price_currency_icon}),不给 ISO 代码。
+ * 这里按符号反推常见币种,反推不出时 currency 为 null、price 也为 null,
+ * 原值保留在 attributes 里。改由店铺币种兜底需要账户信息,当前不猜。
+ */
private ProductListing toProductListing(AmazonVcListingDto dto, LingxingCall call) {
- List images = dto.getSmallMinImageUrl() == null
- ? Collections.emptyList()
- : Collections.singletonList(dto.getSmallMinImageUrl());
+ ZoneId zone = ZoneId.of(call.ctx().account().marketplaceZone());
+ String currency = currencyOf(dto.getPriceCurrencyIcon());
+ String gtin = firstNonBlank(dto.getUpc(), dto.getEan());
return ProductListing.builder()
+ .platform(call.ctx().platform())
.omsStoreId(call.ctx().omsStoreId())
- // msku 是平台侧 SKU,参与 canonicalKey
.platformSku(dto.getMsku())
+ .asin(trimToNull(dto.getAsin()))
+ .parentAsin(trimToNull(dto.getParentAsin()))
+ .gtin(gtin)
.title(dto.getItemName())
- .imageUrls(images)
- // -1 已删除 / 0 停售 / 1 在售;保留原值,由宿主解释
- .status(dto.getStatus() == null ? null : String.valueOf(dto.getStatus()))
- .updatedAt(onSaleTime(dto.getOnSaleTime(), call))
+ .imageUrls(dto.getSmallMinImageUrl() == null
+ ? Collections.emptyList()
+ : Collections.singletonList(dto.getSmallMinImageUrl()))
+ .status(statusOf(dto))
+ .rawStatus(dto.getStatus() == null ? null : String.valueOf(dto.getStatus()))
+ .price(moneyOrNull(dto.getPrice(), currency))
+ .currency(currency)
+ .listedAt(saleDate(dto.getOnSaleTime(), zone))
+ // VC 接口没有内容更新时间
+ .updatedAt(null)
+ .attributes(attributesOf(dto))
.sourceProvider(ChannelProvider.LINGXING)
.build();
}
- /** on_sale_time 只有日期,按市场当地时区零点解析;缺失或非法时返回 null。 */
- private static PlatformTime onSaleTime(String raw, LingxingCall call) {
+ /** VC:-1 已删除,0 停售,1 在售。 */
+ private static ProductStatus statusOf(AmazonVcListingDto dto) {
+ if (dto.getStatus() == null) {
+ return ProductStatus.UNKNOWN;
+ }
+ switch (dto.getStatus()) {
+ case 1:
+ return ProductStatus.ACTIVE;
+ case 0:
+ return ProductStatus.INACTIVE;
+ case -1:
+ return ProductStatus.DELETED;
+ default:
+ return ProductStatus.UNKNOWN;
+ }
+ }
+
+ /** 未标准化的原始字段统一放进 attributes。 */
+ private static Map attributesOf(AmazonVcListingDto dto) {
+ Map attrs = new LinkedHashMap();
+ attrs.put("vc_store_id", dto.getVcStoreId());
+ attrs.put("asin_url", dto.getAsinUrl());
+ attrs.put("local_sku", dto.getLocalSku());
+ attrs.put("local_name", dto.getLocalName());
+ attrs.put("upc", dto.getUpc());
+ attrs.put("ean", dto.getEan());
+ attrs.put("category_id", dto.getCategoryId());
+ attrs.put("category_name", dto.getCategoryName());
+ attrs.put("brand_id", dto.getBrandId());
+ attrs.put("product_id", dto.getProductId());
+ attrs.put("classification_rank", dto.getClassificationRank());
+ attrs.put("display_group_rank", dto.getDisplayGroupRank());
+ attrs.put("reviews_num", dto.getReviewsNum());
+ attrs.put("stars", dto.getStars());
+ attrs.put("principal_list", dto.getPrincipalList());
+ attrs.put("remark", dto.getRemark());
+ attrs.put("price_currency_icon", dto.getPriceCurrencyIcon());
+ attrs.put("on_sale_time", dto.getOnSaleTime());
+ 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 ("¥".equals(s) || "¥".equals(s)) {
+ // 人民币与日元共用符号,无法区分;返回 null 避免误判
+ return null;
+ }
+ if ("C$".equals(s) || "CA$".equals(s)) {
+ return "CAD";
+ }
+ if ("A$".equals(s) || "AU$".equals(s)) {
+ return "AUD";
+ }
+ return null;
+ }
+
+ /** on_sale_time 只有日期,按市场当地时区零点解析。 */
+ private static PlatformTime saleDate(String raw, ZoneId zone) {
if (raw == null || raw.trim().isEmpty()) {
return null;
}
try {
- ZoneId zone = ZoneId.of(call.ctx().account().marketplaceZone());
Instant utc = LocalDate.parse(raw.trim(), DATE).atStartOfDay(zone).toInstant();
return PlatformTime.of(utc, zone);
} catch (DateTimeParseException e) {
return null;
}
}
+
+ private static common.ecommerce.model.support.Money moneyOrNull(String value, String currency) {
+ if (value == null || value.trim().isEmpty() || currency == null) {
+ return null;
+ }
+ try {
+ return common.ecommerce.model.support.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;
+ }
}
diff --git a/testkit/src/main/java/common/ecommerce/testkit/FakeDirectAdapter.java b/testkit/src/main/java/common/ecommerce/testkit/FakeDirectAdapter.java
index 798a7fb..1b618f7 100644
--- a/testkit/src/main/java/common/ecommerce/testkit/FakeDirectAdapter.java
+++ b/testkit/src/main/java/common/ecommerce/testkit/FakeDirectAdapter.java
@@ -14,6 +14,7 @@ import common.ecommerce.model.Platform;
import common.ecommerce.model.support.PlatformTime;
import common.ecommerce.model.product.ProductListing;
import common.ecommerce.model.product.ProductQuery;
+import common.ecommerce.model.product.ProductStatus;
import common.ecommerce.model.product.ProductRef;
import common.ecommerce.model.product.ProductSyncStrategy;
import common.ecommerce.model.order.SalesOrder;
@@ -266,7 +267,9 @@ public final class FakeDirectAdapter implements SalesOrderCapable, ProductCapabl
.omsStoreId("oms-test-001")
.platformSku("SKU-" + i)
.title("Fake product " + i)
- .status("ACTIVE")
+ .platform(platform)
+ .status(ProductStatus.ACTIVE)
+ .rawStatus("ACTIVE")
.sourceProvider(ChannelProvider.DIRECT)
.build());
}