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双号:{@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响应是一个完整对象,但只有 {@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响应里没有回传 {@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