Browse Source

feat(yqn): 按 API 101 对接查询入库计划

- 路径 /inbound/InboundPlanQuery → /v1/inbound/getInboundPlanInfo
- 入参只有 orderNo,入库单号与来源单号都能传
- 补齐 create 之后空着的能力:get() 返回完整详情,query() 按单号查一条

入库单模型按响应重写:
- 新增 InboundStatus 枚举,把运去哪的 0/5/6/8/10/16/17/20/25/70/100
  归一化;未知码归 UNKNOWN,不猜
- InboundOrder 补 estimatedArrivalAt / actualArrivalAt / shipper 四项 /
  totalWeightKg / totalVolumeCbm / inventoryType / lines
- 新增 InboundOrderLine:计划 / 装箱 / 实收 / 可售 / 不可售五个数量分开存,
  并给 quantityMatchesPlan() 供对账判断短少与溢装

两点保守处理:
- createdAt 留 null:响应里只有 estimateArrive / actualArrive /
  firstReception,没有下单时间
- 状态码按精确匹配,不做包含判断:运去哪的码是整数枚举,模糊匹配会把
  6(审核拒回) 误判成 16(收货中)

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
29d41da00f
  1. 183
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
  2. 128
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java
  3. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java
  4. 4
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  5. 36
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  6. 142
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
  7. 70
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

183
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java

@ -1,30 +1,68 @@ @@ -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;
/** 头程入库单(查询结果)。 */
/**
* 头程入库单(查询结果)。
*
* <p>双号:{@link #inboundRequestNo()} 是 OMS 下发时的来源单号,
* {@link #providerInboundId()} 是仓侧计划单号。</p>
*
* <p>数量分三层:计划 / 装箱 / 实收。三层都保留,短少与溢装靠比对它们发现。</p>
*/
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<InboundOrderLine> 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.<InboundOrderLine>emptyList()
: Collections.unmodifiableList(new ArrayList<InboundOrderLine>(b.lines));
}
public static Builder builder() {
@ -43,12 +81,7 @@ public final class InboundOrder { @@ -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 { @@ -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 { @@ -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<InboundOrderLine> 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 { @@ -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<InboundOrderLine> lines;
public Builder inboundRequestNo(String v) {
this.inboundRequestNo = v;
@ -101,12 +196,7 @@ public final class InboundOrder { @@ -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 { @@ -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 { @@ -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<InboundOrderLine> v) {
this.lines = v;
return this;
}
public InboundOrder build() {
return new InboundOrder(this);
}

128
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java

@ -0,0 +1,128 @@ @@ -0,0 +1,128 @@
package common.ecommerce.warehouse.model;
import java.time.Instant;
/**
* 入库商品行(计划 / 装箱 / 实收)。
*
* <p>三个数量必须分开看:{@code plannedQuantity} 是预报,{@code packedQuantity}
* 是装箱时实际装进去的,{@code receivedQuantity} 是仓签收上架的。
* 三者不一致就是短少 / 溢装的来源,对账时都要。</p>
*/
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);
}
}
}

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

@ -0,0 +1,32 @@ @@ -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
}

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

@ -38,8 +38,8 @@ public final class YqnConstants { @@ -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";
/** 退货处理方式(二次上架 / 销毁)。 */

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

@ -343,17 +343,43 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -343,17 +343,43 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
}
/**
* 入库单查询暂未接入:Spec §8.1 提到 {@code /inbound/InboundPlanQuery},
* 但没有字段级文档。这里显式拒绝,不返回空。
* 查入库计划详情(API 101)。
*
* <p>入参是入库单号或来源单号,两者都能传;我们下发的来源单号即
* {@code inboundRequestNo}。</p>
*/
@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<InboundOrder> query(WarehouseContext ctx, String cursor) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.INBOUND);
public Page<InboundOrder> 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.<InboundOrder>empty()
: Page.last(java.util.Collections.singletonList(order));
}
// ------------------------------------------------------------------ internals

142
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java

@ -5,10 +5,16 @@ import common.ecommerce.warehouse.model.InboundBatch; @@ -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 { @@ -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<InboundOrderLine> toOrderLines(
List<YqnDtos.InboundPlanInfo.PlanProductDetail> details, ZoneId zone) {
if (details == null || details.isEmpty()) {
return java.util.Collections.emptyList();
}
List<InboundOrderLine> lines = new ArrayList<InboundOrderLine>(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");
}

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

@ -678,4 +678,74 @@ public final class YqnDtos { @@ -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<PlanProductDetail> 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;
}
}
}

Loading…
Cancel
Save