From 258d59b796bad4e273f000701a9bffd1652973a6 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Wed, 11 Nov 2026 11:27:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(yqn):=20=E6=A0=87=E6=B3=A8=E5=B9=B3?= =?UTF-8?q?=E5=8F=B0=E4=B8=8D=E5=9B=9E=E4=BC=A0=E7=9A=84=E5=AD=97=E6=AE=B5?= =?UTF-8?q?=E4=B8=8E=E5=BE=85=E6=A0=B8=E5=AE=9E=E7=9A=84=E5=8D=95=E4=BD=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按核实结果把 5 处平台限制写进 Javadoc,避免后来人当成「接漏了」: - OutboundReceipt.providerOrderId:创建销售订单(API 123)返回的内部数字 id,只能用于列表/关联;查详情(API 128)要用来源单号 outboundRequestNo - OutboundOrder.orderRef / requestedAt:订单详情不回传,恒为 null, 宿主需自行保存映射 - WarehouseReturn.createdAt:退货计划查询(API 83)无创建时间 - BillingDocument.documentNo / providerSku:结算明细(API 133)响应无这两个 字段,对账靠 saleOrderNo + settledAt + feeName - TransferOrder.totalWeightKg / totalVolumeCbm:调拨(API 139)文档未标单位, 按 kg / m³ 原样透传;若确认是 lb / in³ 则分别偏大 2.2 / 16.4 倍 Co-Authored-By: Claude --- .../common/ecommerce/warehouse/model/BillingDocument.java | 12 ++++++++++++ .../common/ecommerce/warehouse/model/OutboundOrder.java | 15 +++++++++++++-- .../common/ecommerce/warehouse/model/OutboundReceipt.java | 8 ++++++++ .../common/ecommerce/warehouse/model/TransferOrder.java | 14 ++++++++++++-- .../common/ecommerce/warehouse/model/WarehouseReturn.java | 6 ++++++ 5 files changed, 51 insertions(+), 4 deletions(-) diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java index d0d2235..3b9d8c6 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java @@ -18,6 +18,12 @@ public final class BillingDocument { private final String warehouseCode; /** 该单据来自哪家仓;解释原始字段与选择平台枚举时使用。 */ private final WarehouseProvider sourceProvider; + /** + * 仓方单据号。 + * + *

运去哪不返回(API 133 costs/detail 响应无此字段):恒为 null, + * 对账只能靠 {@code saleOrderNo + settledAt + feeName} 组合。

+ */ private final String documentNo; /** 仓方费用名称原值,如「尾程运费」「仓储费」。 */ private final String feeName; @@ -29,6 +35,12 @@ public final class BillingDocument { private final boolean estimated; /** 金额币种;仓方未标时按 USD。 */ private final Money amount; + /** + * 关联 SKU。 + * + *

运去哪不返回(API 133 响应无 SKU 字段):恒为 null, + * 费用只到订单 / 仓粒度。

+ */ private final String providerSku; /** 关联的销售订单号(仓侧)。 */ private final String saleOrderNo; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java index 5f2c27b..73da5c3 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java @@ -25,7 +25,13 @@ public final class OutboundOrder { private final String outboundRequestNo; /** 仓方生成的出库单号;仓未返回时为 null。 */ private final String providerOrderId; - /** 业务侧订单引用(渠道订单号等)。 */ + /** + * 业务侧订单引用(渠道订单号等)。 + * + *

运去哪不回传(API 128 findOne 响应无此字段):下单时通过 + * {@code poNumber} 发出去了,但查详情拿不回来,宿主需自行保存映射。 + * 该值恒为 null。

+ */ private final String orderRef; /** 面单模式。 */ private final LabelMode labelMode; @@ -37,7 +43,12 @@ public final class OutboundOrder { private final String carrier; /** 跟踪号;仓未出单时为 null。 */ private final String trackingNumber; - /** 请求下发时间(UTC)。 */ + /** + * 请求下发时间(UTC)。 + * + *

运去哪不回传(API 128 findOne 响应无创建时间):该值恒为 null, + * 由调用方在下单时自行记录。

+ */ private final Instant requestedAt; /** 交运时间(UTC);未交运为 null。 */ private final Instant shippedAt; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundReceipt.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundReceipt.java index 1c8e46f..5b50284 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundReceipt.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundReceipt.java @@ -8,6 +8,14 @@ public final class OutboundReceipt { /** OMS 生成的出库单号。 */ private final String outboundRequestNo; /** 仓生成的出库单号;仓未返回时为 null。 */ + /** + * 仓侧订单 id。 + * + *

不一定能当查询键用:运去哪(创建销售订单 API 123)返回的 + * {@code data.orderId} 是内部数字 id,只能用于列表 / 关联场景; + * 查订单详情(API 128 findOne)必须用来源单号,也就是 + * {@link #outboundRequestNo()},不是本字段。

+ */ private final String providerOrderId; /** 仓返回的受理状态原值。 */ private final String rawStatus; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java index 37a6650..c03fe41 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java @@ -35,9 +35,19 @@ public final class TransferOrder { private final String toWarehouseTitle; /** 承运商 code;未指定承运商时为 null。 */ private final String carrierCode; - /** 总重量(kg);仓方未给时为 null。 */ + /** + * 总重量(kg);仓方未给时为 null。 + * + *

单位待核实:运去哪(API 139)文档只写「总重量」,未标单位。 + * 这里按 kg 原样透传、不做换算;若联调确认是 lb,数值会偏大约 2.2 倍。

+ */ private final Double totalWeightKg; - /** 总体积(m³);仓方未给时为 null。 */ + /** + * 总体积(m³);仓方未给时为 null。 + * + *

单位待核实:运去哪(API 139)文档只写「总体积」,未标单位。 + * 这里按 m³ 原样透传、不做换算;若联调确认是 in³,数值会偏大约 16.4 倍。

+ */ private final Double totalVolumeCbm; /** * 仓方异常码;无异常时为 null。 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java index 86fe05c..7b22681 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java @@ -29,6 +29,12 @@ public final class WarehouseReturn { /** 处理方式(检验后的归一化视图);无法识别为 UNKNOWN,原值见 {@link #rawStatus()}。 */ private final ReturnProcessDisposition disposition; private final List lines; + /** + * 创建时间(UTC)。 + * + *

运去哪不回传(API 83 getInboundPlanInfo 响应无创建时间): + * 该值恒为 null;{@link #actualReceivedAt()} 是实际收货时间,语义不同。

+ */ private final Instant createdAt; /** 实际收货时间(UTC);未收货为 null。 */ private final Instant actualReceivedAt;