Browse Source

feat(yqn): 按 API 139 对接创建调拨单

上门 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 <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
1d3ebce5ab
  1. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java
  2. 24
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
  3. 338
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
  4. 185
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
  5. 29
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java
  6. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java
  7. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  8. 4
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  9. 38
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  10. 243
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
  11. 80
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java

@ -20,6 +20,8 @@ public enum WarehouseCapability { @@ -20,6 +20,8 @@ public enum WarehouseCapability {
INVENTORY_QUERY,
/** 库存调整 / 调拨 */
INVENTORY_ADJUST,
/** 仓间调拨单(移库 / FBA 移入移出) */
TRANSFER,
/** 头程入库单创建 / 查询 */
INBOUND,
/** 退货发起 / 查询 */

24
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java

@ -0,0 +1,24 @@ @@ -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;
/**
* 仓库间调拨能力。
*
* <p>{@link #create} 是<b>写操作</b>,幂等键为
* {@code warehouseCode + transferRequestNo + "create"}。
* 该请求会移动两个仓的库存,重复下发等于搬两次货。</p>
*/
public interface TransferCapable extends WarehouseAdapter {
/**
* 创建调拨单。
*
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 仓不支持该调拨类型
*/
TransferOrder create(WarehouseContext ctx, TransferCommand cmd);
}

338
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java

@ -0,0 +1,338 @@ @@ -0,0 +1,338 @@
package common.ecommerce.warehouse.model;
/**
* 调拨单创建命令。<b>写操作</b>,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。
*
* <p>运去哪对 {@code sourceNo} 有唯一约束,查询与取消都靠它,所以它同时是业务主键。</p>
*/
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<Integer> serviceTypes;
private final String truckCompany;
private final java.time.LocalDate pickupDate;
private final java.util.List<TransferLine> lines;
/** 标签:150 采集 SN / 160 后置提供 BOL。 */
private final java.util.List<Integer> tags;
private final java.util.List<InboundBatch> 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<Integer>(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<TransferLine>(b.lines));
this.tags = java.util.Collections.unmodifiableList(
new java.util.ArrayList<Integer>(b.tags));
this.batches = java.util.Collections.unmodifiableList(
new java.util.ArrayList<InboundBatch>(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<Integer> serviceTypes() {
return serviceTypes;
}
public String truckCompany() {
return truckCompany;
}
public java.time.LocalDate pickupDate() {
return pickupDate;
}
public java.util.List<TransferLine> lines() {
return lines;
}
public java.util.List<Integer> tags() {
return tags;
}
public java.util.List<InboundBatch> 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<Integer> serviceTypes = new java.util.ArrayList<Integer>();
private String truckCompany;
private java.time.LocalDate pickupDate;
private final java.util.List<TransferLine> lines = new java.util.ArrayList<TransferLine>();
private final java.util.List<Integer> tags = new java.util.ArrayList<Integer>();
private final java.util.List<InboundBatch> batches = new java.util.ArrayList<InboundBatch>();
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);
}
}
}

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

@ -0,0 +1,185 @@ @@ -0,0 +1,185 @@
package common.ecommerce.warehouse.model;
import java.time.Instant;
/**
* 调拨单(查询 / 创建结果)。
*
* <p>双号:{@link #transferRequestNo()} 是我们下发的 {@code sourceNo},
* {@link #providerTransferNo()} 是仓侧生成的 {@code transferOutboundPlanNo}。</p>
*/
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);
}
}
}

29
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java

@ -0,0 +1,29 @@ @@ -0,0 +1,29 @@
package common.ecommerce.warehouse.model;
/**
* 调拨单状态,已归一化。
*
* <p>运去哪的码:0 草稿 / 3 已驳回 / 5 待审核 / 6 审核中 / 7 审核通过 / 8 待确认 /
* 9 待备货 / 10 待出库 / 15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 /
* 90 已关闭 / 100 取消中 / 110 已取消 / 120 取消异常。</p>
*/
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
}

19
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java

