Browse Source

feat(lingxing): 接入多平台店铺与 Walmart 在线商品

- 新增 MultiPlatformShopSource:
  /pb/mp/shop/v2/getSellerList,offset/length 内部翻页,
  按 platform_code + is_sync/status 过滤
- 新增 WalmartProductSource:
  /basicOpen/multiplatform/walmart/list,更新时间窗 ≤31 天,
  兼容 data.list 与 data[] 两种响应
- WalmartSubPlatform 装配 shopSource / productSource
- LingxingApi 增加两个接口枚举,常量补分页与窗口上限
- smoke 增加 Walmart 店铺 → 商品链路

说明:
- Walmart 商品接口没有返回更新时间,ProductListing.updatedAt 暂为 null
- listing 日期参数文档未标时区,按北京时间解析,待真实报文核对
feature/supplier-lingxing
lml 2 weeks ago
parent
commit
2bbc5e3cf3
  1. 6
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java
  2. 8
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java
  3. 49
      lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/dto/MultiPlatformShopDto.java
  4. 83
      lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/shop/MultiPlatformShopSource.java
  5. 21
      lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java
  6. 99
      lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/dto/WalmartListingDto.java
  7. 146
      lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java
  8. 51
      lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java

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

@ -26,6 +26,9 @@ public enum LingxingApi { @@ -26,6 +26,9 @@ public enum LingxingApi {
/** 亚马逊 VC 店铺列表。POST,offset/length 分页,上限 200。 */
SHOP_LIST_AMAZON_VC("/basicOpen/platformAuth/vcSeller/pageList", 1),
/** 多平台店铺信息。POST,offset/length 分页,上限 200;可按 platform_code 过滤。 */
SHOP_LIST_MULTI_PLATFORM("/pb/mp/shop/v2/getSellerList", 10),
/** 亚马逊 VC 订单列表(DF / PO / DI)。POST,offset/length 分页,上限 200。 */
ORDER_LIST_AMAZON_VC("/basicOpen/platformOrder/vcOrder/pageList", 1),
@ -38,6 +41,9 @@ public enum LingxingApi { @@ -38,6 +41,9 @@ public enum LingxingApi {
/** 亚马逊 SC Listing 列表。POST,offset/length 分页,上限 1000。 */
LISTING_AMAZON_SC("/erp/sc/data/mws/listing", 1),
/** Walmart 在线商品。POST,offset/length 分页,上限 200,时间窗 ≤31 天。 */
LISTING_WALMART("/basicOpen/multiplatform/walmart/list", 1),
/**
* 亚马逊 SC 订单列表。POST,offset/length 分页,length 上限 5000;
* 查询时间窗不超过 1 年。

8
lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java

@ -51,6 +51,14 @@ public final class LingxingConstants { @@ -51,6 +51,14 @@ public final class LingxingConstants {
/** 亚马逊 VC 订单查询时间跨度上限:90 天。 */
public static final int VC_MAX_QUERY_DAYS = 90;
/** 多平台店铺列表分页 length 上限。 */
public static final int MULTI_PLATFORM_MAX_PAGE_SIZE = 200;
/** Walmart 在线商品分页 length 上限。 */
public static final int WALMART_MAX_PAGE_SIZE = 200;
/** Walmart 在线商品查询时间跨度上限:31 天。 */
public static final int WALMART_MAX_QUERY_DAYS = 31;
/** 结算交易明细分页 length 上限。 */
public static final int SETTLEMENT_MAX_PAGE_SIZE = 10000;
/** 结算时间查询跨度上限:7 天(双闭区间)。 */

49
lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/dto/MultiPlatformShopDto.java

@ -0,0 +1,49 @@ @@ -0,0 +1,49 @@
package common.ecommerce.lingxing.platform.multiplatform.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/**
* 领星 · 多平台店铺({@code /pb/mp/shop/v2/getSellerList} 的 {@code data.list[]})。
*
* <p>{@code store_id} 是多平台店铺唯一键;{@code sid} 只有亚马逊店铺才有意义。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class MultiPlatformShopDto {
/** 店铺 ID,多平台唯一键。 */
@JsonProperty("store_id")
private String storeId;
/** 亚马逊店铺 sid,非亚马逊平台为空。 */
@JsonProperty("sid")
private String sid;
/** 店铺名称。 */
@JsonProperty("store_name")
private String storeName;
/** 平台 code;响应里可能是字符串,用 Integer 接收。 */
@JsonProperty("platform_code")
private Integer platformCode;
/** 平台名称,如 Walmart。 */
@JsonProperty("platform_name")
private String platformName;
/** 店铺币种。 */
@JsonProperty("currency")
private String currency;
/** 店铺同步状态:1 启用、0 停用。 */
@JsonProperty("is_sync")
private Integer isSync;
/** 店铺授权状态:1 正常授权、0 授权失败。 */
@JsonProperty("status")
private Integer status;
}

83
lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/shop/MultiPlatformShopSource.java

@ -0,0 +1,83 @@ @@ -0,0 +1,83 @@
package common.ecommerce.lingxing.platform.multiplatform.shop;
import common.ecommerce.capability.AggregatorCapable.SubChannel;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.lingxing.LingxingApi;
import common.ecommerce.lingxing.LingxingConstants;
import common.ecommerce.lingxing.http.LingxingEnvelope;
import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.multiplatform.dto.MultiPlatformShopDto;
import common.ecommerce.lingxing.platform.shop.LingxingShopSource;
import common.ecommerce.model.Platform;
import common.ecommerce.model.account.ChannelAccount;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 领星 · 多平台店铺列表。
*
* <p>接口 {@code /pb/mp/shop/v2/getSellerList}:POST,{@code offset}/{@code length}
* 分页(上限 200),令牌桶 10 req/s。</p>
*
* <p>只返回当前账户 {@code platformCode} 对应的店铺,并过滤为「启用 + 正常授权」。
* 响应结构是 {@code data.list[]} + {@code data.total}。</p>
*/
public final class MultiPlatformShopSource implements LingxingShopSource {
private static final int SYNC_ENABLED = 1;
private static final int STATUS_AUTHORIZED = 1;
private static final String OP = "shops.list.multi";
@Override
public List<SubChannel> shops(LingxingCall call) {
ChannelAccount account = call.ctx().account();
int length = LingxingConstants.MULTI_PLATFORM_MAX_PAGE_SIZE;
int offset = 0;
List<SubChannel> out = new ArrayList<SubChannel>();
while (true) {
Map<String, Object> body = new LinkedHashMap<String, Object>();
body.put("offset", offset);
body.put("length", length);
body.put("is_sync", SYNC_ENABLED);
body.put("status", STATUS_AUTHORIZED);
if (account.platformCode() != null) {
body.put("platform_code", Collections.singletonList(account.platformCode()));
}
HttpRequest req = call.signed(LingxingApi.SHOP_LIST_MULTI_PLATFORM, body, OP);
HttpResponse resp = call.execute(req);
LingxingEnvelope envelope = call.envelope(resp, OP);
List<MultiPlatformShopDto> shops =
call.json().listAt(envelope.body(), "data.list", MultiPlatformShopDto.class);
for (MultiPlatformShopDto shop : shops) {
if (shop.getStoreId() == null || shop.getStoreId().trim().isEmpty()) {
continue;
}
Integer code = shop.getPlatformCode();
Platform platform = LingxingConstants.toPlatform(code);
out.add(new SubChannel(
code == null ? 0 : code,
shop.getStoreId(),
platform == null ? Platform.CUSTOM : platform,
shop.getStoreName()));
}
offset += shops.size();
boolean exhausted = shops.size() < length
|| (envelope.total() >= 0 && offset >= envelope.total());
if (exhausted) {
break;
}
}
return Collections.unmodifiableList(out);
}
}

21
lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java

@ -3,19 +3,30 @@ package common.ecommerce.lingxing.platform.walmart; @@ -3,19 +3,30 @@ package common.ecommerce.lingxing.platform.walmart;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.lingxing.platform.LingxingSubPlatform;
import common.ecommerce.lingxing.platform.multiplatform.shop.MultiPlatformShopSource;
import common.ecommerce.lingxing.platform.order.LingxingOrderSource;
import common.ecommerce.lingxing.platform.product.LingxingProductSource;
import common.ecommerce.lingxing.platform.shop.LingxingShopSource;
import common.ecommerce.lingxing.platform.walmart.order.WalmartOrderSource;
import common.ecommerce.lingxing.platform.walmart.product.WalmartProductSource;
import common.ecommerce.model.Platform;
/**
* 领星 · 沃尔玛子平台:只做能力组合,不写业务逻辑。
*
* <p>订单复用领星多平台统一接口;店铺用多平台店铺接口(按 platform_code=10008 过滤);
* 商品用 Walmart 在线商品接口。</p>
*/
public final class WalmartSubPlatform implements LingxingSubPlatform {
private final LingxingOrderSource orders;
private final LingxingProductSource products;
private final LingxingShopSource shops;
public WalmartSubPlatform(HttpTransport transport, JacksonJsonCodec json) {
this.orders = new WalmartOrderSource(transport, json);
this.products = new WalmartProductSource();
this.shops = new MultiPlatformShopSource();
}
@Override
@ -27,4 +38,14 @@ public final class WalmartSubPlatform implements LingxingSubPlatform { @@ -27,4 +38,14 @@ public final class WalmartSubPlatform implements LingxingSubPlatform {
public LingxingOrderSource orderSource() {
return orders;
}
@Override
public LingxingProductSource productSource() {
return products;
}
@Override
public LingxingShopSource shopSource() {
return shops;
}
}

99
lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/dto/WalmartListingDto.java

@ -0,0 +1,99 @@ @@ -0,0 +1,99 @@
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;
/**
* 领星 · Walmart 在线商品
* ({@code /basicOpen/multiplatform/walmart/list} 的 {@code data[]} / {@code data.list[]})。
*
* <p>平台 SKU 是 {@code msku};{@code item_id} 是 Walmart 商品 ID。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class WalmartListingDto {
/** 产品跳转链接。 */
@JsonProperty("item_url")
private String itemUrl;
/** Walmart 商品 ID。 */
@JsonProperty("item_id")
private String itemId;
/** 图片链接。 */
@JsonProperty("picture_url")
private String pictureUrl;
/** 平台 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 等。 */
@JsonProperty("status_name")
private String statusName;
@JsonProperty("store_id")
private String storeId;
@JsonProperty("store_name")
private String storeName;
@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;
@JsonProperty("buy_box_price")
private String buyBoxPrice;
@JsonProperty("gtin")
private String gtin;
@JsonProperty("upc")
private String upc;
@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("listing_start_time")
private String listingStartTime;
/** 销售结束时间。 */
@JsonProperty("listing_end_time")
private String listingEndTime;
@JsonProperty("variant_unique_id")
private String variantUniqueId;
}

146
lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/product/WalmartProductSource.java

@ -0,0 +1,146 @@ @@ -0,0 +1,146 @@
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.LingxingConstants;
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.account.ChannelAccount;
import common.ecommerce.model.product.ProductListing;
import common.ecommerce.model.product.ProductQuery;
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.time.temporal.ChronoUnit;
import java.util.ArrayList;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 领星 · Walmart 在线商品。
*
* <p>接口 {@code /basicOpen/multiplatform/walmart/list}:POST,{@code offset}/{@code length}
* 分页(上限 200),令牌桶 1 req/s;时间窗按「创建时间 / 更新时间」过滤,最多 31 天。</p>
*
* <p>响应有两种形态:文档字段树写 {@code data.list[]},示例又给 {@code data[]},
* 这里先按 {@code data.list} 解析,为空再回退 {@code data},两种都能吃。</p>
*
* <p><b>时区待核对</b>:{@code listing_start_time}/{@code listing_end_time} 只到日期且未标时区,
* 这里按领星系统时间(北京时间)换算。</p>
*/
public final class WalmartProductSource implements LingxingProductSource {
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
/** 文档未注明时区,按 ERP 系统时间(北京时间)解释,待真实报文核对。 */
private static final ZoneId SYSTEM_ZONE = PlatformTime.BEIJING_ZONE;
/** listing_time_field:2 = 更新时间。 */
private static final int TIME_FIELD_UPDATE = 2;
private static final String OP = "products.pull.walmart";
@Override
public Page<ProductListing> products(LingxingCall call, ProductQuery query) {
ChannelAccount account = call.ctx().account();
int length = Math.min(query.pageSize() <= 0 ? 20 : query.pageSize(),
LingxingConstants.WALMART_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);
if (trimToNull(account.externalStoreId()) != null) {
body.put("store_ids", Collections.singletonList(account.externalStoreId().trim()));
}
Instant from = query.updatedAfter();
if (from != null) {
LocalDate endDate = query.updatedBefore() != null
? LocalDateTime.ofInstant(query.updatedBefore(), SYSTEM_ZONE).toLocalDate()
: LocalDateTime.ofInstant(Instant.now(call.ctx().clock()), SYSTEM_ZONE).toLocalDate();
LocalDate startDate = LocalDateTime.ofInstant(from, SYSTEM_ZONE).toLocalDate();
// 文档:开始结束时间不超过 31 天,双闭区间
if (ChronoUnit.DAYS.between(startDate, endDate) > LingxingConstants.WALMART_MAX_QUERY_DAYS) {
startDate = endDate.minusDays(LingxingConstants.WALMART_MAX_QUERY_DAYS);
}
body.put("listing_time_field", TIME_FIELD_UPDATE);
body.put("listing_start_time", DATE.format(startDate));
body.put("listing_end_time", DATE.format(endDate));
}
HttpRequest req = call.signed(LingxingApi.LISTING_WALMART, body, OP);
HttpResponse resp = call.execute(req);
LingxingEnvelope envelope = call.envelope(resp, OP);
List<WalmartListingDto> dtos = call.json().listAt(envelope.body(), "data.list", WalmartListingDto.class);
if (dtos.isEmpty()) {
dtos = call.json().listAt(envelope.body(), "data", WalmartListingDto.class);
}
List<ProductListing> out = new ArrayList<ProductListing>(dtos.size());
for (WalmartListingDto dto : dtos) {
ProductListing listing = toProductListing(dto, call);
if (listing != null) {
out.add(listing);
}
}
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);
}
private ProductListing toProductListing(WalmartListingDto dto, LingxingCall call) {
// MSKU 是平台 SKU;缺失时退回商品 ID / 本地 SKU
String platformSku = firstNonBlank(dto.getMsku(), dto.getItemId(), dto.getLocalSku());
if (platformSku == null) {
return null;
}
List<String> images = trimToNull(dto.getPictureUrl()) == null
? Collections.<String>emptyList()
: Collections.singletonList(dto.getPictureUrl().trim());
return ProductListing.builder()
.omsStoreId(call.ctx().omsStoreId())
.platformSku(platformSku)
.title(firstNonBlank(dto.getTitle(), dto.getLocalName()))
.imageUrls(images)
.status(trimToNull(dto.getStatusName()))
// 接口没有返回更新时间;listing_start_time 是创建时间,不能冒充更新时间
.updatedAt(null)
.sourceProvider(ChannelProvider.LINGXING)
.build();
}
private static String firstNonBlank(String... values) {
for (String value : values) {
String trimmed = trimToNull(value);
if (trimmed != null) {
return trimmed;
}
}
return null;
}
private static String trimToNull(String value) {
if (value == null) {
return null;
}
String trimmed = value.trim();
return trimmed.isEmpty() ? null : trimmed;
}
}

51
lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java

@ -15,6 +15,8 @@ import common.ecommerce.model.account.ChannelAccount; @@ -15,6 +15,8 @@ import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.model.order.SalesOrderRef;
import common.ecommerce.model.product.ProductListing;
import common.ecommerce.model.product.ProductQuery;
import common.ecommerce.model.settlement.SettlementQuery;
import common.ecommerce.model.settlement.SettlementTransaction;
import common.ecommerce.model.support.Page;
@ -212,6 +214,51 @@ class LingxingLiveSmokeTest { @@ -212,6 +214,51 @@ class LingxingLiveSmokeTest {
}
/**
* 第 4 步(多平台):列 Walmart 店铺,再拉一页 Walmart 在线商品。
*
* <p>店铺来自 {@code /pb/mp/shop/v2/getSellerList},商品来自
* {@code /basicOpen/multiplatform/walmart/list}。</p>
*/
@Test
void listsWalmartShopsAndProducts() {
requireCredentials();
LingxingAdapter adapter = adapter();
ChannelAccount discovery = walmartAccount("0");
List<SubChannel> shops = adapter.listSubChannels(context(discovery, "smoke-walmart-shops-"));
System.out.println("[walmart shops] count=" + shops.size());
for (SubChannel shop : shops) {
System.out.println(" store_id=" + shop.externalStoreId()
+ " name=" + shop.name()
+ " platform=" + shop.platform());
}
if (shops.isEmpty()) {
System.out.println("[walmart shops] 没有已授权店铺,跳过商品拉取");
return;
}
ChannelContext ctx = context(walmartAccount(shops.get(0).externalStoreId()),
"smoke-walmart-products-");
Instant to = Instant.now();
Instant from = to.minus(Duration.ofDays(7));
Page<ProductListing> page = adapter.pull(ctx, ProductQuery.builder()
.updatedAfter(from)
.updatedBefore(to)
.pageSize(20)
.build());
System.out.println("[walmart products] store_id=" + ctx.account().externalStoreId()
+ " window=" + from + " .. " + to
+ " items=" + page.size() + " nextCursor=" + page.nextCursor());
for (ProductListing p : page.items()) {
System.out.println(" msku=" + p.platformSku()
+ " status=" + p.status()
+ " title=" + p.title()
+ " images=" + p.imageUrls().size());
}
}
/**
* 第 5 步(亚马逊 VC):先列 VC 店铺拿 vc_store_id,再拉订单列表,最后取一单详情。
*
* <p>VC 详情分 DF / PO 两个接口,{@code get()} 会先按订单编号查出类型再分派。</p>
@ -369,6 +416,10 @@ class LingxingLiveSmokeTest { @@ -369,6 +416,10 @@ class LingxingLiveSmokeTest {
return account(Platform.AMAZON_VC, LingxingConstants.PLATFORM_CODE_AMAZON_VC, vcStoreId);
}
private ChannelAccount walmartAccount(String storeId) {
return account(Platform.WALMART_SC, 10008, storeId);
}
private ChannelAccount account(Platform platform, int platformCode, String storeId) {
return ChannelAccount.builder()
.key(AccountKey.of(ChannelProvider.LINGXING, platform, "oms-smoke-001"))

Loading…
Cancel
Save