Browse Source

docs(yqn): 标注平台不回传的字段与待核实的单位

按核实结果把 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 <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
258d59b796
  1. 12
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java
  2. 15
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
  3. 8
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundReceipt.java
  4. 14
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
  5. 6
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java

12
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 String warehouseCode;
/** 该单据来自哪家仓;解释原始字段与选择平台枚举时使用。 */ /** 该单据来自哪家仓;解释原始字段与选择平台枚举时使用。 */
private final WarehouseProvider sourceProvider; private final WarehouseProvider sourceProvider;
/**
* 仓方单据号。
*
* <p><b>运去哪不返回</b>(API 133 costs/detail 响应无此字段):恒为 null,
* 对账只能靠 {@code saleOrderNo + settledAt + feeName} 组合。</p>
*/
private final String documentNo; private final String documentNo;
/** 仓方费用名称原值,如「尾程运费」「仓储费」。 */ /** 仓方费用名称原值,如「尾程运费」「仓储费」。 */
private final String feeName; private final String feeName;
@ -29,6 +35,12 @@ public final class BillingDocument {
private final boolean estimated; private final boolean estimated;
/** 金额币种;仓方未标时按 USD。 */ /** 金额币种;仓方未标时按 USD。 */
private final Money amount; private final Money amount;
/**
* 关联 SKU。
*
* <p><b>运去哪不返回</b>(API 133 响应无 SKU 字段):恒为 null,
* 费用只到订单 / 仓粒度。</p>
*/
private final String providerSku; private final String providerSku;
/** 关联的销售订单号(仓侧)。 */ /** 关联的销售订单号(仓侧)。 */
private final String saleOrderNo; private final String saleOrderNo;

15
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java

@ -25,7 +25,13 @@ public final class OutboundOrder {
private final String outboundRequestNo; private final String outboundRequestNo;
/** 仓方生成的出库单号;仓未返回时为 null。 */ /** 仓方生成的出库单号;仓未返回时为 null。 */
private final String providerOrderId; private final String providerOrderId;
/** 业务侧订单引用(渠道订单号等)。 */ /**
* 业务侧订单引用(渠道订单号等)。
*
* <p><b>运去哪不回传</b>(API 128 findOne 响应无此字段):下单时通过
* {@code poNumber} 发出去了,但查详情拿不回来,宿主需自行保存映射。
* 该值恒为 null。</p>
*/
private final String orderRef; private final String orderRef;
/** 面单模式。 */ /** 面单模式。 */
private final LabelMode labelMode; private final LabelMode labelMode;
@ -37,7 +43,12 @@ public final class OutboundOrder {
private final String carrier; private final String carrier;
/** 跟踪号;仓未出单时为 null。 */ /** 跟踪号;仓未出单时为 null。 */
private final String trackingNumber; private final String trackingNumber;
/** 请求下发时间(UTC)。 */ /**
* 请求下发时间(UTC)。
*
* <p><b>运去哪不回传</b>(API 128 findOne 响应无创建时间):该值恒为 null,
* 由调用方在下单时自行记录。</p>
*/
private final Instant requestedAt; private final Instant requestedAt;
/** 交运时间(UTC);未交运为 null。 */ /** 交运时间(UTC);未交运为 null。 */
private final Instant shippedAt; private final Instant shippedAt;

8
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundReceipt.java

@ -8,6 +8,14 @@ public final class OutboundReceipt {
/** OMS 生成的出库单号。 */ /** OMS 生成的出库单号。 */
private final String outboundRequestNo; private final String outboundRequestNo;
/** 仓生成的出库单号;仓未返回时为 null。 */ /** 仓生成的出库单号;仓未返回时为 null。 */
/**
* 仓侧订单 id。
*
* <p><b>不一定能当查询键用</b>:运去哪(创建销售订单 API 123)返回的
* {@code data.orderId} 是内部数字 id,只能用于列表 / 关联场景;
* 查订单详情(API 128 findOne)必须用<b>来源单号</b>,也就是
* {@link #outboundRequestNo()},不是本字段。</p>
*/
private final String providerOrderId; private final String providerOrderId;
/** 仓返回的受理状态原值。 */ /** 仓返回的受理状态原值。 */
private final String rawStatus; private final String rawStatus;

14
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java

@ -35,9 +35,19 @@ public final class TransferOrder {
private final String toWarehouseTitle; private final String toWarehouseTitle;
/** 承运商 code;未指定承运商时为 null。 */ /** 承运商 code;未指定承运商时为 null。 */
private final String carrierCode; private final String carrierCode;
/** 总重量(kg);仓方未给时为 null。 */ /**
* 总重量(kg);仓方未给时为 null。
*
* <p><b>单位待核实</b>:运去哪(API 139)文档只写「总重量」,未标单位。
* 这里按 kg 原样透传、不做换算;若联调确认是 lb,数值会偏大约 2.2 倍。</p>
*/
private final Double totalWeightKg; private final Double totalWeightKg;
/** 总体积(m³);仓方未给时为 null。 */ /**
* 总体积(m³);仓方未给时为 null。
*
* <p><b>单位待核实</b>:运去哪(API 139)文档只写「总体积」,未标单位。
* 这里按 m³ 原样透传、不做换算;若联调确认是 in³,数值会偏大约 16.4 倍。</p>
*/
private final Double totalVolumeCbm; private final Double totalVolumeCbm;
/** /**
* 仓方异常码;无异常时为 null。 * 仓方异常码;无异常时为 null。

6
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java

@ -29,6 +29,12 @@ public final class WarehouseReturn {
/** 处理方式(检验后的归一化视图);无法识别为 UNKNOWN,原值见 {@link #rawStatus()}。 */ /** 处理方式(检验后的归一化视图);无法识别为 UNKNOWN,原值见 {@link #rawStatus()}。 */
private final ReturnProcessDisposition disposition; private final ReturnProcessDisposition disposition;
private final List<ReturnLine> lines; private final List<ReturnLine> lines;
/**
* 创建时间(UTC)。
*
* <p><b>运去哪不回传</b>(API 83 getInboundPlanInfo 响应无创建时间):
* 该值恒为 null;{@link #actualReceivedAt()} 是实际收货时间,语义不同。</p>
*/
private final Instant createdAt; private final Instant createdAt;
/** 实际收货时间(UTC);未收货为 null。 */ /** 实际收货时间(UTC);未收货为 null。 */
private final Instant actualReceivedAt; private final Instant actualReceivedAt;

Loading…
Cancel
Save