From 138ffe05b5c8d63fa4ae6ce315a086b19b341529 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Fri, 6 Nov 2026 15:24:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(lingxing):=20=E8=A1=A5=E5=85=A5=E5=BA=93?= =?UTF-8?q?=E6=9F=A5=E8=AF=A2=E7=9A=84=E5=88=86=E9=A1=B5=E3=80=81=E6=97=B6?= =?UTF-8?q?=E5=8C=BA=E4=B8=8E=E5=AD=97=E6=AE=B5=E6=98=A0=E5=B0=84=E6=B3=A8?= =?UTF-8?q?=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 只加注释:分页终点判定、北京时间转换、字符串数量回退、待核对字段说明,不改逻辑。 --- core/src/main/java/common/ecommerce/capability/Inbounds.java | 3 +++ .../common/ecommerce/model/inbound/InboundReceiptQuery.java | 1 + .../common/ecommerce/model/inbound/InboundShipmentQuery.java | 1 + .../common/ecommerce/lingxing/adapter/LingxingAdapter.java | 1 + .../ecommerce/lingxing/platform/inbound/AwdCargoSource.java | 10 ++++++++++ .../lingxing/platform/inbound/FbaReceivedInventorySource.java | 10 ++++++++++ .../ecommerce/lingxing/platform/inbound/FbtCargoSource.java | 9 +++++++++ .../ecommerce/lingxing/platform/inbound/InboundSupport.java | 4 ++++ .../ecommerce/lingxing/platform/inbound/WfsCargoSource.java | 10 ++++++++++ .../lingxing/platform/inbound/AwdCargoSourceTest.java | 2 ++ .../platform/inbound/FbaReceivedInventorySourceTest.java | 2 ++ .../lingxing/platform/inbound/FbtCargoSourceTest.java | 1 + .../lingxing/platform/inbound/WfsCargoSourceTest.java | 1 + 13 files changed, 55 insertions(+) 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");