diff --git a/core/src/main/java/common/ecommerce/capability/SettlementCapable.java b/core/src/main/java/common/ecommerce/capability/SettlementCapable.java new file mode 100644 index 0000000..29cb5e6 --- /dev/null +++ b/core/src/main/java/common/ecommerce/capability/SettlementCapable.java @@ -0,0 +1,17 @@ +package common.ecommerce.capability; + +import common.ecommerce.model.settlement.SettlementQuery; +import common.ecommerce.model.settlement.SettlementTransaction; +import common.ecommerce.model.support.Page; +import common.ecommerce.sdk.ChannelContext; + +/** + * 结算 / 账单能力:拉取平台结算交易明细。 + * + *
一行代表一笔费用(佣金、配送费、退款、广告费等),平台可能按 + * 结算周期或修改时间分页给出。重复同步按 {@code transactionKey} upsert。
+ */ +public interface SettlementCapable extends PlatformAdapter { + + Page平台通常要求「结算时间」与「修改时间」二选一,或给出精确搜索值; + * 具体校验在适配器里做,core 只承载条件。
+ */ +public final class SettlementQuery { + + private final LocalDate settledAfter; + private final LocalDate settledBefore; + private final Instant modifiedAfter; + private final Instant modifiedBefore; + private final String eventType; + private final String transactionType; + private final String searchField; + private final List用于对账:一笔订单可能拆成佣金、配送费、退款、广告费等多行, + * 每行由 {@code transactionKey} 唯一标识。{@code transactionKey} 必须稳定, + * 否则重复同步会产生重复账单;平台在未结算阶段可能变更 key 的, + * 由适配器文档单独说明。
+ */ +public final class SettlementTransaction { + + private final String omsStoreId; + private final String transactionKey; + private final ChannelProvider sourceProvider; + private final String sourceAccountId; + private final String channelOrderId; + private final String storeName; + private final String countryCode; + private final String fulfillment; + private final String eventType; + private final String transactionType; + private final String sellerSku; + private final String localSku; + private final String asin; + private final Money amount; + private final int quantity; + private final String processingStatus; + private final String fundTransferStatus; + private final String settlementId; + private final PlatformTime postedAt; + private final String marketplaceName; + + private SettlementTransaction(Builder b) { + this.omsStoreId = Objects.requireNonNull(b.omsStoreId, "omsStoreId"); + this.transactionKey = Objects.requireNonNull(b.transactionKey, "transactionKey"); + this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider"); + this.sourceAccountId = b.sourceAccountId; + this.channelOrderId = b.channelOrderId; + this.storeName = b.storeName; + this.countryCode = b.countryCode; + this.fulfillment = b.fulfillment; + this.eventType = b.eventType; + this.transactionType = b.transactionType; + this.sellerSku = b.sellerSku; + this.localSku = b.localSku; + this.asin = b.asin; + this.amount = b.amount; + this.quantity = b.quantity; + this.processingStatus = b.processingStatus; + this.fundTransferStatus = b.fundTransferStatus; + this.settlementId = b.settlementId; + this.postedAt = b.postedAt; + this.marketplaceName = b.marketplaceName; + } + + public static Builder builder() { + return new Builder(); + } + + public String omsStoreId() { + return omsStoreId; + } + + /** 交易明细唯一标识,重复同步按它 upsert。 */ + public String transactionKey() { + return transactionKey; + } + + public ChannelProvider sourceProvider() { + return sourceProvider; + } + + public String sourceAccountId() { + return sourceAccountId; + } + + public String channelOrderId() { + return channelOrderId; + } + + public String storeName() { + return storeName; + } + + public String countryCode() { + return countryCode; + } + + public String fulfillment() { + return fulfillment; + } + + /** 来源事件,如 Shipment / Refund / ServiceFee。 */ + public String eventType() { + return eventType; + } + + /** 交易类型,如 Commission / Tax / Refund。 */ + public String transactionType() { + return transactionType; + } + + public String sellerSku() { + return sellerSku; + } + + public String localSku() { + return localSku; + } + + public String asin() { + return asin; + } + + /** 金额;平台未给币种时为 null。 */ + public Money amount() { + return amount; + } + + public int quantity() { + return quantity; + } + + /** 结算状态:Open / Closed / Reconciled。 */ + public String processingStatus() { + return processingStatus; + } + + /** 转账状态:Succeeded / Processing / Failed / Unknown。 */ + public String fundTransferStatus() { + return fundTransferStatus; + } + + public String settlementId() { + return settlementId; + } + + /** 结算时间;平台未给可解析时间时为 null。 */ + public PlatformTime postedAt() { + return postedAt; + } + + public String marketplaceName() { + return marketplaceName; + } + + public static final class Builder { + + private String omsStoreId; + private String transactionKey; + private ChannelProvider sourceProvider; + private String sourceAccountId; + private String channelOrderId; + private String storeName; + private String countryCode; + private String fulfillment; + private String eventType; + private String transactionType; + private String sellerSku; + private String localSku; + private String asin; + private Money amount; + private int quantity; + private String processingStatus; + private String fundTransferStatus; + private String settlementId; + private PlatformTime postedAt; + private String marketplaceName; + + public Builder omsStoreId(String omsStoreId) { + this.omsStoreId = omsStoreId; + return this; + } + + public Builder transactionKey(String transactionKey) { + this.transactionKey = transactionKey; + return this; + } + + public Builder sourceProvider(ChannelProvider sourceProvider) { + this.sourceProvider = sourceProvider; + return this; + } + + public Builder sourceAccountId(String sourceAccountId) { + this.sourceAccountId = sourceAccountId; + return this; + } + + public Builder channelOrderId(String channelOrderId) { + this.channelOrderId = channelOrderId; + return this; + } + + public Builder storeName(String storeName) { + this.storeName = storeName; + return this; + } + + public Builder countryCode(String countryCode) { + this.countryCode = countryCode; + return this; + } + + public Builder fulfillment(String fulfillment) { + this.fulfillment = fulfillment; + return this; + } + + public Builder eventType(String eventType) { + this.eventType = eventType; + return this; + } + + public Builder transactionType(String transactionType) { + this.transactionType = transactionType; + return this; + } + + public Builder sellerSku(String sellerSku) { + this.sellerSku = sellerSku; + return this; + } + + public Builder localSku(String localSku) { + this.localSku = localSku; + return this; + } + + public Builder asin(String asin) { + this.asin = asin; + return this; + } + + public Builder amount(Money amount) { + this.amount = amount; + return this; + } + + public Builder quantity(int quantity) { + this.quantity = quantity; + return this; + } + + public Builder processingStatus(String processingStatus) { + this.processingStatus = processingStatus; + return this; + } + + public Builder fundTransferStatus(String fundTransferStatus) { + this.fundTransferStatus = fundTransferStatus; + return this; + } + + public Builder settlementId(String settlementId) { + this.settlementId = settlementId; + return this; + } + + public Builder postedAt(PlatformTime postedAt) { + this.postedAt = postedAt; + return this; + } + + public Builder marketplaceName(String marketplaceName) { + this.marketplaceName = marketplaceName; + return this; + } + + public SettlementTransaction build() { + return new SettlementTransaction(this); + } + } +} diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java index 90506b1..83ace37 100644 --- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java +++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java @@ -9,6 +9,7 @@ import common.ecommerce.capability.CapabilityReport; import common.ecommerce.capability.PlatformAdapter; import common.ecommerce.capability.Products; import common.ecommerce.capability.SalesOrders; +import common.ecommerce.capability.Settlements; import common.ecommerce.idempotency.IdempotencyGuard; import common.ecommerce.model.account.AccountKey; import common.ecommerce.model.account.ChannelAccount; @@ -79,6 +80,12 @@ public final class ChannelSdk implements ProviderResolver { return new Products(resolve(key), account, newContext(account, connection)); } + /** 结算 / 账单交易明细视图。 */ + public Settlements settlements(AccountKey key, ChannelConnection connection) { + ChannelAccount account = requireAccount(key); + return new Settlements(resolve(key), account, newContext(account, connection)); + } + /** * 聚合器的子店铺列表(如领星下已授权的亚马逊 / 沃尔玛店铺)。 * diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java index b132094..d4587bf 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java @@ -23,12 +23,24 @@ public enum LingxingApi { /** 亚马逊 SC 店铺列表(企业已授权的全部 SC 店铺)。GET,非分页。 */ SHOP_LIST_AMAZON_SC("/erp/sc/data/seller/lists", 1), + /** 亚马逊 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), + + /** 亚马逊 VC 订单详情【DF】。POST,入参 vc_store_id + purchase_order_number。 */ + ORDER_DETAIL_DF_AMAZON_VC("/basicOpen/platformOrder/vcOrderDf/detail", 1), + + /** 亚马逊 VC 订单详情【PO】。POST,入参 local_po_number。 */ + ORDER_DETAIL_PO_AMAZON_VC("/basicOpen/platformOrder/vcOrderPo/detail", 1), + /** 亚马逊 SC Listing 列表。POST,offset/length 分页,上限 1000。 */ LISTING_AMAZON_SC("/erp/sc/data/mws/listing", 1), - /** 亚马逊 VC 店铺列表。POST,offset/length 分页(上限 200)。 */ - SHOP_LIST_AMAZON_VC("/basicOpen/platformAuth/vcSeller/pageList", 1), - /** 亚马逊 VC Listing 列表。POST,offset/length 分页(上限 200)。 */ LISTING_AMAZON_VC("/basicOpen/listingManage/vcListing/pageList", 1), @@ -53,6 +65,29 @@ public enum LingxingApi { /** TikTok 在线商品。POST,offset/length(上限 1000),返回 data.list。 */ LISTING_TIKTOK("/basicOpen/multiplatform/tiktok/list", 1), + /** + * 亚马逊 SC 订单列表。POST,offset/length 分页,length 上限 5000; + * 查询时间窗不超过 1 年。 + */ + ORDER_LIST_AMAZON_SC("/erp/sc/data/mws/orders", 1), + + /** 亚马逊 SC 订单详情。POST,{@code order_id} 支持逗号分隔多个(上限 200)。 */ + ORDER_DETAIL_AMAZON_SC("/erp/sc/data/mws/orderDetail", 1), + + /** + * 亚马逊自发货(FBM)订单列表。POST,{@code page} 从 1 开始,{@code length} 默认 100。 + * + *与 {@link #ORDER_LIST_AMAZON_SC} 不同:主键是领星系统单号 {@code order_number}, + * 不是平台订单号。
+ */ + ORDER_LIST_FBM_AMAZON_SC("/erp/sc/routing/order/Order/getOrderList", 1), + + /** 亚马逊自发货(FBM)订单详情。POST,入参是领星系统单号 {@code order_number}。 */ + ORDER_DETAIL_FBM_AMAZON_SC("/erp/sc/routing/order/Order/getOrderDetail", 1), + + /** 亚马逊结算中心交易明细。POST,offset/length 分页,上限 10000。 */ + SETTLEMENT_TRANSACTION_LIST("/bd/sp/api/open/settlement/transaction/detail/list", 10), + /** 多平台订单列表;当前实现使用的跨平台接口。 */ ORDER_LIST("/pb/mp/order/v2/list", 10); diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java index 2445161..d12cfed 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java @@ -19,12 +19,50 @@ public final class LingxingConstants { public static final String ADAPTER_ID = "lingxing"; - // 接口路径与限流值统一放在 LingxingApi 枚举里,这里不再重复。 + /** 获取令牌。 */ + public static final String PATH_ACCESS_TOKEN = "/api/auth-server/oauth/access-token"; + /** 多平台订单列表(各平台自发货)。 */ + public static final String PATH_ORDER_LIST = "/pb/mp/order/v2/list"; + /** 店铺列表。 */ + public static final String PATH_SELLER_LIST = "/pb/mp/shop/v2/getSellerList"; - /** 订单查询时间跨度上限:31 天(领星统一订单接口的限制)。 */ + /** 亚马逊 SC 的领星 platform_code。 */ + public static final int PLATFORM_CODE_AMAZON = 10001; + /** 亚马逊 VC 的领星 platform_code。 */ + public static final int PLATFORM_CODE_AMAZON_VC = 10035; + + /** 多平台订单列表令牌桶:10 req/s(亚马逊/VC/Walmart 接口是 1 req/s)。 */ + public static final int ORDER_LIST_PER_SECOND = 10; + + /** 订单查询时间跨度上限:31 天。 */ public static final int MAX_QUERY_DAYS = 31; - /** 分页 length 上限(领星统一订单接口的限制)。 */ + /** 亚马逊订单查询时间跨度上限:1 年。 */ + public static final int AMAZON_MAX_QUERY_DAYS = 365; + + /** 多平台分页 length 上限(领星统一订单接口的限制)。 */ public static final int MAX_PAGE_SIZE = 500; + /** 亚马逊订单分页 length 上限。 */ + public static final int AMAZON_MAX_PAGE_SIZE = 5000; + /** 亚马逊 FBM 订单分页 length:文档默认 100,未给上限,按默认值取。 */ + public static final int FBM_MAX_PAGE_SIZE = 100; + + /** 亚马逊 VC 接口(店铺 / 订单列表)分页 length 上限。 */ + public static final int VC_MAX_PAGE_SIZE = 200; + /** 亚马逊 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 天(双闭区间)。 */ + public static final int SETTLEMENT_MAX_QUERY_DAYS = 7; private LingxingConstants() { } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java index abfc443..fde0a4d 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java @@ -1,26 +1,25 @@ package common.ecommerce.lingxing.adapter; -import common.ecommerce.lingxing.LingxingConstants; -import common.ecommerce.lingxing.mapper.LingxingOrderMapper; -import common.ecommerce.lingxing.http.LingxingRateLimiter; -import common.ecommerce.lingxing.http.LingxingRequestFactory; -import common.ecommerce.lingxing.auth.LingxingTokenClient; -import common.ecommerce.lingxing.platform.LingxingCall; -import common.ecommerce.lingxing.platform.LingxingSubPlatform; -import common.ecommerce.lingxing.platform.LingxingSubPlatforms; import common.ecommerce.capability.AggregatorCapable; import common.ecommerce.capability.ProductCapable; import common.ecommerce.capability.SalesOrderCapable; +import common.ecommerce.capability.SettlementCapable; import common.ecommerce.error.AuthException; import common.ecommerce.error.ChannelException; import common.ecommerce.http.HttpTransport; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.http.TokenManager; +import common.ecommerce.lingxing.LingxingConstants; +import common.ecommerce.lingxing.auth.LingxingTokenClient; +import common.ecommerce.lingxing.http.LingxingRateLimiter; +import common.ecommerce.lingxing.http.LingxingRequestFactory; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.LingxingSubPlatform; +import common.ecommerce.lingxing.platform.LingxingSubPlatforms; import common.ecommerce.model.Capability; -import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.model.ChannelProvider; -import common.ecommerce.model.support.Page; import common.ecommerce.model.Platform; +import common.ecommerce.model.account.ChannelAccount; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.model.order.SalesOrderQuery; import common.ecommerce.model.order.SalesOrderRef; @@ -28,6 +27,9 @@ import common.ecommerce.model.product.ProductListing; import common.ecommerce.model.product.ProductQuery; import common.ecommerce.model.product.ProductRef; import common.ecommerce.model.product.ProductSyncStrategy; +import common.ecommerce.model.settlement.SettlementQuery; +import common.ecommerce.model.settlement.SettlementTransaction; +import common.ecommerce.model.support.Page; import common.ecommerce.sdk.ChannelContext; import common.ecommerce.spi.AccessToken; import common.ecommerce.spi.ChannelSecret; @@ -35,8 +37,6 @@ import common.ecommerce.spi.LockProvider; import common.ecommerce.spi.TokenStore; import java.time.Clock; -import java.time.Duration; -import java.time.ZoneId; import java.util.EnumSet; import java.util.List; import java.util.Set; @@ -45,14 +45,17 @@ import java.util.Set; * 领星聚合适配器。 * *一个适配器服务多个子平台,子平台由 {@code ChannelAccount.platformCode} 决定, - * 能力按子平台细化({@link #supports})。首期只实现订单列表拉取。
+ * 能力按子平台细化({@link #supports})。 + * + *适配器只做三件事:取 token、把公共设施装进 {@link LingxingCall}、按子平台分派。 + * 具体的「拼请求体 + 解析响应」由各子平台的 Source 实现,见 + * {@link LingxingSubPlatform}。
*/ -public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, AggregatorCapable { +public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, SettlementCapable, + AggregatorCapable { private final HttpTransport transport; private final JacksonJsonCodec json; - private final Clock clock; - private final LingxingOrderMapper mapper; private final TokenManager tokenManager; private final LingxingRateLimiter rateLimiter; private final LingxingRequestFactory requestFactory; @@ -64,8 +67,6 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, TokenStore tokenStore, LockProvider lockProvider, Clock clock) { this.transport = transport; this.json = json; - this.clock = clock; - this.mapper = new LingxingOrderMapper(json); final LingxingTokenClient tokenClient = new LingxingTokenClient(transport, json, clock); // 领星 access_token 约 2h,提前 10 分钟续期。 // @@ -111,14 +112,14 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @Override public EnumSeteBay / SHEIN / Mirakl / 自定义平台在领星侧只有订单,未见账单与售后接口, - * 因此只声明 SALES_ORDER,缺口由能力报告显式暴露,不假装支持。
+ *能力以子平台实际装配的 Source 为准:没有 orderSource 就不声明订单, + * 缺口由能力报告显式暴露,不假装支持。
*/ @Override public boolean supports(ChannelAccount account, Capability capability) { @@ -126,7 +127,7 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, return false; } Platform p = LingxingConstants.toPlatform(account.platformCode()); - if (!LingxingSubPlatforms.isRegistered(p)) { + if (p == null || !LingxingSubPlatforms.isRegistered(p)) { return false; } LingxingSubPlatform impl = LingxingSubPlatforms.of(p); @@ -136,6 +137,9 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, if (capability == Capability.PRODUCT) { return impl.productSource() != null; } + if (capability == Capability.BILLING) { + return impl.settlementSource() != null; + } return false; } @@ -144,9 +148,6 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, */ @Override public List与 {@link #pull(ChannelContext, SalesOrderQuery)} 不是同一条路由: + * 这套接口的主键是领星系统单号 {@code order_number},用于「订单管理」视角; + * 跨渠道同步仍用标准订单路由。
+ */ + public Page领星部分接口(如亚马逊店铺列表)是 GET 且无业务参数, * 此时 query 里只有 {@code app_key} / {@code timestamp} / {@code sign}。
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/mapper/LingxingOrderMapper.java b/lingxing/src/main/java/common/ecommerce/lingxing/mapper/LingxingOrderMapper.java index 6224f84..7499fdf 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/mapper/LingxingOrderMapper.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/mapper/LingxingOrderMapper.java @@ -131,8 +131,10 @@ public final class LingxingOrderMapper { /** * 领星金额可能带币种符号或千分位({@code "¥49.16"}、{@code "-¥0.98"}、{@code "1,234.56"}), * 只保留数字、小数点与符号位;没有数字时视为缺失。 + * + *亚马逊订单与多平台订单共用这套清洗规则,故对外暴露。
*/ - static String cleanAmount(String raw) { + public static String cleanAmount(String raw) { if (raw == null) { return null; } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatform.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatform.java index e6fb1dc..43035a2 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatform.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatform.java @@ -1,42 +1,50 @@ package common.ecommerce.lingxing.platform; -import common.ecommerce.capability.AggregatorCapable.SubChannel; -import common.ecommerce.model.order.SalesOrder; -import common.ecommerce.model.order.SalesOrderQuery; -import common.ecommerce.model.product.ProductListing; -import common.ecommerce.model.product.ProductQuery; -import common.ecommerce.model.support.Page; - -import java.util.List; +import common.ecommerce.lingxing.platform.order.LingxingOrderSource; +import common.ecommerce.lingxing.platform.product.LingxingProductSource; +import common.ecommerce.lingxing.platform.settlement.LingxingSettlementSource; +import common.ecommerce.lingxing.platform.shop.LingxingShopSource; /** * 领星子平台的能力分派入口:只做组合,不写业务逻辑。 * - *各能力由独立的 Source 实现({@link common.ecommerce.lingxing.platform.order.LingxingOrderSource}、 - * {@link common.ecommerce.lingxing.platform.product.LingxingProductSource}、 - * {@link common.ecommerce.lingxing.platform.shop.LingxingShopSource})提供, - * 子平台不支持的 Source 传 {@code null} 即可,调用时统一抛 - * {@code UnsupportedCapabilityException}。
- * - *这样单个平台类不会随能力增长而膨胀,能力之间也互不干扰。
+ *各能力由独立的 Source 实现({@link LingxingOrderSource}、 + * {@link LingxingProductSource}、{@link LingxingShopSource}、 + * {@link LingxingSettlementSource})提供,子平台不支持的 Source 传 {@code null} 即可, + * 调用时统一抛 {@code UnsupportedCapabilityException}。
*/ public interface LingxingSubPlatform { /** 对应的业务平台,用于注册表与日志。 */ common.ecommerce.model.Platform platform(); - /** 订单能力;不支持时为 null。 */ - default common.ecommerce.lingxing.platform.order.LingxingOrderSource orderSource() { + /** 订单能力(领星标准订单接口);不支持时为 null。 */ + default LingxingOrderSource orderSource() { + return null; + } + + /** + * 亚马逊 FBM(自发货)路由订单能力;不支持时为 null。 + * + *这套接口的主键是领星系统单号 {@code order_number},与 + * {@link #orderSource()} 的平台订单号不同,因此单独成一路,不混用。
+ */ + default LingxingOrderSource fbmOrderSource() { return null; } /** 商品能力;不支持时为 null。 */ - default common.ecommerce.lingxing.platform.product.LingxingProductSource productSource() { + default LingxingProductSource productSource() { return null; } /** 店铺能力;不支持时为 null。 */ - default common.ecommerce.lingxing.platform.shop.LingxingShopSource shopSource() { + default LingxingShopSource shopSource() { + return null; + } + + /** 结算 / 账单能力;不支持时为 null。 */ + default LingxingSettlementSource settlementSource() { return null; } } 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 79e73a4..9a64565 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatforms.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatforms.java @@ -3,6 +3,8 @@ package common.ecommerce.lingxing.platform; import common.ecommerce.error.ChannelException; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.lingxing.platform.amazon.AmazonScSubPlatform; +import common.ecommerce.lingxing.platform.amazon.AmazonVcSubPlatform; import common.ecommerce.model.Platform; import common.ecommerce.lingxing.platform.walmart.WalmartSubPlatform; @@ -30,6 +32,8 @@ public final class LingxingSubPlatforms { static { MapVC 目前没有商品与结算接口;能力由 Source 是否装配决定, + * 未装配的能力不会被声明。
+ */ +public final class AmazonVcSubPlatform implements LingxingSubPlatform { + + private final LingxingOrderSource orders; + private final LingxingShopSource shops; + + public AmazonVcSubPlatform(HttpTransport transport, JacksonJsonCodec json) { + this.orders = new VcOrderSource(); + this.shops = new VcShopSource(); + } + + @Override + public Platform platform() { + return Platform.AMAZON_VC; + } + + @Override + public LingxingOrderSource orderSource() { + return orders; + } + + @Override + public LingxingShopSource shopSource() { + return shops; + } +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonFbmOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonFbmOrderSource.java new file mode 100644 index 0000000..ba27ca7 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/order/AmazonFbmOrderSource.java @@ -0,0 +1,298 @@ +package common.ecommerce.lingxing.platform.amazon.order; + +import com.fasterxml.jackson.databind.JsonNode; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.ValidationException; +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.mapper.LingxingOrderMapper; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.amazon.dto.FbmOrderDetailDto; +import common.ecommerce.lingxing.platform.amazon.dto.FbmOrderDto; +import common.ecommerce.lingxing.platform.amazon.dto.FbmOrderItemDto; +import common.ecommerce.lingxing.platform.order.LingxingOrderSource; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.order.OrderLine; +import common.ecommerce.model.order.SalesOrder; +import common.ecommerce.model.order.SalesOrderQuery; +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.LocalDateTime; +import java.time.ZoneId; +import java.time.format.DateTimeFormatter; +import java.time.format.DateTimeParseException; +import java.util.ArrayList; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 领星 · 亚马逊 FBM(自发货)路由订单。 + * + *对应领星 ERP「销售 > 订单管理」,与 {@link AmazonOrderSource} + * ({@code /erp/sc/data/mws/orders})是两个不同视角:
+ *两者不要混用同一个 canonicalKey 存储:需要跨渠道去重时用 + * {@link AmazonOrderSource},需要按领星系统单号查 FBM 作业数据时用本类。
+ * + *时区待核对:文档没有标注 {@code purchase_time} 的时区, + * 这里按领星 ERP 系统时间(北京时间)解析。首次真实联调时应打印报文确认。
+ */ +public final class AmazonFbmOrderSource implements LingxingOrderSource { + + /** 接口时间格式。 */ + private static final DateTimeFormatter DATE_TIME = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + /** 文档未注明时区,按 ERP 系统时间(北京时间)解释,待真实报文核对。 */ + private static final ZoneId SYSTEM_ZONE = PlatformTime.BEIJING_ZONE; + + private static final String OP_PULL = "salesOrders.pull.fbm"; + private static final String OP_GET = "salesOrders.get.fbm"; + + @Override + public Page列表 {@link LingxingApi#ORDER_LIST_AMAZON_SC}:POST,{@code offset}/{@code length} + * 分页(上限 5000),查询窗口不超过 1 年,{@code total} 在顶层。
+ * + *详情 {@link LingxingApi#ORDER_DETAIL_AMAZON_SC}:只有详情返回单价/税额/折扣, + * 列表接口没有这些字段。
+ * + *与多平台订单的区别:状态是字符串枚举、时间是字符串、{@code data} 直接是数组。 + * 因此不复用 {@link LingxingOrderMapper},只复用它的金额清洗规则。
+ */ +public final class AmazonOrderSource implements LingxingOrderSource { + + /** 亚马逊接口时间参数格式:{@code yyyy-MM-dd HH:mm:ss}(UTC)。 */ + private static final DateTimeFormatter DATE_TIME = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + /** {@code date_type=3}:平台更新时间(UTC),与 updatedAfter/updatedBefore 语义一致。 */ + private static final int DATE_TYPE_PLATFORM_UPDATE_UTC = 3; + + private static final String OP_PULL = "salesOrders.pull.amazon"; + private static final String OP_GET = "salesOrders.get.amazon"; + + @Override + public Page这是领星 ERP「销售 > 订单管理」的自发货订单视图,主键是系统单号 + * {@code order_number},不是亚马逊订单号;平台单号在 {@code platform_list} 里, + * 当前不解析(避免数组元素类型不一致导致整页解析失败)。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class FbmOrderDto { + + /** 领星系统单号,详情接口的入参。 */ + @JsonProperty("order_number") + private String orderNumber; + + /** 订单状态(中文原值,如 待发货 / 已发货 / 已取消)。 */ + @JsonProperty("status") + private String status; + + /** 订单类型,如 线上订单 / 手工订单。 */ + @JsonProperty("order_from") + private String orderFrom; + + /** 目的国代码。 */ + @JsonProperty("country_code") + private String countryCode; + + /** 订购时间。 */ + @JsonProperty("purchase_time") + private String purchaseTime; + + /** 付款时间。 */ + @JsonProperty("payment_time") + private String paymentTime; + + @JsonProperty("logistics_type_id") + private String logisticsTypeId; + + @JsonProperty("logistics_provider_id") + private String logisticsProviderId; + + @JsonProperty("logistics_type_name") + private String logisticsTypeName; + + @JsonProperty("logistics_provider_name") + private String logisticsProviderName; + + /** 发货仓库 id。 */ + @JsonProperty("wid") + private Long wid; + + @JsonProperty("warehouse_name") + private String warehouseName; + + @JsonProperty("customer_comment") + private String customerComment; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/dto/FbmOrderItemDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/dto/FbmOrderItemDto.java new file mode 100644 index 0000000..7c12c2a --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/dto/FbmOrderItemDto.java @@ -0,0 +1,55 @@ +package common.ecommerce.lingxing.platform.amazon.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** + * 领星 · 亚马逊 FBM 订单详情的商品行({@code data.order_item[]})。 + * + *字段名 {@code MSKU} 是全大写,Jackson 按注解原样匹配;数量字段文档写作 + * {@code quality}(不是 quantity),照文档保留。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class FbmOrderItemDto { + + /** 平台订单号。 */ + @JsonProperty("platform_order_id") + private String platformOrderId; + + /** 平台 MSKU。 */ + @JsonProperty("MSKU") + private String msku; + + /** 订单明细单号。 */ + @JsonProperty("order_item_no") + private String orderItemNo; + + @JsonProperty("pic_url") + private String picUrl; + + /** 领星本地 SKU。 */ + @JsonProperty("sku") + private String sku; + + @JsonProperty("product_name") + private String productName; + + /** 数量;文档字段名是 {@code quality}。 */ + @JsonProperty("quality") + private Integer quality; + + /** 单价。 */ + @JsonProperty("item_unit_price") + private String itemUnitPrice; + + /** 单价币种。 */ + @JsonProperty("currency_code") + private String currencyCode; + + @JsonProperty("customization") + private String customization; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/settlement/AmazonSettlementSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/settlement/AmazonSettlementSource.java new file mode 100644 index 0000000..76fbc4b --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/settlement/AmazonSettlementSource.java @@ -0,0 +1,259 @@ +package common.ecommerce.lingxing.platform.amazon.settlement; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.ValidationException; +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.mapper.LingxingOrderMapper; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.amazon.dto.AmazonSettlementTransactionDto; +import common.ecommerce.lingxing.platform.settlement.LingxingSettlementSource; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.settlement.SettlementQuery; +import common.ecommerce.model.settlement.SettlementTransaction; +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.OffsetDateTime; +import java.time.ZoneId; +import java.time.format.DateTimeFormatter; +import java.time.format.DateTimeParseException; +import java.util.ArrayList; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 领星 · 亚马逊结算中心交易明细。 + * + *接口 {@link LingxingApi#SETTLEMENT_TRANSACTION_LIST}:POST,{@code offset}/{@code length} + * 分页(上限 10000),令牌桶 10 req/s。
+ * + *查询窗口规则(官方文档):结算时间 {@code startDate/endDate} 双闭区间、 + * 间隔不得超过 7 天;没有搜索值时,结算时间与修改时间二选一必填。 + * 修改时间按北京时间传。
+ */ +public final class AmazonSettlementSource implements LingxingSettlementSource { + + /** 结算日期格式。 */ + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + /** 修改时间格式(北京时间)。 */ + private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + private static final String OP = "settlements.pull.amazon"; + + @Override + public Page两套详情接口的字段高度重合,只有 {@code waiting_shipped_amount} 与 + * {@code to_ship_amount} 的区别,用同一个 DTO 接收,未知字段忽略。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class VcOrderDetailItemDto { + + @JsonProperty("sequence_number") + private String sequenceNumber; + + @JsonProperty("asin") + private String asin; + + @JsonProperty("asin_url") + private String asinUrl; + + /** 平台 MSKU。 */ + @JsonProperty("msku") + private String msku; + + @JsonProperty("item_name") + private String itemName; + + @JsonProperty("large_main_image_url") + private String largeMainImageUrl; + + @JsonProperty("medium_main_image_url") + private String mediumMainImageUrl; + + @JsonProperty("small_main_image_url") + private String smallMainImageUrl; + + @JsonProperty("pic_url") + private String picUrl; + + @JsonProperty("local_sku") + private String localSku; + + @JsonProperty("local_name") + private String localName; + + /** 采购量;文档类型是 string。 */ + @JsonProperty("purchase_amount") + private String purchaseAmount; + + @JsonProperty("shipped_amount") + private String shippedAmount; + + /** DF 的待发货量。 */ + @JsonProperty("waiting_shipped_amount") + private String waitingShippedAmount; + + /** PO 的待发货量。 */ + @JsonProperty("to_ship_amount") + private String toShipAmount; + + @JsonProperty("available_amount") + private Integer availableAmount; + + /** 单价。 */ + @JsonProperty("unit_price") + private String unitPrice; + + /** 成本价。 */ + @JsonProperty("net_price") + private String netPrice; + + @JsonProperty("net_price_currency_code") + private String netPriceCurrencyCode; + + @JsonProperty("tax_amount") + private String taxAmount; + + @JsonProperty("tax_amount_currency_code") + private String taxAmountCurrencyCode; + + @JsonProperty("tax_rate") + private String taxRate; + + @JsonProperty("tax_rate_percent") + private String taxRatePercent; + + @JsonProperty("deal_total_price") + private String dealTotalPrice; + + @JsonProperty("deal_unit_price") + private String dealUnitPrice; + + @JsonProperty("is_back_order_allowed") + private String isBackOrderAllowed; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/dto/VcOrderDfDetailDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/dto/VcOrderDfDetailDto.java new file mode 100644 index 0000000..19b3688 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/dto/VcOrderDfDetailDto.java @@ -0,0 +1,102 @@ +package common.ecommerce.lingxing.platform.amazon.vc.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +import java.util.ArrayList; +import java.util.List; + +/** + * 领星 · 亚马逊 VC 订单详情【DF】 + * ({@code /basicOpen/platformOrder/vcOrderDf/detail} 的 {@code data})。 + * + *{@code data} 是对象,不是数组。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class VcOrderDfDetailDto { + + @JsonProperty("vc_store_id") + private String vcStoreId; + + @JsonProperty("seller_name") + private String sellerName; + + @JsonProperty("local_po_number") + private String localPoNumber; + + @JsonProperty("purchase_order_number") + private String purchaseOrderNumber; + + /** 下单时间。 */ + @JsonProperty("purchase_order_date") + private String purchaseOrderDate; + + /** New / SHIPPED / ACCEPTED / CANCELED。 */ + @JsonProperty("purchase_order_state") + private String purchaseOrderState; + + /** 0 DF、1 PO。 */ + @JsonProperty("purchase_order_type") + private String purchaseOrderType; + + @JsonProperty("bill_to_party_id") + private String billToPartyId; + + @JsonProperty("ship_from_party_id") + private String shipFromPartyId; + + @JsonProperty("related_warehouse_id") + private String relatedWarehouseId; + + @JsonProperty("related_warehouse_name") + private String relatedWarehouseName; + + @JsonProperty("ship_method") + private String shipMethod; + + /** 要求发货时间。 */ + @JsonProperty("ship_window_time") + private String shipWindowTime; + + /** 承诺送达时间。 */ + @JsonProperty("promised_delivery_date") + private String promisedDeliveryDate; + + @JsonProperty("is_pslip_required") + private String isPslipRequired; + + @JsonProperty("is_gift") + private String isGift; + + @JsonProperty("is_scheduled_delivery_shipment") + private String isScheduledDeliveryShipment; + + @JsonProperty("is_priority_shipment") + private String isPriorityShipment; + + @JsonProperty("message_to_customer") + private String messageToCustomer; + + @JsonProperty("total_price") + private String totalPrice; + + @JsonProperty("currency_code") + private String currencyCode; + + @JsonProperty("currency_icon") + private String currencyIcon; + + /** 货物数量;文档类型是 string。 */ + @JsonProperty("item_amount") + private String itemAmount; + + @JsonProperty("remark") + private String remark; + + @JsonProperty("items") + private List列表已经带商品行与订单总额,可以直接映射成统一订单;详情接口补充 + * 发货窗口、仓库、收件方等信息。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class VcOrderDto { + + @JsonProperty("gmt_create") + private String gmtCreate; + + @JsonProperty("gmt_modified") + private String gmtModified; + + /** 领星订单 id。 */ + @JsonProperty("id") + private String id; + + /** 订单编号,平台单号,参与 canonicalKey。 */ + @JsonProperty("purchase_order_number") + private String purchaseOrderNumber; + + /** 客户订单号(DF 类型)。 */ + @JsonProperty("customer_order_number") + private String customerOrderNumber; + + /** VC 店铺 id。 */ + @JsonProperty("vc_store_id") + private String vcStoreId; + + @JsonProperty("seller_name") + private String sellerName; + + /** 订单类型:0 DF、1 PO、2 DI。 */ + @JsonProperty("purchase_order_type") + private Integer purchaseOrderType; + + /** DF:New / SHIPPED / ACCEPTED / CANCELLED;PO:Acknowledged / Closed。 */ + @JsonProperty("purchase_order_state") + private String purchaseOrderState; + + /** 订单流转状态:0 待处理、1 待发货、2 已完成、3 已取消。 */ + @JsonProperty("purchase_order_process_state") + private Integer purchaseOrderProcessState; + + /** 订单下单时间。 */ + @JsonProperty("purchase_order_date") + private String purchaseOrderDate; + + @JsonProperty("ack_status") + private Integer ackStatus; + + @JsonProperty("ack_status_desc") + private String ackStatusDesc; + + @JsonProperty("ack_update_time") + private String ackUpdateTime; + + /** DF 要求发货时间。 */ + @JsonProperty("ship_window_time") + private String shipWindowTime; + + /** PO 要求起始发货时间。 */ + @JsonProperty("ship_window_start") + private String shipWindowStart; + + /** PO 要求截止发货时间;文档字段名是 ship_windows_end。 */ + @JsonProperty("ship_windows_end") + private String shipWindowsEnd; + + @JsonProperty("total_price") + private String totalPrice; + + @JsonProperty("currency_code") + private String currencyCode; + + @JsonProperty("currency_icon") + private String currencyIcon; + + /** 货物总数量。 */ + @JsonProperty("item_amount") + private Integer itemAmount; + + /** 本地 PO 号,PO 详情接口的入参。 */ + @JsonProperty("local_po_number") + private String localPoNumber; + + @JsonProperty("ship_to_party_id") + private String shipToPartyId; + + @JsonProperty("remark") + private String remark; + + @JsonProperty("shipment_confirm_status") + private Integer shipmentConfirmStatus; + + @JsonProperty("shipment_label_status") + private Integer shipmentLabelStatus; + + @JsonProperty("print_num") + private Integer printNum; + + /** 商品行。 */ + @JsonProperty("purchase_order_sku_list") + private ListPO 详情按 {@code local_po_number} 查询,不是按订单编号。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class VcOrderPoDetailDto { + + @JsonProperty("vc_store_id") + private String vcStoreId; + + @JsonProperty("seller_name") + private String sellerName; + + @JsonProperty("purchase_order_number") + private String purchaseOrderNumber; + + /** 本地 PO 号,PO 详情接口的入参。 */ + @JsonProperty("local_po_number") + private String localPoNumber; + + @JsonProperty("purchase_order_date") + private String purchaseOrderDate; + + /** Acknowledged / Closed。 */ + @JsonProperty("purchase_order_state") + private String purchaseOrderState; + + /** 0 待处理、1 确认中、2 确认成功、3 确认失败。 */ + @JsonProperty("purchase_order_process_state") + private String purchaseOrderProcessState; + + @JsonProperty("payment_method") + private String paymentMethod; + + /** 0 DF、1 PO。 */ + @JsonProperty("purchase_order_type") + private String purchaseOrderType; + + @JsonProperty("remark") + private String remark; + + @JsonProperty("related_warehouse_id") + private String relatedWarehouseId; + + @JsonProperty("related_warehouse_name") + private String relatedWarehouseName; + + @JsonProperty("ship_to_party_id") + private String shipToPartyId; + + @JsonProperty("total_price") + private String totalPrice; + + @JsonProperty("currency_code") + private String currencyCode; + + @JsonProperty("currency_icon") + private String currencyIcon; + + /** 货物数量;文档类型是 string。 */ + @JsonProperty("item_amount") + private String itemAmount; + + @JsonProperty("ship_window_start") + private String shipWindowStart; + + @JsonProperty("ship_window_end") + private String shipWindowEnd; + + @JsonProperty("delivery_window_start") + private String deliveryWindowStart; + + @JsonProperty("delivery_window_end") + private String deliveryWindowEnd; + + @JsonProperty("items") + private List唯一键是 {@code vc_store_id},VC 订单接口与详情接口都用它指定店铺。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class VcShopDto { + + /** 账号 id。 */ + @JsonProperty("account_id") + private Long accountId; + + /** SELLER_ID。 */ + @JsonProperty("seller_id") + private String sellerId; + + /** 账号名称。 */ + @JsonProperty("account_name") + private String accountName; + + /** 站点简称,如 na。 */ + @JsonProperty("region") + private String region; + + /** 站点名称,如 北美洲。 */ + @JsonProperty("region_name") + private String regionName; + + /** VC 店铺 id,唯一键。 */ + @JsonProperty("vc_store_id") + private String vcStoreId; + + /** 店铺名称。 */ + @JsonProperty("name") + private String name; + + /** + * 店铺授权服务状态: + * -1 删除、0 暂停同步、1 正常同步、2 授权异常。 + */ + @JsonProperty("status") + private Integer status; + + /** 站点 id。 */ + @JsonProperty("mid") + private Integer mid; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/order/VcOrderSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/order/VcOrderSource.java new file mode 100644 index 0000000..cb97de4 --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/vc/order/VcOrderSource.java @@ -0,0 +1,411 @@ +package common.ecommerce.lingxing.platform.amazon.vc.order; + +import com.fasterxml.jackson.databind.JsonNode; + +import common.ecommerce.error.ChannelException; +import common.ecommerce.error.ValidationException; +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.mapper.LingxingOrderMapper; +import common.ecommerce.lingxing.platform.LingxingCall; +import common.ecommerce.lingxing.platform.amazon.vc.dto.VcOrderDetailItemDto; +import common.ecommerce.lingxing.platform.amazon.vc.dto.VcOrderDfDetailDto; +import common.ecommerce.lingxing.platform.amazon.vc.dto.VcOrderDto; +import common.ecommerce.lingxing.platform.amazon.vc.dto.VcOrderItemDto; +import common.ecommerce.lingxing.platform.amazon.vc.dto.VcOrderPoDetailDto; +import common.ecommerce.lingxing.platform.order.LingxingOrderSource; +import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.account.ChannelAccount; +import common.ecommerce.model.order.OrderLine; +import common.ecommerce.model.order.SalesOrder; +import common.ecommerce.model.order.SalesOrderQuery; +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.time.format.DateTimeParseException; +import java.time.temporal.ChronoUnit; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 领星 · 亚马逊 VC 订单。 + * + *列表 {@link LingxingApi#ORDER_LIST_AMAZON_VC} 同时覆盖 DF / PO / DI, + * 并且已经返回商品行与订单总额。详情分两个接口:
+ *{@link #order} 先用列表的 {@code search_field=purchase_order_number} 查出订单类型与 + * {@code local_po_number},再按类型走对应详情;DI 没有详情接口,直接用列表数据。
+ * + *时区待核对:文档没有标注 {@code purchase_order_date} 的时区, + * 查询日期与时间解析都按领星系统时间(北京时间)处理。
+ */ +public final class VcOrderSource implements LingxingOrderSource { + + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + /** 文档未注明时区,按 ERP 系统时间(北京时间)解释,待真实报文核对。 */ + private static final ZoneId SYSTEM_ZONE = PlatformTime.BEIJING_ZONE; + + private static final int TYPE_DF = 0; + private static final int TYPE_PO = 1; + private static final int TYPE_DI = 2; + + /** 查询时间类型:3 = 订单更新时间,与 updatedAfter/updatedBefore 对齐。 */ + private static final int SEARCH_FIELD_TIME_UPDATE = 3; + + private static final String OP_PULL = "salesOrders.pull.vc"; + private static final String OP_GET = "salesOrders.get.vc"; + + @Override + public Page接口 {@code /basicOpen/platformAuth/vcSeller/pageList}:POST,{@code offset}/{@code length} + * 分页,length 默认 20、上限 200,令牌桶 1 req/s。
+ * + *{@link LingxingShopSource#shops(LingxingCall)} 要返回全量店铺,所以这里内部翻页, + * 直到返回不足一页或达到 {@code total}。
+ */ +public final class VcShopSource implements LingxingShopSource { + + /** 店铺授权服务状态:1 = 正常同步。 */ + private static final int STATUS_ACTIVE = 1; + + private static final String OP = "shops.list.vc"; + + @Override + public List{@code store_id} 是多平台店铺唯一键;{@code sid} 只有亚马逊店铺才有意义。
+ */ +@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; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/shop/MultiPlatformShopSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/shop/MultiPlatformShopSource.java new file mode 100644 index 0000000..5eb3d2d --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/multiplatform/shop/MultiPlatformShopSource.java @@ -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; + +/** + * 领星 · 多平台店铺列表。 + * + *接口 {@code /pb/mp/shop/v2/getSellerList}:POST,{@code offset}/{@code length} + * 分页(上限 200),令牌桶 10 req/s。
+ * + *只返回当前账户 {@code platformCode} 对应的店铺,并过滤为「启用 + 正常授权」。 + * 响应结构是 {@code data.list[]} + {@code data.total}。
+ */ +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只负责「拼请求体 + 解析响应」;限流、取 token、签名、业务码校验由 + * {@link LingxingCall} 提供。
+ */ +public interface LingxingSettlementSource { + + /** 分页拉取结算交易明细。 */ + Page订单复用领星多平台统一接口;店铺用多平台店铺接口(按 platform_code=10008 过滤); + * 商品用 Walmart 在线商品接口。
*/ 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 @@ -36,4 +44,9 @@ public final class WalmartSubPlatform implements LingxingSubPlatform { public LingxingProductSource productSource() { return products; } + + @Override + public LingxingShopSource shopSource() { + return shops; + } } 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 index 4466b55..88b371a 100644 --- 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 @@ -26,6 +26,10 @@ public class WalmartListingDto { @JsonProperty("item_url") private String itemUrl; + /** Walmart 商品 ID。 */ + @JsonProperty("item_id") + private String itemId; + /** 图片链接。 */ @JsonProperty("picture_url") private String pictureUrl; 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 index 306741d..60bc912 100644 --- 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 @@ -3,21 +3,26 @@ 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.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.time.temporal.ChronoUnit; import java.util.ArrayList; import java.util.Collections; import java.util.LinkedHashMap; @@ -67,6 +72,10 @@ public final class WalmartProductSource implements LingxingProductSource { LingxingEnvelope envelope = call.envelope(resp, "products.pull"); List不依赖 STORE_ID:sid 来自 {@code /erp/sc/data/seller/lists}。
+ */ + @Test + void listsAmazonShopsAndPullsOrders() { + requireCredentials(); + LingxingAdapter adapter = adapter(); + + String sid = firstAmazonShopSid(adapter); + if (sid == null) { + return; + } + + ChannelContext ctx = context(amazonAccount(sid), "smoke-amazon-orders-"); + Instant to = Instant.now(); + Instant from = to.minus(Duration.ofDays(2)); + Page这条路由的主键是领星系统单号 {@code order_number},不是平台订单号。
+ */ + @Test + void pullsAmazonFbmOrders() { + requireCredentials(); + LingxingAdapter adapter = adapter(); + + String sid = firstAmazonShopSid(adapter); + if (sid == null) { + return; + } + + ChannelContext ctx = context(amazonAccount(sid), "smoke-fbm-"); + Instant to = Instant.now(); + Instant from = to.minus(Duration.ofDays(2)); + Page店铺来自 {@code /pb/mp/shop/v2/getSellerList},商品来自 + * {@code /basicOpen/multiplatform/walmart/list}。
+ */ + @Test + void listsWalmartShopsAndProducts() { + requireCredentials(); + LingxingAdapter adapter = adapter(); + + ChannelAccount discovery = walmartAccount("0"); + ListVC 详情分 DF / PO 两个接口,{@code get()} 会先按订单编号查出类型再分派。
+ */ + @Test + void listsAmazonVcShopsAndPullsOrders() { + requireCredentials(); + LingxingAdapter adapter = adapter(); + + String vcStoreId = firstVcShopId(adapter); + if (vcStoreId == null) { + return; + } + + ChannelContext ctx = context(vcAccount(vcStoreId), "smoke-vc-orders-"); + Instant to = Instant.now(); + Instant from = to.minus(Duration.ofDays(2)); + Page