diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java index c3443bb..7b14048 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java @@ -1,30 +1,68 @@ package common.ecommerce.warehouse.model; import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; -/** 头程入库单(查询结果)。 */ +/** + * 头程入库单(查询结果)。 + * + *

双号:{@link #inboundRequestNo()} 是 OMS 下发时的来源单号, + * {@link #providerInboundId()} 是仓侧计划单号。

+ * + *

数量分三层:计划 / 装箱 / 实收。三层都保留,短少与溢装靠比对它们发现。

+ */ public final class InboundOrder { private final String inboundRequestNo; private final String providerInboundId; private final String warehouseCode; - private final String type; - private final String status; + /** 单据状态,已归一化。 */ + private final InboundStatus status; + /** 仓方状态原值,保留便于排查。 */ private final String rawStatus; + /** 库存类型:0 可售 / 1 不可售。 */ + private final int inventoryType; private final int boxCount; private final Instant createdAt; private final Instant receivedAt; + /** 预计到仓(UTC)。 */ + private final Instant estimatedArrivalAt; + /** 实际到仓(UTC)。 */ + private final Instant actualArrivalAt; + private final String shipperName; + private final String shipperContact; + private final String shipperPhone; + private final String shipperAddress; + /** 总重量(kg);仓方原值。 */ + private final Double totalWeightKg; + /** 总体积(CBM);仓方原值。 */ + private final Double totalVolumeCbm; + private final String remark; + private final List lines; private InboundOrder(Builder b) { this.inboundRequestNo = require(b.inboundRequestNo, "inboundRequestNo"); this.providerInboundId = b.providerInboundId; this.warehouseCode = require(b.warehouseCode, "warehouseCode"); - this.type = b.type; - this.status = b.status; + this.status = b.status == null ? InboundStatus.UNKNOWN : b.status; this.rawStatus = b.rawStatus; + this.inventoryType = b.inventoryType; this.boxCount = b.boxCount; this.createdAt = b.createdAt; this.receivedAt = b.receivedAt; + this.estimatedArrivalAt = b.estimatedArrivalAt; + this.actualArrivalAt = b.actualArrivalAt; + this.shipperName = b.shipperName; + this.shipperContact = b.shipperContact; + this.shipperPhone = b.shipperPhone; + this.shipperAddress = b.shipperAddress; + this.totalWeightKg = b.totalWeightKg; + this.totalVolumeCbm = b.totalVolumeCbm; + this.remark = b.remark; + this.lines = b.lines == null ? Collections.emptyList() + : Collections.unmodifiableList(new ArrayList(b.lines)); } public static Builder builder() { @@ -43,12 +81,7 @@ public final class InboundOrder { return warehouseCode; } - /** 自发 / 标准。 */ - public String type() { - return type; - } - - public String status() { + public InboundStatus status() { return status; } @@ -56,6 +89,10 @@ public final class InboundOrder { return rawStatus; } + public int inventoryType() { + return inventoryType; + } + public int boxCount() { return boxCount; } @@ -68,6 +105,54 @@ public final class InboundOrder { return receivedAt; } + public Instant estimatedArrivalAt() { + return estimatedArrivalAt; + } + + public Instant actualArrivalAt() { + return actualArrivalAt; + } + + public String shipperName() { + return shipperName; + } + + public String shipperContact() { + return shipperContact; + } + + public String shipperPhone() { + return shipperPhone; + } + + public String shipperAddress() { + return shipperAddress; + } + + /** 总重量(kg)。 */ + public Double totalWeightKg() { + return totalWeightKg; + } + + /** 总体积(CBM)。 */ + public Double totalVolumeCbm() { + return totalVolumeCbm; + } + + public String remark() { + return remark; + } + + /** 商品行;未查询详情时为空列表。 */ + public List lines() { + return lines; + } + + /** 是否整体完成入库。 */ + public boolean completed() { + return status == InboundStatus.COMPLETED; + } + private static String require(String v, String n) { if (v == null || v.trim().isEmpty()) { throw new IllegalArgumentException(n + " must not be blank"); @@ -79,12 +164,22 @@ public final class InboundOrder { private String inboundRequestNo; private String providerInboundId; private String warehouseCode; - private String type; - private String status; + private InboundStatus status; private String rawStatus; + private int inventoryType; private int boxCount; private Instant createdAt; private Instant receivedAt; + private Instant estimatedArrivalAt; + private Instant actualArrivalAt; + private String shipperName; + private String shipperContact; + private String shipperPhone; + private String shipperAddress; + private Double totalWeightKg; + private Double totalVolumeCbm; + private String remark; + private List lines; public Builder inboundRequestNo(String v) { this.inboundRequestNo = v; @@ -101,12 +196,7 @@ public final class InboundOrder { return this; } - public Builder type(String v) { - this.type = v; - return this; - } - - public Builder status(String v) { + public Builder status(InboundStatus v) { this.status = v; return this; } @@ -116,6 +206,11 @@ public final class InboundOrder { return this; } + public Builder inventoryType(int v) { + this.inventoryType = v; + return this; + } + public Builder boxCount(int v) { this.boxCount = v; return this; @@ -131,6 +226,56 @@ public final class InboundOrder { return this; } + public Builder estimatedArrivalAt(Instant v) { + this.estimatedArrivalAt = v; + return this; + } + + public Builder actualArrivalAt(Instant v) { + this.actualArrivalAt = v; + return this; + } + + public Builder shipperName(String v) { + this.shipperName = v; + return this; + } + + public Builder shipperContact(String v) { + this.shipperContact = v; + return this; + } + + public Builder shipperPhone(String v) { + this.shipperPhone = v; + return this; + } + + public Builder shipperAddress(String v) { + this.shipperAddress = v; + return this; + } + + public Builder totalWeightKg(Double v) { + this.totalWeightKg = v; + return this; + } + + public Builder totalVolumeCbm(Double v) { + this.totalVolumeCbm = v; + return this; + } + + public Builder remark(String v) { + this.remark = v; + return this; + } + + public Builder lines(List v) { + this.lines = v; + return this; + } + public InboundOrder build() { return new InboundOrder(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java new file mode 100644 index 0000000..5e22717 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java @@ -0,0 +1,128 @@ +package common.ecommerce.warehouse.model; + +import java.time.Instant; + +/** + * 入库商品行(计划 / 装箱 / 实收)。 + * + *

三个数量必须分开看:{@code plannedQuantity} 是预报,{@code packedQuantity} + * 是装箱时实际装进去的,{@code receivedQuantity} 是仓签收上架的。 + * 三者不一致就是短少 / 溢装的来源,对账时都要。

+ */ +public final class InboundOrderLine { + + private final String providerSku; + private final int plannedQuantity; + private final int packedQuantity; + /** 上架数量。 */ + private final int receivedQuantity; + /** 上架中可售数量。 */ + private final int receivedSaleableQuantity; + /** 上架中不可售数量。 */ + private final int receivedUnsaleableQuantity; + /** 最近上架时间(备货完成时间)。 */ + private final Instant receivedAt; + + private InboundOrderLine(Builder b) { + this.providerSku = require(b.providerSku, "providerSku"); + this.plannedQuantity = b.plannedQuantity; + this.packedQuantity = b.packedQuantity; + this.receivedQuantity = b.receivedQuantity; + this.receivedSaleableQuantity = b.receivedSaleableQuantity; + this.receivedUnsaleableQuantity = b.receivedUnsaleableQuantity; + this.receivedAt = b.receivedAt; + } + + public static Builder builder() { + return new Builder(); + } + + public String providerSku() { + return providerSku; + } + + public int plannedQuantity() { + return plannedQuantity; + } + + public int packedQuantity() { + return packedQuantity; + } + + public int receivedQuantity() { + return receivedQuantity; + } + + public int receivedSaleableQuantity() { + return receivedSaleableQuantity; + } + + public int receivedUnsaleableQuantity() { + return receivedUnsaleableQuantity; + } + + public Instant receivedAt() { + return receivedAt; + } + + /** 实收与计划是否一致;不一致说明短少或溢装,需要人工核对。 */ + public boolean quantityMatchesPlan() { + return receivedQuantity == plannedQuantity; + } + + private static String require(String v, String n) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(n + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + private String providerSku; + private int plannedQuantity; + private int packedQuantity; + private int receivedQuantity; + private int receivedSaleableQuantity; + private int receivedUnsaleableQuantity; + private Instant receivedAt; + + public Builder providerSku(String v) { + this.providerSku = v; + return this; + } + + public Builder plannedQuantity(int v) { + this.plannedQuantity = v; + return this; + } + + public Builder packedQuantity(int v) { + this.packedQuantity = v; + return this; + } + + public Builder receivedQuantity(int v) { + this.receivedQuantity = v; + return this; + } + + public Builder receivedSaleableQuantity(int v) { + this.receivedSaleableQuantity = v; + return this; + } + + public Builder receivedUnsaleableQuantity(int v) { + this.receivedUnsaleableQuantity = v; + return this; + } + + public Builder receivedAt(Instant v) { + this.receivedAt = v; + return this; + } + + public InboundOrderLine build() { + return new InboundOrderLine(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java new file mode 100644 index 0000000..06da686 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java @@ -0,0 +1,32 @@ +package common.ecommerce.warehouse.model; + +/** 入库计划单状态,已归一化。仓方状态值在适配器内映射到这里。 */ +public enum InboundStatus { + + /** 草稿 / 已创建。 */ + DRAFT, + /** 待审核。 */ + PENDING_REVIEW, + /** 审核拒绝。 */ + REJECTED, + /** 待装箱。 */ + PENDING_PACKING, + /** 待发货。 */ + PENDING_SHIPMENT, + /** 已发运 / 在途。 */ + IN_TRANSIT, + /** 收货中。 */ + RECEIVING, + /** 已收货。 */ + RECEIVED, + /** 待入库(上架)。 */ + PENDING_STORAGE, + /** 入库中(上架中)。 */ + STORING, + /** 已完成。 */ + COMPLETED, + /** 已取消。 */ + CANCELLED, + /** 无法识别的状态。 */ + UNKNOWN +} 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 7313e6e..04bfde0 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 @@ -38,8 +38,8 @@ public final class YqnConstants { public static final String PATH_TRANSFER_OUTBOUND = "/transferoutboundplan/TransferOutboundPlanCreate"; /** 创建入库计划单(API 97)。 */ public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan"; - /** 头程入库查询。 */ - public static final String PATH_INBOUND_QUERY = "/inbound/InboundPlanQuery"; + /** 查询入库计划(API 101)。 */ + public static final String PATH_INBOUND_GET = "/v1/inbound/getInboundPlanInfo"; /** 退货发起。 */ public static final String PATH_RETURN_CREATE = "/salereturn/SalesReturnCreate"; /** 退货处理方式(二次上架 / 销毁)。 */ 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 afa917c..cadfb6c 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 @@ -343,17 +343,43 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl } /** - * 入库单查询暂未接入:Spec §8.1 提到 {@code /inbound/InboundPlanQuery}, - * 但没有字段级文档。这里显式拒绝,不返回空。 + * 查入库计划详情(API 101)。 + * + *

入参是入库单号或来源单号,两者都能传;我们下发的来源单号即 + * {@code inboundRequestNo}。

*/ @Override public InboundOrder get(WarehouseContext ctx, String inboundRef) { - throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.INBOUND); + YqnDtos.GetInboundPlanRequest body = new YqnDtos.GetInboundPlanRequest(); + body.orderNo = inboundRef; + String raw = execute(ctx, YqnConstants.PATH_INBOUND_GET, body, "warehouse.inbound.get"); + com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data"); + if (data == null || data.isNull() || data.isMissingNode()) { + return null; + } + YqnDtos.InboundPlanInfo info = json.fromJson(data.toString(), YqnDtos.InboundPlanInfo.class); + return YqnInboundMapper.toOrder(info, ctx.warehouseCode(), zoneOf(ctx)); } + /** + * 运去哪没有入库单列表接口,与订单一样只能按单号取。 + * {@code cursor} 在这里被当作入库单号使用;不给就拒绝,不返回全量。 + */ @Override - public Page query(WarehouseContext ctx, String cursor) { - throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.INBOUND); + public Page query(WarehouseContext ctx, String inboundRef) { + if (inboundRef == null || inboundRef.trim().isEmpty()) { + throw new common.ecommerce.shared.error.ValidationException( + WarehouseException.builder() + .message("yqn has no inbound list API; query requires an inbound order no") + .operation("warehouse.inbound.query") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false)); + } + InboundOrder order = get(ctx, inboundRef); + return order == null ? Page.empty() + : Page.last(java.util.Collections.singletonList(order)); } // ------------------------------------------------------------------ internals diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java index 43a3969..3ea40ea 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java @@ -5,10 +5,16 @@ import common.ecommerce.warehouse.model.InboundBatch; import common.ecommerce.warehouse.model.InboundCarton; import common.ecommerce.warehouse.model.InboundCommand; import common.ecommerce.warehouse.model.InboundLine; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundOrderLine; +import common.ecommerce.warehouse.model.InboundStatus; 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; @@ -148,4 +154,138 @@ public final class YqnInboundMapper { private static Double positiveOrNull(double v) { return v > 0 ? v : null; } -} + + // ------------------------------------------------------------------ 查询 + + /** 运去哪入库状态码 → 统一状态。未知码归 {@link InboundStatus#UNKNOWN},不猜。 */ + static InboundStatus toStatus(String rawStatus) { + if (rawStatus == null || rawStatus.trim().isEmpty()) { + return InboundStatus.UNKNOWN; + } + switch (rawStatus.trim()) { + case "0": + return InboundStatus.DRAFT; + case "5": + return InboundStatus.PENDING_REVIEW; + case "6": + return InboundStatus.REJECTED; + case "8": + return InboundStatus.PENDING_PACKING; + case "10": + return InboundStatus.PENDING_SHIPMENT; + case "16": + return InboundStatus.RECEIVING; + case "17": + return InboundStatus.RECEIVED; + case "20": + return InboundStatus.PENDING_STORAGE; + case "25": + return InboundStatus.STORING; + case "70": + return InboundStatus.COMPLETED; + case "100": + return InboundStatus.CANCELLED; + default: + return InboundStatus.UNKNOWN; + } + } + + /** 入库计划详情 → 统一入库单(API 101)。 */ + public static InboundOrder toOrder(YqnDtos.InboundPlanInfo info, String warehouseCode, ZoneId zone) { + return InboundOrder.builder() + .inboundRequestNo(firstNonBlank(info.sourceNo, info.inboundPlanOrderNo)) + .providerInboundId(info.inboundPlanOrderNo) + .warehouseCode(firstNonBlank(info.orgWarehouseCode, warehouseCode)) + .status(toStatus(info.inboundPlanOrderStatus)) + .rawStatus(info.inboundPlanOrderStatus) + .inventoryType(intOf(info.inventoryType)) + .boxCount(intOf(info.cartonQty)) + .createdAt(null) + .receivedAt(parseDate(info.firstReceptionDate, zone)) + .estimatedArrivalAt(parseDate(info.estimateArriveTime, zone)) + .actualArrivalAt(parseDate(info.actualArriveTime, zone)) + .shipperName(info.shipperName) + .shipperContact(info.shipperContact) + .shipperPhone(info.shipperPhone) + .shipperAddress(info.shipperAddress) + .totalWeightKg(info.totalWeight) + .totalVolumeCbm(info.totalVolume) + .remark(info.remark) + .lines(toOrderLines(info.planProductDetailParamList, zone)) + .build(); + } + + private static List toOrderLines( + List details, ZoneId zone) { + if (details == null || details.isEmpty()) { + return java.util.Collections.emptyList(); + } + List lines = new ArrayList(details.size()); + for (YqnDtos.InboundPlanInfo.PlanProductDetail detail : details) { + if (detail.sku == null || detail.sku.trim().isEmpty()) { + continue; + } + lines.add(InboundOrderLine.builder() + .providerSku(detail.sku.trim()) + .plannedQuantity(intOf(detail.qty)) + .packedQuantity(intOf(detail.qtyPacked)) + .receivedQuantity(intOf(detail.qtyReceived)) + .receivedSaleableQuantity(intOf(detail.qtyReceivedSaleable)) + .receivedUnsaleableQuantity(intOf(detail.qtyReceivedUnsaleable)) + .receivedAt(parseTime(detail.receivedTime, zone)) + .build()); + } + return lines; + } + + /** 文档里的日期字段是 {@code yyyy-MM-dd},也可能是完整时间;两种都接。 */ + 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; + } + } + } + + static Instant parseTime(String value, ZoneId zone) { + return parseDate(value, zone); + } + + static int intOf(String value) { + if (value == null || value.trim().isEmpty()) { + return 0; + } + try { + return Integer.parseInt(value.trim()); + } catch (NumberFormatException e) { + return 0; + } + } + + static int intOf(Integer value) { + return value == null ? 0 : value; + } + + private static String firstNonBlank(String a, String b) { + if (a != null && !a.trim().isEmpty()) { + return a.trim(); + } + return b; + } + + private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai"); +} \ No newline at end of file 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 112d974..f790959 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 @@ -678,4 +678,74 @@ public final class YqnDtos { /** 入库计划单号。 */ public String inboundPlanOrderNo; } + + /** 查询入库计划请求(API 101):入库单号或来源单号都能传。 */ + public static final class GetInboundPlanRequest { + + public String orderNo; + } + + /** 出入库计划详情(API 101 {@code data})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class InboundPlanInfo { + + public String orgWarehouseCode; + public String lineName; + /** 库存类型;文档标为 string。 */ + public String inventoryType; + public String inboundPlanOrderNo; + /** 0 草稿 / 5 待审核 / 6 审核拒回 / 8 待装箱 / 10 待发货 / 16 收货中 / + * 17 已收货 / 20 待入库 / 25 入库中 / 70 已完成 / 100 已取消。 */ + public String inboundPlanOrderStatus; + public String sourceNo; + public String shipmentId; + public String referenceId; + public String shipmentNo; + public String estimateArriveTime; + public String actualArriveTime; + public String firstReceptionDate; + public String shipperName; + public String shipperAddress; + public String shipperContact; + public String shipperPhone; + /** 货物形态。 */ + public String goodsType; + public String gpQuantity20; + public String gpCartonNo20; + public String gpQuantity40; + public String gpCartonNo40; + public String hqQuantity40; + public String hqCartonNo40; + public String hqQuantity45; + public String hqCartonNo45; + /** 纸箱数;文档标为 string。 */ + public String cartonQty; + public Integer planQty; + public Integer packedQty; + public Integer receivedQty; + /** 总重量(kg)。 */ + public Double totalWeight; + /** 总体积(CBM)。 */ + public Double totalVolume; + public String actualShipDate; + public Double cartonTotalWeight; + public Double cartonTotalVolume; + public String remark; + /** 产品详情(计划 / 装箱 / 实收)。 */ + public List planProductDetailParamList; + + /** 产品行。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class PlanProductDetail { + public String sku; + public Integer qty; + public Integer qtyPacked; + /** 上架数量。 */ + public Integer qtyReceived; + public Integer qtyReceivedSaleable; + public Integer qtyReceivedUnsaleable; + /** 最近上架时间。 */ + public String receivedTime; + } + } }