Browse Source

feat(yqn): 批量补齐「仓方有、模型没有」的字段

按「仓方给了就加,并标注来源字段」补齐四类:

1. 创建入库计划(API 97)请求侧 11 个字段,之前完全没下发:
   lineCode / shipmentId / referenceId / attachInfoItems / transportType /
   deliveryType / goodsSize / tmsNos / carrier / socFlag / palletFlag。
   其中 attachInfoItems 意味着之前入库单无法随单传附件(面单/装箱单/BOL)。
   tmsNos 运去哪是逗号分割的字符串,出参用 List 承接。

2. 查询入库计划(API 101)响应侧 10 个字段:
   lineName / shipmentId / referenceId / shipmentNo / goodsType /
   actualShipDate / cartonTotalWeight / cartonTotalVolume / 四种柜型数量与柜号。
   柜型新增 InboundOrder.ContainerInfo(GP20/GP40/HQ40/HQ45 + 数量 + 柜号 +
   仓方原值),只对给了值的柜型产对象。

3. 商品(API 115)11 个字段:
   expirationControl / expirationDate / packedQty / packedLength/Width/Height/
   Weight / isInsuranceFlag / isInsuranceRate / snMgmtMode / lotControl。
   顺带修海关币种:之前把申报额无脑贴成 USD,非美元会被静默算错;
   现在非 USD 直接拒绝,由调用方换算。

4. 物流轨迹(API 189):
   parcel 实重实尺(oz/inch 统一换算成 g/cm 后落模型,宿主不用各仓换算)
   + carrierDetail 的承诺送达日期 / 始发地 / 目的地。

另把 WarehouseReturn.Attachment 合并为通用 WarehouseAttachment,
与出库/入库附件统一。

新增 YqnExtraFieldsTest(9 个)。全量 486 个测试通过。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
a267d67bac
  1. 3
      README.md
  2. 218
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  3. 200
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java
  4. 244
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
  5. 118
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java
  6. 68
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java
  7. 108
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
  8. 45
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
  9. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java
  10. 30
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java
  11. 263
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnExtraFieldsTest.java
  12. 2
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnReturnQueryTest.java

3
README.md

@ -306,7 +306,8 @@ common.ecommerce
│ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult / │ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult /
│ │ InventorySnapshot / InventoryQuery / InboundOrder / InboundOrderLine / │ │ InventorySnapshot / InventoryQuery / InboundOrder / InboundOrderLine /
│ │ InboundCommand / InboundLine / InboundCarton / InboundBatch / │ │ InboundCommand / InboundLine / InboundCarton / InboundBatch /
│ │ InboundReceipt / InboundOrderBatch / InboundOrderBox / ReturnCommand / ReturnProcessCommand / │ │ InboundReceipt / InboundOrderBatch / InboundOrderBox / WarehouseAttachment / SerialNumber /
│ │ ReturnCommand / ReturnProcessCommand /
│ │ WarehouseReturn / TransferCommand / TransferOrder(含 errorCode/errorReason 等)/ │ │ WarehouseReturn / TransferCommand / TransferOrder(含 errorCode/errorReason 等)/
│ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult / │ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult /
│ │ TrackEvent / TrackingInfo / WarehouseCallback / DestructionCommand / DestructionOrder / │ │ TrackEvent / TrackingInfo / WarehouseCallback / DestructionCommand / DestructionOrder /

218
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java

