From eea316163468fec8fc6dfd505a87b492a1b45e83 Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Mon, 9 Nov 2026 16:40:30 +0800
Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8C=89=20API=2097=20=E5=AF=B9?=
=?UTF-8?q?=E6=8E=A5=E5=88=9B=E5=BB=BA=E5=85=A5=E5=BA=93=E8=AE=A1=E5=88=92?=
=?UTF-8?q?=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 路径 /inbound/inboundCreate → /v1/inbound/createInboundPlan
- 响应回 data.inboundPlanOrderNo(字符串),直接作 providerInboundId
入库模型按文档重写,补齐此前缺的维度:
- InboundCommand 补 inventoryType(必填) / factoryBatchNo / currency /
三个日期 / 原产地 / 发货方四项 / 集装箱号 / 装箱 / 批次
- InboundLine 的 boxNo 换成 cost(采购成本影响仓侧库存成本)
- 新增 InboundCarton(箱规 + sid 归并物理箱)、InboundBatch(批次属性
开放式 key/value,各仓支持的 key 不同,不做枚举)
两条本地校验:
- 集装箱号必须是 4 位大写字母 + 7 位数字,传错仓侧直接拒
- expectArriveDate 不能早于 estimateArriveDate
两个显式放弃:
- logisticsType 固定 0:文档写明运去哪头程只支持 web 端,openapi 不开放
- 入库单查询未接:文档只给了创建接口,get/query 抛
UnsupportedCapability,不返回空页
Co-Authored-By: Claude
---
.../ecommerce/warehouse/model/InboundBatch.java | 115 +++++++++++
.../ecommerce/warehouse/model/InboundCarton.java | 149 ++++++++++++++
.../ecommerce/warehouse/model/InboundCommand.java | 215 +++++++++++++++++++--
.../ecommerce/warehouse/model/InboundLine.java | 25 ++-
.../java/common/ecommerce/yqn/YqnConstants.java | 4 +-
.../common/ecommerce/yqn/adapter/YqnAdapter.java | 41 +++-
.../ecommerce/yqn/adapter/YqnInboundMapper.java | 151 +++++++++++++++
.../java/common/ecommerce/yqn/dto/YqnDtos.java | 124 ++++++++++++
8 files changed, 797 insertions(+), 27 deletions(-)
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundBatch.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCarton.java
create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundBatch.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundBatch.java
new file mode 100644
index 0000000..b7503b7
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundBatch.java
@@ -0,0 +1,115 @@
+package common.ecommerce.warehouse.model;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 入库批次明细。
+ *
+ * 批次属性是「key + value」的开放式集合,各仓支持的 key 不同
+ * (运去哪用 {@code ProductionDateNumber}、{@code BatchNumber}、{@code InboundTime} 等),
+ * 所以这里不做枚举,交给调用方按仓方文档填。
+ */
+public final class InboundBatch {
+
+ private final String providerSku;
+ /** 箱唛号;正式箱唛规则由仓方约束(如至少 7 位、末四位为数字)。 */
+ private final String cartonNo;
+ private final int quantity;
+ private final List params;
+
+ private InboundBatch(Builder b) {
+ this.providerSku = require(b.providerSku, "providerSku");
+ this.cartonNo = b.cartonNo;
+ if (b.quantity <= 0) {
+ throw new IllegalArgumentException("quantity must be positive");
+ }
+ this.quantity = b.quantity;
+ if (b.params.isEmpty()) {
+ throw new IllegalArgumentException("batch params must not be empty");
+ }
+ this.params = Collections.unmodifiableList(new ArrayList(b.params));
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public String providerSku() {
+ return providerSku;
+ }
+
+ public String cartonNo() {
+ return cartonNo;
+ }
+
+ public int quantity() {
+ return quantity;
+ }
+
+ public List params() {
+ return params;
+ }
+
+ private static String require(String v, String n) {
+ if (v == null || v.trim().isEmpty()) {
+ throw new IllegalArgumentException(n + " must not be blank");
+ }
+ return v.trim();
+ }
+
+ /** 一条批次属性。 */
+ public static final class BatchParam {
+
+ private final String key;
+ private final String value;
+
+ public BatchParam(String key, String value) {
+ if (key == null || key.trim().isEmpty()) {
+ throw new IllegalArgumentException("batchAttriKey must not be blank");
+ }
+ this.key = key.trim();
+ this.value = value;
+ }
+
+ public String key() {
+ return key;
+ }
+
+ public String value() {
+ return value;
+ }
+ }
+
+ public static final class Builder {
+ private String providerSku;
+ private String cartonNo;
+ private int quantity;
+ private final List params = new ArrayList();
+
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ public Builder cartonNo(String v) {
+ this.cartonNo = v;
+ return this;
+ }
+
+ public Builder quantity(int v) {
+ this.quantity = v;
+ return this;
+ }
+
+ public Builder param(String key, String value) {
+ this.params.add(new BatchParam(key, value));
+ return this;
+ }
+
+ public InboundBatch build() {
+ return new InboundBatch(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCarton.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCarton.java
new file mode 100644
index 0000000..8f15269
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCarton.java
@@ -0,0 +1,149 @@
+package common.ecommerce.warehouse.model;
+
+/**
+ * 入库装箱信息(箱规)。
+ *
+ * {@code cartonNo} 是箱码,仓侧必填且唯一。{@code sid} 用来归并同一个物理箱:
+ * 一箱多 SKU 时会拆成多行,同 {@code sid} 的行属于同一箱。
+ *
+ * 尺寸单位 cm、重量单位 g,与仓库域其它模型一致。
+ */
+public final class InboundCarton {
+
+ private final String providerSku;
+ private final int quantity;
+ /** 装箱入数。 */
+ private final int cartonQuantity;
+ /** 箱码;必填。 */
+ private final String cartonNo;
+ /** 箱序标识;一箱多 SKU 时用来归并同一物理箱。 */
+ private final String sid;
+ private final double weightGrams;
+ private final double lengthCm;
+ private final double widthCm;
+ private final double heightCm;
+
+ private InboundCarton(Builder b) {
+ this.providerSku = require(b.providerSku, "providerSku");
+ if (b.quantity <= 0) {
+ throw new IllegalArgumentException("quantity must be positive");
+ }
+ this.quantity = b.quantity;
+ this.cartonQuantity = b.cartonQuantity;
+ this.cartonNo = require(b.cartonNo, "cartonNo");
+ this.sid = b.sid;
+ this.weightGrams = b.weightGrams;
+ this.lengthCm = b.lengthCm;
+ this.widthCm = b.widthCm;
+ this.heightCm = b.heightCm;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public String providerSku() {
+ return providerSku;
+ }
+
+ public int quantity() {
+ return quantity;
+ }
+
+ /** 装箱入数;未指定为 0。 */
+ public int cartonQuantity() {
+ return cartonQuantity;
+ }
+
+ public String cartonNo() {
+ return cartonNo;
+ }
+
+ public String sid() {
+ return sid;
+ }
+
+ public double weightGrams() {
+ return weightGrams;
+ }
+
+ public double lengthCm() {
+ return lengthCm;
+ }
+
+ public double widthCm() {
+ return widthCm;
+ }
+
+ public double heightCm() {
+ return heightCm;
+ }
+
+ private static String require(String v, String n) {
+ if (v == null || v.trim().isEmpty()) {
+ throw new IllegalArgumentException(n + " must not be blank");
+ }
+ return v.trim();
+ }
+
+ public static final class Builder {
+ private String providerSku;
+ private int quantity;
+ private int cartonQuantity;
+ private String cartonNo;
+ private String sid;
+ private double weightGrams;
+ private double lengthCm;
+ private double widthCm;
+ private double heightCm;
+
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ public Builder quantity(int v) {
+ this.quantity = v;
+ return this;
+ }
+
+ public Builder cartonQuantity(int v) {
+ this.cartonQuantity = v;
+ return this;
+ }
+
+ public Builder cartonNo(String v) {
+ this.cartonNo = v;
+ return this;
+ }
+
+ public Builder sid(String v) {
+ this.sid = v;
+ return this;
+ }
+
+ public Builder weightGrams(double v) {
+ this.weightGrams = v;
+ return this;
+ }
+
+ public Builder lengthCm(double v) {
+ this.lengthCm = v;
+ return this;
+ }
+
+ public Builder widthCm(double v) {
+ this.widthCm = v;
+ return this;
+ }
+
+ public Builder heightCm(double v) {
+ this.heightCm = v;
+ return this;
+ }
+
+ public InboundCarton build() {
+ return new InboundCarton(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java
index 0b19ce5..92bae1f 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java
@@ -1,17 +1,44 @@
package common.ecommerce.warehouse.model;
+import java.time.LocalDate;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
-/** 头程入库创建命令。写操作,幂等键是 {@link #inboundRequestNo()}。 */
+/**
+ * 入库计划创建命令。写操作,幂等键是 {@link #inboundRequestNo()}(仓方的来源单号)。
+ *
+ * 必填:单号、仓、库存类型、至少一条商品行。装箱、批次、附件都是可选的——
+ * 仓会在收货时按实际情况清点,但给了就必须自洽(一箱多 SKU 要用 sid 归并)。
+ */
public final class InboundCommand {
private final String inboundRequestNo;
private final String warehouseId;
- private final String type;
- private final List lines;
+ /** 库存类型:0 正常 / 1 不可售。 */
+ private final int inventoryType;
+ /** 工厂批次号。 */
+ private final String factoryBatchNo;
+ /** 单据币种;影响仓侧库存成本计算,null 时按 USD。 */
+ private final String currency;
+ /** 预计到仓日期。 */
+ private final LocalDate estimateArriveDate;
+ /** 期望到仓日期。 */
+ private final LocalDate expectArriveDate;
+ /** 预计发运日期。 */
+ private final LocalDate predictionShipDate;
+ /** 原产地,ISO 3166-1 alpha-2。 */
+ private final String originCountry;
+ private final String shipperName;
+ private final String shipperAddress;
+ private final String shipperContact;
+ private final String shipperPhone;
+ /** 集装箱号,4 位大写字母 + 7 位数字。 */
+ private final String containerNo;
private final String remark;
+ private final List lines;
+ private final List cartons;
+ private final List batches;
private InboundCommand(Builder b) {
if (b.inboundRequestNo == null || b.inboundRequestNo.trim().isEmpty()) {
@@ -19,44 +46,136 @@ public final class InboundCommand {
}
this.inboundRequestNo = b.inboundRequestNo.trim();
this.warehouseId = b.warehouseId;
- this.type = b.type;
+ if (b.inventoryType != 0 && b.inventoryType != 1) {
+ throw new IllegalArgumentException("inventoryType must be 0 (normal) or 1 (unsellable)");
+ }
+ this.inventoryType = b.inventoryType;
+ this.factoryBatchNo = b.factoryBatchNo;
+ this.currency = b.currency;
+ if (b.estimateArriveDate != null && b.expectArriveDate != null
+ && b.expectArriveDate.isBefore(b.estimateArriveDate)) {
+ throw new IllegalArgumentException(
+ "expectArriveDate must not be earlier than estimateArriveDate");
+ }
+ this.estimateArriveDate = b.estimateArriveDate;
+ this.expectArriveDate = b.expectArriveDate;
+ this.predictionShipDate = b.predictionShipDate;
+ this.originCountry = b.originCountry;
+ this.shipperName = b.shipperName;
+ this.shipperAddress = b.shipperAddress;
+ this.shipperContact = b.shipperContact;
+ this.shipperPhone = b.shipperPhone;
+ this.containerNo = b.containerNo;
+ this.remark = b.remark;
if (b.lines.isEmpty()) {
throw new IllegalArgumentException("lines must not be empty");
}
this.lines = Collections.unmodifiableList(new ArrayList(b.lines));
- this.remark = b.remark;
+ this.cartons = Collections.unmodifiableList(new ArrayList(b.cartons));
+ this.batches = Collections.unmodifiableList(new ArrayList(b.batches));
}
public static Builder builder() {
return new Builder();
}
+ /** OMS 入库单号;同时作为仓方的来源单号与幂等键。 */
public String inboundRequestNo() {
return inboundRequestNo;
}
+ /** 仓侧仓 code;null 时用账户配置的仓。 */
public String warehouseId() {
return warehouseId;
}
- public String type() {
- return type;
+ /** 0 正常 / 1 不可售。 */
+ public int inventoryType() {
+ return inventoryType;
}
- public List lines() {
- return lines;
+ public String factoryBatchNo() {
+ return factoryBatchNo;
+ }
+
+ public String currency() {
+ return currency;
+ }
+
+ public LocalDate estimateArriveDate() {
+ return estimateArriveDate;
+ }
+
+ public LocalDate expectArriveDate() {
+ return expectArriveDate;
+ }
+
+ public LocalDate predictionShipDate() {
+ return predictionShipDate;
+ }
+
+ public String originCountry() {
+ return originCountry;
+ }
+
+ public String shipperName() {
+ return shipperName;
+ }
+
+ public String shipperAddress() {
+ return shipperAddress;
+ }
+
+ public String shipperContact() {
+ return shipperContact;
+ }
+
+ public String shipperPhone() {
+ return shipperPhone;
+ }
+
+ public String containerNo() {
+ return containerNo;
}
public String remark() {
return remark;
}
+ public List lines() {
+ return lines;
+ }
+
+ /** 装箱信息;空表示由仓收货时清点。 */
+ public List cartons() {
+ return cartons;
+ }
+
+ /** 批次明细;空表示不用批次管理。 */
+ public List batches() {
+ return batches;
+ }
+
public static final class Builder {
+
private String inboundRequestNo;
private String warehouseId;
- private String type;
- private final List lines = new ArrayList();
+ private int inventoryType;
+ private String factoryBatchNo;
+ private String currency;
+ private LocalDate estimateArriveDate;
+ private LocalDate expectArriveDate;
+ private LocalDate predictionShipDate;
+ private String originCountry;
+ private String shipperName;
+ private String shipperAddress;
+ private String shipperContact;
+ private String shipperPhone;
+ private String containerNo;
private String remark;
+ private final List lines = new ArrayList();
+ private final List cartons = new ArrayList();
+ private final List batches = new ArrayList();
public Builder inboundRequestNo(String v) {
this.inboundRequestNo = v;
@@ -68,8 +187,69 @@ public final class InboundCommand {
return this;
}
- public Builder type(String v) {
- this.type = v;
+ /** 0 正常库存 / 1 不可售库存。 */
+ public Builder inventoryType(int v) {
+ this.inventoryType = v;
+ return this;
+ }
+
+ public Builder factoryBatchNo(String v) {
+ this.factoryBatchNo = v;
+ return this;
+ }
+
+ public Builder currency(String v) {
+ this.currency = v;
+ return this;
+ }
+
+ public Builder estimateArriveDate(LocalDate v) {
+ this.estimateArriveDate = v;
+ return this;
+ }
+
+ public Builder expectArriveDate(LocalDate v) {
+ this.expectArriveDate = v;
+ return this;
+ }
+
+ public Builder predictionShipDate(LocalDate v) {
+ this.predictionShipDate = v;
+ return this;
+ }
+
+ public Builder originCountry(String v) {
+ this.originCountry = v;
+ return this;
+ }
+
+ public Builder shipperName(String v) {
+ this.shipperName = v;
+ return this;
+ }
+
+ public Builder shipperAddress(String v) {
+ this.shipperAddress = v;
+ return this;
+ }
+
+ public Builder shipperContact(String v) {
+ this.shipperContact = v;
+ return this;
+ }
+
+ public Builder shipperPhone(String v) {
+ this.shipperPhone = v;
+ return this;
+ }
+
+ public Builder containerNo(String v) {
+ this.containerNo = v;
+ return this;
+ }
+
+ public Builder remark(String v) {
+ this.remark = v;
return this;
}
@@ -85,8 +265,13 @@ public final class InboundCommand {
return this;
}
- public Builder remark(String v) {
- this.remark = v;
+ public Builder carton(InboundCarton v) {
+ this.cartons.add(v);
+ return this;
+ }
+
+ public Builder batch(InboundBatch v) {
+ this.batches.add(v);
return this;
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundLine.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundLine.java
index 35ee21f..1be900d 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundLine.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundLine.java
@@ -1,12 +1,20 @@
package common.ecommerce.warehouse.model;
-/** 入库单商品行。 */
+import common.ecommerce.shared.support.Money;
+
+/**
+ * 入库商品行。
+ *
+ * {@code omsSku} 是 OMS 主 SKU,{@code providerSku} 是仓侧 SKU;
+ * 仓不接受主 SKU 时由适配器用宿主提供的映射替换。
+ */
public final class InboundLine {
private final String omsSku;
private final String providerSku;
private final int quantity;
- private final int boxNo;
+ /** 采购成本单价;影响仓侧库存成本计算,可为 null。 */
+ private final Money cost;
private InboundLine(Builder b) {
this.omsSku = require(b.omsSku, "omsSku");
@@ -15,7 +23,7 @@ public final class InboundLine {
throw new IllegalArgumentException("quantity must be positive");
}
this.quantity = b.quantity;
- this.boxNo = b.boxNo;
+ this.cost = b.cost;
}
public static Builder builder() {
@@ -34,8 +42,9 @@ public final class InboundLine {
return quantity;
}
- public int boxNo() {
- return boxNo;
+ /** 采购成本单价;未设置为 null。 */
+ public Money cost() {
+ return cost;
}
private static String require(String v, String n) {
@@ -49,7 +58,7 @@ public final class InboundLine {
private String omsSku;
private String providerSku;
private int quantity;
- private int boxNo;
+ private Money cost;
public Builder omsSku(String v) {
this.omsSku = v;
@@ -66,8 +75,8 @@ public final class InboundLine {
return this;
}
- public Builder boxNo(int v) {
- this.boxNo = v;
+ public Builder cost(Money v) {
+ this.cost = v;
return this;
}
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
index e04010a..7313e6e 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
@@ -36,8 +36,8 @@ public final class YqnConstants {
public static final String PATH_INVENTORY_PAGE = "/v2/inventory/get_inventory_by_page";
/** 库存调拨出库计划。 */
public static final String PATH_TRANSFER_OUTBOUND = "/transferoutboundplan/TransferOutboundPlanCreate";
- /** 头程入库创建。 */
- public static final String PATH_INBOUND_CREATE = "/inbound/inboundCreate";
+ /** 创建入库计划单(API 97)。 */
+ public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan";
/** 头程入库查询。 */
public static final String PATH_INBOUND_QUERY = "/inbound/InboundPlanQuery";
/** 退货发起。 */
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
index b847b51..afa917c 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
@@ -11,6 +11,10 @@ import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.FeeQuery;
+import common.ecommerce.warehouse.capability.InboundCapable;
+import common.ecommerce.warehouse.model.InboundCommand;
+import common.ecommerce.warehouse.model.InboundOrder;
+import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.InventorySyncStrategy;
@@ -20,6 +24,7 @@ import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.WarehouseException;
+import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelEligibility;
import common.ecommerce.warehouse.model.CancelResult;
@@ -54,7 +59,7 @@ import java.util.Map;
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。
*/
public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable,
- WarehouseFeeCapable, InventoryCapable {
+ WarehouseFeeCapable, InventoryCapable, InboundCapable {
/** 运去哪请求里的时间格式;待核对。 */
private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
@@ -88,7 +93,8 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
WarehouseCapability.OUTBOUND,
WarehouseCapability.SPLIT,
WarehouseCapability.FEE_SETTLEMENT,
- WarehouseCapability.INVENTORY_QUERY);
+ WarehouseCapability.INVENTORY_QUERY,
+ WarehouseCapability.INBOUND);
}
// ------------------------------------------------------------------ 商品
@@ -319,6 +325,37 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
return YqnInventoryMapper.toPage(page, ctx.providerWarehouseId(), zoneOf(ctx), query.cursor());
}
+ // ------------------------------------------------------------------ 入库
+
+ /**
+ * 创建入库计划单(API 97)。
+ *
+ * 响应只回 {@code data.inboundPlanOrderNo}(字符串计划单号),
+ * 正好可直接作为 {@code providerInboundId} 落库。
+ */
+ @Override
+ public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) {
+ String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId());
+ YqnDtos.CreateInboundPlanRequest body = YqnInboundMapper.toRequest(cmd, warehouseCode);
+ String raw = execute(ctx, YqnConstants.PATH_INBOUND_CREATE, body, "warehouse.inbound.create");
+ String planNo = json.stringAt(raw, "data.inboundPlanOrderNo");
+ return InboundReceipt.of(cmd.inboundRequestNo(), planNo);
+ }
+
+ /**
+ * 入库单查询暂未接入:Spec §8.1 提到 {@code /inbound/InboundPlanQuery},
+ * 但没有字段级文档。这里显式拒绝,不返回空。
+ */
+ @Override
+ public InboundOrder get(WarehouseContext ctx, String inboundRef) {
+ throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.INBOUND);
+ }
+
+ @Override
+ public Page query(WarehouseContext ctx, String cursor) {
+ throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.INBOUND);
+ }
+
// ------------------------------------------------------------------ internals
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
new file mode 100644
index 0000000..43a3969
--- /dev/null
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
@@ -0,0 +1,151 @@
+package common.ecommerce.yqn.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.model.InboundBatch;
+import common.ecommerce.warehouse.model.InboundCarton;
+import common.ecommerce.warehouse.model.InboundCommand;
+import common.ecommerce.warehouse.model.InboundLine;
+import common.ecommerce.yqn.dto.YqnDtos;
+
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 运去哪入库计划报文映射(API 97)。
+ */
+public final class YqnInboundMapper {
+
+ private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+
+ /** 容器号:4 位大写字母 + 7 位数字。 */
+ private static final java.util.regex.Pattern CONTAINER_NO =
+ java.util.regex.Pattern.compile("^[A-Z]{4}\\d{7}$");
+
+ private YqnInboundMapper() {
+ }
+
+ /** 统一命令 → 运去哪创建入库计划请求。 */
+ public static YqnDtos.CreateInboundPlanRequest toRequest(InboundCommand cmd, String warehouseCode) {
+ requireContainerNo(cmd.containerNo());
+
+ YqnDtos.CreateInboundPlanRequest req = new YqnDtos.CreateInboundPlanRequest();
+ req.warehouseCode = warehouseCode;
+ req.orderNo = cmd.inboundRequestNo();
+ req.inventoryType = cmd.inventoryType();
+ req.batchNumber = cmd.factoryBatchNo();
+ req.currency = cmd.currency();
+ req.estimateArriveTime = formatDate(cmd.estimateArriveDate());
+ req.expectArriveDate = formatDate(cmd.expectArriveDate());
+ req.predictionShipDate = formatDate(cmd.predictionShipDate());
+ req.originCountry = cmd.originCountry();
+ req.shipperName = cmd.shipperName();
+ req.shipperAddress = cmd.shipperAddress();
+ req.shipperContact = cmd.shipperContact();
+ req.shipperPhone = cmd.shipperPhone();
+ req.containerNo = cmd.containerNo();
+ req.remark = cmd.remark();
+ // openapi 只支持自发头程;给 1 会被仓拒绝,这里前置挡掉
+ req.logisticsType = 0;
+
+ req.productItems = toProductItems(cmd.lines());
+ req.cartonItems = toCartonItems(cmd.cartons());
+ req.batchItems = toBatchItems(cmd.batches());
+ return req;
+ }
+
+ private static List toProductItems(
+ List lines) {
+ List items =
+ new ArrayList(lines.size());
+ for (InboundLine line : lines) {
+ YqnDtos.CreateInboundPlanRequest.InboundProductItem item =
+ new YqnDtos.CreateInboundPlanRequest.InboundProductItem();
+ item.sku = skuOf(line.providerSku(), line.omsSku());
+ item.qty = line.quantity();
+ Money cost = line.cost();
+ item.cost = cost == null ? null : cost.amount().doubleValue();
+ items.add(item);
+ }
+ return items;
+ }
+
+ private static List toCartonItems(
+ List cartons) {
+ if (cartons == null || cartons.isEmpty()) {
+ return null;
+ }
+ List items =
+ new ArrayList(cartons.size());
+ for (InboundCarton carton : cartons) {
+ YqnDtos.CreateInboundPlanRequest.InboundCartonItem item =
+ new YqnDtos.CreateInboundPlanRequest.InboundCartonItem();
+ item.sku = carton.providerSku();
+ item.qty = carton.quantity();
+ item.cartonQty = carton.cartonQuantity() > 0 ? carton.cartonQuantity() : null;
+ item.cartonNo = carton.cartonNo();
+ item.sid = carton.sid();
+ item.cartonWeight = positiveOrNull(carton.weightGrams());
+ item.cartonLength = positiveOrNull(carton.lengthCm());
+ item.cartonWidth = positiveOrNull(carton.widthCm());
+ item.cartonHeight = positiveOrNull(carton.heightCm());
+ items.add(item);
+ }
+ return items;
+ }
+
+ private static List toBatchItems(
+ List batches) {
+ if (batches == null || batches.isEmpty()) {
+ return null;
+ }
+ List items =
+ new ArrayList(batches.size());
+ for (InboundBatch batch : batches) {
+ YqnDtos.CreateInboundPlanRequest.InboundBatchItem item =
+ new YqnDtos.CreateInboundPlanRequest.InboundBatchItem();
+ item.sku = batch.providerSku();
+ item.cartonNo = batch.cartonNo();
+ item.qty = batch.quantity();
+ List params =
+ new ArrayList(batch.params().size());
+ for (InboundBatch.BatchParam param : batch.params()) {
+ YqnDtos.CreateInboundPlanRequest.BatchAttr attr =
+ new YqnDtos.CreateInboundPlanRequest.BatchAttr();
+ attr.batchAttriKey = param.key();
+ attr.batchAttriValue = param.value();
+ params.add(attr);
+ }
+ item.batchParam = params;
+ items.add(item);
+ }
+ return items;
+ }
+
+ /** 运去哪对集装箱号有格式要求,传错会被仓拒绝;本地先挡,省一个来回。 */
+ static void requireContainerNo(String containerNo) {
+ if (containerNo == null || containerNo.trim().isEmpty()) {
+ return;
+ }
+ if (!CONTAINER_NO.matcher(containerNo.trim()).matches()) {
+ throw new IllegalArgumentException(
+ "yqn containerNo must be 4 uppercase letters + 7 digits, got: " + containerNo);
+ }
+ }
+
+ static String formatDate(LocalDate date) {
+ return date == null ? null : DATE.format(date);
+ }
+
+ static String skuOf(String providerSku, String omsSku) {
+ if (providerSku != null && !providerSku.trim().isEmpty()) {
+ return providerSku.trim();
+ }
+ return omsSku;
+ }
+
+ private static Double positiveOrNull(double v) {
+ return v > 0 ? v : null;
+ }
+}
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
index e24fc16..112d974 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
@@ -554,4 +554,128 @@ public final class YqnDtos {
@com.fasterxml.jackson.annotation.JsonProperty("inventory_pcs_current")
public Integer inventoryPcsCurrent;
}
+
+ /** 创建入库计划单请求(API 97)。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class CreateInboundPlanRequest {
+
+ /** 入库仓库 CODE,必填。 */
+ public String warehouseCode;
+ /** 项目名称。 */
+ public String lineCode;
+ /** 0 正常库存 / 1 不可售库存,必填。 */
+ public Integer inventoryType;
+ /** 工厂批次号。 */
+ public String batchNumber;
+ /** 入库单号(外部来源单号),必填。 */
+ public String orderNo;
+ /** Amazon 订单 ShipmentId。 */
+ public String shipmentId;
+ /** Amazon 订单 referenceId。 */
+ public String referenceId;
+ /** 单据币种,默认 USD;影响库存成本计算。 */
+ public String currency;
+ /** 预计到仓 yyyy-MM-dd。 */
+ public String estimateArriveTime;
+ public String originCountry;
+ /** 期望到仓 yyyy-MM-dd。 */
+ public String expectArriveDate;
+ /** 预计发运 yyyy-MM-dd。 */
+ public String predictionShipDate;
+ public String shipperName;
+ public String shipperAddress;
+ public String shipperContact;
+ public String shipperPhone;
+ /** 集装箱号:4 位大写字母 + 7 位数字。 */
+ public String containerNo;
+ public String remark;
+ /** 产品明细,必填。 */
+ public List productItems;
+ /** 附件。 */
+ public List attachInfoItems;
+ /** 装箱信息。 */
+ public List cartonItems;
+ /** 批次明细。 */
+ public List batchItems;
+ /** 头程类型 0 自发 / 1 运去哪头程(openapi 只支持 0)。 */
+ public Integer logisticsType;
+ /** 国际运输方式 0 海运整柜 / 1 海运散货 / 2 国际快递 / 3 空运。 */
+ public Integer transportType;
+ /** 送仓方式 1 集装箱 / 2 卡车 / 3 快递。 */
+ public Integer deliveryType;
+ /** 集装箱尺寸 0 无 / 1 GP20 / 2 GP40 / 3 HQ40 / 4 HQ45。 */
+ public Integer goodsSize;
+ /** 物流单号集合,逗号分割。 */
+ public String tmsNos;
+ /** 承运商 0 FEDEX / 1 USPS / 2 UPS / 3 DHL / 4 OTHER。 */
+ public Integer carrier;
+ /** 是否 SOC 箱 0 否 / 1 是。 */
+ public Integer socFlag;
+ /** 是否打托 0 否 / 1 是。 */
+ public Integer palletFlag;
+
+ /** 入库商品行。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class InboundProductItem {
+ public String sku;
+ public Integer qty;
+ /** 采购成本,影响库存成本。 */
+ public Double cost;
+ }
+
+ /** 附件。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class InboundAttachItem {
+ public String name;
+ /** 与 file 至少给一个。 */
+ public String url;
+ /** base64;给了就忽略 url。 */
+ public String file;
+ /** ShippingLabel / PackingList / BOL / Other。 */
+ public String type;
+ public String remark;
+ }
+
+ /** 装箱信息。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class InboundCartonItem {
+ public String sku;
+ public Integer qty;
+ /** 装箱入数。 */
+ public Integer cartonQty;
+ /** 箱码,必填。 */
+ public String cartonNo;
+ /** 外箱重量(g)。 */
+ public Double cartonWeight;
+ /** 外箱尺寸(cm)。 */
+ public Double cartonLength;
+ public Double cartonWidth;
+ public Double cartonHeight;
+ /** 箱序标识;一箱多 SKU 时归并同一物理箱。 */
+ public String sid;
+ }
+
+ /** 批次明细。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class InboundBatchItem {
+ public String sku;
+ /** 箱唛号;正式箱唛最少 7 位且末四位为数字。 */
+ public String cartonNo;
+ public Integer qty;
+ public List batchParam;
+ }
+
+ /** 批次属性键值。 */
+ public static final class BatchAttr {
+ public String batchAttriKey;
+ public String batchAttriValue;
+ }
+ }
+
+ /** 创建入库计划响应 {@code data}。 */
+ public static final class CreateInboundPlanResponse {
+
+ /** 入库计划单号。 */
+ public String inboundPlanOrderNo;
+ }
}