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; + } }