@ -3,6 +3,7 @@ package common.ecommerce.warehouse.capability;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.ReturnDealMethod; import common.ecommerce.warehouse.enums.ReturnDealMethod;
import java.util.List;
import java.util.Objects; import java.util.Objects;
/** /**
@ -50,6 +51,78 @@ public final class WarehouseProduct {
private final Money cost; private final Money cost;
private final String link; private final String link;
private final String remark; private final String remark;
/**
* 保质期管理开关:null 未指定 / true 开启 / false 关闭。
*
* <p>运去哪字段:{@code expirationControl}(API 115 product/save)。</p>
*/
private final Boolean expirationControl;
/**
* 保质期天数。
*
* <p>运去哪字段:{@code expirationDate}(API 115)。</p>
*/
private final Integer expirationDays;
/**
* 装箱数量(一箱几件)。
*
* <p>运去哪字段:{@code packedQty}(API 115)。</p>
*/
private final Integer packedQuantity;
/**
* 外箱长(cm)。
*
* <p>运去哪字段:{@code packedLength}(API 115)。</p>
*/
private final Double packedLengthCm;
/**
* 外箱宽(cm)。
*
* <p>运去哪字段:{@code packedWidth}(API 115)。</p>
*/
private final Double packedWidthCm;
/**
* 外箱高(cm)。
*
* <p>运去哪字段:{@code packedHeight}(API 115)。</p>
*/
private final Double packedHeightCm;
/**
* 外箱重量(g)。
*
* <p>运去哪字段:{@code packedWeight}(API 115)。</p>
*/
private final Double packedWeightGrams;
/**
* 是否保价:null 未指定 / true 保价 / false 不保价。
*
* <p>运去哪字段:{@code isInsuranceFlag}(API 115,Y / N)。</p>
*/
private final Boolean insured;
/**
* 保价费用。
*
* <p>运去哪字段:{@code isInsuranceRate}(API 115)。</p>
*/
private final Money insuranceFee;
/**
* 序列号管理方式码,取值由各仓定义(运去哪:1 全链路 SN / 2 出库采集)。
*
* <p>运去哪字段:{@code snMgmtMode}(API 115)。</p>
*/
private final Integer snManagementMode;
/**
* 是否开启批次管理。
*
* <p>运去哪字段:{@code lotControl.lotEnabled}(API 115)。</p>
*/
private final Boolean lotControlEnabled;
/**
* 需要开启的批次属性编码。
*
* <p>运去哪字段:{@code lotControl.lotAttrCodeList}(API 115)。</p>
*/
private final List<String> lotAttributeCodes;
private WarehouseProduct(Builder b) { private WarehouseProduct(Builder b) {
this.omsSku = require(b.omsSku, "omsSku"); this.omsSku = require(b.omsSku, "omsSku");
@ -82,6 +155,19 @@ public final class WarehouseProduct {
this.cost = b.cost; this.cost = b.cost;
this.link = b.link; this.link = b.link;
this.remark = b.remark; this.remark = b.remark;
this.expirationControl = b.expirationControl;
this.expirationDays = b.expirationDays;
this.packedQuantity = b.packedQuantity;
this.packedLengthCm = b.packedLengthCm;
this.packedWidthCm = b.packedWidthCm;
this.packedHeightCm = b.packedHeightCm;
this.packedWeightGrams = b.packedWeightGrams;
this.insured = b.insured;
this.insuranceFee = b.insuranceFee;
this.snManagementMode = b.snManagementMode;
this.lotControlEnabled = b.lotControlEnabled;
this.lotAttributeCodes = java.util.Collections.unmodifiableList(
new java.util.ArrayList<String>(b.lotAttributeCodes));
// 海关信息要么整组给、要么整组不给:国家编码 / HS Code / 申报价值缺一即失败 // 海关信息要么整组给、要么整组不给:国家编码 / HS Code / 申报价值缺一即失败
int customsFields = 0; int customsFields = 0;
@ -214,6 +300,66 @@ public final class WarehouseProduct {
return link; return link;
} }
/** 保质期管理开关;null 表示未指定。 */
public Boolean expirationControl() {
return expirationControl;
}
/** 保质期天数;未给为 null。 */
public Integer expirationDays() {
return expirationDays;
}
/** 装箱数量;未给为 null。 */
public Integer packedQuantity() {
return packedQuantity;
}
/** 外箱长(cm);未给为 null。 */
public Double packedLengthCm() {
return packedLengthCm;
}
/** 外箱宽(cm);未给为 null。 */
public Double packedWidthCm() {
return packedWidthCm;
}
/** 外箱高(cm);未给为 null。 */
public Double packedHeightCm() {
return packedHeightCm;
}
/** 外箱重量(g);未给为 null。 */
public Double packedWeightGrams() {
return packedWeightGrams;
}
/** 是否保价;null 表示未指定。 */
public Boolean insured() {
return insured;
}
/** 保价费用;未给为 null。 */
public Money insuranceFee() {
return insuranceFee;
}
/** 序列号管理方式码(仓方口径);未给为 null。 */
public Integer snManagementMode() {
return snManagementMode;
}
/** 是否开启批次管理;null 表示未指定。 */
public Boolean lotControlEnabled() {
return lotControlEnabled;
}
/** 需要开启的批次属性编码;不可变。 */
public List<String> lotAttributeCodes() {
return lotAttributeCodes;
}
public String remark() { public String remark() {
return remark; return remark;
} }
@ -270,6 +416,18 @@ public final class WarehouseProduct {
private Money cost; private Money cost;
private String link; private String link;
private String remark; private String remark;
private Boolean expirationControl;
private Integer expirationDays;
private Integer packedQuantity;
private Double packedLengthCm;
private Double packedWidthCm;
private Double packedHeightCm;
private Double packedWeightGrams;
private Boolean insured;
private Money insuranceFee;
private Integer snManagementMode;
private Boolean lotControlEnabled;
private final List<String> lotAttributeCodes = new java.util.ArrayList<String>();
public Builder omsSku(String v) { public Builder omsSku(String v) {
this.omsSku = v; this.omsSku = v;
@ -403,6 +561,66 @@ public final class WarehouseProduct {
return this; return this;
} }
public Builder expirationControl(Boolean v) {
this.expirationControl = v;
return this;
}
public Builder expirationDays(Integer v) {
this.expirationDays = v;
return this;
}
public Builder packedQuantity(Integer v) {
this.packedQuantity = v;
return this;
}
public Builder packedLengthCm(Double v) {
this.packedLengthCm = v;
return this;
}
public Builder packedWidthCm(Double v) {
this.packedWidthCm = v;
return this;
}
public Builder packedHeightCm(Double v) {
this.packedHeightCm = v;
return this;
}
public Builder packedWeightGrams(Double v) {
this.packedWeightGrams = v;
return this;
}
public Builder insured(Boolean v) {
this.insured = v;
return this;
}
public Builder insuranceFee(Money v) {
this.insuranceFee = v;
return this;
}
public Builder snManagementMode(Integer v) {
this.snManagementMode = v;
return this;
}
public Builder lotControlEnabled(Boolean v) {
this.lotControlEnabled = v;
return this;
}
public Builder lotAttributeCode(String v) {
this.lotAttributeCodes.add(v);
return this;
}
public Builder remark(String v) { public Builder remark(String v) {
this.remark = v; this.remark = v;
return this; return this;

200
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java

@ -39,6 +39,72 @@ public final class InboundCommand {
private final List<InboundLine> lines; private final List<InboundLine> lines;
private final List<InboundCarton> cartons; private final List<InboundCarton> cartons;
private final List<InboundBatch> batches; private final List<InboundBatch> batches;
/**
* 项目名称(仓方按项目分账 / 路由)。
*
* <p>运去哪字段:{@code lineCode}(API 97 createInboundPlan)。</p>
*/
private final String lineName;
/**
* Amazon 货件号。
*
* <p>运去哪字段:{@code shipmentId}(API 97)。</p>
*/
private final String shipmentId;
/**
* Amazon 货件 reference id。
*
* <p>运去哪字段:{@code referenceId}(API 97)。</p>
*/
private final String referenceId;
/**
* 附件(面单 / 装箱单 / BOL / 发票)。
*
* <p>运去哪字段:{@code attachInfoItems}(API 97)。</p>
*/
private final List<WarehouseAttachment> attachments;
/**
* 国际运输方式码,取值由各仓定义(运去哪:0 海运整柜 / 1 海运散货 / 2 国际快递 / 3 空运)。
*
* <p>运去哪字段:{@code transportType}(API 97)。</p>
*/
private final Integer transportType;
/**
* 送仓方式码,取值由各仓定义(运去哪:1 集装箱 / 2 卡车 / 3 快递)。
*
* <p>运去哪字段:{@code deliveryType}(API 97)。</p>
*/
private final Integer deliveryType;
/**
* 集装箱尺寸码,取值由各仓定义(运去哪:0 无 / 1 GP20 / 2 GP40 / 3 HQ40 / 4 HQ45)。
*
* <p>运去哪字段:{@code goodsSize}(API 97)。</p>
*/
private final Integer containerSize;
/**
* 头程物流单号集合(如柜号、提单号)。
*
* <p>运去哪字段:{@code tmsNos}(API 97,逗号分隔的字符串)。</p>
*/
private final List<String> transportOrderNos;
/**
* 头程承运商码,取值由各仓定义(运去哪:0 FEDEX / 1 USPS / 2 UPS / 3 DHL / 4 OTHER)。
*
* <p>运去哪字段:{@code carrier}(API 97)。</p>
*/
private final Integer carrierCode;
/**
* 是否 SOC 箱。
*
* <p>运去哪字段:{@code socFlag}(API 97,0 否 / 1 是)。</p>
*/
private final Boolean socContainer;
/**
* 是否打托。
*
* <p>运去哪字段:{@code palletFlag}(API 97,0 否 / 1 是)。</p>
*/
private final Boolean palletized;
private InboundCommand(Builder b) { private InboundCommand(Builder b) {
if (b.inboundRequestNo == null || b.inboundRequestNo.trim().isEmpty()) { if (b.inboundRequestNo == null || b.inboundRequestNo.trim().isEmpty()) {
@ -73,6 +139,19 @@ public final class InboundCommand {
this.lines = Collections.unmodifiableList(new ArrayList<InboundLine>(b.lines)); this.lines = Collections.unmodifiableList(new ArrayList<InboundLine>(b.lines));
this.cartons = Collections.unmodifiableList(new ArrayList<InboundCarton>(b.cartons)); this.cartons = Collections.unmodifiableList(new ArrayList<InboundCarton>(b.cartons));
this.batches = Collections.unmodifiableList(new ArrayList<InboundBatch>(b.batches)); this.batches = Collections.unmodifiableList(new ArrayList<InboundBatch>(b.batches));
this.lineName = b.lineName;
this.shipmentId = b.shipmentId;
this.referenceId = b.referenceId;
this.attachments = java.util.Collections.unmodifiableList(
new java.util.ArrayList<WarehouseAttachment>(b.attachments));
this.transportType = b.transportType;
this.deliveryType = b.deliveryType;
this.containerSize = b.containerSize;
this.transportOrderNos = java.util.Collections.unmodifiableList(
new java.util.ArrayList<String>(b.transportOrderNos));
this.carrierCode = b.carrierCode;
this.socContainer = b.socContainer;
this.palletized = b.palletized;
} }
public static Builder builder() { public static Builder builder() {
@ -156,6 +235,61 @@ public final class InboundCommand {
return batches; return batches;
} }
/** 项目名称;未给为 null。 */
public String lineName() {
return lineName;
}
/** Amazon 货件号;非 FBA 为 null。 */
public String shipmentId() {
return shipmentId;
}
/** Amazon 货件 reference id;非 FBA 为 null。 */
public String referenceId() {
return referenceId;
}
/** 随单附件;不可变。 */
public List<WarehouseAttachment> attachments() {
return attachments;
}
/** 国际运输方式码(仓方口径);未给为 null。 */
public Integer transportType() {
return transportType;
}
/** 送仓方式码(仓方口径);未给为 null。 */
public Integer deliveryType() {
return deliveryType;
}
/** 集装箱尺寸码(仓方口径);未给为 null。 */
public Integer containerSize() {
return containerSize;
}
/** 头程物流单号集合;不可变。 */
public List<String> transportOrderNos() {
return transportOrderNos;
}
/** 头程承运商码(仓方口径);未给为 null。 */
public Integer carrierCode() {
return carrierCode;
}
/** 是否 SOC 箱;null 表示未指定。 */
public Boolean socContainer() {
return socContainer;
}
/** 是否打托;null 表示未指定。 */
public Boolean palletized() {
return palletized;
}
public static final class Builder { public static final class Builder {
private String inboundRequestNo; private String inboundRequestNo;
@ -176,6 +310,17 @@ public final class InboundCommand {
private final List<InboundLine> lines = new ArrayList<InboundLine>(); private final List<InboundLine> lines = new ArrayList<InboundLine>();
private final List<InboundCarton> cartons = new ArrayList<InboundCarton>(); private final List<InboundCarton> cartons = new ArrayList<InboundCarton>();
private final List<InboundBatch> batches = new ArrayList<InboundBatch>(); private final List<InboundBatch> batches = new ArrayList<InboundBatch>();
private String lineName;
private String shipmentId;
private String referenceId;
private final List<WarehouseAttachment> attachments = new ArrayList<WarehouseAttachment>();
private Integer transportType;
private Integer deliveryType;
private Integer containerSize;
private final List<String> transportOrderNos = new ArrayList<String>();
private Integer carrierCode;
private Boolean socContainer;
private Boolean palletized;
public Builder inboundRequestNo(String v) { public Builder inboundRequestNo(String v) {
this.inboundRequestNo = v; this.inboundRequestNo = v;
@ -270,6 +415,61 @@ public final class InboundCommand {
return this; return this;
} }
public Builder lineName(String v) {
this.lineName = v;
return this;
}
public Builder shipmentId(String v) {
this.shipmentId = v;
return this;
}
public Builder referenceId(String v) {
this.referenceId = v;
return this;
}
public Builder attachment(WarehouseAttachment v) {
this.attachments.add(v);
return this;
}
public Builder transportType(Integer v) {
this.transportType = v;
return this;
}
public Builder deliveryType(Integer v) {
this.deliveryType = v;
return this;
}
public Builder containerSize(Integer v) {
this.containerSize = v;
return this;
}
public Builder transportOrderNo(String v) {
this.transportOrderNos.add(v);
return this;
}
public Builder carrierCode(Integer v) {
this.carrierCode = v;
return this;
}
public Builder socContainer(Boolean v) {
this.socContainer = v;
return this;
}
public Builder palletized(Boolean v) {
this.palletized = v;
return this;
}
public Builder batch(InboundBatch v) { public Builder batch(InboundBatch v) {
this.batches.add(v); this.batches.add(v);
return this; return this;

244
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java

@ -65,6 +65,61 @@ public final class InboundOrder {
private final Double totalVolumeCbm; private final Double totalVolumeCbm;
private final String remark; private final String remark;
private final List<InboundOrderLine> lines; private final List<InboundOrderLine> lines;
/**
* 项目名称。
*
* <p>运去哪字段:{@code lineName}(API 101 getInboundPlanInfo)。</p>
*/
private final String lineName;
/**
* Amazon 货件号。
*
* <p>运去哪字段:{@code shipmentId}(API 101)。</p>
*/
private final String shipmentId;
/**
* Amazon 货件 reference id。
*
* <p>运去哪字段:{@code referenceId}(API 101)。</p>
*/
private final String referenceId;
/**
* 物流单号。
*
* <p>运去哪字段:{@code shipmentNo}(API 101)。</p>
*/
private final String shipmentNo;
/**
* 货物形态(如普货 / 带电)。
*
* <p>运去哪字段:{@code goodsType}(API 101)。</p>
*/
private final String goodsType;
/**
* 实际发运时间(UTC)。
*
* <p>运去哪字段:{@code actualShipDate}(API 101)。</p>
*/
private final Instant actualShippedAt;
/**
* 总纸箱重量(kg)。
*
* <p>运去哪字段:{@code cartonTotalWeight}(API 101)。</p>
*/
private final Double cartonTotalWeightKg;
/**
* 总纸箱体积(CBM)。
*
* <p>运去哪字段:{@code cartonTotalVolume}(API 101)。</p>
*/
private final Double cartonTotalVolumeCbm;
/**
* 集装箱信息(GP20 / GP40 / HQ40 / HQ45 的数量与柜号)。
*
* <p>运去哪字段:{@code gpQuantity20 / gpCartonNo20 / gpQuantity40 / gpCartonNo40 /
* hqQuantity40 / hqCartonNo40 / hqQuantity45 / hqCartonNo45}(API 101)。</p>
*/
private final List<ContainerInfo> containers;
private InboundOrder(Builder b) { private InboundOrder(Builder b) {
this.inboundRequestNo = require(b.inboundRequestNo, "inboundRequestNo"); this.inboundRequestNo = require(b.inboundRequestNo, "inboundRequestNo");
@ -94,6 +149,15 @@ public final class InboundOrder {
this.remark = b.remark; this.remark = b.remark;
this.lines = b.lines == null ? Collections.<InboundOrderLine>emptyList() this.lines = b.lines == null ? Collections.<InboundOrderLine>emptyList()
: Collections.unmodifiableList(new ArrayList<InboundOrderLine>(b.lines)); : Collections.unmodifiableList(new ArrayList<InboundOrderLine>(b.lines));
this.lineName = b.lineName;
this.shipmentId = b.shipmentId;
this.referenceId = b.referenceId;
this.shipmentNo = b.shipmentNo;
this.goodsType = b.goodsType;
this.actualShippedAt = b.actualShippedAt;
this.cartonTotalWeightKg = b.cartonTotalWeightKg;
this.cartonTotalVolumeCbm = b.cartonTotalVolumeCbm;
this.containers = Collections.unmodifiableList(new ArrayList<ContainerInfo>(b.containers));
} }
public static Builder builder() { public static Builder builder() {
@ -215,6 +279,132 @@ public final class InboundOrder {
} }
/** 该单据来自哪家仓。 */ /** 该单据来自哪家仓。 */
/** 项目名称;未给为 null。 */
public String lineName() {
return lineName;
}
/** Amazon 货件号;非 FBA 为 null。 */
public String shipmentId() {
return shipmentId;
}
/** Amazon 货件 reference id;非 FBA 为 null。 */
public String referenceId() {
return referenceId;
}
/** 物流单号;未给为 null。 */
public String shipmentNo() {
return shipmentNo;
}
/** 货物形态;未给为 null。 */
public String goodsType() {
return goodsType;
}
/** 实际发运时间;未发运为 null。 */
public Instant actualShippedAt() {
return actualShippedAt;
}
/** 总纸箱重量(kg);未给为 null。 */
public Double cartonTotalWeightKg() {
return cartonTotalWeightKg;
}
/** 总纸箱体积(CBM);未给为 null。 */
public Double cartonTotalVolumeCbm() {
return cartonTotalVolumeCbm;
}
/** 集装箱信息;不可变。 */
public List<ContainerInfo> containers() {
return containers;
}
/** 集装箱类型。 */
public enum ContainerType {
/** 20 尺普柜。 */
GP20,
/** 40 尺普柜。 */
GP40,
/** 40 尺高柜。 */
HQ40,
/** 45 尺高柜。 */
HQ45
}
/** 一类集装箱的数量与柜号。 */
public static final class ContainerInfo {
private final ContainerType type;
private final Integer quantity;
private final String containerNo;
/** 仓方原值;用于解释无法识别的柜型。 */
private final String rawType;
private ContainerInfo(Builder b) {
this.type = b.type;
this.quantity = b.quantity;
this.containerNo = b.containerNo;
this.rawType = b.rawType;
}
public static Builder builder() {
return new Builder();
}
public ContainerType type() {
return type;
}
public Integer quantity() {
return quantity;
}
public String containerNo() {
return containerNo;
}
/** 仓方原值,如运去哪的 {@code gpQuantity20}。 */
public String rawType() {
return rawType;
}
public static final class Builder {
private ContainerType type;
private Integer quantity;
private String containerNo;
private String rawType;
public Builder type(ContainerType v) {
this.type = v;
return this;
}
public Builder quantity(Integer v) {
this.quantity = v;
return this;
}
public Builder containerNo(String v) {
this.containerNo = v;
return this;
}
public Builder rawType(String v) {
this.rawType = v;
return this;
}
public ContainerInfo build() {
return new ContainerInfo(this);
}
}
}
public WarehouseProvider sourceProvider() { public WarehouseProvider sourceProvider() {
return sourceProvider; return sourceProvider;
} }
@ -253,6 +443,15 @@ public final class InboundOrder {
private Double totalVolumeCbm; private Double totalVolumeCbm;
private String remark; private String remark;
private List<InboundOrderLine> lines; private List<InboundOrderLine> lines;
private String lineName;
private String shipmentId;
private String referenceId;
private String shipmentNo;
private String goodsType;
private Instant actualShippedAt;
private Double cartonTotalWeightKg;
private Double cartonTotalVolumeCbm;
private final List<ContainerInfo> containers = new ArrayList<ContainerInfo>();
public Builder inboundRequestNo(String v) { public Builder inboundRequestNo(String v) {
this.inboundRequestNo = v; this.inboundRequestNo = v;
@ -319,6 +518,51 @@ public final class InboundOrder {
return this; return this;
} }
public Builder lineName(String v) {
this.lineName = v;
return this;
}
public Builder shipmentId(String v) {
this.shipmentId = v;
return this;
}
public Builder referenceId(String v) {
this.referenceId = v;
return this;
}
public Builder shipmentNo(String v) {
this.shipmentNo = v;
return this;
}
public Builder goodsType(String v) {
this.goodsType = v;
return this;
}
public Builder actualShippedAt(Instant v) {
this.actualShippedAt = v;
return this;
}
public Builder cartonTotalWeightKg(Double v) {
this.cartonTotalWeightKg = v;
return this;
}
public Builder cartonTotalVolumeCbm(Double v) {
this.cartonTotalVolumeCbm = v;
return this;
}
public Builder container(ContainerInfo v) {
this.containers.add(v);
return this;
}
public Builder packingLabelUrl(String v) { public Builder packingLabelUrl(String v) {
this.packingLabelUrl = v; this.packingLabelUrl = v;
return this; return this;

118
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java

@ -31,6 +31,40 @@ public final class TrackingInfo {
/** 承运商侧可公开查询的轨迹页地址。 */ /** 承运商侧可公开查询的轨迹页地址。 */
private final String publicUrl; private final String publicUrl;
private final List<TrackEvent> events; private final List<TrackEvent> events;
/**
* 包裹实测重量(克);仓方未给为 null。
*
* <p>运去哪字段:{@code parcel.weight}(API 189,单位 oz,已换算成克)。</p>
*/
private final Double parcelWeightGrams;
/**
* 包裹实测长(厘米);仓方未给为 null。
*
* <p>运去哪字段:{@code parcel.length}(API 189,单位 inch,已换算成厘米)。</p>
*/
private final Double parcelLengthCm;
/** 包裹实测宽(厘米)。 */
private final Double parcelWidthCm;
/** 包裹实测高(厘米)。 */
private final Double parcelHeightCm;
/**
* 承运商承诺送达日期。
*
* <p>运去哪字段:{@code carrierDetail.guaranteedDeliveryDate}(API 189)。</p>
*/
private final String guaranteedDeliveryDate;
/**
* 始发地。
*
* <p>运去哪字段:{@code carrierDetail.originLocation}(API 189)。</p>
*/
private final String originLocation;
/**
* 目的地。
*
* <p>运去哪字段:{@code carrierDetail.destinationLocation}(API 189)。</p>
*/
private final String destinationLocation;
private TrackingInfo(Builder b) { private TrackingInfo(Builder b) {
this.trackingNumber = require(b.trackingNumber, "trackingNumber"); this.trackingNumber = require(b.trackingNumber, "trackingNumber");
@ -42,6 +76,13 @@ public final class TrackingInfo {
this.signedBy = b.signedBy; this.signedBy = b.signedBy;
this.publicUrl = b.publicUrl; this.publicUrl = b.publicUrl;
this.events = Collections.unmodifiableList(new ArrayList<TrackEvent>(b.events)); this.events = Collections.unmodifiableList(new ArrayList<TrackEvent>(b.events));
this.parcelWeightGrams = b.parcelWeightGrams;
this.parcelLengthCm = b.parcelLengthCm;
this.parcelWidthCm = b.parcelWidthCm;
this.parcelHeightCm = b.parcelHeightCm;
this.guaranteedDeliveryDate = b.guaranteedDeliveryDate;
this.originLocation = b.originLocation;
this.destinationLocation = b.destinationLocation;
} }
public static Builder builder() { public static Builder builder() {
@ -86,6 +127,41 @@ public final class TrackingInfo {
return events; return events;
} }
/** 包裹实测重量(克);仓方未给为 null。 */
public Double parcelWeightGrams() {
return parcelWeightGrams;
}
/** 包裹实测长(厘米);仓方未给为 null。 */
public Double parcelLengthCm() {
return parcelLengthCm;
}
/** 包裹实测宽(厘米);仓方未给为 null。 */
public Double parcelWidthCm() {
return parcelWidthCm;
}
/** 包裹实测高(厘米);仓方未给为 null。 */
public Double parcelHeightCm() {
return parcelHeightCm;
}
/** 承运商承诺送达日期;未给为 null。 */
public String guaranteedDeliveryDate() {
return guaranteedDeliveryDate;
}
/** 始发地;未给为 null。 */
public String originLocation() {
return originLocation;
}
/** 目的地;未给为 null。 */
public String destinationLocation() {
return destinationLocation;
}
private static String require(String v, String name) { private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) { if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank"); throw new IllegalArgumentException(name + " must not be blank");
@ -103,6 +179,13 @@ public final class TrackingInfo {
private String signedBy; private String signedBy;
private String publicUrl; private String publicUrl;
private final List<TrackEvent> events = new ArrayList<TrackEvent>(); private final List<TrackEvent> events = new ArrayList<TrackEvent>();
private Double parcelWeightGrams;
private Double parcelLengthCm;
private Double parcelWidthCm;
private Double parcelHeightCm;
private String guaranteedDeliveryDate;
private String originLocation;
private String destinationLocation;
public Builder trackingNumber(String v) { public Builder trackingNumber(String v) {
this.trackingNumber = v; this.trackingNumber = v;
@ -144,6 +227,41 @@ public final class TrackingInfo {
return this; return this;
} }
public Builder parcelWeightGrams(Double v) {
this.parcelWeightGrams = v;
return this;
}
public Builder parcelLengthCm(Double v) {
this.parcelLengthCm = v;
return this;
}
public Builder parcelWidthCm(Double v) {
this.parcelWidthCm = v;
return this;
}
public Builder parcelHeightCm(Double v) {
this.parcelHeightCm = v;
return this;
}
public Builder guaranteedDeliveryDate(String v) {
this.guaranteedDeliveryDate = v;
return this;
}
public Builder originLocation(String v) {
this.originLocation = v;
return this;
}
public Builder destinationLocation(String v) {
this.destinationLocation = v;
return this;
}
public Builder event(TrackEvent v) { public Builder event(TrackEvent v) {
this.events.add(v); this.events.add(v);
return this; return this;

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

@ -39,7 +39,7 @@ public final class WarehouseReturn {
/** 项目名称。 */ /** 项目名称。 */
private final String lineName; private final String lineName;
/** 附件。 */ /** 附件。 */
private final List<Attachment> attachments; private final List<WarehouseAttachment> attachments;
private WarehouseReturn(Builder b) { private WarehouseReturn(Builder b) {
this.returnRequestNo = require(b.returnRequestNo, "returnRequestNo"); this.returnRequestNo = require(b.returnRequestNo, "returnRequestNo");
@ -57,7 +57,7 @@ public final class WarehouseReturn {
this.inspectedQuantity = b.inspectedQuantity; this.inspectedQuantity = b.inspectedQuantity;
this.relatedProcessNo = b.relatedProcessNo; this.relatedProcessNo = b.relatedProcessNo;
this.lineName = b.lineName; this.lineName = b.lineName;
this.attachments = Collections.unmodifiableList(new ArrayList<Attachment>(b.attachments)); this.attachments = Collections.unmodifiableList(new ArrayList<WarehouseAttachment>(b.attachments));
} }
public static Builder builder() { public static Builder builder() {
@ -124,67 +124,11 @@ public final class WarehouseReturn {
return lineName; return lineName;
} }
/** 附件;不可变。 */ /** 附件;不可变。统一用 {@link WarehouseAttachment},与出库/入库一致。 */
public List<Attachment> attachments() { public List<WarehouseAttachment> attachments() {
return attachments; return attachments;
} }
/** 退货单附件。 */
public static final class Attachment {
private final String name;
private final String type;
private final String url;
private Attachment(Builder b) {
this.name = b.name;
this.type = b.type;
this.url = b.url;
}
public static Builder builder() {
return new Builder();
}
public String name() {
return name;
}
/** 仓方附件类型原值。 */
public String type() {
return type;
}
public String url() {
return url;
}
public static final class Builder {
private String name;
private String type;
private String url;
public Builder name(String v) {
this.name = v;
return this;
}
public Builder type(String v) {
this.type = v;
return this;
}
public Builder url(String v) {
this.url = v;
return this;
}
public Attachment build() {
return new Attachment(this);
}
}
}
/** 该单据来自哪家仓。 */ /** 该单据来自哪家仓。 */
public WarehouseProvider sourceProvider() { public WarehouseProvider sourceProvider() {
return sourceProvider; return sourceProvider;
@ -381,7 +325,7 @@ public final class WarehouseReturn {
private Integer inspectedQuantity; private Integer inspectedQuantity;
private String relatedProcessNo; private String relatedProcessNo;
private String lineName; private String lineName;
private final List<Attachment> attachments = new ArrayList<Attachment>(); private final List<WarehouseAttachment> attachments = new ArrayList<WarehouseAttachment>();
public Builder returnRequestNo(String v) { public Builder returnRequestNo(String v) {
this.returnRequestNo = v; this.returnRequestNo = v;
@ -465,7 +409,7 @@ public final class WarehouseReturn {
return this; return this;
} }
public Builder attachment(Attachment v) { public Builder attachment(WarehouseAttachment v) {
this.attachments.add(v); this.attachments.add(v);
return this; return this;
} }

108
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java

@ -56,6 +56,20 @@ public final class YqnInboundMapper {
req.containerNo = cmd.containerNo(); req.containerNo = cmd.containerNo();
req.remark = cmd.remark(); req.remark = cmd.remark();
// openapi 只支持自发头程;给 1 会被仓拒绝,这里前置挡掉 // openapi 只支持自发头程;给 1 会被仓拒绝,这里前置挡掉
req.lineCode = cmd.lineName();
req.shipmentId = cmd.shipmentId();
req.referenceId = cmd.referenceId();
req.transportType = cmd.transportType();
req.deliveryType = cmd.deliveryType();
req.goodsSize = cmd.containerSize();
req.carrier = cmd.carrierCode();
req.socFlag = flagOf(cmd.socContainer());
req.palletFlag = flagOf(cmd.palletized());
if (!cmd.transportOrderNos().isEmpty()) {
// 运去哪这个字段是「逗号分割的字符串」,不是数组
req.tmsNos = join(cmd.transportOrderNos());
}
req.attachInfoItems = toAttachItems(cmd.attachments());
req.logisticsType = 0; req.logisticsType = 0;
req.productItems = toProductItems(cmd.lines()); req.productItems = toProductItems(cmd.lines());
@ -160,6 +174,46 @@ public final class YqnInboundMapper {
// ------------------------------------------------------------------ 查询 // ------------------------------------------------------------------ 查询
/** 附件:运去哪要求 type 用英文枚举名(ShippingLabel / PackingList / BOL / Other)。 */
private static List<YqnCreateInboundDtos.CreateInboundPlanRequest.InboundAttachItem> toAttachItems(
List<common.ecommerce.warehouse.model.WarehouseAttachment> attachments) {
if (attachments == null || attachments.isEmpty()) {
return null;
}
List<YqnCreateInboundDtos.CreateInboundPlanRequest.InboundAttachItem> out =
new ArrayList<YqnCreateInboundDtos.CreateInboundPlanRequest.InboundAttachItem>(
attachments.size());
for (common.ecommerce.warehouse.model.WarehouseAttachment a : attachments) {
YqnCreateInboundDtos.CreateInboundPlanRequest.InboundAttachItem item =
new YqnCreateInboundDtos.CreateInboundPlanRequest.InboundAttachItem();
item.name = a.name();
item.url = a.url();
// 仓方原值优先;调用方给了别的类型就原样透传,让仓方自己判断
item.type = a.type();
item.remark = a.remark();
out.add(item);
}
return out;
}
private static String join(List<String> values) {
StringBuilder sb = new StringBuilder();
for (String v : values) {
if (v == null || v.trim().isEmpty()) {
continue;
}
if (sb.length() > 0) {
sb.append(',');
}
sb.append(v.trim());
}
return sb.length() == 0 ? null : sb.toString();
}
private static Integer flagOf(Boolean flag) {
return flag == null ? null : (flag ? 1 : 0);
}
/** 入库计划详情 → 统一入库单(API 101)。 */ /** 入库计划详情 → 统一入库单(API 101)。 */
public static InboundOrder toOrder(YqnInboundPlanDtos.InboundPlanInfo info, String warehouseCode, ZoneId zone) { public static InboundOrder toOrder(YqnInboundPlanDtos.InboundPlanInfo info, String warehouseCode, ZoneId zone) {
InboundOrder.Builder builder = InboundOrder.builder() InboundOrder.Builder builder = InboundOrder.builder()
@ -186,6 +240,14 @@ public final class YqnInboundMapper {
.packedQuantity(intOf(info.packedQty)) .packedQuantity(intOf(info.packedQty))
.receivedQuantity(intOf(info.receivedQty)) .receivedQuantity(intOf(info.receivedQty))
.packingLabelUrl(info.packingLabelUrl) .packingLabelUrl(info.packingLabelUrl)
.lineName(info.lineName)
.shipmentId(info.shipmentId)
.referenceId(info.referenceId)
.shipmentNo(info.shipmentNo)
.goodsType(info.goodsType)
.actualShippedAt(parseDate(info.actualShipDate, zone))
.cartonTotalWeightKg(info.cartonTotalWeight)
.cartonTotalVolumeCbm(info.cartonTotalVolume)
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN); .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN);
for (common.ecommerce.warehouse.model.InboundOrderBatch batch : toOrderBatches(info.batchInfo)) { for (common.ecommerce.warehouse.model.InboundOrderBatch batch : toOrderBatches(info.batchInfo)) {
builder.batch(batch); builder.batch(batch);
@ -193,6 +255,9 @@ public final class YqnInboundMapper {
for (common.ecommerce.warehouse.model.InboundOrderBox box : toOrderBoxes(info.boxInfo)) { for (common.ecommerce.warehouse.model.InboundOrderBox box : toOrderBoxes(info.boxInfo)) {
builder.box(box); builder.box(box);
} }
for (common.ecommerce.warehouse.model.InboundOrder.ContainerInfo c : toContainers(info)) {
builder.container(c);
}
return builder.build(); return builder.build();
} }
@ -257,6 +322,49 @@ public final class YqnInboundMapper {
return out; return out;
} }
/** 柜型信息:运去哪按 4 类柜型给「数量 + 柜号」,逐类映射。 */
private static List<common.ecommerce.warehouse.model.InboundOrder.ContainerInfo> toContainers(
YqnInboundPlanDtos.InboundPlanInfo info) {
List<common.ecommerce.warehouse.model.InboundOrder.ContainerInfo> out =
new java.util.ArrayList<common.ecommerce.warehouse.model.InboundOrder.ContainerInfo>();
addContainer(out, common.ecommerce.warehouse.model.InboundOrder.ContainerType.GP20,
info.gpQuantity20, info.gpCartonNo20, "gpQuantity20");
addContainer(out, common.ecommerce.warehouse.model.InboundOrder.ContainerType.GP40,
info.gpQuantity40, info.gpCartonNo40, "gpQuantity40");
addContainer(out, common.ecommerce.warehouse.model.InboundOrder.ContainerType.HQ40,
info.hqQuantity40, info.hqCartonNo40, "hqQuantity40");
addContainer(out, common.ecommerce.warehouse.model.InboundOrder.ContainerType.HQ45,
info.hqQuantity45, info.hqCartonNo45, "hqQuantity45");
return out;
}
private static void addContainer(
List<common.ecommerce.warehouse.model.InboundOrder.ContainerInfo> out,
common.ecommerce.warehouse.model.InboundOrder.ContainerType type,
String quantity, String containerNo, String rawType) {
if ((quantity == null || quantity.trim().isEmpty())
&& (containerNo == null || containerNo.trim().isEmpty())) {
return;
}
out.add(common.ecommerce.warehouse.model.InboundOrder.ContainerInfo.builder()
.type(type)
.quantity(intOrNull(quantity))
.containerNo(containerNo)
.rawType(rawType)
.build());
}
private static Integer intOrNull(String v) {
if (v == null || v.trim().isEmpty()) {
return null;
}
try {
return Integer.valueOf(v.trim());
} catch (NumberFormatException e) {
return null;
}
}
private static List<InboundOrderLine> toOrderLines( private static List<InboundOrderLine> toOrderLines(
List<YqnInboundPlanDtos.InboundPlanInfo.PlanProductDetail> details, ZoneId zone) { List<YqnInboundPlanDtos.InboundPlanInfo.PlanProductDetail> details, ZoneId zone) {
if (details == null || details.isEmpty()) { if (details == null || details.isEmpty()) {

45
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java

@ -52,6 +52,19 @@ public final class YqnProductMapper {
req.customNameEn = product.declaredNameEn(); req.customNameEn = product.declaredNameEn();
req.link = product.link(); req.link = product.link();
req.remark = product.remark(); req.remark = product.remark();
req.expirationControl = flagOf(product.expirationControl());
req.expirationDate = product.expirationDays();
req.packedQty = product.packedQuantity();
req.packedLength = product.packedLengthCm();
req.packedWidth = product.packedWidthCm();
req.packedHeight = product.packedHeightCm();
req.packedWeight = product.packedWeightGrams();
req.isInsuranceFlag = insuranceFlag(product.insured());
if (product.insuranceFee() != null) {
req.isInsuranceRate = product.insuranceFee().amount().doubleValue();
}
req.snMgmtMode = product.snManagementMode();
req.lotControl = lotControl(product);
Money cost = product.cost(); Money cost = product.cost();
if (cost != null) { if (cost != null) {
@ -77,11 +90,43 @@ public final class YqnProductMapper {
* <p>三项没有整组给时返回 null(不发 customs), * <p>三项没有整组给时返回 null(不发 customs),
* {@link WarehouseProduct} 已在构造期挡掉「只给一半」的情况。</p> * {@link WarehouseProduct} 已在构造期挡掉「只给一半」的情况。</p>
*/ */
/** 0/1 开关 → 运去哪的 Integer 形态;null 透传(不传)。 */
private static Integer flagOf(Boolean flag) {
return flag == null ? null : (flag ? 1 : 0);
}
/** 保价开关 → 运去哪的 {@code Y / N};null 不传。 */
private static String insuranceFlag(Boolean insured) {
return insured == null ? null : (insured ? "Y" : "N");
}
/** 批次管理;未开启时不传。 */
private static YqnProductDtos.SaveProductRequest.LotControl lotControl(
common.ecommerce.warehouse.capability.WarehouseProduct product) {
if (product.lotControlEnabled() == null && product.lotAttributeCodes().isEmpty()) {
return null;
}
YqnProductDtos.SaveProductRequest.LotControl lot = new YqnProductDtos.SaveProductRequest.LotControl();
lot.lotEnabled = flagOf(product.lotControlEnabled());
if (!product.lotAttributeCodes().isEmpty()) {
lot.lotAttrCodeList = new ArrayList<String>(product.lotAttributeCodes());
}
return lot;
}
static List<YqnProductDtos.SaveProductRequest.Customs> toCustoms(Money declaredValue, static List<YqnProductDtos.SaveProductRequest.Customs> toCustoms(Money declaredValue,
String hsCode, String countryCode) { String hsCode, String countryCode) {
if (declaredValue == null || isBlank(hsCode) || isBlank(countryCode)) { if (declaredValue == null || isBlank(hsCode) || isBlank(countryCode)) {
return null; return null;
} }
// 运去哪海关只接受 USD。之前无脑把申报额贴成 USD,非美元申报会被静默算错,
// 这里直接拒绝,由调用方换算后再传。
String currency = declaredValue.currency().getCurrencyCode();
if (!CUSTOMS_CURRENCY.equalsIgnoreCase(currency)) {
throw new IllegalArgumentException(
"yqn customs declared value must be " + CUSTOMS_CURRENCY
+ ", got " + currency + "; convert before calling");
}
YqnProductDtos.SaveProductRequest.Customs customs = new YqnProductDtos.SaveProductRequest.Customs(); YqnProductDtos.SaveProductRequest.Customs customs = new YqnProductDtos.SaveProductRequest.Customs();
customs.countryCode = countryCode.trim().toUpperCase(Locale.ROOT); customs.countryCode = countryCode.trim().toUpperCase(Locale.ROOT);
customs.customCode = hsCode.trim(); customs.customCode = hsCode.trim();

2
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java

@ -133,7 +133,7 @@ public final class YqnReturnMapper {
if (info.orderAttachesItems != null) { if (info.orderAttachesItems != null) {
for (YqnSaleReturnPlanDtos.SaleReturnPlanInfo.ReturnAttach attach for (YqnSaleReturnPlanDtos.SaleReturnPlanInfo.ReturnAttach attach
: info.orderAttachesItems) { : info.orderAttachesItems) {
builder.attachment(WarehouseReturn.Attachment.builder() builder.attachment(common.ecommerce.warehouse.model.WarehouseAttachment.builder()
.name(attach.filename) .name(attach.filename)
.type(attach.attachType) .type(attach.attachType)
.url(attach.fileurl) .url(attach.fileurl)

30
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java

@ -43,7 +43,12 @@ public final class YqnTrackingMapper {
.statusDetail(track.statusDetail) .statusDetail(track.statusDetail)
.estimatedDeliveryAt(parseTime(track.estDeliveryDate, zone)) .estimatedDeliveryAt(parseTime(track.estDeliveryDate, zone))
.signedBy(track.signedBy) .signedBy(track.signedBy)
.publicUrl(track.publicUrl); .publicUrl(track.publicUrl)
.guaranteedDeliveryDate(carrierDetail == null ? null
: carrierDetail.guaranteedDeliveryDate)
.originLocation(carrierDetail == null ? null : carrierDetail.originLocation)
.destinationLocation(carrierDetail == null ? null : carrierDetail.destinationLocation);
addParcel(builder, track.parcel);
List<YqnTrackingDtos.ShipmentTrack.TrackDetail> details = track.trackingDetails; List<YqnTrackingDtos.ShipmentTrack.TrackDetail> details = track.trackingDetails;
if (details != null) { if (details != null) {
@ -54,6 +59,29 @@ public final class YqnTrackingMapper {
return builder.build(); return builder.build();
} }
/**
* 包裹实重实尺:运去哪固定给 oz / inch,统一换算成 g / cm 后再落模型,
* 避免宿主拿到不同仓的包裹尺寸还要各自换算。
*/
private static void addParcel(TrackingInfo.Builder builder,
YqnTrackingDtos.ShipmentTrack.Parcel parcel) {
if (parcel == null) {
return;
}
builder.parcelWeightGrams(ouncesToGrams(parcel.weight))
.parcelLengthCm(inchesToCm(parcel.length))
.parcelWidthCm(inchesToCm(parcel.width))
.parcelHeightCm(inchesToCm(parcel.height));
}
private static Double ouncesToGrams(Double ounces) {
return ounces == null ? null : ounces * 28.349523125;
}
private static Double inchesToCm(Double inches) {
return inches == null ? null : inches * 2.54;
}
/** 只取节点明细。 */ /** 只取节点明细。 */
public static List<TrackEvent> toTrackEvents(YqnTrackingDtos.ShipmentTrack track, String requestedTrackingNo, public static List<TrackEvent> toTrackEvents(YqnTrackingDtos.ShipmentTrack track, String requestedTrackingNo,
ZoneId zone) { ZoneId zone) {

263
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnExtraFieldsTest.java

@ -0,0 +1,263 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.model.WarehouseAttachment;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.yqn.YqnConstants;
import org.junit.jupiter.api.Test;
import java.math.BigDecimal;
import java.time.Clock;
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneOffset;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 本轮补齐的「仓方有、模型没有」字段:入库请求/响应、商品、轨迹。
*/
class YqnExtraFieldsTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-11T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US",
WarehouseConnection.of(YqnConstants.PR_BASE_URL,
ChannelSecret.builder().appSecret("key-1").build()),
"req-extra", CLOCK);
}
// ------------------------------------------------------------ 入库请求
private static InboundCommand inboundCommand() {
return InboundCommand.builder()
.inboundRequestNo("OMS-IN-1")
.inventoryType(0)
.lineName("项目A")
.shipmentId("FBA15ABC")
.referenceId("REF-1")
.transportType(0)
.deliveryType(1)
.containerSize(2)
.transportOrderNo("TMS-1")
.transportOrderNo("TMS-2")
.carrierCode(2)
.socContainer(true)
.palletized(false)
.attachment(WarehouseAttachment.builder()
.name("装箱单.pdf").type("PackingList").url("https://f/p.pdf").build())
.line(common.ecommerce.warehouse.model.InboundLine.builder()
.omsSku("DM1").quantity(10).build())
.build();
}
@Test
void inboundRequestSendsNewFields() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_CREATE, req -> Responses.ok(
"{\"code\":200,\"data\":{\"inboundPlanOrderNo\":\"IP1\"}}"));
new YqnAdapter(transport, new JacksonJsonCodec()).create(ctx(), inboundCommand());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"lineCode\":\"项目A\""), body);
assertTrue(body.contains("\"shipmentId\":\"FBA15ABC\""), body);
assertTrue(body.contains("\"referenceId\":\"REF-1\""), body);
assertTrue(body.contains("\"transportType\":0"), body);
assertTrue(body.contains("\"deliveryType\":1"), body);
assertTrue(body.contains("\"goodsSize\":2"), body);
// 运去哪是逗号分割的字符串
assertTrue(body.contains("\"tmsNos\":\"TMS-1,TMS-2\""), body);
assertTrue(body.contains("\"carrier\":2"), body);
assertTrue(body.contains("\"socFlag\":1"), body);
assertTrue(body.contains("\"palletFlag\":0"), body);
assertTrue(body.contains("\"attachInfoItems\""), body);
assertTrue(body.contains("\"type\":\"PackingList\""), body);
// openapi 只支持自发头程
assertTrue(body.contains("\"logisticsType\":0"), body);
}
// ------------------------------------------------------------ 入库响应
@Test
void inboundResponseMapsNewFields() {
String body = "{\"code\":\"200\",\"data\":{"
+ "\"orgWarehouseCode\":\"RF_NY_US\",\"inventoryType\":\"0\","
+ "\"inboundPlanOrderNo\":\"IP1\",\"sourceNo\":\"S1\","
+ "\"inboundPlanOrderStatus\":\"25\","
+ "\"lineName\":\"项目A\",\"shipmentId\":\"FBA15ABC\","
+ "\"referenceId\":\"REF-1\",\"shipmentNo\":\"1Z999\","
+ "\"goodsType\":\"普货\",\"actualShipDate\":\"2026-11-12 10:00:00\","
+ "\"cartonTotalWeight\":118.5,\"cartonTotalVolume\":1.75,"
+ "\"gpQuantity20\":\"1\",\"gpCartonNo20\":\"GP-1\","
+ "\"hqQuantity40\":\"2\",\"hqCartonNo40\":\"HQ-1\"}}";
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(body));
InboundOrder order = new YqnAdapter(transport, new JacksonJsonCodec()).get(ctx(), "S1");
assertEquals("项目A", order.lineName());
assertEquals("FBA15ABC", order.shipmentId());
assertEquals("REF-1", order.referenceId());
assertEquals("1Z999", order.shipmentNo());
assertEquals("普货", order.goodsType());
assertEquals(Instant.parse("2026-11-12T10:00:00Z"), order.actualShippedAt());
assertEquals(Double.valueOf(118.5), order.cartonTotalWeightKg());
assertEquals(Double.valueOf(1.75), order.cartonTotalVolumeCbm());
// 只映射有值的柜型
assertEquals(2, order.containers().size());
assertEquals(InboundOrder.ContainerType.GP20, order.containers().get(0).type());
assertEquals(Integer.valueOf(1), order.containers().get(0).quantity());
assertEquals("GP-1", order.containers().get(0).containerNo());
assertEquals(InboundOrder.ContainerType.HQ40, order.containers().get(1).type());
assertEquals("gpQuantity20", order.containers().get(0).rawType());
}
/** 没有柜型信息时不产空对象。 */
@Test
void noContainersWhenAbsent() {
String body = "{\"code\":\"200\",\"data\":{\"orgWarehouseCode\":\"W\","
+ "\"inventoryType\":\"0\",\"inboundPlanOrderNo\":\"IP1\","
+ "\"sourceNo\":\"S1\",\"inboundPlanOrderStatus\":\"0\"}}";
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_INBOUND_GET, req -> Responses.ok(body));
assertTrue(new YqnAdapter(transport, new JacksonJsonCodec())
.get(ctx(), "S1").containers().isEmpty());
}
// ------------------------------------------------------------ 商品
private static WarehouseProduct.Builder product() {
return WarehouseProduct.builder()
.omsSku("DM1").name("测试").nameEn("Test")
.packingType(1).lengthCm(10).widthCm(8).heightCm(6).weightGrams(500);
}
@Test
void productSendsNewFields() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\"}"));
new YqnAdapter(transport, new JacksonJsonCodec()).createOrUpdate(ctx(),
product().expirationControl(true).expirationDays(365)
.packedQuantity(24).packedLengthCm(40.0).packedWeightGrams(1200.0)
.insured(true).insuranceFee(Money.of("2.50", "USD"))
.snManagementMode(1).lotControlEnabled(true)
.lotAttributeCode("ProductionDateNumber")
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"expirationControl\":1"), body);
assertTrue(body.contains("\"expirationDate\":365"), body);
assertTrue(body.contains("\"packedQty\":24"), body);
assertTrue(body.contains("\"packedLength\":40.0"), body);
assertTrue(body.contains("\"packedWeight\":1200.0"), body);
assertTrue(body.contains("\"isInsuranceFlag\":\"Y\""), body);
assertTrue(body.contains("\"isInsuranceRate\":2.5"), body);
assertTrue(body.contains("\"snMgmtMode\":1"), body);
assertTrue(body.contains("\"lotEnabled\":1"), body);
assertTrue(body.contains("ProductionDateNumber"), body);
}
@Test
void productOmitsUnsetOptionalFields() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\"}"));
new YqnAdapter(transport, new JacksonJsonCodec()).createOrUpdate(ctx(), product().build());
String body = transport.lastDataRequest().body();
assertTrue(!body.contains("expirationControl"), body);
assertTrue(!body.contains("lotControl"), body);
assertTrue(!body.contains("isInsuranceFlag"), body);
}
/** 海关只接受 USD,非美元直接拒绝而不是贴错币种。 */
@Test
void customsRejectsNonUsd() {
RecordingTransport transport = RecordingTransport.create();
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter.createOrUpdate(ctx(), product()
.countryOfOrigin("US").hsCode("1234567890")
.declaredValue(Money.of("10.00", "CNY"))
.build()));
assertTrue(ex.getMessage().contains("USD"), ex.getMessage());
}
@Test
void customsAcceptsUsd() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\"}"));
new YqnAdapter(transport, new JacksonJsonCodec()).createOrUpdate(ctx(), product()
.countryOfOrigin("US").hsCode("1234567890")
.declaredValue(Money.of("10.00", "USD")).build());
assertTrue(transport.lastDataRequest().body().contains("\"importDeclaredCurrency\":\"USD\""));
}
// ------------------------------------------------------------ 轨迹
@Test
void trackingMapsParcelWithUnitConversion() {
String body = "{\"code\":1,\"message\":\"ok\",\"data\":{"
+ "\"trackingCode\":\"TRK1\",\"carrier\":\"FEDEX\",\"status\":\"DELIVERED\","
+ "\"parcel\":{\"weight\":1.0,\"length\":10.0,\"width\":8.0,\"height\":6.0,"
+ "\"weightUnits\":\"oz\",\"packageDimensionsUnits\":\"inch\"},"
+ "\"carrierDetail\":{\"service\":\"FedEx_Ground\","
+ "\"guaranteedDeliveryDate\":\"2026-11-15\","
+ "\"originLocation\":\"Newark,NJ\",\"destinationLocation\":\"NY,NY\"}}}";
RecordingTransport transport = RecordingTransport.create()
.route("/api/v2/orderShipment/track/TRK1", req -> Responses.ok(body));
WarehouseContext trackingCtx = WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN,
"RF_NY_US", WarehouseConnection.of(YqnConstants.PR_BASE_URL,
YqnConstants.AUX_BASE_URL_PR, ChannelSecret.builder().appSecret("k").build()),
"req-track", CLOCK);
TrackingInfo info = new YqnAdapter(transport, new JacksonJsonCodec())
.trackShipment(trackingCtx, "TRK1");
// oz → g:1 oz ≈ 28.3495 g
assertEquals(28.349523125, info.parcelWeightGrams(), 0.000001);
// inch → cm:10 inch = 25.4 cm
assertEquals(25.4, info.parcelLengthCm(), 0.000001);
assertEquals(20.32, info.parcelWidthCm(), 0.000001);
assertEquals(15.24, info.parcelHeightCm(), 0.000001);
assertEquals("2026-11-15", info.guaranteedDeliveryDate());
assertEquals("Newark,NJ", info.originLocation());
assertEquals("NY,NY", info.destinationLocation());
}
@Test
void trackingWithoutParcelIsSafe() {
String body = "{\"code\":1,\"data\":{\"trackingCode\":\"TRK1\",\"carrier\":\"FEDEX\"}}";
RecordingTransport transport = RecordingTransport.create()
.route("/api/v2/orderShipment/track/TRK1", req -> Responses.ok(body));
WarehouseContext trackingCtx = WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN,
"RF_NY_US", WarehouseConnection.of(YqnConstants.PR_BASE_URL,
YqnConstants.AUX_BASE_URL_PR, ChannelSecret.builder().appSecret("k").build()),
"req-track", CLOCK);
TrackingInfo info = new YqnAdapter(transport, new JacksonJsonCodec())
.trackShipment(trackingCtx, "TRK1");
assertEquals(null, info.parcelWeightGrams());
assertEquals(null, info.guaranteedDeliveryDate());
}
}

2
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnReturnQueryTest.java

@ -117,7 +117,7 @@ class YqnReturnQueryTest {
@Test @Test
void mapsAttachments() { void mapsAttachments() {
List<WarehouseReturn.Attachment> attachments = query(FULL_BODY).attachments(); List<common.ecommerce.warehouse.model.WarehouseAttachment> attachments = query(FULL_BODY).attachments();
assertEquals(1, attachments.size()); assertEquals(1, attachments.size());
assertEquals("凭证.pdf", attachments.get(0).name()); assertEquals("凭证.pdf", attachments.get(0).name());

Loading…
Cancel
Save