();
+ if (statuses != null) {
+ Collections.addAll(values, statuses);
+ }
+ this.statuses = values;
+ return this;
+ }
+
+ public Builder shipmentNo(String shipmentNo) {
+ this.shipmentNo = shipmentNo;
+ return this;
+ }
+
+ public Builder inboundOrderNo(String inboundOrderNo) {
+ this.inboundOrderNo = inboundOrderNo;
+ return this;
+ }
+
+ public Builder pageSize(int pageSize) {
+ this.pageSize = pageSize;
+ return this;
+ }
+
+ public Builder cursor(String cursor) {
+ this.cursor = cursor;
+ return this;
+ }
+
+ public InboundShipmentQuery build() {
+ return new InboundShipmentQuery(this);
+ }
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/model/inbound/InboundShipmentTimeType.java b/core/src/main/java/common/ecommerce/model/inbound/InboundShipmentTimeType.java
new file mode 100644
index 0000000..b9dd8be
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/model/inbound/InboundShipmentTimeType.java
@@ -0,0 +1,19 @@
+package common.ecommerce.model.inbound;
+
+/**
+ * 入库货件查询使用的时间字段。
+ *
+ * 不同平台的可用字段不同,适配器只映射自己支持的取值;
+ * 不支持的取值显式抛 {@code ValidationException},不静默降级成别的时间字段。
+ */
+public enum InboundShipmentTimeType {
+
+ /** 创建时间。 */
+ CREATED,
+
+ /** 平台更新时间。 */
+ UPDATED,
+
+ /** 完成时间(如 FBT 货件的完成时间)。 */
+ COMPLETED
+}
diff --git a/core/src/main/java/common/ecommerce/model/inbound/InboundShippingRef.java b/core/src/main/java/common/ecommerce/model/inbound/InboundShippingRef.java
new file mode 100644
index 0000000..d69568e
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/model/inbound/InboundShippingRef.java
@@ -0,0 +1,103 @@
+package common.ecommerce.model.inbound;
+
+import common.ecommerce.model.support.PlatformTime;
+
+/**
+ * 入库货件关联的发货单摘要。
+ *
+ * FBT 的 {@code shippingInfo} 会给出数量与状态;WFS 只给发货单号,
+ * 此时数量为 0、状态为 null。
+ */
+public final class InboundShippingRef {
+
+ private final String shippingListCode;
+ private final int quantity;
+ private final Integer status;
+ private final String statusName;
+ private final PlatformTime shippedAt;
+ private final PlatformTime arrivedAt;
+
+ private InboundShippingRef(Builder b) {
+ this.shippingListCode = b.shippingListCode;
+ this.quantity = b.quantity;
+ this.status = b.status;
+ this.statusName = b.statusName;
+ this.shippedAt = b.shippedAt;
+ this.arrivedAt = b.arrivedAt;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 发货单号。 */
+ public String shippingListCode() {
+ return shippingListCode;
+ }
+
+ public int quantity() {
+ return quantity;
+ }
+
+ public Integer status() {
+ return status;
+ }
+
+ public String statusName() {
+ return statusName;
+ }
+
+ /** 实际发货时间。 */
+ public PlatformTime shippedAt() {
+ return shippedAt;
+ }
+
+ /** 到货时间。 */
+ public PlatformTime arrivedAt() {
+ return arrivedAt;
+ }
+
+ public static final class Builder {
+
+ private String shippingListCode;
+ private int quantity;
+ private Integer status;
+ private String statusName;
+ private PlatformTime shippedAt;
+ private PlatformTime arrivedAt;
+
+ public Builder shippingListCode(String shippingListCode) {
+ this.shippingListCode = shippingListCode;
+ return this;
+ }
+
+ public Builder quantity(int quantity) {
+ this.quantity = quantity;
+ return this;
+ }
+
+ public Builder status(Integer status) {
+ this.status = status;
+ return this;
+ }
+
+ public Builder statusName(String statusName) {
+ this.statusName = statusName;
+ return this;
+ }
+
+ public Builder shippedAt(PlatformTime shippedAt) {
+ this.shippedAt = shippedAt;
+ return this;
+ }
+
+ public Builder arrivedAt(PlatformTime arrivedAt) {
+ this.arrivedAt = arrivedAt;
+ return this;
+ }
+
+ public InboundShippingRef build() {
+ return new InboundShippingRef(this);
+ }
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
index c117e2e..206027b 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.AggregatorCapable;
import common.ecommerce.error.ChannelException;
import common.ecommerce.model.Capability;
import common.ecommerce.capability.CapabilityReport;
+import common.ecommerce.capability.Inbounds;
import common.ecommerce.capability.PlatformAdapter;
import common.ecommerce.capability.Products;
import common.ecommerce.capability.SalesOrders;
@@ -200,6 +201,18 @@ public final class ChannelSdk implements ProviderResolver {
}
/**
+ * 入库视图:平台仓入库货件与 FBA 到货接收明细(只读)。
+ *
+ * 能力检查发生在 {@code shipments()} / {@code receipts()} 调用时;
+ * 适配器未实现对应接口或未声明能力时抛
+ * {@code UnsupportedCapabilityException}。
+ */
+ public Inbounds inbounds(AccountKey key, ChannelConnection connection) {
+ ChannelAccount account = requireAccount(key);
+ return new Inbounds(resolve(key), account, newContext(account, connection), callObserver);
+ }
+
+ /**
* 聚合器的子店铺列表(如领星下已授权的亚马逊 / 沃尔玛店铺)。
*
* 典型用途是首次接入:把 platformCode + externalStoreId 拉下来,
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java
index ec823c1..5fae28d 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java
@@ -107,6 +107,18 @@ public enum LingxingApi {
/** 销售出库单列表。POST,page/page_size 分页(上限 200),默认最近一个月,令牌桶 1。 */
OUTBOUND_ORDER_LIST("/erp/sc/routing/wms/order/wmsOrderList", 1),
+ /** FBT 货件列表。POST,offset/length 分页(上限 200),令牌桶 1。 */
+ INBOUND_SHIPMENT_FBT("/basicOpen/fbtShipment/cargo/list", 1),
+
+ /** WFS 货件列表。POST,offset/length 分页(上限 200),令牌桶 10。 */
+ INBOUND_SHIPMENT_WFS("/cepf/warehouse/api/openApi/queryWFSCargoPage", 10),
+
+ /** AWD 入库货件列表。POST,page/length 分页,令牌桶 1。 */
+ INBOUND_SHIPMENT_AWD("/amzStaServer/openapi/awd/inbound-shipment/page", 1),
+
+ /** FBA 到货接收明细。POST,offset/length 分页,令牌桶 1。 */
+ INBOUND_RECEIPT_FBA("/erp/sc/data/fba_report/receivedInventory", 1),
+
/** 销售出库单物流面单。POST,按销售出库单号或系统单号查,单次上限 50。 */
LOGISTICS_LABEL_LIST("/erp/sc/routing/wms/order/getWmsLogisticsLabels", 1),
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 c83ce2f..e801fe6 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java
@@ -2,6 +2,8 @@ package common.ecommerce.lingxing.adapter;
import common.ecommerce.capability.AfterSaleCapable;
import common.ecommerce.capability.AggregatorCapable;
+import common.ecommerce.capability.InboundReceiptCapable;
+import common.ecommerce.capability.InboundShipmentCapable;
import common.ecommerce.capability.OrderEditCapable;
import common.ecommerce.capability.OutboundCapable;
import common.ecommerce.capability.OutboundOrderCapable;
@@ -51,6 +53,10 @@ import common.ecommerce.model.fulfillment.OutboundPackage;
import common.ecommerce.model.fulfillment.OutboundResult;
import common.ecommerce.model.fulfillment.ShipmentReviewResult;
import common.ecommerce.model.fulfillment.ShippingLabel;
+import common.ecommerce.model.inbound.InboundReceipt;
+import common.ecommerce.model.inbound.InboundReceiptQuery;
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
import common.ecommerce.model.product.ProductListing;
import common.ecommerce.model.product.ProductQuery;
import common.ecommerce.model.product.ProductRef;
@@ -81,7 +87,8 @@ import java.util.Set;
*/
public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, SettlementCapable,
OutboundCapable, AfterSaleCapable, OutboundOrderCapable, ShippingLabelCapable,
- ShipmentReviewCapable, OrderEditCapable, AggregatorCapable {
+ ShipmentReviewCapable, OrderEditCapable, InboundShipmentCapable, InboundReceiptCapable,
+ AggregatorCapable {
private final HttpTransport transport;
private final JacksonJsonCodec json;
@@ -173,7 +180,8 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
public EnumSet capabilities() {
return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.BILLING,
Capability.MARK_SHIPPED, Capability.RETURNS, Capability.OUTBOUND_ORDER,
- Capability.LABEL, Capability.SHIPMENT_REVIEW, Capability.ORDER_EDIT);
+ Capability.LABEL, Capability.SHIPMENT_REVIEW, Capability.ORDER_EDIT,
+ Capability.INBOUND_SHIPMENT, Capability.INBOUND_RECEIPT);
}
/**
@@ -209,6 +217,12 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
if (capability == Capability.RETURNS) {
return impl.afterSaleSource() != null;
}
+ if (capability == Capability.INBOUND_SHIPMENT) {
+ return impl.inboundShipmentSource() != null;
+ }
+ if (capability == Capability.INBOUND_RECEIPT) {
+ return impl.inboundReceiptSource() != null;
+ }
// ERP 级接口(出库单 / 面单 / 审核发货)不按子平台区分,Source 装配即可用
if (capability == Capability.OUTBOUND_ORDER) {
return outboundOrderSource != null;
@@ -353,6 +367,26 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
return outboundOrderSource.outboundOrders(call(ctx), query);
}
+ /** 平台仓入库货件(FBT / WFS / AWD),按子平台分派。 */
+ @Override
+ public Page pull(ChannelContext ctx, InboundShipmentQuery query) {
+ LingxingSubPlatform impl = subPlatforms.of(ctx.platform());
+ if (impl.inboundShipmentSource() == null) {
+ throw new ChannelException.UnsupportedCapabilityException(Capability.INBOUND_SHIPMENT);
+ }
+ return impl.inboundShipmentSource().shipments(call(ctx), query);
+ }
+
+ /** FBA 到货接收明细;目前只有亚马逊 SC 装配。 */
+ @Override
+ public Page pull(ChannelContext ctx, InboundReceiptQuery query) {
+ LingxingSubPlatform impl = subPlatforms.of(ctx.platform());
+ if (impl.inboundReceiptSource() == null) {
+ throw new ChannelException.UnsupportedCapabilityException(Capability.INBOUND_RECEIPT);
+ }
+ return impl.inboundReceiptSource().receipts(call(ctx), query);
+ }
+
/** 销售出库单物流面单。 */
@Override
public List labels(ChannelContext ctx, LabelQuery query) {
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingInboundReceiptSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingInboundReceiptSource.java
new file mode 100644
index 0000000..73386cd
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingInboundReceiptSource.java
@@ -0,0 +1,14 @@
+package common.ecommerce.lingxing.platform;
+
+import common.ecommerce.model.inbound.InboundReceipt;
+import common.ecommerce.model.inbound.InboundReceiptQuery;
+import common.ecommerce.model.support.Page;
+
+/**
+ * 子平台的 FBA 到货接收明细能力。
+ */
+public interface LingxingInboundReceiptSource {
+
+ /** 分页拉取 FBA 到货接收明细。 */
+ Page receipts(LingxingCall call, InboundReceiptQuery query);
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingInboundShipmentSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingInboundShipmentSource.java
new file mode 100644
index 0000000..f1be73d
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingInboundShipmentSource.java
@@ -0,0 +1,16 @@
+package common.ecommerce.lingxing.platform;
+
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+import common.ecommerce.model.support.Page;
+
+/**
+ * 子平台的平台仓入库货件能力(FBT / WFS / AWD)。
+ *
+ * 三类平台的协议差异较大,各自实现一个 Source,由子平台按账户平台装配。
+ */
+public interface LingxingInboundShipmentSource {
+
+ /** 分页拉取入库货件。 */
+ Page shipments(LingxingCall call, InboundShipmentQuery query);
+}
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 8a9bb30..e16bae4 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatform.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingSubPlatform.java
@@ -58,4 +58,14 @@ public interface LingxingSubPlatform {
default LingxingOutboundSource outboundSource() {
return null;
}
+
+ /** 平台仓入库货件能力(FBT / WFS / AWD);不支持时为 null。 */
+ default LingxingInboundShipmentSource inboundShipmentSource() {
+ return null;
+ }
+
+ /** FBA 到货接收明细能力;不支持时为 null。 */
+ default LingxingInboundReceiptSource inboundReceiptSource() {
+ return null;
+ }
}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/AmazonScSubPlatform.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/AmazonScSubPlatform.java
index 9a4a4b4..9446edd 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/AmazonScSubPlatform.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/amazon/sc/AmazonScSubPlatform.java
@@ -12,6 +12,10 @@ import common.ecommerce.lingxing.platform.LingxingOrderSource;
import common.ecommerce.lingxing.platform.LingxingProductSource;
import common.ecommerce.lingxing.platform.multiplatform.outbound.MultiPlatformOutboundSource;
import common.ecommerce.lingxing.platform.LingxingOutboundSource;
+import common.ecommerce.lingxing.platform.LingxingInboundShipmentSource;
+import common.ecommerce.lingxing.platform.LingxingInboundReceiptSource;
+import common.ecommerce.lingxing.platform.inbound.AwdCargoSource;
+import common.ecommerce.lingxing.platform.inbound.FbaReceivedInventorySource;
import common.ecommerce.lingxing.platform.LingxingSettlementSource;
import common.ecommerce.lingxing.platform.LingxingShopSource;
import common.ecommerce.lingxing.platform.amazon.sc.product.AmazonScProductSource;
@@ -32,6 +36,8 @@ public final class AmazonScSubPlatform implements LingxingSubPlatform {
private final LingxingShopSource shops;
private final LingxingSettlementSource settlements;
private final LingxingAfterSaleSource afterSales;
+ private final LingxingInboundShipmentSource inboundShipments;
+ private final LingxingInboundReceiptSource inboundReceipts;
public AmazonScSubPlatform(HttpTransport transport, JacksonJsonCodec json) {
this.orders = new AmazonOrderSource();
@@ -40,6 +46,8 @@ public final class AmazonScSubPlatform implements LingxingSubPlatform {
this.shops = new AmazonScShopSource();
this.settlements = new AmazonSettlementSource();
this.afterSales = new LingxingAfterSaleListSource();
+ this.inboundShipments = new AwdCargoSource();
+ this.inboundReceipts = new FbaReceivedInventorySource();
}
@Override
@@ -81,4 +89,14 @@ public final class AmazonScSubPlatform implements LingxingSubPlatform {
public LingxingOutboundSource outboundSource() {
return OUTBOUND;
}
+
+ @Override
+ public LingxingInboundShipmentSource inboundShipmentSource() {
+ return inboundShipments;
+ }
+
+ @Override
+ public LingxingInboundReceiptSource inboundReceiptSource() {
+ return inboundReceipts;
+ }
}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSource.java
new file mode 100644
index 0000000..8c704f7
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSource.java
@@ -0,0 +1,197 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.http.HttpRequest;
+import common.ecommerce.http.HttpResponse;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.lingxing.http.LingxingEnvelope;
+import common.ecommerce.lingxing.platform.LingxingCall;
+import common.ecommerce.lingxing.platform.LingxingInboundShipmentSource;
+import common.ecommerce.lingxing.platform.inbound.dto.AwdAddressDto;
+import common.ecommerce.lingxing.platform.inbound.dto.AwdGoodsItemDto;
+import common.ecommerce.lingxing.platform.inbound.dto.AwdShipmentDto;
+import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentLine;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+import common.ecommerce.model.inbound.InboundShipmentTimeType;
+import common.ecommerce.model.support.Page;
+import common.ecommerce.model.support.PlatformTime;
+
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 领星 · AWD 入库货件列表
+ * ({@code POST /amzStaServer/openapi/awd/inbound-shipment/page})。
+ *
+ * 分页是 {@code page}/{@code length}(页码从 1 开始),游标存字符串化的页码。
+ * 时间窗按 ISO instant 传;{@code dateType} 1 创建 / 2 更新,完成时间不支持。
+ *
+ * 该接口的货件号过滤字段是 {@code shipmentId};没有入库单号过滤。
+ */
+public final class AwdCargoSource implements LingxingInboundShipmentSource {
+
+ private static final int DEFAULT_PAGE_SIZE = 100;
+ private static final int MAX_PAGE_SIZE = 200;
+
+ private static final int DATE_TYPE_CREATED = 1;
+ private static final int DATE_TYPE_UPDATED = 2;
+
+ private static final String OP = "inbounds.shipments";
+
+ @Override
+ public Page shipments(LingxingCall call, InboundShipmentQuery query) {
+ if (query.inboundOrderNo() != null) {
+ throw InboundSupport.validation(call, OP,
+ "AWD inbound shipment does not support inboundOrderNo filter");
+ }
+
+ int length = query.pageSize() <= 0 ? DEFAULT_PAGE_SIZE
+ : Math.min(query.pageSize(), MAX_PAGE_SIZE);
+ int page = query.cursor() == null ? 1 : Integer.parseInt(query.cursor());
+
+ Map body = new LinkedHashMap();
+ body.put("page", page);
+ body.put("length", length);
+ body.put("dateType", dateType(call, query.timeType()));
+ body.put("sidList", InboundSupport.resolveLongStoreIds(call, query, OP));
+ if (query.after() != null) {
+ body.put("startDateTime", query.after().toString());
+ }
+ if (query.before() != null) {
+ body.put("endDateTime", query.before().toString());
+ }
+ if (query.shipmentNo() != null) {
+ body.put("shipmentId", query.shipmentNo());
+ }
+ if (!query.statuses().isEmpty()) {
+ body.put("statusList", new ArrayList(query.statuses()));
+ }
+
+ HttpRequest req = call.signed(LingxingApi.INBOUND_SHIPMENT_AWD, body, OP);
+ HttpResponse resp = call.execute(req);
+ LingxingEnvelope envelope = call.envelope(resp, OP);
+
+ List dtos = call.json().listAt(envelope.body(), "data.records", AwdShipmentDto.class);
+ List out = new ArrayList(dtos.size());
+ ZoneId zone = InboundSupport.marketplaceZone(call);
+ for (AwdShipmentDto dto : dtos) {
+ try {
+ out.add(toShipment(dto, call, zone));
+ } catch (RuntimeException e) {
+ throw InboundSupport.mappingFailure(e, envelope, call, OP);
+ }
+ }
+
+ boolean hasMore = dtos.size() >= length
+ && (envelope.total() < 0 || (long) page * length < envelope.total());
+ return Page.of(out, hasMore ? String.valueOf(page + 1) : null);
+ }
+
+ private static int dateType(LingxingCall call, InboundShipmentTimeType timeType) {
+ InboundShipmentTimeType effective =
+ timeType == null ? InboundShipmentTimeType.CREATED : timeType;
+ if (effective == InboundShipmentTimeType.CREATED) {
+ return DATE_TYPE_CREATED;
+ }
+ if (effective == InboundShipmentTimeType.UPDATED) {
+ return DATE_TYPE_UPDATED;
+ }
+ throw InboundSupport.validation(call, OP,
+ "AWD inbound shipment does not support timeType=" + effective);
+ }
+
+ private static InboundShipment toShipment(AwdShipmentDto dto, LingxingCall call, ZoneId zone) {
+ String storeId = dto.getSid() == null ? null : String.valueOf(dto.getSid());
+ String orderId = InboundSupport.trimToNull(dto.getOrderId());
+ return InboundShipment.builder()
+ .omsStoreId(call.ctx().omsStoreId())
+ .sourceProvider(ChannelProvider.LINGXING)
+ .sourceAccountId(storeId)
+ .shipmentId(orderId)
+ .shipmentNo(orderId)
+ .stockOrderNo(InboundSupport.trimToNull(dto.getStockOrderId()))
+ .warehouseReferenceId(InboundSupport.trimToNull(dto.getWarehouseReferenceId()))
+ .storeId(storeId)
+ .storeIds(storeId == null
+ ? Collections.emptyList() : Collections.singletonList(storeId))
+ .status(InboundSupport.trimToNull(dto.getStatus()))
+ .carrierCode(InboundSupport.trimToNull(dto.getCarrierCode()))
+ .trackingNo(InboundSupport.trimToNull(dto.getTrackingId()))
+ .destinationAddress(deliveredAddress(dto.getDeliveredAddress()))
+ .returnAddress(shippingAddress(dto.getShippingAddress()))
+ .creator(InboundSupport.trimToNull(dto.getCreateByName()))
+ .remark(InboundSupport.trimToNull(dto.getRemark()))
+ .createdAt(platformTime(dto.getGmtCreate(), zone))
+ .updatedAt(platformTime(dto.getGmtModified(), zone))
+ .shippedAt(platformTime(dto.getShipBy(), zone))
+ .lines(toLines(dto.getGoodsItems()))
+ .build();
+ }
+
+ private static List toLines(List items) {
+ if (items == null || items.isEmpty()) {
+ return Collections.emptyList();
+ }
+ List lines = new ArrayList(items.size());
+ for (AwdGoodsItemDto item : items) {
+ String name = InboundSupport.trimToNull(item.getProductName());
+ if (name == null) {
+ name = InboundSupport.trimToNull(item.getTitle());
+ }
+ lines.add(InboundShipmentLine.builder()
+ .productId(InboundSupport.trimToNull(item.getAsin()))
+ .sku(InboundSupport.trimToNull(item.getSku()))
+ .msku(InboundSupport.trimToNull(item.getMsku()))
+ .fnsku(InboundSupport.trimToNull(item.getFnsku()))
+ .asin(InboundSupport.trimToNull(item.getAsin()))
+ .parentAsin(InboundSupport.trimToNull(item.getParentAsin()))
+ .productName(name)
+ .imageUrl(InboundSupport.trimToNull(item.getUrl()))
+ .receivedQuantity(InboundSupport.intOrZero(item.getReceivedQuantity()))
+ .boxQuantity(InboundSupport.intOrZero(item.getBoxQuantity()))
+ .quantityInBox(InboundSupport.integerOrNull(item.getQuantityInBox()))
+ .prepCategory(InboundSupport.trimToNull(item.getPrepCategory()))
+ .prepOwner(InboundSupport.trimToNull(item.getPrepOwner()))
+ .labelOwner(InboundSupport.trimToNull(item.getLabelOwner()))
+ .length(item.getLength())
+ .width(item.getWidth())
+ .height(item.getHeight())
+ .lengthUnit(InboundSupport.trimToNull(item.getLengthUnit()))
+ .weight(item.getWeight())
+ .weightUnit(InboundSupport.trimToNull(item.getWeightUnit()))
+ .expiration(InboundSupport.trimToNull(item.getExpiration()))
+ .build());
+ }
+ return lines;
+ }
+
+ private static String deliveredAddress(AwdAddressDto address) {
+ if (address == null) {
+ return null;
+ }
+ return InboundSupport.joinAddress(address.getDestinationAddressLine1(),
+ address.getDestinationAddressLine2(), address.getDestinationCity(),
+ address.getDestinationStateOrRegion(), address.getDestinationPostalCode(),
+ address.getDestinationCountryCode());
+ }
+
+ private static String shippingAddress(AwdAddressDto address) {
+ if (address == null) {
+ return null;
+ }
+ return InboundSupport.joinAddress(address.getShipperName(), address.getAddressLine1(),
+ address.getAddressLine2(), address.getCity(), address.getStateOrProvinceCode(),
+ address.getPostalCode(), address.getCountryCode());
+ }
+
+ private static PlatformTime platformTime(String value, ZoneId zone) {
+ Instant instant = InboundSupport.parseIso(value);
+ return instant == null ? null : PlatformTime.of(instant, zone);
+ }
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySource.java
new file mode 100644
index 0000000..9b591cb
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySource.java
@@ -0,0 +1,120 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.http.HttpRequest;
+import common.ecommerce.http.HttpResponse;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.lingxing.http.LingxingEnvelope;
+import common.ecommerce.lingxing.platform.LingxingCall;
+import common.ecommerce.lingxing.platform.LingxingInboundReceiptSource;
+import common.ecommerce.lingxing.platform.inbound.dto.FbaReceivedInventoryDto;
+import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.model.inbound.InboundReceipt;
+import common.ecommerce.model.inbound.InboundReceiptQuery;
+import common.ecommerce.model.support.Page;
+import common.ecommerce.model.support.PlatformTime;
+
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 领星 · FBA 到货接收明细
+ * ({@code POST /erp/sc/data/fba_report/receivedInventory})。
+ *
+ * 分页是 {@code offset}/{@code length}(默认 1000),游标存字符串化的 offset。
+ * 响应 {@code data} 是数组,{@code total} 在顶层。
+ *
+ * 签收时间优先用带时区的 {@code received_date},其次 {@code received_date_locale},
+ * 最后退回秒级时间戳;三者都没有时保留 null。
+ */
+public final class FbaReceivedInventorySource implements LingxingInboundReceiptSource {
+
+ private static final int DEFAULT_PAGE_SIZE = 1000;
+ private static final int MAX_PAGE_SIZE = 1000;
+
+ private static final String OP = "inbounds.receipts";
+
+ @Override
+ public Page receipts(LingxingCall call, InboundReceiptQuery query) {
+ int length = query.pageSize() <= 0 ? DEFAULT_PAGE_SIZE
+ : Math.min(query.pageSize(), MAX_PAGE_SIZE);
+ int offset = query.cursor() == null ? 0 : Integer.parseInt(query.cursor());
+
+ Map body = new LinkedHashMap();
+ body.put("sid", resolveSid(call, query));
+ body.put("offset", offset);
+ body.put("length", length);
+ if (query.eventDate() != null) {
+ body.put("event_date", query.eventDate().toString());
+ }
+ InboundSupport.putIfNotEmpty(body, "fba_shipment_id", query.shipmentIds());
+
+ HttpRequest req = call.signed(LingxingApi.INBOUND_RECEIPT_FBA, body, OP);
+ HttpResponse resp = call.execute(req);
+ LingxingEnvelope envelope = call.envelope(resp, OP);
+
+ List dtos =
+ call.json().listAt(envelope.body(), "data", FbaReceivedInventoryDto.class);
+ List out = new ArrayList(dtos.size());
+ ZoneId zone = InboundSupport.marketplaceZone(call);
+ for (FbaReceivedInventoryDto dto : dtos) {
+ try {
+ out.add(toReceipt(dto, call, zone));
+ } catch (RuntimeException e) {
+ throw InboundSupport.mappingFailure(e, envelope, call, OP);
+ }
+ }
+
+ 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);
+ }
+
+ /** sid 必填;账户店铺不是数字时显式失败,不跨店铺查询。 */
+ private static Integer resolveSid(LingxingCall call, InboundReceiptQuery query) {
+ String raw = query.sid();
+ if (raw == null || raw.trim().isEmpty()) {
+ raw = call.ctx().account().externalStoreId();
+ }
+ Integer sid = InboundSupport.parseInt(raw);
+ if (sid == null) {
+ throw InboundSupport.validation(call, OP,
+ "sid must be a numeric lingxing store id: " + raw);
+ }
+ return sid;
+ }
+
+ private static InboundReceipt toReceipt(FbaReceivedInventoryDto dto, LingxingCall call, ZoneId zone) {
+ return InboundReceipt.builder()
+ .omsStoreId(call.ctx().omsStoreId())
+ .sourceProvider(ChannelProvider.LINGXING)
+ .sourceAccountId(dto.getSid() == null ? null : String.valueOf(dto.getSid()))
+ .sid(dto.getSid())
+ .shipmentId(InboundSupport.trimToNull(dto.getFbaShipmentId()))
+ .fnsku(InboundSupport.trimToNull(dto.getFnsku()))
+ .sku(InboundSupport.trimToNull(dto.getSku()))
+ .productName(InboundSupport.trimToNull(dto.getProductName()))
+ .quantity(InboundSupport.intOrZero(dto.getQuantity()))
+ .fulfillmentCenterId(InboundSupport.trimToNull(dto.getFulfillmentCenterId()))
+ .receivedAt(receivedAt(dto, zone))
+ .receivedDateReport(InboundSupport.trimToNull(dto.getReceivedDateReport()))
+ .uniqueIndex(dto.getUniqueIndex())
+ .uniqueMd5(InboundSupport.trimToNull(dto.getUniqueMd5()))
+ .build();
+ }
+
+ private static PlatformTime receivedAt(FbaReceivedInventoryDto dto, ZoneId zone) {
+ Instant instant = InboundSupport.parseIso(dto.getReceivedDate());
+ if (instant == null) {
+ instant = InboundSupport.parseIso(dto.getReceivedDateLocale());
+ }
+ if (instant == null && dto.getReceivedDateTimestamp() != null) {
+ instant = Instant.ofEpochSecond(dto.getReceivedDateTimestamp());
+ }
+ return instant == null ? null : PlatformTime.of(instant, zone);
+ }
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSource.java
new file mode 100644
index 0000000..e8e33b7
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSource.java
@@ -0,0 +1,203 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.http.HttpRequest;
+import common.ecommerce.http.HttpResponse;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.lingxing.http.LingxingEnvelope;
+import common.ecommerce.lingxing.platform.LingxingCall;
+import common.ecommerce.lingxing.platform.LingxingInboundShipmentSource;
+import common.ecommerce.lingxing.platform.inbound.dto.FbtCargoDto;
+import common.ecommerce.lingxing.platform.inbound.dto.FbtCargoGoodDto;
+import common.ecommerce.lingxing.platform.inbound.dto.FbtShippingInfoDto;
+import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentLine;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+import common.ecommerce.model.inbound.InboundShipmentTimeType;
+import common.ecommerce.model.inbound.InboundShippingRef;
+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.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 领星 · FBT 货件列表
+ * ({@code POST /basicOpen/fbtShipment/cargo/list})。
+ *
+ * 分页是 {@code offset}/{@code length}(上限 200),游标存字符串化的 offset。
+ * 时间窗按北京时间取日期;{@code timeType} 只支持创建时间与完成时间,
+ * 更新时间显式拒绝。
+ *
+ * 货件号过滤走 {@code queryType=3} + {@code queryValue};
+ * 该接口没有入库单号过滤,传了直接拒绝。
+ */
+public final class FbtCargoSource implements LingxingInboundShipmentSource {
+
+ private static final int DEFAULT_PAGE_SIZE = 20;
+ private static final int MAX_PAGE_SIZE = 200;
+
+ /** queryType: 3 = 货件单号。 */
+ private static final int QUERY_TYPE_CARGO_CODE = 3;
+
+ private static final String OP = "inbounds.shipments";
+
+ @Override
+ public Page shipments(LingxingCall call, InboundShipmentQuery query) {
+ if (query.inboundOrderNo() != null) {
+ throw InboundSupport.validation(call, OP,
+ "FBT cargo list does not support inboundOrderNo filter");
+ }
+
+ int length = query.pageSize() <= 0 ? DEFAULT_PAGE_SIZE
+ : Math.min(query.pageSize(), MAX_PAGE_SIZE);
+ int offset = query.cursor() == null ? 0 : Integer.parseInt(query.cursor());
+
+ Map body = new LinkedHashMap();
+ body.put("offset", offset);
+ body.put("length", length);
+ body.put("storeIdList", InboundSupport.resolveLongStoreIds(call, query, OP));
+ body.put("timeType", timeTypeCode(call, query.timeType()));
+ if (query.after() != null) {
+ body.put("startTime", InboundSupport.DATE.format(
+ LocalDateTime.ofInstant(query.after(), PlatformTime.BEIJING_ZONE)));
+ }
+ if (query.before() != null) {
+ body.put("endTime", InboundSupport.DATE.format(
+ LocalDateTime.ofInstant(query.before(), PlatformTime.BEIJING_ZONE)));
+ }
+ if (query.shipmentNo() != null) {
+ body.put("queryType", QUERY_TYPE_CARGO_CODE);
+ body.put("queryValue", Collections.singletonList(query.shipmentNo()));
+ }
+ if (!query.statuses().isEmpty()) {
+ body.put("cargoStatusList", InboundSupport.parseStatusCodes(call, query.statuses(), OP));
+ }
+
+ HttpRequest req = call.signed(LingxingApi.INBOUND_SHIPMENT_FBT, body, OP);
+ HttpResponse resp = call.execute(req);
+ LingxingEnvelope envelope = call.envelope(resp, OP);
+
+ List dtos = call.json().listAt(envelope.body(), "data.list", FbtCargoDto.class);
+ List out = new ArrayList(dtos.size());
+ ZoneId zone = InboundSupport.marketplaceZone(call);
+ for (FbtCargoDto dto : dtos) {
+ try {
+ out.add(toShipment(dto, call, zone));
+ } catch (RuntimeException e) {
+ throw InboundSupport.mappingFailure(e, envelope, call, OP);
+ }
+ }
+
+ 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);
+ }
+
+ /** 0 创建时间 / 1 完成时间;更新时间该接口不支持。 */
+ private static int timeTypeCode(LingxingCall call, InboundShipmentTimeType timeType) {
+ InboundShipmentTimeType effective =
+ timeType == null ? InboundShipmentTimeType.CREATED : timeType;
+ if (effective == InboundShipmentTimeType.CREATED) {
+ return 0;
+ }
+ if (effective == InboundShipmentTimeType.COMPLETED) {
+ return 1;
+ }
+ throw InboundSupport.validation(call, OP,
+ "FBT cargo list does not support timeType=" + effective);
+ }
+
+ private static InboundShipment toShipment(FbtCargoDto dto, LingxingCall call, ZoneId zone) {
+ List storeIds = new ArrayList();
+ for (Long id : safe(dto.getStoreIds())) {
+ if (id != null) {
+ storeIds.add(String.valueOf(id));
+ }
+ }
+ String storeId = dto.getStoreId() == null ? null : String.valueOf(dto.getStoreId());
+ if (storeId == null && storeIds.size() == 1) {
+ storeId = storeIds.get(0);
+ }
+
+ return InboundShipment.builder()
+ .omsStoreId(call.ctx().omsStoreId())
+ .sourceProvider(ChannelProvider.LINGXING)
+ .sourceAccountId(storeId)
+ .shipmentId(dto.getId() == null ? null : String.valueOf(dto.getId()))
+ .shipmentNo(InboundSupport.trimToNull(dto.getCargoCode()))
+ .storeId(storeId)
+ .storeName(InboundSupport.trimToNull(dto.getStoreName()))
+ .storeIds(storeIds)
+ .storeNames(safe(dto.getStoreNames()))
+ .warehouseName(InboundSupport.trimToNull(dto.getShippingWarehouse()))
+ .status(dto.getOrderStatus() == null ? null : String.valueOf(dto.getOrderStatus()))
+ .statusName(InboundSupport.trimToNull(dto.getOrderStatusName()))
+ .localStatus(InboundSupport.trimToNull(dto.getOrderStatusName()))
+ .shipStatus(InboundSupport.trimToNull(dto.getShipStatus()))
+ .createdAt(platformTime(dto.getCreateTime(), zone))
+ .shippedAt(platformTime(dto.getDeliveryTime(), zone))
+ .estimatedArrivalAt(platformTime(dto.getExpectedDeliveryTime(), zone))
+ .actualArrivalAt(platformTime(dto.getActualDeliveryTime(), zone))
+ .lines(toLines(dto.getOrderGoodList()))
+ .shippingRefs(toShippingRefs(dto.getShippingInfo(), zone))
+ .build();
+ }
+
+ private static List toLines(List goods) {
+ if (goods == null || goods.isEmpty()) {
+ return Collections.emptyList();
+ }
+ List lines = new ArrayList(goods.size());
+ for (FbtCargoGoodDto good : goods) {
+ lines.add(InboundShipmentLine.builder()
+ .lineId(good.getId() == null ? null : String.valueOf(good.getId()))
+ .productId(InboundSupport.trimToNull(good.getProductId()))
+ .sku(InboundSupport.trimToNull(good.getSku()))
+ .msku(InboundSupport.trimToNull(good.getMsku()))
+ .productName(InboundSupport.trimToNull(good.getProductName()))
+ .imageUrl(InboundSupport.trimToNull(good.getImageUrl()))
+ .declaredQuantity(InboundSupport.intOrZero(good.getDeclarationQuantity()))
+ .shippedQuantity(InboundSupport.intOrZero(good.getShipmentQuantity()))
+ .receivedQuantity(InboundSupport.intOrZero(good.getSignedQuantity()))
+ .normalQuantity(InboundSupport.intOrZero(good.getNormalQuantity()))
+ .defectiveQuantity(InboundSupport.intOrZero(good.getDefectiveQuantity()))
+ .build());
+ }
+ return lines;
+ }
+
+ private static List toShippingRefs(List infos, ZoneId zone) {
+ if (infos == null || infos.isEmpty()) {
+ return Collections.emptyList();
+ }
+ List refs = new ArrayList(infos.size());
+ for (FbtShippingInfoDto info : infos) {
+ refs.add(InboundShippingRef.builder()
+ .shippingListCode(InboundSupport.trimToNull(info.getShippingListCode()))
+ .quantity(InboundSupport.intOrZero(info.getShippingNum()))
+ .status(info.getShippingStatus())
+ .statusName(InboundSupport.trimToNull(info.getShippingStatusName()))
+ .shippedAt(platformTime(info.getActualDeliveryTime(), zone))
+ .arrivedAt(platformTime(info.getArrivalTime(), zone))
+ .build());
+ }
+ return refs;
+ }
+
+ private static PlatformTime platformTime(String value, ZoneId zone) {
+ Instant instant = InboundSupport.parseBeijingDateTime(value);
+ return instant == null ? null : PlatformTime.of(instant, zone);
+ }
+
+ private static List safe(List value) {
+ return value == null ? Collections.emptyList() : value;
+ }
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/InboundSupport.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/InboundSupport.java
new file mode 100644
index 0000000..47842d1
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/InboundSupport.java
@@ -0,0 +1,212 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.error.ChannelException;
+import common.ecommerce.error.ValidationException;
+import common.ecommerce.lingxing.http.LingxingEnvelope;
+import common.ecommerce.lingxing.platform.LingxingCall;
+import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+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.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 入库查询的公共小工具:时间解析、店铺 id 解析、参数校验与映射错误包装。
+ *
+ * 四类平台的时间格式不同(FBT/WFS 是北京时间文本,AWD 是 ISO instant,
+ * FBA 是带偏移的 ISO 文本),集中在这里避免每个 Source 各写一套。
+ */
+final class InboundSupport {
+
+ /** FBT / WFS 的日期格式。 */
+ static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+
+ /** FBT / WFS 的日期时间格式。 */
+ static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+
+ private InboundSupport() {
+ }
+
+ /** 北京时间文本 {@code yyyy-MM-dd HH:mm:ss} → UTC instant。 */
+ static Instant parseBeijingDateTime(String value) {
+ String text = trimToNull(value);
+ if (text == null) {
+ return null;
+ }
+ return LocalDateTime.parse(text, DATE_TIME).atZone(PlatformTime.BEIJING_ZONE).toInstant();
+ }
+
+ /** 北京时间日期 {@code yyyy-MM-dd} → 当天 00:00:00 的 UTC instant。 */
+ static Instant parseBeijingDate(String value) {
+ String text = trimToNull(value);
+ if (text == null) {
+ return null;
+ }
+ return LocalDate.parse(text, DATE).atStartOfDay(PlatformTime.BEIJING_ZONE).toInstant();
+ }
+
+ /**
+ * ISO 时间文本 → UTC instant。
+ *
+ * 兼容 {@code 2018-11-04T00:00:00+00:00}(带偏移)与 {@code ...Z};
+ * 只有日期时按北京时间当天 0 点处理。
+ */
+ static Instant parseIso(String value) {
+ String text = trimToNull(value);
+ if (text == null) {
+ return null;
+ }
+ if (text.length() == 10) {
+ return parseBeijingDate(text);
+ }
+ try {
+ return OffsetDateTime.parse(text).toInstant();
+ } catch (RuntimeException ignored) {
+ // 落到下面的 Instant.parse
+ }
+ return Instant.parse(text);
+ }
+
+ /** 店铺 id 列表:调用方没传时用当前账户的店铺,避免跨店铺查询。 */
+ static List resolveStoreIds(LingxingCall call, InboundShipmentQuery query, String op) {
+ if (!query.storeIds().isEmpty()) {
+ return query.storeIds();
+ }
+ String storeId = trimToNull(call.ctx().account().externalStoreId());
+ if (storeId == null) {
+ throw validation(call, op,
+ "account externalStoreId is not a usable lingxing store id; set storeIds explicitly");
+ }
+ return Collections.singletonList(storeId);
+ }
+
+ /** 店铺 id 列表(数值型协议用);非数字显式失败。 */
+ static List resolveLongStoreIds(LingxingCall call, InboundShipmentQuery query, String op) {
+ List raw = resolveStoreIds(call, query, op);
+ List out = new ArrayList(raw.size());
+ for (String value : raw) {
+ Long id = parseLong(value);
+ if (id == null) {
+ throw validation(call, op, "store id must be numeric: " + value);
+ }
+ out.add(id);
+ }
+ return out;
+ }
+
+ /** 状态列表:数值型协议用;非数字显式失败。 */
+ static List parseStatusCodes(LingxingCall call, List statuses, String op) {
+ List out = new ArrayList(statuses.size());
+ for (String value : statuses) {
+ Integer code = parseInt(value);
+ if (code == null) {
+ throw validation(call, op, "status must be numeric: " + value);
+ }
+ out.add(code);
+ }
+ return out;
+ }
+
+ static Long parseLong(String value) {
+ String text = trimToNull(value);
+ if (text == null) {
+ return null;
+ }
+ try {
+ return Long.valueOf(text);
+ } catch (NumberFormatException e) {
+ return null;
+ }
+ }
+
+ static Integer parseInt(String value) {
+ String text = trimToNull(value);
+ if (text == null) {
+ return null;
+ }
+ try {
+ return Integer.valueOf(text);
+ } catch (NumberFormatException e) {
+ return null;
+ }
+ }
+
+ static int intOrZero(Integer value) {
+ return value == null ? 0 : value;
+ }
+
+ static int intOrZero(String value) {
+ Integer parsed = parseInt(value);
+ return parsed == null ? 0 : parsed;
+ }
+
+ static Integer integerOrNull(String value) {
+ return parseInt(value);
+ }
+
+ /** 地址拼接:跳过空段,用 {@code , } 连接。 */
+ static String joinAddress(String... parts) {
+ StringBuilder sb = new StringBuilder();
+ if (parts == null) {
+ return null;
+ }
+ for (String part : parts) {
+ String text = trimToNull(part);
+ if (text == null) {
+ continue;
+ }
+ if (sb.length() > 0) {
+ sb.append(", ");
+ }
+ sb.append(text);
+ }
+ return sb.length() == 0 ? null : sb.toString();
+ }
+
+ static void putIfNotEmpty(java.util.Map body, String key, List> values) {
+ if (values != null && !values.isEmpty()) {
+ body.put(key, values);
+ }
+ }
+
+ static String trimToNull(String value) {
+ if (value == null) {
+ return null;
+ }
+ String trimmed = value.trim();
+ return trimmed.isEmpty() ? null : trimmed;
+ }
+
+ static ValidationException validation(LingxingCall call, String operation, String message) {
+ return new ValidationException(ChannelException.builder()
+ .message(message)
+ .operation(operation)
+ .provider(ChannelProvider.LINGXING.name())
+ .omsStoreId(call.ctx().omsStoreId())
+ .requestId(call.ctx().requestId())
+ .retryable(false));
+ }
+
+ static ValidationException mappingFailure(RuntimeException e, LingxingEnvelope envelope,
+ LingxingCall call, String operation) {
+ return new ValidationException(ChannelException.builder()
+ .message("lingxing inbound mapping failed: " + e.getMessage())
+ .operation(operation)
+ .provider(ChannelProvider.LINGXING.name())
+ .omsStoreId(call.ctx().omsStoreId())
+ .requestId(call.ctx().requestId())
+ .rawResponse(envelope.body()), e);
+ }
+
+ static ZoneId marketplaceZone(LingxingCall call) {
+ return ZoneId.of(call.ctx().account().marketplaceZone());
+ }
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSource.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSource.java
new file mode 100644
index 0000000..a4f3103
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSource.java
@@ -0,0 +1,190 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.http.HttpRequest;
+import common.ecommerce.http.HttpResponse;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.lingxing.http.LingxingEnvelope;
+import common.ecommerce.lingxing.platform.LingxingCall;
+import common.ecommerce.lingxing.platform.LingxingInboundShipmentSource;
+import common.ecommerce.lingxing.platform.inbound.dto.WfsCargoDto;
+import common.ecommerce.lingxing.platform.inbound.dto.WfsCargoGoodDto;
+import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentLine;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+import common.ecommerce.model.inbound.InboundShipmentTimeType;
+import common.ecommerce.model.inbound.InboundShippingRef;
+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.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 领星 · WFS 货件列表
+ * ({@code POST /cepf/warehouse/api/openApi/queryWFSCargoPage})。
+ *
+ * 分页是 {@code offset}/{@code length}(上限 200),游标存字符串化的 offset。
+ * 创建时间用 {@code start_time}/{@code end_time}(日期,双闭区间);
+ * 更新时间用 {@code update_time_ge}/{@code update_time_le}(北京时间日期时间)。
+ * 完成时间该接口不支持。
+ *
+ * 该接口只有入库单号过滤,没有货件号过滤;传 {@code shipmentNo} 直接拒绝。
+ */
+public final class WfsCargoSource implements LingxingInboundShipmentSource {
+
+ private static final int DEFAULT_PAGE_SIZE = 15;
+ private static final int MAX_PAGE_SIZE = 200;
+
+ private static final String OP = "inbounds.shipments";
+
+ @Override
+ public Page shipments(LingxingCall call, InboundShipmentQuery query) {
+ if (query.shipmentNo() != null) {
+ throw InboundSupport.validation(call, OP,
+ "WFS cargo list does not support shipmentNo filter; use inboundOrderNo");
+ }
+
+ int length = query.pageSize() <= 0 ? DEFAULT_PAGE_SIZE
+ : Math.min(query.pageSize(), MAX_PAGE_SIZE);
+ int offset = query.cursor() == null ? 0 : Integer.parseInt(query.cursor());
+
+ Map body = new LinkedHashMap();
+ body.put("offset", offset);
+ body.put("length", length);
+ body.put("store_id", InboundSupport.resolveStoreIds(call, query, OP));
+ applyTimeWindow(body, call, query);
+ if (query.inboundOrderNo() != null) {
+ body.put("inbound_order_id", query.inboundOrderNo());
+ }
+ if (!query.statuses().isEmpty()) {
+ body.put("cargo_status_list", InboundSupport.parseStatusCodes(call, query.statuses(), OP));
+ }
+
+ HttpRequest req = call.signed(LingxingApi.INBOUND_SHIPMENT_WFS, body, OP);
+ HttpResponse resp = call.execute(req);
+ LingxingEnvelope envelope = call.envelope(resp, OP);
+
+ List dtos = call.json().listAt(envelope.body(), "data.records", WfsCargoDto.class);
+ List out = new ArrayList(dtos.size());
+ ZoneId zone = InboundSupport.marketplaceZone(call);
+ for (WfsCargoDto dto : dtos) {
+ try {
+ out.add(toShipment(dto, call, zone));
+ } catch (RuntimeException e) {
+ throw InboundSupport.mappingFailure(e, envelope, call, OP);
+ }
+ }
+
+ 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 static void applyTimeWindow(Map body, LingxingCall call,
+ InboundShipmentQuery query) {
+ InboundShipmentTimeType timeType =
+ query.timeType() == null ? InboundShipmentTimeType.CREATED : query.timeType();
+ if (timeType == InboundShipmentTimeType.CREATED) {
+ if (query.after() != null) {
+ body.put("start_time", InboundSupport.DATE.format(
+ LocalDateTime.ofInstant(query.after(), PlatformTime.BEIJING_ZONE)));
+ }
+ if (query.before() != null) {
+ body.put("end_time", InboundSupport.DATE.format(
+ LocalDateTime.ofInstant(query.before(), PlatformTime.BEIJING_ZONE)));
+ }
+ return;
+ }
+ if (timeType == InboundShipmentTimeType.UPDATED) {
+ if (query.after() != null) {
+ body.put("update_time_ge", InboundSupport.DATE_TIME.format(
+ LocalDateTime.ofInstant(query.after(), PlatformTime.BEIJING_ZONE)));
+ }
+ if (query.before() != null) {
+ body.put("update_time_le", InboundSupport.DATE_TIME.format(
+ LocalDateTime.ofInstant(query.before(), PlatformTime.BEIJING_ZONE)));
+ }
+ return;
+ }
+ throw InboundSupport.validation(call, OP,
+ "WFS cargo list does not support timeType=" + timeType);
+ }
+
+ private static InboundShipment toShipment(WfsCargoDto dto, LingxingCall call, ZoneId zone) {
+ String storeId = InboundSupport.trimToNull(dto.getStoreId());
+ return InboundShipment.builder()
+ .omsStoreId(call.ctx().omsStoreId())
+ .sourceProvider(ChannelProvider.LINGXING)
+ .sourceAccountId(storeId)
+ .shipmentId(InboundSupport.trimToNull(dto.getId()))
+ .shipmentNo(InboundSupport.trimToNull(dto.getCargoCode()))
+ .inboundOrderNo(InboundSupport.trimToNull(dto.getInBoundOrderId()))
+ .storeId(storeId)
+ .storeName(InboundSupport.trimToNull(dto.getStoreName()))
+ .storeIds(storeId == null
+ ? Collections.emptyList() : Collections.singletonList(storeId))
+ .storeNames(dto.getStoreName() == null
+ ? Collections.emptyList()
+ : Collections.singletonList(dto.getStoreName()))
+ .countryName(InboundSupport.trimToNull(dto.getCountryName()))
+ .status(InboundSupport.trimToNull(dto.getCargoStatus()))
+ .statusName(InboundSupport.trimToNull(dto.getStatusName()))
+ .localStatus(InboundSupport.trimToNull(dto.getCargoSyncStatus()))
+ .carrierCode(InboundSupport.trimToNull(dto.getLogisticsCode()))
+ .destinationAddress(InboundSupport.trimToNull(dto.getDistributionAddresses()))
+ .returnAddress(InboundSupport.trimToNull(dto.getReturnAddresses()))
+ .creator(InboundSupport.trimToNull(dto.getCreator()))
+ .createdAt(platformTime(dto.getCargoCreateDate(), zone))
+ .updatedAt(platformTime(dto.getUpdateDate(), zone))
+ .lines(toLines(dto.getCargoGoodList()))
+ .shippingRefs(toShippingRefs(dto.getShippingListCodes()))
+ .build();
+ }
+
+ private static List toLines(List goods) {
+ if (goods == null || goods.isEmpty()) {
+ return Collections.emptyList();
+ }
+ List lines = new ArrayList(goods.size());
+ for (WfsCargoGoodDto good : goods) {
+ lines.add(InboundShipmentLine.builder()
+ .sku(InboundSupport.trimToNull(good.getSku()))
+ .msku(InboundSupport.trimToNull(good.getMsku()))
+ .productName(InboundSupport.trimToNull(good.getProductName()))
+ .gtin(InboundSupport.trimToNull(good.getGtin()))
+ .declaredQuantity(InboundSupport.intOrZero(good.getDeclareNum()))
+ .shippedQuantity(InboundSupport.intOrZero(good.getShipmentsNum()))
+ .receivedQuantity(InboundSupport.intOrZero(good.getReceivedNum()))
+ .defectiveQuantity(InboundSupport.intOrZero(good.getDamagedQty()))
+ .build());
+ }
+ return lines;
+ }
+
+ /** WFS 只给发货单号,没有数量与状态。 */
+ private static List toShippingRefs(List codes) {
+ if (codes == null || codes.isEmpty()) {
+ return Collections.emptyList();
+ }
+ List refs = new ArrayList(codes.size());
+ for (String code : codes) {
+ refs.add(InboundShippingRef.builder()
+ .shippingListCode(InboundSupport.trimToNull(code))
+ .build());
+ }
+ return refs;
+ }
+
+ private static PlatformTime platformTime(String value, ZoneId zone) {
+ Instant instant = InboundSupport.parseBeijingDateTime(value);
+ return instant == null ? null : PlatformTime.of(instant, zone);
+ }
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdAddressDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdAddressDto.java
new file mode 100644
index 0000000..38a7d57
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdAddressDto.java
@@ -0,0 +1,63 @@
+package common.ecommerce.lingxing.platform.inbound.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * 领星 · AWD 地址。
+ *
+ * 送达地址用 {@code destination*} 字段,发货地址用不带前缀的字段;
+ * 两类结构共用本 DTO,按实际有值的字段拼接。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AwdAddressDto {
+
+ @JsonProperty("destinationAddressLine1")
+ private String destinationAddressLine1;
+
+ @JsonProperty("destinationAddressLine2")
+ private String destinationAddressLine2;
+
+ @JsonProperty("destinationCity")
+ private String destinationCity;
+
+ @JsonProperty("destinationStateOrRegion")
+ private String destinationStateOrRegion;
+
+ @JsonProperty("destinationPostalCode")
+ private String destinationPostalCode;
+
+ @JsonProperty("destinationCountryCode")
+ private String destinationCountryCode;
+
+ @JsonProperty("addressLine1")
+ private String addressLine1;
+
+ @JsonProperty("addressLine2")
+ private String addressLine2;
+
+ @JsonProperty("city")
+ private String city;
+
+ @JsonProperty("stateOrProvinceCode")
+ private String stateOrProvinceCode;
+
+ @JsonProperty("postalCode")
+ private String postalCode;
+
+ @JsonProperty("countryCode")
+ private String countryCode;
+
+ @JsonProperty("shipperName")
+ private String shipperName;
+
+ @JsonProperty("phoneNumber")
+ private String phoneNumber;
+
+ @JsonProperty("zone")
+ private String zone;
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdGoodsItemDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdGoodsItemDto.java
new file mode 100644
index 0000000..223d570
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdGoodsItemDto.java
@@ -0,0 +1,82 @@
+package common.ecommerce.lingxing.platform.inbound.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * 领星 · AWD 货件商品行。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AwdGoodsItemDto {
+
+ @JsonProperty("asin")
+ private String asin;
+
+ @JsonProperty("parentAsin")
+ private String parentAsin;
+
+ @JsonProperty("fnsku")
+ private String fnsku;
+
+ @JsonProperty("msku")
+ private String msku;
+
+ @JsonProperty("sku")
+ private String sku;
+
+ @JsonProperty("productName")
+ private String productName;
+
+ @JsonProperty("title")
+ private String title;
+
+ /** 图片 url。 */
+ @JsonProperty("url")
+ private String url;
+
+ /** 签收数量。 */
+ @JsonProperty("receivedQuantity")
+ private Integer receivedQuantity;
+
+ /** 箱数,平台给的是字符串。 */
+ @JsonProperty("boxQuantity")
+ private String boxQuantity;
+
+ /** 单箱数量,平台给的是字符串。 */
+ @JsonProperty("quantityInBox")
+ private String quantityInBox;
+
+ @JsonProperty("prepCategory")
+ private String prepCategory;
+
+ @JsonProperty("prepOwner")
+ private String prepOwner;
+
+ @JsonProperty("labelOwner")
+ private String labelOwner;
+
+ @JsonProperty("length")
+ private Double length;
+
+ @JsonProperty("width")
+ private Double width;
+
+ @JsonProperty("height")
+ private Double height;
+
+ @JsonProperty("lengthUnit")
+ private String lengthUnit;
+
+ @JsonProperty("weight")
+ private Double weight;
+
+ @JsonProperty("weightUnit")
+ private String weightUnit;
+
+ @JsonProperty("expiration")
+ private String expiration;
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdShipmentDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdShipmentDto.java
new file mode 100644
index 0000000..c59a539
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/AwdShipmentDto.java
@@ -0,0 +1,72 @@
+package common.ecommerce.lingxing.platform.inbound.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;
+
+/**
+ * 领星 · AWD 入库货件
+ * ({@code /amzStaServer/openapi/awd/inbound-shipment/page} 的 {@code data.records[]})。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class AwdShipmentDto {
+
+ /** AWD 货件单号。 */
+ @JsonProperty("orderId")
+ private String orderId;
+
+ /** 备货单号。 */
+ @JsonProperty("stockOrderId")
+ private String stockOrderId;
+
+ /** referenceId。 */
+ @JsonProperty("warehouseReferenceId")
+ private String warehouseReferenceId;
+
+ /** 货件状态:CREATED / SHIPPED / IN_TRANSIT / RECEIVING / DELIVERED / CLOSED / CANCELLED。 */
+ @JsonProperty("status")
+ private String status;
+
+ @JsonProperty("gmtCreate")
+ private String gmtCreate;
+
+ @JsonProperty("gmtModified")
+ private String gmtModified;
+
+ /** 发货日期,平台给的是 {@code YYYY-MM-DD}。 */
+ @JsonProperty("shipBy")
+ private String shipBy;
+
+ @JsonProperty("trackingId")
+ private String trackingId;
+
+ @JsonProperty("carrierCode")
+ private String carrierCode;
+
+ @JsonProperty("sid")
+ private Long sid;
+
+ @JsonProperty("remark")
+ private String remark;
+
+ @JsonProperty("createByName")
+ private String createByName;
+
+ /** 送达地址。 */
+ @JsonProperty("awdDeliveredGoodsBO")
+ private AwdAddressDto deliveredAddress;
+
+ /** 商品行。 */
+ @JsonProperty("awdDeliveredGoodsItemBOS")
+ private List goodsItems = new ArrayList();
+
+ /** 发货地址。 */
+ @JsonProperty("awdShippingAddressBO")
+ private AwdAddressDto shippingAddress;
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbaReceivedInventoryDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbaReceivedInventoryDto.java
new file mode 100644
index 0000000..52948df
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbaReceivedInventoryDto.java
@@ -0,0 +1,61 @@
+package common.ecommerce.lingxing.platform.inbound.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * 领星 · FBA 到货接收明细
+ * ({@code /erp/sc/data/fba_report/receivedInventory} 的 {@code data[]})。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class FbaReceivedInventoryDto {
+
+ @JsonProperty("sid")
+ private Integer sid;
+
+ /** 签收时间,带时区偏移,如 {@code 2018-11-04T00:00:00+00:00}。 */
+ @JsonProperty("received_date")
+ private String receivedDate;
+
+ /** 本地时区签收时间。 */
+ @JsonProperty("received_date_locale")
+ private String receivedDateLocale;
+
+ /** 签收时间戳(秒)。 */
+ @JsonProperty("received_date_timestamp")
+ private Long receivedDateTimestamp;
+
+ @JsonProperty("fnsku")
+ private String fnsku;
+
+ /** MSKU。 */
+ @JsonProperty("sku")
+ private String sku;
+
+ @JsonProperty("product_name")
+ private String productName;
+
+ /** 签收数量;可能为负数。 */
+ @JsonProperty("quantity")
+ private Integer quantity;
+
+ @JsonProperty("fba_shipment_id")
+ private String fbaShipmentId;
+
+ @JsonProperty("fulfillment_center_id")
+ private String fulfillmentCenterId;
+
+ @JsonProperty("unique_index")
+ private Integer uniqueIndex;
+
+ @JsonProperty("unique_md5")
+ private String uniqueMd5;
+
+ /** 处理过的接收日期,{@code yyyy-MM-dd}。 */
+ @JsonProperty("received_date_report")
+ private String receivedDateReport;
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtCargoDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtCargoDto.java
new file mode 100644
index 0000000..8f758d7
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtCargoDto.java
@@ -0,0 +1,72 @@
+package common.ecommerce.lingxing.platform.inbound.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;
+
+/**
+ * 领星 · FBT 货件({@code /basicOpen/fbtShipment/cargo/list} 的 {@code data.list[]})。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class FbtCargoDto {
+
+ /** 货件 ID。 */
+ @JsonProperty("id")
+ private Long id;
+
+ /** 货件单号。 */
+ @JsonProperty("cargoCode")
+ private String cargoCode;
+
+ /** 收货仓。 */
+ @JsonProperty("shippingWarehouse")
+ private String shippingWarehouse;
+
+ @JsonProperty("createTime")
+ private String createTime;
+
+ @JsonProperty("deliveryTime")
+ private String deliveryTime;
+
+ @JsonProperty("expectedDeliveryTime")
+ private String expectedDeliveryTime;
+
+ @JsonProperty("actualDeliveryTime")
+ private String actualDeliveryTime;
+
+ /** 订单状态原始值。 */
+ @JsonProperty("orderStatus")
+ private Integer orderStatus;
+
+ @JsonProperty("orderStatusName")
+ private String orderStatusName;
+
+ /** 发货状态,平台给的是展示文案(如「已发货」)。 */
+ @JsonProperty("shipStatus")
+ private String shipStatus;
+
+ /** 单店铺 id;跨店铺货件以 {@code storeIds} 为准。 */
+ @JsonProperty("storeId")
+ private Long storeId;
+
+ @JsonProperty("storeName")
+ private String storeName;
+
+ @JsonProperty("storeIds")
+ private List storeIds = new ArrayList();
+
+ @JsonProperty("storeNames")
+ private List storeNames = new ArrayList();
+
+ @JsonProperty("orderGoodList")
+ private List orderGoodList = new ArrayList();
+
+ @JsonProperty("shippingInfo")
+ private List shippingInfo = new ArrayList();
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtCargoGoodDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtCargoGoodDto.java
new file mode 100644
index 0000000..1466cce
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtCargoGoodDto.java
@@ -0,0 +1,59 @@
+package common.ecommerce.lingxing.platform.inbound.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * 领星 · FBT 货件商品行。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class FbtCargoGoodDto {
+
+ @JsonProperty("id")
+ private Long id;
+
+ @JsonProperty("goodId")
+ private String goodId;
+
+ @JsonProperty("productId")
+ private String productId;
+
+ @JsonProperty("skuId")
+ private String skuId;
+
+ @JsonProperty("sku")
+ private String sku;
+
+ @JsonProperty("msku")
+ private String msku;
+
+ @JsonProperty("productName")
+ private String productName;
+
+ @JsonProperty("imageUrl")
+ private String imageUrl;
+
+ /** 申报数量。 */
+ @JsonProperty("declarationQuantity")
+ private Integer declarationQuantity;
+
+ /** 发货数量。 */
+ @JsonProperty("shipmentQuantity")
+ private Integer shipmentQuantity;
+
+ /** 签收数量。 */
+ @JsonProperty("signedQuantity")
+ private Integer signedQuantity;
+
+ /** 合格数量。 */
+ @JsonProperty("normalQuantity")
+ private Integer normalQuantity;
+
+ /** 次品数量。 */
+ @JsonProperty("defectiveQuantity")
+ private Integer defectiveQuantity;
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtShippingInfoDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtShippingInfoDto.java
new file mode 100644
index 0000000..2cb4646
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/FbtShippingInfoDto.java
@@ -0,0 +1,34 @@
+package common.ecommerce.lingxing.platform.inbound.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * 领星 · FBT 货件关联的发货单。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class FbtShippingInfoDto {
+
+ @JsonProperty("shippingListCode")
+ private String shippingListCode;
+
+ /** 发货数量,平台给的是字符串。 */
+ @JsonProperty("shippingNum")
+ private String shippingNum;
+
+ @JsonProperty("shippingStatus")
+ private Integer shippingStatus;
+
+ @JsonProperty("shippingStatusName")
+ private String shippingStatusName;
+
+ @JsonProperty("actualDeliveryTime")
+ private String actualDeliveryTime;
+
+ @JsonProperty("arrivalTime")
+ private String arrivalTime;
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/WfsCargoDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/WfsCargoDto.java
new file mode 100644
index 0000000..a750339
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/WfsCargoDto.java
@@ -0,0 +1,82 @@
+package common.ecommerce.lingxing.platform.inbound.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;
+
+/**
+ * 领星 · WFS 货件({@code /cepf/warehouse/api/openApi/queryWFSCargoPage}
+ * 的 {@code data.records[]})。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class WfsCargoDto {
+
+ /** WFS 货件 id。 */
+ @JsonProperty("id")
+ private String id;
+
+ /** 货件单号。 */
+ @JsonProperty("cargo_code")
+ private String cargoCode;
+
+ /** 入库单号。 */
+ @JsonProperty("in_bound_order_id")
+ private String inBoundOrderId;
+
+ @JsonProperty("store_id")
+ private String storeId;
+
+ @JsonProperty("store_name")
+ private String storeName;
+
+ @JsonProperty("country_name")
+ private String countryName;
+
+ @JsonProperty("creator")
+ private String creator;
+
+ /** 平台物流方式编码。 */
+ @JsonProperty("logistics_code")
+ private String logisticsCode;
+
+ @JsonProperty("cargo_create_date")
+ private String cargoCreateDate;
+
+ @JsonProperty("update_date")
+ private String updateDate;
+
+ /** 平台状态(字符串,如 PENDING_SHIPMENT_DETAILS)。 */
+ @JsonProperty("cargo_status")
+ private String cargoStatus;
+
+ /** 货件同步状态文案(如「已申报」)。 */
+ @JsonProperty("cargo_sync_status")
+ private String cargoSyncStatus;
+
+ /** 本地状态码:0~4。 */
+ @JsonProperty("status")
+ private Integer status;
+
+ @JsonProperty("status_name")
+ private String statusName;
+
+ /** 配送地址,平台已拼接成一段文本。 */
+ @JsonProperty("distribution_addresses")
+ private String distributionAddresses;
+
+ /** 退货地址,平台已拼接成一段文本。 */
+ @JsonProperty("return_addresses")
+ private String returnAddresses;
+
+ @JsonProperty("shipping_list_codes")
+ private List shippingListCodes = new ArrayList();
+
+ @JsonProperty("cargo_good_list")
+ private List cargoGoodList = new ArrayList();
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/WfsCargoGoodDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/WfsCargoGoodDto.java
new file mode 100644
index 0000000..2f43d39
--- /dev/null
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/dto/WfsCargoGoodDto.java
@@ -0,0 +1,42 @@
+package common.ecommerce.lingxing.platform.inbound.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * 领星 · WFS 货件商品行。
+ *
+ * 数量字段平台给的都是字符串,映射时按整数解析;无法解析按 0 处理。
+ */
+@Getter
+@Setter
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class WfsCargoGoodDto {
+
+ @JsonProperty("msku")
+ private String msku;
+
+ @JsonProperty("sku")
+ private String sku;
+
+ @JsonProperty("product_name")
+ private String productName;
+
+ @JsonProperty("gtin")
+ private String gtin;
+
+ @JsonProperty("declare_num")
+ private String declareNum;
+
+ @JsonProperty("shipments_num")
+ private String shipmentsNum;
+
+ @JsonProperty("received_num")
+ private String receivedNum;
+
+ /** 平台字段名就是 {@code dameged_qty}(拼写错误),按原样接收。 */
+ @JsonProperty("dameged_qty")
+ private String damagedQty;
+}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/tiktok/TiktokSubPlatform.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/tiktok/TiktokSubPlatform.java
index f0e7808..fe4934c 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/tiktok/TiktokSubPlatform.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/tiktok/TiktokSubPlatform.java
@@ -10,6 +10,8 @@ import common.ecommerce.lingxing.platform.multiplatform.order.MultiPlatformOrder
import common.ecommerce.lingxing.platform.multiplatform.outbound.MultiPlatformOutboundSource;
import common.ecommerce.lingxing.platform.multiplatform.shop.MultiPlatformShopSource;
import common.ecommerce.lingxing.platform.LingxingOutboundSource;
+import common.ecommerce.lingxing.platform.LingxingInboundShipmentSource;
+import common.ecommerce.lingxing.platform.inbound.FbtCargoSource;
import common.ecommerce.lingxing.platform.tiktok.product.TiktokProductSource;
import common.ecommerce.model.Platform;
@@ -24,11 +26,13 @@ public final class TiktokSubPlatform implements LingxingSubPlatform {
private final LingxingOrderSource orders;
private final LingxingProductSource products;
private final LingxingShopSource shops;
+ private final LingxingInboundShipmentSource inboundShipments;
public TiktokSubPlatform(HttpTransport transport, JacksonJsonCodec json) {
this.orders = new MultiPlatformOrderSource(transport, json);
this.products = new TiktokProductSource();
this.shops = new MultiPlatformShopSource(Platform.TIKTOK);
+ this.inboundShipments = new FbtCargoSource();
}
@Override
@@ -55,4 +59,9 @@ public final class TiktokSubPlatform implements LingxingSubPlatform {
public LingxingOutboundSource outboundSource() {
return OUTBOUND;
}
+
+ @Override
+ public LingxingInboundShipmentSource inboundShipmentSource() {
+ return inboundShipments;
+ }
}
diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java
index 05d2052..f31f050 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/walmart/WalmartSubPlatform.java
@@ -8,6 +8,8 @@ import common.ecommerce.lingxing.platform.LingxingOrderSource;
import common.ecommerce.lingxing.platform.LingxingProductSource;
import common.ecommerce.lingxing.platform.multiplatform.outbound.MultiPlatformOutboundSource;
import common.ecommerce.lingxing.platform.LingxingOutboundSource;
+import common.ecommerce.lingxing.platform.LingxingInboundShipmentSource;
+import common.ecommerce.lingxing.platform.inbound.WfsCargoSource;
import common.ecommerce.lingxing.platform.LingxingShopSource;
import common.ecommerce.lingxing.platform.walmart.order.WalmartOrderSource;
import common.ecommerce.lingxing.platform.walmart.product.WalmartProductSource;
@@ -27,11 +29,13 @@ public final class WalmartSubPlatform implements LingxingSubPlatform {
private final LingxingOrderSource orders;
private final LingxingProductSource products;
private final LingxingShopSource shops;
+ private final LingxingInboundShipmentSource inboundShipments;
public WalmartSubPlatform(HttpTransport transport, JacksonJsonCodec json) {
this.orders = new WalmartOrderSource(transport, json);
this.products = new WalmartProductSource();
this.shops = new MultiPlatformShopSource(Platform.WALMART_SC);
+ this.inboundShipments = new WfsCargoSource();
}
@Override
@@ -58,4 +62,9 @@ public final class WalmartSubPlatform implements LingxingSubPlatform {
public LingxingOutboundSource outboundSource() {
return OUTBOUND;
}
+
+ @Override
+ public LingxingInboundShipmentSource inboundShipmentSource() {
+ return inboundShipments;
+ }
}
diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingInboundCapabilityTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingInboundCapabilityTest.java
new file mode 100644
index 0000000..db32abe
--- /dev/null
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingInboundCapabilityTest.java
@@ -0,0 +1,128 @@
+package common.ecommerce.lingxing.adapter;
+
+import common.ecommerce.error.ChannelException;
+import common.ecommerce.http.JacksonJsonCodec;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.lingxing.support.LingxingTestSupport;
+import common.ecommerce.model.Capability;
+import common.ecommerce.model.Platform;
+import common.ecommerce.model.account.ChannelAccount;
+import common.ecommerce.model.inbound.InboundReceipt;
+import common.ecommerce.model.inbound.InboundReceiptQuery;
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+import common.ecommerce.model.support.Page;
+import common.ecommerce.sdk.ChannelConnection;
+import common.ecommerce.sdk.ChannelSdk;
+import common.ecommerce.spi.ChannelSecret;
+import common.ecommerce.testkit.InMemoryAccounts;
+import common.ecommerce.testkit.InMemoryLockProvider;
+import common.ecommerce.testkit.InMemoryTokenStore;
+import common.ecommerce.testkit.JsonFixture;
+import common.ecommerce.testkit.RecordingTransport;
+import common.ecommerce.testkit.Responses;
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+import java.time.LocalDate;
+
+import static common.ecommerce.lingxing.support.LingxingTestSupport.ENDPOINT;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.account;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertUrlStartsWith;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastUrl;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/** 领星入库能力:按子平台收窄 + 门面路由。 */
+class LingxingInboundCapabilityTest {
+
+ private static ChannelConnection connection() {
+ return ChannelConnection.of(ENDPOINT, ChannelSecret.builder()
+ .appKey(LingxingTestSupport.APP_KEY)
+ .appSecret(LingxingTestSupport.APP_SECRET)
+ .build());
+ }
+
+ private static LingxingAdapter adapter(RecordingTransport transport) {
+ return new LingxingAdapter(transport, new JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), LingxingTestSupport.CLOCK);
+ }
+
+ private static ChannelSdk sdk(RecordingTransport transport, ChannelAccount account) {
+ return ChannelSdk.builder()
+ .accountRepository(new InMemoryAccounts().put(account))
+ .clock(LingxingTestSupport.CLOCK)
+ .register(adapter(transport))
+ .build();
+ }
+
+ @Test
+ void capabilitiesFollowSubPlatformWiring() {
+ LingxingAdapter adapter = adapter(RecordingTransport.create());
+
+ ChannelAccount amazon = account(Platform.AMAZON_SC, 10001, "123456789");
+ assertTrue(adapter.supports(amazon, Capability.INBOUND_SHIPMENT));
+ assertTrue(adapter.supports(amazon, Capability.INBOUND_RECEIPT));
+
+ ChannelAccount tiktok = account(Platform.TIKTOK, 10011, "134225003201380864");
+ assertTrue(adapter.supports(tiktok, Capability.INBOUND_SHIPMENT));
+ assertFalse(adapter.supports(tiktok, Capability.INBOUND_RECEIPT));
+
+ ChannelAccount walmart = account(Platform.WALMART_SC, 10008, "110000000020008001");
+ assertTrue(adapter.supports(walmart, Capability.INBOUND_SHIPMENT));
+ assertFalse(adapter.supports(walmart, Capability.INBOUND_RECEIPT));
+
+ ChannelAccount ebay = account(Platform.EBAY, 10003, "1");
+ assertFalse(adapter.supports(ebay, Capability.INBOUND_SHIPMENT));
+ assertFalse(adapter.supports(ebay, Capability.INBOUND_RECEIPT));
+ }
+
+ @Test
+ void facadeRoutesAmazonScShipmentsToAwd() {
+ RecordingTransport transport = RecordingTransport.create()
+ .route(LingxingApi.INBOUND_SHIPMENT_AWD.path(), r -> Responses.ok(
+ JsonFixture.load("fixtures/lingxing/inbound/awdShipment/success.json")));
+ ChannelAccount amazon = account(Platform.AMAZON_SC, 10001, "123456789");
+
+ Page page = sdk(transport, amazon).inbounds(amazon.key(), connection())
+ .shipments(InboundShipmentQuery.builder()
+ .storeIds("123456789")
+ .after(Instant.parse("2026-04-01T00:00:00Z"))
+ .before(Instant.parse("2026-04-02T00:00:00Z"))
+ .build());
+
+ assertEquals(1, page.size());
+ assertEquals("AWD20230715001", page.items().get(0).shipmentNo());
+ assertUrlStartsWith(lastUrl(transport), ENDPOINT + LingxingApi.INBOUND_SHIPMENT_AWD.path());
+ }
+
+ @Test
+ void facadeRoutesAmazonScReceiptsToFba() {
+ RecordingTransport transport = RecordingTransport.create()
+ .route(LingxingApi.INBOUND_RECEIPT_FBA.path(), r -> Responses.ok(
+ JsonFixture.load(
+ "fixtures/lingxing/inbound/fbaReceivedInventory/success.json")));
+ ChannelAccount amazon = account(Platform.AMAZON_SC, 10001, "101");
+
+ Page page = sdk(transport, amazon).inbounds(amazon.key(), connection())
+ .receipts(InboundReceiptQuery.builder()
+ .eventDate(LocalDate.parse("2026-04-01"))
+ .build());
+
+ assertEquals(1, page.size());
+ assertEquals("FBA1Y4ZJFZ", page.items().get(0).shipmentId());
+ assertUrlStartsWith(lastUrl(transport), ENDPOINT + LingxingApi.INBOUND_RECEIPT_FBA.path());
+ }
+
+ @Test
+ void ebayRejectsInboundShipmentsExplicitly() {
+ RecordingTransport transport = RecordingTransport.create();
+ ChannelAccount ebay = account(Platform.EBAY, 10003, "1");
+
+ assertThrows(ChannelException.UnsupportedCapabilityException.class,
+ () -> sdk(transport, ebay).inbounds(ebay.key(), connection())
+ .shipments(InboundShipmentQuery.builder().storeIds("1").build()));
+ }
+}
diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSourceTest.java
new file mode 100644
index 0000000..50da0a0
--- /dev/null
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSourceTest.java
@@ -0,0 +1,118 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.error.ValidationException;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.model.Platform;
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+import common.ecommerce.model.inbound.InboundShipmentTimeType;
+import common.ecommerce.model.support.Page;
+import common.ecommerce.testkit.JsonFixture;
+import common.ecommerce.testkit.RecordingTransport;
+import common.ecommerce.testkit.Responses;
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+
+import static common.ecommerce.lingxing.support.LingxingTestSupport.ENDPOINT;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.account;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyContains;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertUrlStartsWith;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.call;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastBody;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastUrl;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/** 领星 AWD 入库货件列表:请求构造 + 响应映射 + 不支持的维度。 */
+class AwdCargoSourceTest {
+
+ private final RecordingTransport transport = RecordingTransport.create()
+ .route(LingxingApi.INBOUND_SHIPMENT_AWD.path(),
+ r -> Responses.ok(JsonFixture.load("fixtures/lingxing/inbound/awdShipment/success.json")));
+
+ private static InboundShipmentQuery.Builder baseQuery() {
+ return InboundShipmentQuery.builder()
+ .storeIds("123456789")
+ .after(Instant.parse("2026-04-01T00:00:00Z"))
+ .before(Instant.parse("2026-04-02T00:00:00Z"));
+ }
+
+ @Test
+ void requestCarriesPageAndIsoTimeWindow() {
+ new AwdCargoSource().shipments(
+ call(transport, account(Platform.AMAZON_SC, 10001, "123456789")),
+ baseQuery()
+ .timeType(InboundShipmentTimeType.UPDATED)
+ .shipmentNo("AWD20230715001")
+ .statuses("SHIPPED", "IN_TRANSIT")
+ .pageSize(50)
+ .cursor("2")
+ .build());
+
+ assertUrlStartsWith(lastUrl(transport), ENDPOINT + LingxingApi.INBOUND_SHIPMENT_AWD.path());
+ String body = lastBody(transport);
+ assertBodyContains(body, "\"page\":2");
+ assertBodyContains(body, "\"length\":50");
+ assertBodyContains(body, "\"dateType\":2");
+ assertBodyContains(body, "\"sidList\":[123456789]");
+ assertBodyContains(body, "\"startDateTime\":\"2026-04-01T00:00:00Z\"");
+ assertBodyContains(body, "\"endDateTime\":\"2026-04-02T00:00:00Z\"");
+ assertBodyContains(body, "\"shipmentId\":\"AWD20230715001\"");
+ assertBodyContains(body, "\"statusList\":[\"SHIPPED\",\"IN_TRANSIT\"]");
+ }
+
+ @Test
+ void mapsShipmentWithAddressesAndLines() {
+ Page page = new AwdCargoSource().shipments(
+ call(transport, account(Platform.AMAZON_SC, 10001, "123456789")),
+ baseQuery().build());
+
+ assertEquals(1, page.size());
+ assertNull(page.nextCursor());
+
+ InboundShipment shipment = page.items().get(0);
+ assertEquals("AWD20230715001", shipment.shipmentNo());
+ assertEquals("STOCK001", shipment.stockOrderNo());
+ assertEquals("PHX5", shipment.warehouseReferenceId());
+ assertEquals("SHIPPED", shipment.status());
+ assertEquals("UPS", shipment.carrierCode());
+ assertEquals("1Z1234567890123456", shipment.trackingNo());
+ assertEquals("123456789", shipment.storeId());
+ assertEquals("易碎品", shipment.remark());
+ assertEquals("456 Distribution Ave, Building 3, Phoenix, AZ, 85001, US",
+ shipment.destinationAddress());
+ assertEquals("Example Shipper, 123 Main St, Suite 100, Seattle, WA, 98101, US",
+ shipment.returnAddress());
+ assertNotNull(shipment.createdAt());
+ assertNotNull(shipment.updatedAt());
+ assertNotNull(shipment.shippedAt());
+
+ assertEquals(1, shipment.lines().size());
+ assertEquals("B0ABCD1234", shipment.lines().get(0).asin());
+ assertEquals("B0PARENT12", shipment.lines().get(0).parentAsin());
+ assertEquals("X000123ABC", shipment.lines().get(0).fnsku());
+ assertEquals(18, shipment.lines().get(0).receivedQuantity());
+ assertEquals(5, shipment.lines().get(0).boxQuantity());
+ assertEquals(Integer.valueOf(20), shipment.lines().get(0).quantityInBox());
+ assertEquals("AMAZON", shipment.lines().get(0).labelOwner());
+ assertEquals(Double.valueOf(15.75), shipment.lines().get(0).length());
+ assertEquals("INCHES", shipment.lines().get(0).lengthUnit());
+ }
+
+ @Test
+ void completedTimeTypeIsRejected() {
+ assertThrows(ValidationException.class, () -> new AwdCargoSource().shipments(
+ call(transport, account(Platform.AMAZON_SC, 10001, "123456789")),
+ baseQuery().timeType(InboundShipmentTimeType.COMPLETED).build()));
+ }
+
+ @Test
+ void inboundOrderNoIsRejected() {
+ assertThrows(ValidationException.class, () -> new AwdCargoSource().shipments(
+ call(transport, account(Platform.AMAZON_SC, 10001, "123456789")),
+ baseQuery().inboundOrderNo("IN-1").build()));
+ }
+}
diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySourceTest.java
new file mode 100644
index 0000000..3a0d1ed
--- /dev/null
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySourceTest.java
@@ -0,0 +1,108 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.error.ValidationException;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.model.Platform;
+import common.ecommerce.model.inbound.InboundReceipt;
+import common.ecommerce.model.inbound.InboundReceiptQuery;
+import common.ecommerce.model.support.Page;
+import common.ecommerce.testkit.JsonFixture;
+import common.ecommerce.testkit.RecordingTransport;
+import common.ecommerce.testkit.Responses;
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+import java.time.LocalDate;
+
+import static common.ecommerce.lingxing.support.LingxingTestSupport.ENDPOINT;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.account;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyContains;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyNotContains;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertUrlStartsWith;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.call;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastBody;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastUrl;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/** 领星 FBA 到货接收明细:请求构造 + 响应映射 + 必填校验。 */
+class FbaReceivedInventorySourceTest {
+
+ private final RecordingTransport transport = RecordingTransport.create()
+ .route(LingxingApi.INBOUND_RECEIPT_FBA.path(),
+ r -> Responses.ok(JsonFixture.load(
+ "fixtures/lingxing/inbound/fbaReceivedInventory/success.json")));
+
+ @Test
+ void requestCarriesEventDateAndShipmentIds() {
+ new FbaReceivedInventorySource().receipts(
+ call(transport, account(Platform.AMAZON_SC, 10001, "101")),
+ InboundReceiptQuery.builder()
+ .eventDate(LocalDate.parse("2026-04-01"))
+ .shipmentIds("FBA1Y4ZJFZ")
+ .pageSize(500)
+ .build());
+
+ assertUrlStartsWith(lastUrl(transport), ENDPOINT + LingxingApi.INBOUND_RECEIPT_FBA.path());
+ String body = lastBody(transport);
+ assertBodyContains(body, "\"sid\":101");
+ assertBodyContains(body, "\"offset\":0");
+ assertBodyContains(body, "\"length\":500");
+ assertBodyContains(body, "\"event_date\":\"2026-04-01\"");
+ assertBodyContains(body, "\"fba_shipment_id\":[\"FBA1Y4ZJFZ\"]");
+ }
+
+ @Test
+ void shipmentIdOnlyQueryOmitsEventDate() {
+ new FbaReceivedInventorySource().receipts(
+ call(transport, account(Platform.AMAZON_SC, 10001, "101")),
+ InboundReceiptQuery.builder()
+ .shipmentIds("FBA1Y4ZJFZ")
+ .build());
+
+ String body = lastBody(transport);
+ assertBodyNotContains(body, "event_date");
+ assertBodyContains(body, "\"fba_shipment_id\":[\"FBA1Y4ZJFZ\"]");
+ }
+
+ @Test
+ void mapsReceiptRow() {
+ Page page = new FbaReceivedInventorySource().receipts(
+ call(transport, account(Platform.AMAZON_SC, 10001, "101")),
+ InboundReceiptQuery.builder()
+ .eventDate(LocalDate.parse("2026-04-01"))
+ .build());
+
+ assertEquals(1, page.size());
+ assertNull(page.nextCursor());
+
+ InboundReceipt receipt = page.items().get(0);
+ assertEquals(Integer.valueOf(101), receipt.sid());
+ assertEquals("FBA1Y4ZJFZ", receipt.shipmentId());
+ assertEquals("X000123ABC", receipt.fnsku());
+ assertEquals("MSKU-1", receipt.sku());
+ assertEquals(-5, receipt.quantity());
+ assertEquals("BHX4", receipt.fulfillmentCenterId());
+ assertEquals("2026-04-01", receipt.receivedDateReport());
+ assertEquals(Integer.valueOf(3), receipt.uniqueIndex());
+ assertEquals("ad971e653ad89e2c94a939df63b8c884", receipt.uniqueMd5());
+ assertNotNull(receipt.receivedAt());
+ assertEquals(Instant.parse("2026-04-01T00:00:00Z"), receipt.receivedAt().utc());
+ }
+
+ @Test
+ void queryRequiresEventDateOrShipmentIds() {
+ assertThrows(IllegalArgumentException.class, () -> InboundReceiptQuery.builder().build());
+ }
+
+ @Test
+ void nonNumericSidIsRejected() {
+ assertThrows(ValidationException.class, () -> new FbaReceivedInventorySource().receipts(
+ call(transport, account(Platform.AMAZON_SC, 10001, "not-a-sid")),
+ InboundReceiptQuery.builder()
+ .eventDate(LocalDate.parse("2026-04-01"))
+ .build()));
+ }
+}
diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSourceTest.java
new file mode 100644
index 0000000..e0add6a
--- /dev/null
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSourceTest.java
@@ -0,0 +1,113 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.error.ValidationException;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.model.Platform;
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+import common.ecommerce.model.inbound.InboundShipmentTimeType;
+import common.ecommerce.model.support.Page;
+import common.ecommerce.testkit.JsonFixture;
+import common.ecommerce.testkit.RecordingTransport;
+import common.ecommerce.testkit.Responses;
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+
+import static common.ecommerce.lingxing.support.LingxingTestSupport.ENDPOINT;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.account;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyContains;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertUrlStartsWith;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.call;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastBody;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastUrl;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/** 领星 FBT 货件列表:请求构造 + 响应映射 + 不支持的维度。 */
+class FbtCargoSourceTest {
+
+ private final RecordingTransport transport = RecordingTransport.create()
+ .route(LingxingApi.INBOUND_SHIPMENT_FBT.path(),
+ r -> Responses.ok(JsonFixture.load("fixtures/lingxing/inbound/fbtCargo/success.json")));
+
+ private static InboundShipmentQuery.Builder baseQuery() {
+ return InboundShipmentQuery.builder()
+ .storeIds("134225003201380864")
+ .after(Instant.parse("2026-04-01T00:00:00Z"))
+ .before(Instant.parse("2026-04-02T00:00:00Z"));
+ }
+
+ @Test
+ void requestCarriesTimeWindowStoreAndCargoFilter() {
+ new FbtCargoSource().shipments(
+ call(transport, account(Platform.TIKTOK, 10011, "134225003201380864")),
+ baseQuery()
+ .timeType(InboundShipmentTimeType.COMPLETED)
+ .statuses("1")
+ .shipmentNo("CARGO001")
+ .pageSize(100)
+ .build());
+
+ assertUrlStartsWith(lastUrl(transport), ENDPOINT + LingxingApi.INBOUND_SHIPMENT_FBT.path());
+ String body = lastBody(transport);
+ assertBodyContains(body, "\"offset\":0");
+ assertBodyContains(body, "\"length\":100");
+ assertBodyContains(body, "\"storeIdList\":[134225003201380864]");
+ assertBodyContains(body, "\"timeType\":1");
+ assertBodyContains(body, "\"startTime\":\"2026-04-01\"");
+ assertBodyContains(body, "\"endTime\":\"2026-04-02\"");
+ assertBodyContains(body, "\"queryType\":3");
+ assertBodyContains(body, "\"queryValue\":[\"CARGO001\"]");
+ assertBodyContains(body, "\"cargoStatusList\":[1]");
+ }
+
+ @Test
+ void mapsCargoIntoShipmentWithLinesAndShippingRefs() {
+ Page page = new FbtCargoSource().shipments(
+ call(transport, account(Platform.TIKTOK, 10011, "134225003201380864")),
+ baseQuery().build());
+
+ assertEquals(1, page.size());
+ assertNull(page.nextCursor());
+
+ InboundShipment shipment = page.items().get(0);
+ assertEquals("CARGO001", shipment.shipmentNo());
+ assertEquals("1234567890", shipment.shipmentId());
+ assertEquals("1", shipment.status());
+ assertEquals("已完成", shipment.statusName());
+ assertEquals("已发货", shipment.shipStatus());
+ assertEquals("134225003201380864", shipment.storeId());
+ assertEquals(2, shipment.storeIds().size());
+ assertEquals("仓库A", shipment.warehouseName());
+ assertNotNull(shipment.createdAt());
+ assertNotNull(shipment.actualArrivalAt());
+
+ assertEquals(1, shipment.lines().size());
+ assertEquals(100, shipment.lines().get(0).declaredQuantity());
+ assertEquals(99, shipment.lines().get(0).shippedQuantity());
+ assertEquals(98, shipment.lines().get(0).receivedQuantity());
+ assertEquals(95, shipment.lines().get(0).normalQuantity());
+ assertEquals(3, shipment.lines().get(0).defectiveQuantity());
+
+ assertEquals(1, shipment.shippingRefs().size());
+ assertEquals("SHP001", shipment.shippingRefs().get(0).shippingListCode());
+ assertEquals(100, shipment.shippingRefs().get(0).quantity());
+ }
+
+ @Test
+ void updatedTimeTypeIsRejected() {
+ assertThrows(ValidationException.class, () -> new FbtCargoSource().shipments(
+ call(transport, account(Platform.TIKTOK, 10011, "134225003201380864")),
+ baseQuery().timeType(InboundShipmentTimeType.UPDATED).build()));
+ }
+
+ @Test
+ void inboundOrderNoIsRejected() {
+ assertThrows(ValidationException.class, () -> new FbtCargoSource().shipments(
+ call(transport, account(Platform.TIKTOK, 10011, "134225003201380864")),
+ baseQuery().inboundOrderNo("IN-1").build()));
+ }
+}
diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSourceTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSourceTest.java
new file mode 100644
index 0000000..0130dc5
--- /dev/null
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSourceTest.java
@@ -0,0 +1,122 @@
+package common.ecommerce.lingxing.platform.inbound;
+
+import common.ecommerce.error.ValidationException;
+import common.ecommerce.lingxing.LingxingApi;
+import common.ecommerce.model.Platform;
+import common.ecommerce.model.inbound.InboundShipment;
+import common.ecommerce.model.inbound.InboundShipmentQuery;
+import common.ecommerce.model.inbound.InboundShipmentTimeType;
+import common.ecommerce.model.support.Page;
+import common.ecommerce.testkit.JsonFixture;
+import common.ecommerce.testkit.RecordingTransport;
+import common.ecommerce.testkit.Responses;
+import org.junit.jupiter.api.Test;
+
+import java.time.Instant;
+
+import static common.ecommerce.lingxing.support.LingxingTestSupport.ENDPOINT;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.account;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyContains;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertBodyNotContains;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.assertUrlStartsWith;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.call;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastBody;
+import static common.ecommerce.lingxing.support.LingxingTestSupport.lastUrl;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/** 领星 WFS 货件列表:请求构造 + 响应映射 + 不支持的维度。 */
+class WfsCargoSourceTest {
+
+ private final RecordingTransport transport = RecordingTransport.create()
+ .route(LingxingApi.INBOUND_SHIPMENT_WFS.path(),
+ r -> Responses.ok(JsonFixture.load("fixtures/lingxing/inbound/wfsCargo/success.json")));
+
+ private static InboundShipmentQuery.Builder baseQuery() {
+ return InboundShipmentQuery.builder()
+ .storeIds("110000000020008001")
+ .after(Instant.parse("2026-04-01T00:00:00Z"))
+ .before(Instant.parse("2026-04-02T00:00:00Z"));
+ }
+
+ @Test
+ void createdTimeUsesDateRange() {
+ new WfsCargoSource().shipments(
+ call(transport, account(Platform.WALMART_SC, 10008, "110000000020008001")),
+ baseQuery()
+ .statuses("0")
+ .inboundOrderNo("lry-inbound-31")
+ .pageSize(50)
+ .build());
+
+ assertUrlStartsWith(lastUrl(transport), ENDPOINT + LingxingApi.INBOUND_SHIPMENT_WFS.path());
+ String body = lastBody(transport);
+ assertBodyContains(body, "\"offset\":0");
+ assertBodyContains(body, "\"length\":50");
+ assertBodyContains(body, "\"store_id\":[\"110000000020008001\"]");
+ assertBodyContains(body, "\"start_time\":\"2026-04-01\"");
+ assertBodyContains(body, "\"end_time\":\"2026-04-02\"");
+ assertBodyContains(body, "\"inbound_order_id\":\"lry-inbound-31\"");
+ assertBodyContains(body, "\"cargo_status_list\":[0]");
+ assertBodyNotContains(body, "update_time_ge");
+ }
+
+ @Test
+ void updatedTimeUsesDateTimeRange() {
+ new WfsCargoSource().shipments(
+ call(transport, account(Platform.WALMART_SC, 10008, "110000000020008001")),
+ baseQuery().timeType(InboundShipmentTimeType.UPDATED).build());
+
+ String body = lastBody(transport);
+ assertBodyContains(body, "\"update_time_ge\":\"2026-04-01 08:00:00\"");
+ assertBodyContains(body, "\"update_time_le\":\"2026-04-02 08:00:00\"");
+ assertBodyNotContains(body, "start_time");
+ }
+
+ @Test
+ void mapsCargoIntoShipment() {
+ Page page = new WfsCargoSource().shipments(
+ call(transport, account(Platform.WALMART_SC, 10008, "110000000020008001")),
+ baseQuery().build());
+
+ assertEquals(1, page.size());
+ assertNull(page.nextCursor());
+
+ InboundShipment shipment = page.items().get(0);
+ assertEquals("lry-shipment-31", shipment.shipmentNo());
+ assertEquals("lry-inbound-31", shipment.inboundOrderNo());
+ assertEquals("PENDING_SHIPMENT_DETAILS", shipment.status());
+ assertEquals("等待发货明细", shipment.statusName());
+ assertEquals("已申报", shipment.localStatus());
+ assertEquals("LRY03", shipment.carrierCode());
+ assertEquals("沃尔玛测试店", shipment.storeName());
+ assertEquals("美国", shipment.countryName());
+ assertNotNull(shipment.createdAt());
+ assertNotNull(shipment.updatedAt());
+
+ assertEquals(1, shipment.lines().size());
+ assertEquals(10, shipment.lines().get(0).declaredQuantity());
+ assertEquals(8, shipment.lines().get(0).shippedQuantity());
+ assertEquals(7, shipment.lines().get(0).receivedQuantity());
+ assertEquals(1, shipment.lines().get(0).defectiveQuantity());
+ assertEquals("006344827368521", shipment.lines().get(0).gtin());
+
+ assertEquals(2, shipment.shippingRefs().size());
+ }
+
+ @Test
+ void shipmentNoIsRejected() {
+ assertThrows(ValidationException.class, () -> new WfsCargoSource().shipments(
+ call(transport, account(Platform.WALMART_SC, 10008, "110000000020008001")),
+ baseQuery().shipmentNo("lry-shipment-31").build()));
+ }
+
+ @Test
+ void completedTimeTypeIsRejected() {
+ assertThrows(ValidationException.class, () -> new WfsCargoSource().shipments(
+ call(transport, account(Platform.WALMART_SC, 10008, "110000000020008001")),
+ baseQuery().timeType(InboundShipmentTimeType.COMPLETED).build()));
+ }
+}
diff --git a/lingxing/src/test/resources/fixtures/lingxing/inbound/awdShipment/success.json b/lingxing/src/test/resources/fixtures/lingxing/inbound/awdShipment/success.json
new file mode 100644
index 0000000..2214c9c
--- /dev/null
+++ b/lingxing/src/test/resources/fixtures/lingxing/inbound/awdShipment/success.json
@@ -0,0 +1,73 @@
+{
+ "code": 0,
+ "message": "Success",
+ "error_details": [],
+ "request_id": "c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8",
+ "response_time": "2026-04-23T12:00:00Z",
+ "data": {
+ "current": 1,
+ "pages": 1,
+ "size": 10,
+ "total": 1,
+ "records": [
+ {
+ "orderId": "AWD20230715001",
+ "stockOrderId": "STOCK001",
+ "warehouseReferenceId": "PHX5",
+ "status": "SHIPPED",
+ "gmtCreate": "2026-04-01T10:00:00Z",
+ "gmtModified": "2026-04-02T14:30:00Z",
+ "shipBy": "2026-04-03",
+ "trackingId": "1Z1234567890123456",
+ "carrierCode": "UPS",
+ "sid": 123456789,
+ "remark": "易碎品",
+ "createByName": "API User",
+ "awdDeliveredGoodsBO": {
+ "destinationAddressLine1": "456 Distribution Ave",
+ "destinationAddressLine2": "Building 3",
+ "destinationCity": "Phoenix",
+ "destinationStateOrRegion": "AZ",
+ "destinationPostalCode": "85001",
+ "destinationCountryCode": "US"
+ },
+ "awdShippingAddressBO": {
+ "addressLine1": "123 Main St",
+ "addressLine2": "Suite 100",
+ "city": "Seattle",
+ "stateOrProvinceCode": "WA",
+ "postalCode": "98101",
+ "countryCode": "US",
+ "shipperName": "Example Shipper",
+ "phoneNumber": "1234567890",
+ "zone": "Downtown"
+ },
+ "awdDeliveredGoodsItemBOS": [
+ {
+ "asin": "B0ABCD1234",
+ "parentAsin": "B0PARENT12",
+ "fnsku": "X000123ABC",
+ "msku": "ABC123",
+ "sku": "SKU12345",
+ "productName": "示例商品",
+ "title": "示例商品标题",
+ "url": "https://example.com/product.jpg",
+ "receivedQuantity": 18,
+ "boxQuantity": "5",
+ "quantityInBox": "20",
+ "prepCategory": "NONE",
+ "prepOwner": "SELF",
+ "labelOwner": "AMAZON",
+ "length": 15.75,
+ "width": 8.25,
+ "height": 10.5,
+ "lengthUnit": "INCHES",
+ "weight": 12.3,
+ "weightUnit": "POUNDS",
+ "expiration": "2027-12-31"
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/lingxing/src/test/resources/fixtures/lingxing/inbound/fbaReceivedInventory/success.json b/lingxing/src/test/resources/fixtures/lingxing/inbound/fbaReceivedInventory/success.json
new file mode 100644
index 0000000..ad1672e
--- /dev/null
+++ b/lingxing/src/test/resources/fixtures/lingxing/inbound/fbaReceivedInventory/success.json
@@ -0,0 +1,25 @@
+{
+ "code": 0,
+ "message": "success",
+ "error_details": "",
+ "request_id": "C3D9F541-8083-E376-EB5C-606A872F5C89",
+ "response_time": "2026-04-23 12:00:00",
+ "data": [
+ {
+ "sid": 101,
+ "received_date": "2026-04-01T00:00:00+00:00",
+ "received_date_locale": "2026-04-01T01:00:00+01:00",
+ "received_date_timestamp": 1743465600,
+ "fnsku": "X000123ABC",
+ "sku": "MSKU-1",
+ "product_name": "Product 1",
+ "quantity": -5,
+ "fba_shipment_id": "FBA1Y4ZJFZ",
+ "fulfillment_center_id": "BHX4",
+ "unique_index": 3,
+ "unique_md5": "ad971e653ad89e2c94a939df63b8c884",
+ "received_date_report": "2026-04-01"
+ }
+ ],
+ "total": 1
+}
diff --git a/lingxing/src/test/resources/fixtures/lingxing/inbound/fbtCargo/success.json b/lingxing/src/test/resources/fixtures/lingxing/inbound/fbtCargo/success.json
new file mode 100644
index 0000000..7323237
--- /dev/null
+++ b/lingxing/src/test/resources/fixtures/lingxing/inbound/fbtCargo/success.json
@@ -0,0 +1,58 @@
+{
+ "code": 0,
+ "message": "success",
+ "error_details": [],
+ "request_id": "a0d54debf93140f3b58d1ed81e8e3583",
+ "response_time": "2026-04-23 12:00:00",
+ "data": {
+ "list": [
+ {
+ "id": 1234567890,
+ "cargoCode": "CARGO001",
+ "shippingWarehouse": "仓库A",
+ "createTime": "2026-04-01 12:00:00",
+ "deliveryTime": "2026-04-02 12:00:00",
+ "expectedDeliveryTime": "2026-04-05 12:00:00",
+ "actualDeliveryTime": "2026-04-04 12:00:00",
+ "orderStatus": 1,
+ "orderStatusName": "已完成",
+ "shipStatus": "已发货",
+ "storeId": 134225003201380864,
+ "storeName": "示例店铺A",
+ "storeIds": [134225003201380864, 134225003201380865],
+ "storeNames": ["示例店铺A", "示例店铺B"],
+ "orderGoodList": [
+ {
+ "id": 9876543210,
+ "goodId": "GOOD001",
+ "productId": "PROD001",
+ "skuId": "SKUID001",
+ "sku": "SKU001",
+ "msku": "MSKU001",
+ "productName": "示例商品",
+ "imageUrl": "https://example.com/image.jpg",
+ "declarationQuantity": 100,
+ "shipmentQuantity": 99,
+ "signedQuantity": 98,
+ "normalQuantity": 95,
+ "defectiveQuantity": 3
+ }
+ ],
+ "shippingInfo": [
+ {
+ "shippingListCode": "SHP001",
+ "shippingNum": "100",
+ "shippingStatus": 1,
+ "shippingStatusName": "已发货",
+ "actualDeliveryTime": "2026-04-02 12:00:00",
+ "arrivalTime": "2026-04-04 12:00:00"
+ }
+ ]
+ }
+ ],
+ "offset": 0,
+ "length": 20,
+ "pages": 1
+ },
+ "total": 1
+}
diff --git a/lingxing/src/test/resources/fixtures/lingxing/inbound/wfsCargo/success.json b/lingxing/src/test/resources/fixtures/lingxing/inbound/wfsCargo/success.json
new file mode 100644
index 0000000..796b186
--- /dev/null
+++ b/lingxing/src/test/resources/fixtures/lingxing/inbound/wfsCargo/success.json
@@ -0,0 +1,43 @@
+{
+ "code": 0,
+ "message": "success",
+ "error_details": [],
+ "request_id": "c4db3691436d4acbbda0f8b1dc53fe97",
+ "response_time": "2026-04-23 12:00:00",
+ "data": {
+ "total": "1",
+ "records": [
+ {
+ "id": "200498",
+ "cargo_code": "lry-shipment-31",
+ "in_bound_order_id": "lry-inbound-31",
+ "store_id": "110000000020008001",
+ "store_name": "沃尔玛测试店",
+ "country_name": "美国",
+ "creator": "张三",
+ "logistics_code": "LRY03",
+ "cargo_create_date": "2026-04-01 12:00:00",
+ "update_date": "2026-04-02 13:00:00",
+ "cargo_status": "PENDING_SHIPMENT_DETAILS",
+ "cargo_sync_status": "已申报",
+ "status": 0,
+ "status_name": "等待发货明细",
+ "distribution_addresses": "3 Sorbello Way,Pedricktown1,NJ9,美国,US,08067",
+ "return_addresses": "860 W California Ave,Sunnyvale,94086,美国,CA",
+ "shipping_list_codes": ["SP202307270010196", "SP202307270010197"],
+ "cargo_good_list": [
+ {
+ "msku": "test1_sku1",
+ "sku": "ueeshop1111",
+ "product_name": "测试商品",
+ "gtin": "006344827368521",
+ "shipments_num": "8",
+ "received_num": "7",
+ "declare_num": "10",
+ "dameged_qty": "1"
+ }
+ ]
+ }
+ ]
+ }
+}