diff --git a/core/src/main/java/common/ecommerce/capability/Inbounds.java b/core/src/main/java/common/ecommerce/capability/Inbounds.java
index cc70f85..34ab172 100644
--- a/core/src/main/java/common/ecommerce/capability/Inbounds.java
+++ b/core/src/main/java/common/ecommerce/capability/Inbounds.java
@@ -52,6 +52,7 @@ public final class Inbounds {
/** 分页拉取平台仓入库货件。 */
public Page shipments(final InboundShipmentQuery query) {
return CallSupport.observe(observer, ctx, "inbounds.shipments",
+ // 只放摘要(时间窗、分页、数量、是否有过滤),不放店铺明细与完整报文。
CallSupport.params(
"timeType", query.timeType(),
"after", query.after(),
@@ -85,6 +86,8 @@ public final class Inbounds {
}
private void require(Capability capability, Class> type) {
+ // supports() 是权威判断,但自定义适配器可能声明了能力却没实现接口,
+ // 这里再查一次类型,保证不把 ClassCastException 抛给调用方。
if (!adapter.supports(account, capability) || !type.isInstance(adapter)) {
throw new ChannelException.UnsupportedCapabilityException(capability);
}
diff --git a/core/src/main/java/common/ecommerce/model/inbound/InboundReceiptQuery.java b/core/src/main/java/common/ecommerce/model/inbound/InboundReceiptQuery.java
index 541c2ab..44c87c6 100644
--- a/core/src/main/java/common/ecommerce/model/inbound/InboundReceiptQuery.java
+++ b/core/src/main/java/common/ecommerce/model/inbound/InboundReceiptQuery.java
@@ -72,6 +72,7 @@ public final class InboundReceiptQuery {
private String sid;
private LocalDate eventDate;
private List shipmentIds = Collections.emptyList();
+ /** 默认取平台上限 1000:该报表按天取数,单页越大越省请求。 */
private int pageSize = 1000;
private String cursor;
diff --git a/core/src/main/java/common/ecommerce/model/inbound/InboundShipmentQuery.java b/core/src/main/java/common/ecommerce/model/inbound/InboundShipmentQuery.java
index 084ed45..30f4014 100644
--- a/core/src/main/java/common/ecommerce/model/inbound/InboundShipmentQuery.java
+++ b/core/src/main/java/common/ecommerce/model/inbound/InboundShipmentQuery.java
@@ -119,6 +119,7 @@ public final class InboundShipmentQuery {
private List statuses = Collections.emptyList();
private String shipmentNo;
private String inboundOrderNo;
+ /** 默认 50:低于各平台单页上限,兼顾首屏延迟与请求次数。 */
private int pageSize = 50;
private String cursor;
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 8e31060..0d3c878 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java
@@ -371,6 +371,7 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
@Override
public Page pull(ChannelContext ctx, InboundShipmentQuery query) {
LingxingSubPlatform impl = subPlatforms.of(ctx.platform());
+ // supports() 已按子平台收窄,这里再判一次是为了防止绕过门面直接调适配器。
if (impl.inboundShipmentSource() == null) {
throw new ChannelException.UnsupportedCapabilityException(Capability.INBOUND_SHIPMENT);
}
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
index 8c704f7..f6f33ea 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSource.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSource.java
@@ -33,6 +33,10 @@ import java.util.Map;
* 时间窗按 ISO instant 传;{@code dateType} 1 创建 / 2 更新,完成时间不支持。
*
* 该接口的货件号过滤字段是 {@code shipmentId};没有入库单号过滤。
+ *
+ * 待核对:{@code sidList} 为数值、{@code startDateTime}/{@code endDateTime}
+ * 为 ISO instant、{@code shipBy} 为 {@code YYYY-MM-DD},均按官方文档拼接,
+ * 首次真实调用需确认平台是否接受这些格式。
*/
public final class AwdCargoSource implements LingxingInboundShipmentSource {
@@ -51,15 +55,19 @@ public final class AwdCargoSource implements LingxingInboundShipmentSource {
"AWD inbound shipment does not support inboundOrderNo filter");
}
+ // 平台单页上限按 200 处理;默认 100 是折中值,避免大店铺翻页过慢。
int length = query.pageSize() <= 0 ? DEFAULT_PAGE_SIZE
: Math.min(query.pageSize(), MAX_PAGE_SIZE);
+ // 与另外两个接口不同:AWD 用页码,且从 1 开始。
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()));
+ // 店铺 id 必须是数值,账号里存的是字符串,这里统一转 Long。
body.put("sidList", InboundSupport.resolveLongStoreIds(call, query, OP));
+ // 平台要 ISO instant(带 Z),内部时间本来就是 UTC,直接 toString 即可。
if (query.after() != null) {
body.put("startDateTime", query.after().toString());
}
@@ -88,6 +96,7 @@ public final class AwdCargoSource implements LingxingInboundShipmentSource {
}
}
+ // 页码制:已取条数 = 当前页 * 每页长度;用 long 乘避免大页码溢出。
boolean hasMore = dtos.size() >= length
&& (envelope.total() < 0 || (long) page * length < envelope.total());
return Page.of(out, hasMore ? String.valueOf(page + 1) : null);
@@ -140,6 +149,7 @@ public final class AwdCargoSource implements LingxingInboundShipmentSource {
}
List lines = new ArrayList(items.size());
for (AwdGoodsItemDto item : items) {
+ // 平台有的行只给 title、有的只给 productName,统一回退到 title。
String name = InboundSupport.trimToNull(item.getProductName());
if (name == null) {
name = InboundSupport.trimToNull(item.getTitle());
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
index 9b591cb..b970196 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySource.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySource.java
@@ -29,6 +29,9 @@ import java.util.Map;
*
* 签收时间优先用带时区的 {@code received_date},其次 {@code received_date_locale},
* 最后退回秒级时间戳;三者都没有时保留 null。
+ *
+ * 待核对:{@code event_date} 的 {@code yyyy-MM-dd}、{@code sid} 为数值、
+ * {@code fba_shipment_id} 为字符串数组,均按官方文档拼接,首次真实调用需确认。
*/
public final class FbaReceivedInventorySource implements LingxingInboundReceiptSource {
@@ -39,11 +42,14 @@ public final class FbaReceivedInventorySource implements LingxingInboundReceiptS
@Override
public Page receipts(LingxingCall call, InboundReceiptQuery query) {
+ // 该接口默认 length=1000 且没有更小的推荐值;再大平台也不接受。
int length = query.pageSize() <= 0 ? DEFAULT_PAGE_SIZE
: Math.min(query.pageSize(), MAX_PAGE_SIZE);
+ // 游标是上一页返回的 offset,首页为 0。
int offset = query.cursor() == null ? 0 : Integer.parseInt(query.cursor());
Map body = new LinkedHashMap();
+ // sid 必填:查询条件没给时用账户的 externalStoreId,绝不省略成「全店铺」。
body.put("sid", resolveSid(call, query));
body.put("offset", offset);
body.put("length", length);
@@ -69,6 +75,7 @@ public final class FbaReceivedInventorySource implements LingxingInboundReceiptS
}
int nextOffset = offset + dtos.size();
+ // 顶层 total 缺失时退化为「满页即还有下一页」。
boolean hasMore = dtos.size() >= length
&& (envelope.total() < 0 || nextOffset < envelope.total());
return Page.of(out, hasMore ? String.valueOf(nextOffset) : null);
@@ -98,6 +105,7 @@ public final class FbaReceivedInventorySource implements LingxingInboundReceiptS
.fnsku(InboundSupport.trimToNull(dto.getFnsku()))
.sku(InboundSupport.trimToNull(dto.getSku()))
.productName(InboundSupport.trimToNull(dto.getProductName()))
+ // 领星可能返回负数(库存分类账调整行),原样保留,不做 abs / 归零。
.quantity(InboundSupport.intOrZero(dto.getQuantity()))
.fulfillmentCenterId(InboundSupport.trimToNull(dto.getFulfillmentCenterId()))
.receivedAt(receivedAt(dto, zone))
@@ -108,6 +116,8 @@ public final class FbaReceivedInventorySource implements LingxingInboundReceiptS
}
private static PlatformTime receivedAt(FbaReceivedInventoryDto dto, ZoneId zone) {
+ // 优先级:带偏移的 received_date → 本地时区的 received_date_locale → 秒级时间戳。
+ // 前两个都按 ISO 解析,只有日期时按北京时间当天 0 点处理。
Instant instant = InboundSupport.parseIso(dto.getReceivedDate());
if (instant == null) {
instant = InboundSupport.parseIso(dto.getReceivedDateLocale());
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
index e8e33b7..8c4829d 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSource.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSource.java
@@ -37,6 +37,9 @@ import java.util.Map;
*
* 货件号过滤走 {@code queryType=3} + {@code queryValue};
* 该接口没有入库单号过滤,传了直接拒绝。
+ *
+ * 待核对:{@code queryType=3} / {@code queryValue} 的数组形式、
+ * {@code cargoStatusList} 的数值语义均来自官方文档,首次真实调用需拿报文确认。
*/
public final class FbtCargoSource implements LingxingInboundShipmentSource {
@@ -55,8 +58,10 @@ public final class FbtCargoSource implements LingxingInboundShipmentSource {
"FBT cargo list does not support inboundOrderNo filter");
}
+ // 平台单页上限 200,超出会被截断;未指定时用默认值而不是把 length 传 0。
int length = query.pageSize() <= 0 ? DEFAULT_PAGE_SIZE
: Math.min(query.pageSize(), MAX_PAGE_SIZE);
+ // 游标就是上一页返回的 offset,首页为 0(领星 offsets 从 0 开始)。
int offset = query.cursor() == null ? 0 : Integer.parseInt(query.cursor());
Map body = new LinkedHashMap();
@@ -95,6 +100,8 @@ public final class FbtCargoSource implements LingxingInboundShipmentSource {
}
}
+ // 先按「本页是否装满」判断,再用 total 兜底:total 缺失(<0)时
+ // 只能依赖满页推断,会多一次空页请求,但不会漏数据。
int nextOffset = offset + dtos.size();
boolean hasMore = dtos.size() >= length
&& (envelope.total() < 0 || nextOffset < envelope.total());
@@ -122,6 +129,8 @@ public final class FbtCargoSource implements LingxingInboundShipmentSource {
storeIds.add(String.valueOf(id));
}
}
+ // 单店铺货件取 storeId;跨店铺货件 storeId 可能为空,优先保留 storeIds 全量。
+ // 只有一个店铺时回填 storeId,方便宿主按单店铺维度直接索引。
String storeId = dto.getStoreId() == null ? null : String.valueOf(dto.getStoreId());
if (storeId == null && storeIds.size() == 1) {
storeId = storeIds.get(0);
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
index 47842d1..a993a1e 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/InboundSupport.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/InboundSupport.java
@@ -139,10 +139,12 @@ final class InboundSupport {
}
}
+ /** null → 0;非空值原样返回(负数保留)。 */
static int intOrZero(Integer value) {
return value == null ? 0 : value;
}
+ /** 平台字符串数量 → int;null / 空串 / 非数字按 0,避免单行脏数据拖垮整页。 */
static int intOrZero(String value) {
Integer parsed = parseInt(value);
return parsed == null ? 0 : parsed;
@@ -171,6 +173,7 @@ final class InboundSupport {
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);
@@ -206,6 +209,7 @@ final class InboundSupport {
.rawResponse(envelope.body()), e);
}
+ /** 账户配置的市场时区;只用于展示,时间真值始终是 UTC。 */
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
index a4f3103..59c0426 100644
--- a/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSource.java
+++ b/lingxing/src/main/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSource.java
@@ -36,6 +36,9 @@ import java.util.Map;
* 完成时间该接口不支持。
*
* 该接口只有入库单号过滤,没有货件号过滤;传 {@code shipmentNo} 直接拒绝。
+ *
+ * 待核对:{@code cargo_status_list} 的 0~4 取值与 {@code start_time}
+ * 是否确为「创建时间」以官方文档为准,首次真实调用需确认。
*/
public final class WfsCargoSource implements LingxingInboundShipmentSource {
@@ -51,8 +54,10 @@ public final class WfsCargoSource implements LingxingInboundShipmentSource {
"WFS cargo list does not support shipmentNo filter; use inboundOrderNo");
}
+ // 平台单页上限 200;默认 15 与领星文档一致,避免一次拉太多。
int length = query.pageSize() <= 0 ? DEFAULT_PAGE_SIZE
: Math.min(query.pageSize(), MAX_PAGE_SIZE);
+ // 游标是上一页返回的 offset,首页为 0。
int offset = query.cursor() == null ? 0 : Integer.parseInt(query.cursor());
Map body = new LinkedHashMap();
@@ -83,6 +88,8 @@ public final class WfsCargoSource implements LingxingInboundShipmentSource {
}
int nextOffset = offset + dtos.size();
+ // WFS 的 total 可能是字符串,已由 LingxingEnvelope.parseTotal 统一成 long。
+ // total 缺失时退化为「满页即还有下一页」。
boolean hasMore = dtos.size() >= length
&& (envelope.total() < 0 || nextOffset < envelope.total());
return Page.of(out, hasMore ? String.valueOf(nextOffset) : null);
@@ -92,6 +99,7 @@ public final class WfsCargoSource implements LingxingInboundShipmentSource {
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(
@@ -103,6 +111,7 @@ public final class WfsCargoSource implements LingxingInboundShipmentSource {
}
return;
}
+ // 更新时间精确到秒,字段名与创建时间不同,不能复用 start_time/end_time。
if (timeType == InboundShipmentTimeType.UPDATED) {
if (query.after() != null) {
body.put("update_time_ge", InboundSupport.DATE_TIME.format(
@@ -155,6 +164,7 @@ public final class WfsCargoSource implements LingxingInboundShipmentSource {
}
List lines = new ArrayList(goods.size());
for (WfsCargoGoodDto good : goods) {
+ // 数量字段平台给的是字符串,无法解析时按 0 处理,不让单行脏数据整页失败。
lines.add(InboundShipmentLine.builder()
.sku(InboundSupport.trimToNull(good.getSku()))
.msku(InboundSupport.trimToNull(good.getMsku()))
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
index 50da0a0..a2e2ae3 100644
--- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSourceTest.java
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/AwdCargoSourceTest.java
@@ -71,6 +71,7 @@ class AwdCargoSourceTest {
baseQuery().build());
assertEquals(1, page.size());
+ // total=1 小于页长,已取完。
assertNull(page.nextCursor());
InboundShipment shipment = page.items().get(0);
@@ -94,6 +95,7 @@ class AwdCargoSourceTest {
assertEquals("B0ABCD1234", shipment.lines().get(0).asin());
assertEquals("B0PARENT12", shipment.lines().get(0).parentAsin());
assertEquals("X000123ABC", shipment.lines().get(0).fnsku());
+ // 平台给的是字符串 "5",模型按 int 暴露。
assertEquals(18, shipment.lines().get(0).receivedQuantity());
assertEquals(5, shipment.lines().get(0).boxQuantity());
assertEquals(Integer.valueOf(20), shipment.lines().get(0).quantityInBox());
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
index 3a0d1ed..429c41e 100644
--- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySourceTest.java
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbaReceivedInventorySourceTest.java
@@ -83,12 +83,14 @@ class FbaReceivedInventorySourceTest {
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());
+ // received_date 带 +00:00 偏移,优先于 locale / 时间戳,换算后仍是同一 UTC 时刻。
assertEquals(Instant.parse("2026-04-01T00:00:00Z"), receipt.receivedAt().utc());
}
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
index e0add6a..764cb19 100644
--- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSourceTest.java
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/FbtCargoSourceTest.java
@@ -71,6 +71,7 @@ class FbtCargoSourceTest {
baseQuery().build());
assertEquals(1, page.size());
+ // total=1 且小于页长,说明已经取完,不再给游标。
assertNull(page.nextCursor());
InboundShipment shipment = page.items().get(0);
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
index 0130dc5..fdca2e1 100644
--- a/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSourceTest.java
+++ b/lingxing/src/test/java/common/ecommerce/lingxing/platform/inbound/WfsCargoSourceTest.java
@@ -70,6 +70,7 @@ class WfsCargoSourceTest {
baseQuery().timeType(InboundShipmentTimeType.UPDATED).build());
String body = lastBody(transport);
+ // UTC 00:00 对应北京时间 08:00;这里验证用的是北京时间而非 UTC 直出。
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");