@ -0,0 +1,19 @@ @@ -0,0 +1,19 @@
package common.ecommerce.warehouse.model;
/**
* 调拨类型。
*
* <p>运去哪的 {@code type} 是 0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。
* 只保留业务语义,适配器维护到仓方码值的映射。</p>
*/
public enum TransferType {
/** 仓到仓调拨。 */
WAREHOUSE_TO_WAREHOUSE,
/** 调拨出库(发往外部地址或平台仓)。 */
OUTBOUND,
/** 亚马逊移除订单(FBA 移出)。 */
AMAZON_REMOVAL,
/** 亚马逊移入(FBA 入库)。 */
AMAZON_INBOUND
}

32
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -18,6 +18,9 @@ import common.ecommerce.warehouse.capability.WarehouseWebhookCapable; @@ -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 { @@ -72,6 +75,35 @@ public final class WarehouseOperations {
() -> ((WarehouseProductCapable) adapter).createOrUpdate(ctx, product));
}
/**
* 创建调拨单。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + transferRequestNo + create}。
*
* <p>调拨会移动两个仓的库存,重复下发等于搬两次货,所以和其它写操作一样
* 不给「无幂等」的降级路径。</p>
*/
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<TransferOrder> 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();

4
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -34,8 +34,8 @@ public final class YqnConstants { @@ -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)。 */

38
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -16,10 +16,13 @@ import common.ecommerce.warehouse.model.InboundCommand; @@ -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; @@ -59,7 +62,7 @@ import java.util.Map;
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p>
*/
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 @@ -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 @@ -382,6 +386,36 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
: Page.last(java.util.Collections.singletonList(order));
}
// ------------------------------------------------------------------ 调拨
/**
* 创建调拨单(API 139)。
*
* <p>响应是一个完整对象,但只有 {@code transferOutboundPlanNo} /
* {@code transferOutboundPlanStatus} / {@code totalQuantity} 这几个字段有用。
* 类型不回传,从请求侧带过去。</p>
*/
@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
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */

243
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java

@ -0,0 +1,243 @@ @@ -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<Integer>(cmd.serviceTypes());
}
if (!cmd.tags().isEmpty()) {
req.tags = new ArrayList<Integer>(cmd.tags());
}
req.transferOutboundPlanItems = toItems(cmd.lines());
req.batchItems = toBatchItems(cmd.batches());
return req;
}
private static List<YqnDtos.CreateTransferPlanRequest.TransferItem> toItems(
List<TransferCommand.TransferLine> lines) {
List<YqnDtos.CreateTransferPlanRequest.TransferItem> items =
new ArrayList<YqnDtos.CreateTransferPlanRequest.TransferItem>(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<YqnDtos.CreateTransferPlanRequest.TransferBatchItem> toBatchItems(
List<InboundBatch> batches) {
if (batches == null || batches.isEmpty()) {
return null;
}
List<YqnDtos.CreateTransferPlanRequest.TransferBatchItem> items =
new ArrayList<YqnDtos.CreateTransferPlanRequest.TransferBatchItem>(batches.size());
for (InboundBatch batch : batches) {
YqnDtos.CreateTransferPlanRequest.TransferBatchItem item =
new YqnDtos.CreateTransferPlanRequest.TransferBatchItem();
item.sku = batch.providerSku();
item.qty = batch.quantity();
List<YqnDtos.CreateInboundPlanRequest.BatchAttr> params =
new ArrayList<YqnDtos.CreateInboundPlanRequest.BatchAttr>(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;
}
}
/**
* 创建响应 → 统一调拨单。
*
* <p>响应里没有回传 {@code type}(0/1/2/3),所以类型从请求侧带过来,
* 不从响应猜。</p>
*/
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;
}
}
}
}

80
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -748,4 +748,84 @@ public final class YqnDtos { @@ -748,4 +748,84 @@ public final class YqnDtos {
public String receivedTime;
}
}
/**
* 创建调拨单请求(API 139)。
*
* <p>必填:type / 调出调入仓 / inventoryType / 两种运输类型 / sourceNo /
* 期望出入库日期 / 收货地址 / 产品明细。</p>
*/
@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<Integer> serviceType;
public String truckCompany;
/** 提货时间 yyyy-MM-dd。 */
public String pickupTime;
/** 产品明细,必填。 */
public List<TransferItem> transferOutboundPlanItems;
/** 标签 150 采集 SN / 160 后置提供 BOL。 */
public List<Integer> tags;
public List<TransferBatchItem> 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<CreateInboundPlanRequest.BatchAttr> 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;
}
}

Loading…
Cancel
Save