From 1d3ebce5ab7a8060cd826a78698751d2e530e9b7 Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Mon, 9 Nov 2026 17:20:57 +0800
Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8C=89=20API=20139=20=E5=AF=B9?=
=?UTF-8?q?=E6=8E=A5=E5=88=9B=E5=BB=BA=E8=B0=83=E6=8B=A8=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
上门 8 个接口都是单仓内动作,这个是第一个跨仓写操作:会同时改两个仓的库存。
- 路径 /transferoutboundplan/TransferOutboundPlanCreate →
/v2/transferOutboundPlan/create
- 新增 TRANSFER 能力位与 TransferCapable:直接建独立能力接口,不塞进
InventoryCapable.adjust —— 调拨是跨仓单据,不是单仓库存调整
- 门面 createTransfer() 强制经幂等守卫,幂等键
warehouseCode + transferRequestNo + create
新增模型:
- TransferCommand:调出/调入仓、两种运输类型、期望出入库日期、
FBA shipmentId/removeOrderId、收货地址、增值服务、标签、批次
- TransferOrder:双号 + 归一化状态
- TransferType / TransferStatus:运去哪的 0/1/2/3 与 16 个状态码各自映射,
未知归 UNKNOWN
三条本地校验:
- 期望入库日期不能早于期望出库日期
- 调拨出库类型必须给收货地址;仓到仓由仓自己处理
- inventoryType 只接受 0/1
Co-Authored-By: Claude
---
.../ecommerce/warehouse/WarehouseCapability.java | 2 +
.../warehouse/capability/TransferCapable.java | 24 ++
.../ecommerce/warehouse/model/TransferCommand.java | 338 +++++++++++++++++++++
.../ecommerce/warehouse/model/TransferOrder.java | 185 +++++++++++
.../ecommerce/warehouse/model/TransferStatus.java | 29 ++
.../ecommerce/warehouse/model/TransferType.java | 19 ++
.../warehouse/sdk/WarehouseOperations.java | 32 ++
.../java/common/ecommerce/yqn/YqnConstants.java | 4 +-
.../common/ecommerce/yqn/adapter/YqnAdapter.java | 38 ++-
.../ecommerce/yqn/adapter/YqnTransferMapper.java | 243 +++++++++++++++
.../java/common/ecommerce/yqn/dto/YqnDtos.java | 80 +++++
11 files changed, 990 insertions(+), 4 deletions(-)
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java
create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java
index 0d22cd5..e6934a4 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java
@@ -20,6 +20,8 @@ public enum WarehouseCapability {
INVENTORY_QUERY,
/** 库存调整 / 调拨 */
INVENTORY_ADJUST,
+ /** 仓间调拨单(移库 / FBA 移入移出) */
+ TRANSFER,
/** 头程入库单创建 / 查询 */
INBOUND,
/** 退货发起 / 查询 */
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
new file mode 100644
index 0000000..7c91790
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
@@ -0,0 +1,24 @@
+package common.ecommerce.warehouse.capability;
+
+import common.ecommerce.warehouse.model.TransferCommand;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.warehouse.sdk.WarehouseAdapter;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+
+/**
+ * 仓库间调拨能力。
+ *
+ * {@link #create} 是写操作,幂等键为
+ * {@code warehouseCode + transferRequestNo + "create"}。
+ * 该请求会移动两个仓的库存,重复下发等于搬两次货。
+ */
+public interface TransferCapable extends WarehouseAdapter {
+
+ /**
+ * 创建调拨单。
+ *
+ * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
+ * 仓不支持该调拨类型
+ */
+ TransferOrder create(WarehouseContext ctx, TransferCommand cmd);
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
new file mode 100644
index 0000000..33d36a1
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
@@ -0,0 +1,338 @@
+package common.ecommerce.warehouse.model;
+
+/**
+ * 调拨单创建命令。写操作,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。
+ *
+ * 运去哪对 {@code sourceNo} 有唯一约束,查询与取消都靠它,所以它同时是业务主键。
+ */
+public final class TransferCommand {
+
+ private final String transferRequestNo;
+ private final TransferType type;
+ private final String fromWarehouseCode;
+ private final String toWarehouseCode;
+ /** 库存类型:0 可售 / 1 不可售。 */
+ private final int inventoryType;
+ /** 运送类型:1 卡车派送 / 2 快递派送。 */
+ private final int carrierType;
+ /** 运输方式:1 客户自提 / 2 仓库预约卡车 / 3 仓库物流 / 4 客户面单。 */
+ private final int transportationType;
+ private final java.time.LocalDate estimateOutboundDate;
+ private final java.time.LocalDate estimateInboundDate;
+ /** FBA shipmentId。 */
+ private final String shipmentId;
+ /** FBA referenceId / Remove Order ID。 */
+ private final String removeOrderId;
+ /** 目的地地址 code(FBA 地址 code)。 */
+ private final String receiveStore;
+ /** 目的地地址;仓到仓调拨可为 null,调拨出库必填。 */
+ private final ShipTo shipTo;
+ private final String remark;
+ /** 增值服务:1 贴产品标 / 2 贴箱标 / 3 贴托盘标。 */
+ private final java.util.List serviceTypes;
+ private final String truckCompany;
+ private final java.time.LocalDate pickupDate;
+ private final java.util.List lines;
+ /** 标签:150 采集 SN / 160 后置提供 BOL。 */
+ private final java.util.List tags;
+ private final java.util.List batches;
+
+ private TransferCommand(Builder b) {
+ if (b.transferRequestNo == null || b.transferRequestNo.trim().isEmpty()) {
+ throw new IllegalArgumentException("transferRequestNo must not be blank");
+ }
+ this.transferRequestNo = b.transferRequestNo.trim();
+ this.type = java.util.Objects.requireNonNull(b.type, "type");
+ this.fromWarehouseCode = require(b.fromWarehouseCode, "fromWarehouseCode");
+ this.toWarehouseCode = require(b.toWarehouseCode, "toWarehouseCode");
+ if (b.inventoryType != 0 && b.inventoryType != 1) {
+ throw new IllegalArgumentException("inventoryType must be 0 (sellable) or 1 (unsellable)");
+ }
+ this.inventoryType = b.inventoryType;
+ this.carrierType = b.carrierType;
+ this.transportationType = b.transportationType;
+ if (b.estimateOutboundDate == null || b.estimateInboundDate == null) {
+ throw new IllegalArgumentException(
+ "estimateOutboundDate and estimateInboundDate are required");
+ }
+ if (b.estimateInboundDate.isBefore(b.estimateOutboundDate)) {
+ throw new IllegalArgumentException(
+ "estimateInboundDate must not be earlier than estimateOutboundDate");
+ }
+ this.estimateOutboundDate = b.estimateOutboundDate;
+ this.estimateInboundDate = b.estimateInboundDate;
+ this.shipmentId = b.shipmentId;
+ this.removeOrderId = b.removeOrderId;
+ this.receiveStore = b.receiveStore;
+ this.shipTo = b.shipTo;
+ // 调拨出库必须给收货地址;仓到仓由仓自己处理
+ if (type == TransferType.OUTBOUND && shipTo == null) {
+ throw new IllegalArgumentException("shipTo is required when transfer type is OUTBOUND");
+ }
+ this.remark = b.remark;
+ this.serviceTypes = java.util.Collections.unmodifiableList(
+ new java.util.ArrayList(b.serviceTypes));
+ this.truckCompany = b.truckCompany;
+ this.pickupDate = b.pickupDate;
+ if (b.lines.isEmpty()) {
+ throw new IllegalArgumentException("lines must not be empty");
+ }
+ this.lines = java.util.Collections.unmodifiableList(
+ new java.util.ArrayList(b.lines));
+ this.tags = java.util.Collections.unmodifiableList(
+ new java.util.ArrayList(b.tags));
+ this.batches = java.util.Collections.unmodifiableList(
+ new java.util.ArrayList(b.batches));
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 来源单号;仓方要求全局唯一,查询与取消都靠它。 */
+ public String transferRequestNo() {
+ return transferRequestNo;
+ }
+
+ public TransferType type() {
+ return type;
+ }
+
+ public String fromWarehouseCode() {
+ return fromWarehouseCode;
+ }
+
+ public String toWarehouseCode() {
+ return toWarehouseCode;
+ }
+
+ public int inventoryType() {
+ return inventoryType;
+ }
+
+ public int carrierType() {
+ return carrierType;
+ }
+
+ public int transportationType() {
+ return transportationType;
+ }
+
+ public java.time.LocalDate estimateOutboundDate() {
+ return estimateOutboundDate;
+ }
+
+ public java.time.LocalDate estimateInboundDate() {
+ return estimateInboundDate;
+ }
+
+ public String shipmentId() {
+ return shipmentId;
+ }
+
+ public String removeOrderId() {
+ return removeOrderId;
+ }
+
+ public String receiveStore() {
+ return receiveStore;
+ }
+
+ public ShipTo shipTo() {
+ return shipTo;
+ }
+
+ public String remark() {
+ return remark;
+ }
+
+ public java.util.List serviceTypes() {
+ return serviceTypes;
+ }
+
+ public String truckCompany() {
+ return truckCompany;
+ }
+
+ public java.time.LocalDate pickupDate() {
+ return pickupDate;
+ }
+
+ public java.util.List lines() {
+ return lines;
+ }
+
+ public java.util.List tags() {
+ return tags;
+ }
+
+ public java.util.List batches() {
+ return batches;
+ }
+
+ 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 TransferLine {
+
+ private final String providerSku;
+ private final int quantity;
+
+ public TransferLine(String providerSku, int quantity) {
+ if (providerSku == null || providerSku.trim().isEmpty()) {
+ throw new IllegalArgumentException("providerSku must not be blank");
+ }
+ if (quantity <= 0) {
+ throw new IllegalArgumentException("quantity must be positive");
+ }
+ this.providerSku = providerSku.trim();
+ this.quantity = quantity;
+ }
+
+ public String providerSku() {
+ return providerSku;
+ }
+
+ public int quantity() {
+ return quantity;
+ }
+ }
+
+ public static final class Builder {
+
+ private String transferRequestNo;
+ private TransferType type;
+ private String fromWarehouseCode;
+ private String toWarehouseCode;
+ private int inventoryType;
+ private int carrierType;
+ private int transportationType;
+ private java.time.LocalDate estimateOutboundDate;
+ private java.time.LocalDate estimateInboundDate;
+ private String shipmentId;
+ private String removeOrderId;
+ private String receiveStore;
+ private ShipTo shipTo;
+ private String remark;
+ private final java.util.List serviceTypes = new java.util.ArrayList();
+ private String truckCompany;
+ private java.time.LocalDate pickupDate;
+ private final java.util.List lines = new java.util.ArrayList();
+ private final java.util.List tags = new java.util.ArrayList();
+ private final java.util.List batches = new java.util.ArrayList();
+
+ public Builder transferRequestNo(String v) {
+ this.transferRequestNo = v;
+ return this;
+ }
+
+ public Builder type(TransferType v) {
+ this.type = v;
+ return this;
+ }
+
+ public Builder fromWarehouseCode(String v) {
+ this.fromWarehouseCode = v;
+ return this;
+ }
+
+ public Builder toWarehouseCode(String v) {
+ this.toWarehouseCode = v;
+ return this;
+ }
+
+ /** 0 可售 / 1 不可售。 */
+ public Builder inventoryType(int v) {
+ this.inventoryType = v;
+ return this;
+ }
+
+ /** 1 卡车派送 / 2 快递派送。 */
+ public Builder carrierType(int v) {
+ this.carrierType = v;
+ return this;
+ }
+
+ /** 1 客户自提 / 2 仓库预约卡车 / 3 仓库物流 / 4 客户面单。 */
+ public Builder transportationType(int v) {
+ this.transportationType = v;
+ return this;
+ }
+
+ public Builder estimateOutboundDate(java.time.LocalDate v) {
+ this.estimateOutboundDate = v;
+ return this;
+ }
+
+ public Builder estimateInboundDate(java.time.LocalDate v) {
+ this.estimateInboundDate = v;
+ return this;
+ }
+
+ public Builder shipmentId(String v) {
+ this.shipmentId = v;
+ return this;
+ }
+
+ public Builder removeOrderId(String v) {
+ this.removeOrderId = v;
+ return this;
+ }
+
+ public Builder receiveStore(String v) {
+ this.receiveStore = v;
+ return this;
+ }
+
+ public Builder shipTo(ShipTo v) {
+ this.shipTo = v;
+ return this;
+ }
+
+ public Builder remark(String v) {
+ this.remark = v;
+ return this;
+ }
+
+ /** 增值服务 1 贴产品标 / 2 贴箱标 / 3 贴托盘标。 */
+ public Builder serviceType(int code) {
+ this.serviceTypes.add(code);
+ return this;
+ }
+
+ public Builder truckCompany(String v) {
+ this.truckCompany = v;
+ return this;
+ }
+
+ public Builder pickupDate(java.time.LocalDate v) {
+ this.pickupDate = v;
+ return this;
+ }
+
+ public Builder line(String providerSku, int quantity) {
+ this.lines.add(new TransferLine(providerSku, quantity));
+ return this;
+ }
+
+ /** 标签 150 采集 SN / 160 后置提供 BOL。 */
+ public Builder tag(int code) {
+ this.tags.add(code);
+ return this;
+ }
+
+ public Builder batch(InboundBatch v) {
+ this.batches.add(v);
+ return this;
+ }
+
+ public TransferCommand build() {
+ return new TransferCommand(this);
+ }
+ }
+}
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
new file mode 100644
index 0000000..d84d8ff
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
@@ -0,0 +1,185 @@
+package common.ecommerce.warehouse.model;
+
+import java.time.Instant;
+
+/**
+ * 调拨单(查询 / 创建结果)。
+ *
+ * 双号:{@link #transferRequestNo()} 是我们下发的 {@code sourceNo},
+ * {@link #providerTransferNo()} 是仓侧生成的 {@code transferOutboundPlanNo}。
+ */
+public final class TransferOrder {
+
+ private final String transferRequestNo;
+ private final String providerTransferNo;
+ private final String fromWarehouseCode;
+ private final String toWarehouseCode;
+ private final TransferType type;
+ private final TransferStatus status;
+ private final String rawStatus;
+ private final int totalQuantity;
+ private final Instant estimatedOutboundAt;
+ private final Instant estimatedInboundAt;
+ private final String trackingNumber;
+ private final String remark;
+
+ private TransferOrder(Builder b) {
+ this.transferRequestNo = require(b.transferRequestNo, "transferRequestNo");
+ this.providerTransferNo = b.providerTransferNo;
+ this.fromWarehouseCode = b.fromWarehouseCode;
+ this.toWarehouseCode = b.toWarehouseCode;
+ this.type = b.type;
+ this.status = b.status == null ? TransferStatus.UNKNOWN : b.status;
+ this.rawStatus = b.rawStatus;
+ this.totalQuantity = b.totalQuantity;
+ this.estimatedOutboundAt = b.estimatedOutboundAt;
+ this.estimatedInboundAt = b.estimatedInboundAt;
+ this.trackingNumber = b.trackingNumber;
+ this.remark = b.remark;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 来源单号(我们下发的)。 */
+ public String transferRequestNo() {
+ return transferRequestNo;
+ }
+
+ /** 仓侧调拨计划单号。 */
+ public String providerTransferNo() {
+ return providerTransferNo;
+ }
+
+ public String fromWarehouseCode() {
+ return fromWarehouseCode;
+ }
+
+ public String toWarehouseCode() {
+ return toWarehouseCode;
+ }
+
+ public TransferType type() {
+ return type;
+ }
+
+ public TransferStatus status() {
+ return status;
+ }
+
+ public String rawStatus() {
+ return rawStatus;
+ }
+
+ public int totalQuantity() {
+ return totalQuantity;
+ }
+
+ public Instant estimatedOutboundAt() {
+ return estimatedOutboundAt;
+ }
+
+ public Instant estimatedInboundAt() {
+ return estimatedInboundAt;
+ }
+
+ /** 调拨入库 tracking no;未发货时为 null。 */
+ public String trackingNumber() {
+ return trackingNumber;
+ }
+
+ public String remark() {
+ return remark;
+ }
+
+ public boolean completed() {
+ return status == TransferStatus.COMPLETED;
+ }
+
+ 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 transferRequestNo;
+ private String providerTransferNo;
+ private String fromWarehouseCode;
+ private String toWarehouseCode;
+ private TransferType type;
+ private TransferStatus status;
+ private String rawStatus;
+ private int totalQuantity;
+ private Instant estimatedOutboundAt;
+ private Instant estimatedInboundAt;
+ private String trackingNumber;
+ private String remark;
+
+ public Builder transferRequestNo(String v) {
+ this.transferRequestNo = v;
+ return this;
+ }
+
+ public Builder providerTransferNo(String v) {
+ this.providerTransferNo = v;
+ return this;
+ }
+
+ public Builder fromWarehouseCode(String v) {
+ this.fromWarehouseCode = v;
+ return this;
+ }
+
+ public Builder toWarehouseCode(String v) {
+ this.toWarehouseCode = v;
+ return this;
+ }
+
+ public Builder type(TransferType v) {
+ this.type = v;
+ return this;
+ }
+
+ public Builder status(TransferStatus v) {
+ this.status = v;
+ return this;
+ }
+
+ public Builder rawStatus(String v) {
+ this.rawStatus = v;
+ return this;
+ }
+
+ public Builder totalQuantity(int v) {
+ this.totalQuantity = v;
+ return this;
+ }
+
+ public Builder estimatedOutboundAt(Instant v) {
+ this.estimatedOutboundAt = v;
+ return this;
+ }
+
+ public Builder estimatedInboundAt(Instant v) {
+ this.estimatedInboundAt = v;
+ return this;
+ }
+
+ public Builder trackingNumber(String v) {
+ this.trackingNumber = v;
+ return this;
+ }
+
+ public Builder remark(String v) {
+ this.remark = v;
+ return this;
+ }
+
+ public TransferOrder build() {
+ return new TransferOrder(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java
new file mode 100644
index 0000000..353a21d
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java
@@ -0,0 +1,29 @@
+package common.ecommerce.warehouse.model;
+
+/**
+ * 调拨单状态,已归一化。
+ *
+ * 运去哪的码:0 草稿 / 3 已驳回 / 5 待审核 / 6 审核中 / 7 审核通过 / 8 待确认 /
+ * 9 待备货 / 10 待出库 / 15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 /
+ * 90 已关闭 / 100 取消中 / 110 已取消 / 120 取消异常。
+ */
+public enum TransferStatus {
+
+ DRAFT,
+ REJECTED,
+ PENDING_REVIEW,
+ REVIEWING,
+ APPROVED,
+ PENDING_CONFIRM,
+ PENDING_PICKING,
+ PENDING_OUTBOUND,
+ OUTBOUNDING,
+ PENDING_INBOUND,
+ INBOUNDING,
+ COMPLETED,
+ CLOSED,
+ CANCELLING,
+ CANCELLED,
+ CANCEL_EXCEPTION,
+ UNKNOWN
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java
new file mode 100644
index 0000000..73ce5d5
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java
@@ -0,0 +1,19 @@
+package common.ecommerce.warehouse.model;
+
+/**
+ * 调拨类型。
+ *
+ * 运去哪的 {@code type} 是 0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。
+ * 只保留业务语义,适配器维护到仓方码值的映射。
+ */
+public enum TransferType {
+
+ /** 仓到仓调拨。 */
+ WAREHOUSE_TO_WAREHOUSE,
+ /** 调拨出库(发往外部地址或平台仓)。 */
+ OUTBOUND,
+ /** 亚马逊移除订单(FBA 移出)。 */
+ AMAZON_REMOVAL,
+ /** 亚马逊移入(FBA 入库)。 */
+ AMAZON_INBOUND
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
index 3f1c9b7..ef76036 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
@@ -18,6 +18,9 @@ import common.ecommerce.warehouse.capability.WarehouseWebhookCapable;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.FeeQuery;
+import common.ecommerce.warehouse.model.TransferCommand;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.model.DestructionOrder;
import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundOrder;
@@ -72,6 +75,35 @@ public final class WarehouseOperations {
() -> ((WarehouseProductCapable) adapter).createOrUpdate(ctx, product));
}
+ /**
+ * 创建调拨单。写操作:强制经幂等守卫,幂等键
+ * {@code warehouseCode + transferRequestNo + create}。
+ *
+ * 调拨会移动两个仓的库存,重复下发等于搬两次货,所以和其它写操作一样
+ * 不给「无幂等」的降级路径。
+ */
+ public TransferOrder createTransfer(final TransferCommand cmd) {
+ require(WarehouseCapability.TRANSFER, TransferCapable.class);
+ if (guard == null) {
+ throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
+ }
+ final TransferCapable capable = (TransferCapable) adapter;
+ common.ecommerce.shared.idempotency.WriteResult result =
+ guard.execute(
+ WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
+ cmd.transferRequestNo(), "create"),
+ () -> capable.create(ctx, cmd),
+ order -> order.providerTransferNo());
+ if (result.alreadyCompleted()) {
+ // 回放:本次没有调仓,只有上次记录的仓单号
+ return TransferOrder.builder()
+ .transferRequestNo(cmd.transferRequestNo())
+ .providerTransferNo(result.resultRef())
+ .build();
+ }
+ return result.value();
+ }
+
/** 库存视图。 */
public InventoryView inventory() {
return new InventoryView();
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 04bfde0..670eb3f 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
@@ -34,8 +34,8 @@ public final class YqnConstants {
public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel";
/** 批量查询库存(API 107),GET + 分页。 */
public static final String PATH_INVENTORY_PAGE = "/v2/inventory/get_inventory_by_page";
- /** 库存调拨出库计划。 */
- public static final String PATH_TRANSFER_OUTBOUND = "/transferoutboundplan/TransferOutboundPlanCreate";
+ /** 创建调拨单(API 139)。 */
+ public static final String PATH_TRANSFER_CREATE = "/v2/transferOutboundPlan/create";
/** 创建入库计划单(API 97)。 */
public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan";
/** 查询入库计划(API 101)。 */
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 cadfb6c..42fae0d 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
@@ -16,10 +16,13 @@ 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.TransferCommand;
+import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.InventorySyncStrategy;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.InventoryCapable;
+import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
@@ -59,7 +62,7 @@ import java.util.Map;
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。
*/
public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable,
- WarehouseFeeCapable, InventoryCapable, InboundCapable {
+ WarehouseFeeCapable, InventoryCapable, InboundCapable, TransferCapable {
/** 运去哪请求里的时间格式;待核对。 */
private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
@@ -94,7 +97,8 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
WarehouseCapability.SPLIT,
WarehouseCapability.FEE_SETTLEMENT,
WarehouseCapability.INVENTORY_QUERY,
- WarehouseCapability.INBOUND);
+ WarehouseCapability.INBOUND,
+ WarehouseCapability.TRANSFER);
}
// ------------------------------------------------------------------ 商品
@@ -382,6 +386,36 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
: Page.last(java.util.Collections.singletonList(order));
}
+ // ------------------------------------------------------------------ 调拨
+
+ /**
+ * 创建调拨单(API 139)。
+ *
+ * 响应是一个完整对象,但只有 {@code transferOutboundPlanNo} /
+ * {@code transferOutboundPlanStatus} / {@code totalQuantity} 这几个字段有用。
+ * 类型不回传,从请求侧带过去。
+ */
+ @Override
+ public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) {
+ YqnDtos.CreateTransferPlanRequest body = YqnTransferMapper.toRequest(cmd);
+ String raw = execute(ctx, YqnConstants.PATH_TRANSFER_CREATE, body, "warehouse.transfer.create");
+ com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data");
+ if (data == null || data.isNull() || data.isMissingNode()) {
+ throw WarehouseException.builder()
+ .message("yqn create transfer returned no data: " + safeRelay(raw))
+ .operation("warehouse.transfer.create")
+ .warehouseCode(ctx.warehouseCode())
+ .provider(provider().name())
+ .requestId(ctx.requestId())
+ .retryable(false)
+ .rawResponse(safeRelay(raw))
+ .build();
+ }
+ YqnDtos.CreateTransferPlanResponse resp =
+ json.fromJson(data.toString(), YqnDtos.CreateTransferPlanResponse.class);
+ return YqnTransferMapper.toOrder(resp, cmd.type(), zoneOf(ctx));
+ }
+
// ------------------------------------------------------------------ internals
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
new file mode 100644
index 0000000..a51fa26
--- /dev/null
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
@@ -0,0 +1,243 @@
+package common.ecommerce.yqn.adapter;
+
+import common.ecommerce.warehouse.model.InboundBatch;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.model.TransferCommand;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.warehouse.model.TransferStatus;
+import common.ecommerce.warehouse.model.TransferType;
+import common.ecommerce.yqn.dto.YqnDtos;
+
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneId;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 运去哪调拨单报文映射(API 139)。
+ */
+public final class YqnTransferMapper {
+
+ private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+ private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai");
+
+ private YqnTransferMapper() {
+ }
+
+ /** 统一命令 → 运去哪创建调拨单请求。 */
+ public static YqnDtos.CreateTransferPlanRequest toRequest(TransferCommand cmd) {
+ YqnDtos.CreateTransferPlanRequest req = new YqnDtos.CreateTransferPlanRequest();
+ req.type = typeOf(cmd.type());
+ req.orgWarehouseCode = cmd.fromWarehouseCode();
+ req.inOrgWarehouseCode = cmd.toWarehouseCode();
+ req.inventoryType = cmd.inventoryType();
+ req.transportationCarrierType = cmd.carrierType();
+ req.transportationType = cmd.transportationType();
+ req.sourceNo = cmd.transferRequestNo();
+ req.estimateOutboundAt = formatDate(cmd.estimateOutboundDate());
+ req.estimateInboundAt = formatDate(cmd.estimateInboundDate());
+ req.shipmentId = cmd.shipmentId();
+ req.removeOrderId = cmd.removeOrderId();
+ req.receiveStore = cmd.receiveStore();
+ req.remark = cmd.remark();
+ req.truckCompany = cmd.truckCompany();
+ req.pickupTime = formatDate(cmd.pickupDate());
+
+ ShipTo shipTo = cmd.shipTo();
+ if (shipTo != null) {
+ req.shipToCountry = shipTo.countryCode();
+ req.shipToState = shipTo.stateOrProvince();
+ req.shipToCity = shipTo.city();
+ req.shipToPostal = shipTo.postalCode();
+ req.shipToAddress1 = shipTo.addressLine1();
+ req.shipToContact = shipTo.name();
+ req.shipToTelephone = shipTo.phone();
+ }
+
+ if (!cmd.serviceTypes().isEmpty()) {
+ req.serviceType = new ArrayList(cmd.serviceTypes());
+ }
+ if (!cmd.tags().isEmpty()) {
+ req.tags = new ArrayList(cmd.tags());
+ }
+ req.transferOutboundPlanItems = toItems(cmd.lines());
+ req.batchItems = toBatchItems(cmd.batches());
+ return req;
+ }
+
+ private static List toItems(
+ List lines) {
+ List items =
+ new ArrayList(lines.size());
+ for (TransferCommand.TransferLine line : lines) {
+ YqnDtos.CreateTransferPlanRequest.TransferItem item =
+ new YqnDtos.CreateTransferPlanRequest.TransferItem();
+ item.sku = line.providerSku();
+ item.qty = line.quantity();
+ 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.CreateTransferPlanRequest.TransferBatchItem item =
+ new YqnDtos.CreateTransferPlanRequest.TransferBatchItem();
+ item.sku = batch.providerSku();
+ 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;
+ }
+
+ /** 业务类型 → 运去哪 type:0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓 / 3 调拨出库。 */
+ static Integer typeOf(TransferType type) {
+ if (type == null) {
+ return null;
+ }
+ switch (type) {
+ case AMAZON_REMOVAL:
+ return 0;
+ case AMAZON_INBOUND:
+ return 1;
+ case WAREHOUSE_TO_WAREHOUSE:
+ return 2;
+ case OUTBOUND:
+ return 3;
+ default:
+ return null;
+ }
+ }
+
+ /** 运去哪 type → 业务类型。 */
+ static TransferType typeOf(Integer code) {
+ if (code == null) {
+ return null;
+ }
+ switch (code) {
+ case 0:
+ return TransferType.AMAZON_REMOVAL;
+ case 1:
+ return TransferType.AMAZON_INBOUND;
+ case 2:
+ return TransferType.WAREHOUSE_TO_WAREHOUSE;
+ case 3:
+ return TransferType.OUTBOUND;
+ default:
+ return null;
+ }
+ }
+
+ /** 运去哪调拨状态码 → 统一状态;未知码归 UNKNOWN,不猜。 */
+ static TransferStatus toStatus(Integer rawStatus) {
+ if (rawStatus == null) {
+ return TransferStatus.UNKNOWN;
+ }
+ switch (rawStatus) {
+ case 0:
+ return TransferStatus.DRAFT;
+ case 3:
+ return TransferStatus.REJECTED;
+ case 5:
+ return TransferStatus.PENDING_REVIEW;
+ case 6:
+ return TransferStatus.REVIEWING;
+ case 7:
+ return TransferStatus.APPROVED;
+ case 8:
+ return TransferStatus.PENDING_CONFIRM;
+ case 9:
+ return TransferStatus.PENDING_PICKING;
+ case 10:
+ return TransferStatus.PENDING_OUTBOUND;
+ case 15:
+ return TransferStatus.OUTBOUNDING;
+ case 20:
+ return TransferStatus.PENDING_INBOUND;
+ case 25:
+ return TransferStatus.INBOUNDING;
+ case 70:
+ return TransferStatus.COMPLETED;
+ case 90:
+ return TransferStatus.CLOSED;
+ case 100:
+ return TransferStatus.CANCELLING;
+ case 110:
+ return TransferStatus.CANCELLED;
+ case 120:
+ return TransferStatus.CANCEL_EXCEPTION;
+ default:
+ return TransferStatus.UNKNOWN;
+ }
+ }
+
+ /**
+ * 创建响应 → 统一调拨单。
+ *
+ * 响应里没有回传 {@code type}(0/1/2/3),所以类型从请求侧带过来,
+ * 不从响应猜。
+ */
+ public static TransferOrder toOrder(YqnDtos.CreateTransferPlanResponse resp,
+ TransferType requestedType, ZoneId zone) {
+ return TransferOrder.builder()
+ .transferRequestNo(resp.sourceNo)
+ .providerTransferNo(resp.transferOutboundPlanNo)
+ .fromWarehouseCode(resp.orgWarehouseCode)
+ .toWarehouseCode(resp.inOrgWarehouseCode)
+ .type(requestedType)
+ .status(toStatus(resp.transferOutboundPlanStatus))
+ .rawStatus(resp.transferOutboundPlanStatus == null ? null
+ : String.valueOf(resp.transferOutboundPlanStatus))
+ .totalQuantity(resp.totalQuantity == null ? 0 : resp.totalQuantity)
+ .estimatedOutboundAt(parseDate(resp.estimateOutboundAt, zone))
+ .estimatedInboundAt(parseDate(resp.estimateInboundAt, zone))
+ .trackingNumber(resp.trackingNo)
+ .remark(resp.remark)
+ .build();
+ }
+
+ static String formatDate(LocalDate date) {
+ return date == null ? null : DATE.format(date);
+ }
+
+ static Instant parseDate(String value, ZoneId zone) {
+ if (value == null || value.trim().isEmpty()) {
+ return null;
+ }
+ String v = value.trim();
+ try {
+ return LocalDate.parse(v, DATE).atStartOfDay(zone == null ? DEFAULT_ZONE : zone).toInstant();
+ } catch (DateTimeParseException ignored) {
+ // 落到完整时间解析
+ }
+ try {
+ return java.time.LocalDateTime.parse(v, DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ .atZone(zone == null ? DEFAULT_ZONE : zone).toInstant();
+ } catch (DateTimeParseException ignored) {
+ try {
+ return Instant.parse(v);
+ } catch (DateTimeParseException alsoIgnored) {
+ return 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 f790959..f6f23f6 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
@@ -748,4 +748,84 @@ public final class YqnDtos {
public String receivedTime;
}
}
+
+ /**
+ * 创建调拨单请求(API 139)。
+ *
+ * 必填:type / 调出调入仓 / inventoryType / 两种运输类型 / sourceNo /
+ * 期望出入库日期 / 收货地址 / 产品明细。
+ */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class CreateTransferPlanRequest {
+
+ /** 0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。 */
+ public Integer type;
+ /** 出库仓 code;没有填 Other。 */
+ public String orgWarehouseCode;
+ /** 入库仓 code;没有填 Other。 */
+ public String inOrgWarehouseCode;
+ /** 0 可售 / 1 不可售。 */
+ public Integer inventoryType;
+ /** 运送类型 1 卡车派送 / 2 快递派送。 */
+ public Integer transportationCarrierType;
+ /** 运输方式 1 客户自提 / 2 仓库预约卡车 / 3 仓库物流 / 4 客户物流面单。 */
+ public Integer transportationType;
+ /** 来源单号;唯一约束,查询与取消都靠它。 */
+ public String sourceNo;
+ /** 期望出库日期 yyyy-MM-dd。 */
+ public String estimateOutboundAt;
+ /** 期望入库日期 yyyy-MM-dd。 */
+ public String estimateInboundAt;
+ public String shipmentId;
+ public String removeOrderId;
+ /** 目的地地址 code。 */
+ public String receiveStore;
+ public String shipToCountry;
+ public String shipToState;
+ public String shipToCity;
+ public String shipToPostal;
+ public String shipToAddress1;
+ public String shipToContact;
+ public String shipToTelephone;
+ public String remark;
+ /** 增值服务 1 贴产品标 / 2 贴箱标 / 3 贴托盘标。 */
+ public List serviceType;
+ public String truckCompany;
+ /** 提货时间 yyyy-MM-dd。 */
+ public String pickupTime;
+ /** 产品明细,必填。 */
+ public List transferOutboundPlanItems;
+ /** 标签 150 采集 SN / 160 后置提供 BOL。 */
+ public List tags;
+ public List batchItems;
+
+ /** 产品行。 */
+ public static final class TransferItem {
+ public String sku;
+ public Integer qty;
+ }
+
+ /** 批次明细。 */
+ public static final class TransferBatchItem {
+ public String sku;
+ public Integer qty;
+ public List batchParam;
+ }
+ }
+
+ /** 创建调拨单响应 {@code data}(只取用得到的字段)。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class CreateTransferPlanResponse {
+
+ public String transferOutboundPlanNo;
+ public Integer transferOutboundPlanStatus;
+ public String sourceNo;
+ public String orgWarehouseCode;
+ public String inOrgWarehouseCode;
+ public Integer totalQuantity;
+ public String estimateOutboundAt;
+ public String estimateInboundAt;
+ public String trackingNo;
+ public String remark;
+ }
}