From ac8a164982a1e4d8b37e05a70d79a07aef1fa9ba Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Mon, 9 Nov 2026 16:07:33 +0800 Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8C=89=20API=20128=20=E5=AF=B9?= =?UTF-8?q?=E6=8E=A5=E8=AE=A2=E5=8D=95=E8=AF=A6=E6=83=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 路径 /saleorder/FindOrderInfor → /v1/saleOrder/findOne - 响应只有 code/message/data,没有 statusCode/status - data 里没有顶层 carrier / trackingNo:运单在 shipmentPackages 按 API 128 改统一模型: - OutboundOrder 补 lines / shipTo / exceptionCode / estimatedShippingFee / paidAt / carrierCode / currency - PackageResult 补 carrierServiceCode / erpSku / shippedQuantity 三个语义坑的处理: - 运去哪没有订单列表接口,query() 只支持按单号查;不给单号直接拒绝, 避免被当成增量同步用 - shipmentPackages 里 packageFlag=1 是面单信息行,会与实际包裹同 trackingNo 重复出现,按 trackingNo 去重且实际包裹优先 - errorCode=unexception 视为无异常,避免带异常标记的空串流进业务 ShipTo 的必填校验从模型挪到适配器:「哪些字段必填」是仓方协议, 查询回来的详情本来就可能缺字段。 Co-Authored-By: Claude --- .../ecommerce/warehouse/model/OutboundOrder.java | 108 +++++++++++ .../ecommerce/warehouse/model/PackageResult.java | 45 +++++ .../common/ecommerce/warehouse/model/ShipTo.java | 15 +- .../java/common/ecommerce/yqn/YqnConstants.java | 4 +- .../common/ecommerce/yqn/adapter/YqnAdapter.java | 127 ++++++------- .../ecommerce/yqn/adapter/YqnOutboundMapper.java | 201 +++++++++++++++++---- .../java/common/ecommerce/yqn/dto/YqnDtos.java | 165 +++++++++++++---- .../ecommerce/yqn/adapter/YqnAdapterTest.java | 36 ++-- 8 files changed, 541 insertions(+), 160 deletions(-) diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java index 76deeaa..49493b4 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java @@ -1,8 +1,12 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.shared.support.Money; import common.ecommerce.warehouse.WarehouseProvider; import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; /** * 出库单查询结果(不可变)。 @@ -36,6 +40,20 @@ public final class OutboundOrder { private final Instant shippedAt; /** 接入通道。 */ private final WarehouseProvider sourceProvider; + /** 商品行;查询详情时回填。 */ + private final List lines; + /** 收件地址;查询详情时回填。 */ + private final ShipTo shipTo; + /** 仓方异常码,如库存不足 / 地址异常;无异常为 null。 */ + private final String exceptionCode; + /** 仓方给出的预估运费;实际以账单为准。 */ + private final Money estimatedShippingFee; + /** 支付时间(UTC)。 */ + private final Instant paidAt; + /** 承运商服务 code。 */ + private final String carrierCode; + /** 下单币种。 */ + private final String currency; private OutboundOrder(Builder b) { this.warehouseCode = requireText(b.warehouseCode, "warehouseCode"); @@ -50,6 +68,14 @@ public final class OutboundOrder { this.requestedAt = b.requestedAt; this.shippedAt = b.shippedAt; this.sourceProvider = b.sourceProvider; + this.lines = b.lines == null ? Collections.emptyList() + : Collections.unmodifiableList(new ArrayList(b.lines)); + this.shipTo = b.shipTo; + this.exceptionCode = b.exceptionCode; + this.estimatedShippingFee = b.estimatedShippingFee; + this.paidAt = b.paidAt; + this.carrierCode = b.carrierCode; + this.currency = b.currency; } public static Builder builder() { @@ -104,6 +130,46 @@ public final class OutboundOrder { return sourceProvider; } + /** 商品行;未查询详情时为空列表。 */ + public List lines() { + return lines; + } + + /** 收件地址;未查询详情时为 null。 */ + public ShipTo shipTo() { + return shipTo; + } + + /** 仓方异常码;无异常为 null。 */ + public String exceptionCode() { + return exceptionCode; + } + + /** 仓方预估运费。 */ + public Money estimatedShippingFee() { + return estimatedShippingFee; + } + + /** 支付时间(UTC)。 */ + public Instant paidAt() { + return paidAt; + } + + /** 承运商服务 code。 */ + public String carrierCode() { + return carrierCode; + } + + /** 下单币种。 */ + public String currency() { + return currency; + } + + /** 是否带仓方异常。 */ + public boolean hasException() { + return exceptionCode != null && !exceptionCode.trim().isEmpty(); + } + private static String requireText(String value, String name) { if (value == null || value.trim().isEmpty()) { throw new IllegalArgumentException(name + " must not be blank"); @@ -125,6 +191,13 @@ public final class OutboundOrder { private Instant requestedAt; private Instant shippedAt; private WarehouseProvider sourceProvider; + private List lines; + private ShipTo shipTo; + private String exceptionCode; + private Money estimatedShippingFee; + private Instant paidAt; + private String carrierCode; + private String currency; public Builder warehouseCode(String warehouseCode) { this.warehouseCode = warehouseCode; @@ -186,6 +259,41 @@ public final class OutboundOrder { return this; } + public Builder lines(List lines) { + this.lines = lines; + return this; + } + + public Builder shipTo(ShipTo shipTo) { + this.shipTo = shipTo; + return this; + } + + public Builder exceptionCode(String exceptionCode) { + this.exceptionCode = exceptionCode; + return this; + } + + public Builder estimatedShippingFee(Money estimatedShippingFee) { + this.estimatedShippingFee = estimatedShippingFee; + return this; + } + + public Builder paidAt(Instant paidAt) { + this.paidAt = paidAt; + return this; + } + + public Builder carrierCode(String carrierCode) { + this.carrierCode = carrierCode; + return this; + } + + public Builder currency(String currency) { + this.currency = currency; + return this; + } + public OutboundOrder build() { return new OutboundOrder(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/PackageResult.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/PackageResult.java index 9954a63..9467009 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/PackageResult.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/PackageResult.java @@ -3,6 +3,9 @@ package common.ecommerce.warehouse.model; import common.ecommerce.shared.support.Money; import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; /** * 仓拆单后的包裹结果。一张出库单可能对应多个包裹。 @@ -16,6 +19,12 @@ public final class PackageResult { private final String labelRef; private final Money weight; private final Instant shippedAt; + /** 承运商服务 code。 */ + private final String carrierServiceCode; + /** 发出该包裹的仓侧 SKU;一包裹多 SKU 时为空。 */ + private final String erpSku; + /** 该 SKU 的发货数量;未知时为 null。 */ + private final Integer shippedQuantity; private PackageResult(Builder b) { this.packageId = requireText(b.packageId, "packageId"); @@ -25,6 +34,9 @@ public final class PackageResult { this.labelRef = b.labelRef; this.weight = b.weight; this.shippedAt = b.shippedAt; + this.carrierServiceCode = b.carrierServiceCode; + this.erpSku = b.erpSku; + this.shippedQuantity = b.shippedQuantity; } public static Builder builder() { @@ -61,6 +73,21 @@ public final class PackageResult { return shippedAt; } + /** 承运商服务 code。 */ + public String carrierServiceCode() { + return carrierServiceCode; + } + + /** 仓侧 SKU;一包裹多 SKU 时为 null。 */ + public String erpSku() { + return erpSku; + } + + /** 发货数量;未知时为 null。 */ + public Integer shippedQuantity() { + return shippedQuantity; + } + private static String requireText(String value, String name) { if (value == null || value.trim().isEmpty()) { throw new IllegalArgumentException(name + " must not be blank"); @@ -77,6 +104,9 @@ public final class PackageResult { private String labelRef; private Money weight; private Instant shippedAt; + private String carrierServiceCode; + private String erpSku; + private Integer shippedQuantity; public Builder packageId(String packageId) { this.packageId = packageId; @@ -113,6 +143,21 @@ public final class PackageResult { return this; } + public Builder carrierServiceCode(String v) { + this.carrierServiceCode = v; + return this; + } + + public Builder erpSku(String v) { + this.erpSku = v; + return this; + } + + public Builder shippedQuantity(Integer v) { + this.shippedQuantity = v; + return this; + } + public PackageResult build() { return new PackageResult(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ShipTo.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ShipTo.java index caa064e..62ac879 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ShipTo.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ShipTo.java @@ -20,14 +20,21 @@ public final class ShipTo { private final String addressLine3; private final String postalCode; + /** + * 只做字段搬运,不校验必填。 + * + *

「哪些字段必填」是仓方协议的约束,由各适配器在下发时校验; + * 这里放宽是为了让查询回来的详情也能原样承载(仓方未返回的字段为 null)。 + * 下单时缺必填字段由适配器抛 {@code ValidationException}。

+ */ private ShipTo(Builder b) { - this.name = Objects.requireNonNull(b.name, "name"); + this.name = b.name; this.phone = b.phone; this.email = b.email; - this.countryCode = Objects.requireNonNull(b.countryCode, "countryCode"); + this.countryCode = b.countryCode; this.stateOrProvince = b.stateOrProvince; - this.city = Objects.requireNonNull(b.city, "city"); - this.addressLine1 = Objects.requireNonNull(b.addressLine1, "addressLine1"); + this.city = b.city; + this.addressLine1 = b.addressLine1; this.addressLine2 = b.addressLine2; this.addressLine3 = b.addressLine3; this.postalCode = b.postalCode; 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 0ff8303..d83e6c9 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 @@ -28,8 +28,8 @@ public final class YqnConstants { public static final String PATH_PRODUCT_SAVE = "/v1/product/save"; /** 创建销售订单(API 123)。 */ public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create"; - /** 出库单查询。 */ - public static final String PATH_ORDER_FIND = "/saleorder/FindOrderInfor"; + /** 订单详情(API 128):按来源单号查完整订单。 */ + public static final String PATH_ORDER_FIND_ONE = "/v1/saleOrder/findOne"; /** 出库单取消。 */ public static final String PATH_ORDER_CANCEL = "/saleorder/OrderCancel"; /** 批量库存查询。 */ 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 a8d8d9d..58be3b4 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 @@ -124,39 +124,64 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @Override public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { - Map body = new LinkedHashMap(); - body.put("orderNo", ref.providerOrderId()); - body.put("customerOrderNo", ref.outboundRequestNo()); - - String raw = execute(ctx, YqnConstants.PATH_ORDER_FIND, body, "warehouse.outbound.get"); - YqnDtos.OrderInfo info = firstOrder(raw); - return info == null ? null : YqnOutboundMapper.toOrder(info, ctx.warehouseCode(), zoneOf(ctx)); + // API 128 只按来源单号查;仓内部 id 查不了,调用方要给 outboundRequestNo + String orderNo = orderNoOf(ref); + YqnDtos.OrderDetail detail = findOne(ctx, orderNo, "warehouse.outbound.get"); + return detail == null ? null : YqnOutboundMapper.toOrder(detail, ctx.warehouseCode(), zoneOf(ctx)); } + /** + * 按条件查询。 + * + *

运去哪的订单查询接口是「按单号取详情」,没有列表/时间窗接口, + * 因此这里按单号逐个取;没有单号时拒绝而不是返回全量, + * 避免误当成增量同步用。

+ */ @Override public Page query(WarehouseContext ctx, OutboundQuery query) { - YqnDtos.FindOrderRequest body = new YqnDtos.FindOrderRequest(); - body.orderNo = query.providerOrderId(); - body.customerOrderNo = query.orderRef(); - body.startTime = query.after() == null ? null - : REQUEST_TIME_FORMAT.format(query.after().atZone(zoneOf(ctx))); - body.endTime = query.before() == null ? null - : REQUEST_TIME_FORMAT.format(query.before().atZone(zoneOf(ctx))); - body.status = query.statuses().isEmpty() ? null : query.statuses().get(0); - body.pageNo = pageNumber(query.cursor()); - body.pageSize = query.pageSize(); + String orderNo = firstNonBlank(query.providerOrderId(), query.orderRef()); + if (orderNo == null) { + throw new common.ecommerce.shared.error.ValidationException( + WarehouseException.builder() + .message("yqn has no order list API; query requires providerOrderId or orderRef") + .operation("warehouse.outbound.query") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false)); + } + YqnDtos.OrderDetail detail = findOne(ctx, orderNo, "warehouse.outbound.query"); + return detail == null ? Page.empty() + : Page.last(java.util.Collections.singletonList( + YqnOutboundMapper.toOrder(detail, ctx.warehouseCode(), zoneOf(ctx)))); + } + + /** 调 findOne 并解析 data;订单不存在时返回 null。 */ + private YqnDtos.OrderDetail findOne(WarehouseContext ctx, String orderNo, String operation) { + YqnDtos.FindOneOrderRequest body = new YqnDtos.FindOneOrderRequest(); + body.orderNo = orderNo; + String raw = execute(ctx, YqnConstants.PATH_ORDER_FIND_ONE, body, operation); + com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data"); + if (data == null || data.isNull() || data.isMissingNode()) { + return null; + } + return json.fromJson(data.toString(), YqnDtos.OrderDetail.class); + } + + /** 统一引用 → 运去哪订单号(来源单号)。 */ + private static String orderNoOf(OutboundRef ref) { + String orderNo = firstNonBlank(ref.outboundRequestNo(), ref.providerOrderId()); + if (orderNo == null) { + throw new IllegalArgumentException("yqn needs outboundRequestNo to query an order"); + } + return orderNo; + } - String raw = execute(ctx, YqnConstants.PATH_ORDER_FIND, body, "warehouse.outbound.query"); - List orders = new ArrayList(); - for (YqnDtos.OrderInfo info : json.listAt(raw, "data.orders", YqnDtos.OrderInfo.class)) { - orders.add(YqnOutboundMapper.toOrder(info, ctx.warehouseCode(), zoneOf(ctx))); + private static String firstNonBlank(String a, String b) { + if (a != null && !a.trim().isEmpty()) { + return a.trim(); } - int total = intAt(raw, "data.total"); - int pageNo = body.pageNo; - int fetched = orders.size(); - String next = pageNo * body.pageSize < total && fetched > 0 - ? String.valueOf(pageNo + 1) : null; - return Page.of(orders, next); + return b == null || b.trim().isEmpty() ? null : b.trim(); } @Override @@ -217,17 +242,9 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @Override public List packages(WarehouseContext ctx, OutboundRef ref) { - OutboundOrder order = get(ctx, ref); - if (order == null) { - return java.util.Collections.emptyList(); - } - Map body = new LinkedHashMap(); - body.put("orderNo", ref.providerOrderId()); - body.put("customerOrderNo", ref.outboundRequestNo()); - String raw = execute(ctx, YqnConstants.PATH_ORDER_FIND, body, "warehouse.outbound.packages"); - YqnDtos.OrderInfo info = firstOrder(raw); - return info == null ? java.util.Collections.emptyList() - : YqnOutboundMapper.toPackages(info); + YqnDtos.OrderDetail detail = findOne(ctx, orderNoOf(ref), "warehouse.outbound.packages"); + return detail == null ? java.util.Collections.emptyList() + : YqnOutboundMapper.toPackages(detail); } // ------------------------------------------------------------------ internals @@ -270,40 +287,6 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl return YqnEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body(); } - private YqnDtos.OrderInfo firstOrder(String raw) { - List rows = json.listAt(raw, "data.orders", YqnDtos.OrderInfo.class); - if (!rows.isEmpty()) { - return rows.get(0); - } - // 单条返回时 data 就是订单对象 - com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data"); - if (data == null || data.isNull() || data.isMissingNode()) { - return null; - } - YqnDtos.OrderInfo info = json.fromJson(data.toString(), YqnDtos.OrderInfo.class); - return info == null || info.orderNo == null ? null : info; - } - - private static int pageNumber(String cursor) { - if (cursor == null || cursor.trim().isEmpty()) { - return 1; - } - try { - return Integer.parseInt(cursor.trim()); - } catch (NumberFormatException e) { - return 1; - } - } - - private int intAt(String raw, String path) { - try { - String v = json.stringAt(raw, path); - return v == null || v.trim().isEmpty() ? 0 : Integer.parseInt(v.trim()); - } catch (RuntimeException e) { - return 0; - } - } - /** 原始响应可能含 PII 与 token,异常里只留长度与首段。 */ private static String safeRelay(String raw) { if (raw == null) { diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java index 47ebf4d..6be7db8 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java @@ -19,7 +19,9 @@ import java.time.format.DateTimeFormatter; import java.time.format.DateTimeParseException; import java.util.ArrayList; import java.util.Collections; +import java.util.LinkedHashMap; import java.util.List; +import java.util.Map; /** * 运去哪报文 → 统一模型。 @@ -164,49 +166,180 @@ public final class YqnOutboundMapper { return instant == null ? null : TIME_FORMAT.format(instant.atZone(DEFAULT_ZONE)); } - /** 运去哪出库单 → 统一模型。 */ - public static OutboundOrder toOrder(YqnDtos.OrderInfo info, String warehouseCode, ZoneId zone) { + /** 订单详情 → 统一出库单(API 128)。 */ + public static OutboundOrder toOrder(YqnDtos.OrderDetail detail, String warehouseCode, ZoneId zone) { + List shippedPackages = shippedPackagesOf(detail); return OutboundOrder.builder() - .warehouseCode(warehouseCode) - .outboundRequestNo(firstNonBlank(info.customerOrderNo, info.orderNo)) - .providerOrderId(info.orderNo) - .orderRef(info.referenceNo) - .labelMode(null) // 查询结果不含面单模式,由 OMS 侧记录 - .status(toStatus(info.status)) - .rawStatus(info.status) - .carrier(info.carrier) - .trackingNumber(info.trackingNumber) - .requestedAt(parseTime(info.createTime, zone)) - .shippedAt(parseTime(info.shipTime, zone)) + .warehouseCode(firstNonBlank(detail.warehouseCode, warehouseCode)) + .outboundRequestNo(firstNonBlank(detail.orderNo, null)) + .orderRef(null) // API 128 不返回平台单号 + .status(toStatus(detail.orderStatusEnum)) + .rawStatus(detail.orderStatusEnum) + .carrier(packagesCarrierOf(shippedPackages, detail.carrierCode)) + .trackingNumber(firstTrackingOf(shippedPackages)) + .carrierCode(detail.carrierCode) + .currency(detail.currency) + .paidAt(parseTime(detail.paidAt, zone)) + .shippedAt(firstShipmentTime(shippedPackages, zone)) + .lines(toLines(detail.productItems)) + .shipTo(toShipTo(detail)) + .exceptionCode(exceptionOf(detail.errorCode)) + .estimatedShippingFee(moneyOrNull(detail.estimatedShippingFee, detail.currency)) .sourceProvider(WarehouseProvider.YQN) .build(); } - /** 出库单 → 包裹列表;一单多包裹时逐个返回。 */ - public static List toPackages(YqnDtos.OrderInfo info) { - if (info.packages == null || info.packages.isEmpty()) { - if (info.trackingNumber == null) { - return Collections.emptyList(); + /** + * 发货包裹 → 统一包裹列表(API 128)。 + * + *

{@code shipmentPackages} 里 {@code packageFlag=1} 是面单信息行, + * 同一个 trackingNo 可能与实际包裹重复出现;按 trackingNo 去重, + * 面单行没有 trackingNo 时跳过,避免虚增包裹数。

+ */ + public static List toPackages(YqnDtos.OrderDetail detail) { + if (detail.shipmentPackages == null || detail.shipmentPackages.isEmpty()) { + return Collections.emptyList(); + } + // 两遍:先放实际包裹(packageFlag=0),再补面单信息行(packageFlag=1), + // 同一个 trackingNo 只保留一条,且以实际包裹为准 + Map byKey = new LinkedHashMap(); + for (YqnDtos.OrderDetail.ShipmentPackage pkg : detail.shipmentPackages) { + if (isActualPackage(pkg)) { + putPackage(byKey, pkg, detail.orderNo); } - return Collections.singletonList(PackageResult.builder() - .packageId(firstNonBlank(info.orderNo, info.customerOrderNo)) - .outboundRequestNo(firstNonBlank(info.customerOrderNo, info.orderNo)) - .trackingNumber(info.trackingNumber) - .carrier(info.carrier) - .labelRef(info.labelUrl) - .build()); } - List out = new ArrayList(info.packages.size()); - for (YqnDtos.Package pkg : info.packages) { - out.add(PackageResult.builder() - .packageId(firstNonBlank(pkg.packageNo, info.orderNo)) - .outboundRequestNo(firstNonBlank(info.customerOrderNo, info.orderNo)) - .trackingNumber(pkg.trackingNumber) - .carrier(pkg.carrier) - .labelRef(pkg.labelUrl) + for (YqnDtos.OrderDetail.ShipmentPackage pkg : detail.shipmentPackages) { + if (!isActualPackage(pkg)) { + putPackage(byKey, pkg, detail.orderNo); + } + } + return new ArrayList(byKey.values()); + } + + private static void putPackage(Map byKey, + YqnDtos.OrderDetail.ShipmentPackage pkg, String orderNo) { + String tracking = pkg.trackingNo == null ? null : pkg.trackingNo.trim(); + String key = hasText(tracking) ? tracking : "SKU-" + pkg.erpSku; + if (byKey.containsKey(key)) { + return; + } + byKey.put(key, PackageResult.builder() + .packageId(key) + .outboundRequestNo(orderNo) + .trackingNumber(tracking) + .carrier(pkg.carrier) + .carrierServiceCode(pkg.carrierServiceCode) + .erpSku(pkg.erpSku) + .shippedQuantity(pkg.shipedQuantity) + .shippedAt(parseTime(pkg.shipmentDate, DEFAULT_ZONE)) + .build()); + } + + /** 是否实际包裹(packageFlag=0 或缺失)。 */ + private static boolean isActualPackage(YqnDtos.OrderDetail.ShipmentPackage pkg) { + return pkg.packageFlag == null || pkg.packageFlag == 0; + } + + /** 实际包裹优先;只用于取顶层承运商与跟踪号。 */ + static List shippedPackagesOf(YqnDtos.OrderDetail detail) { + if (detail.shipmentPackages == null) { + return Collections.emptyList(); + } + List actual = + new ArrayList(); + for (YqnDtos.OrderDetail.ShipmentPackage pkg : detail.shipmentPackages) { + if (isActualPackage(pkg)) { + actual.add(pkg); + } + } + return actual.isEmpty() ? detail.shipmentPackages : actual; + } + + private static String packagesCarrierOf(List packages, + String fallbackCarrierCode) { + for (YqnDtos.OrderDetail.ShipmentPackage pkg : packages) { + if (hasText(pkg.carrier)) { + return pkg.carrier; + } + } + return fallbackCarrierCode; + } + + private static String firstTrackingOf(List packages) { + for (YqnDtos.OrderDetail.ShipmentPackage pkg : packages) { + if (hasText(pkg.trackingNo)) { + return pkg.trackingNo; + } + } + return null; + } + + private static Instant firstShipmentTime(List packages, ZoneId zone) { + for (YqnDtos.OrderDetail.ShipmentPackage pkg : packages) { + Instant time = parseTime(pkg.shipmentDate, zone); + if (time != null) { + return time; + } + } + return null; + } + + private static List toLines(List items) { + if (items == null || items.isEmpty()) { + return Collections.emptyList(); + } + List lines = new ArrayList(items.size()); + for (YqnDtos.OrderDetail.DetailProductItem item : items) { + if (!hasText(item.sku)) { + continue; + } + lines.add(OutboundLine.builder() + .lineNo(firstNonBlank(item.lineNo, item.sku)) + .omsSku(item.sku) + .providerSku(item.sku) + .quantity(item.quantity == null ? 0 : item.quantity) .build()); } - return out; + return lines; + } + + /** 详情里没有任何地址字段时返回 null,避免把「空地址」当成真实地址回传给业务。 */ + private static ShipTo toShipTo(YqnDtos.OrderDetail detail) { + if (!hasText(detail.shipToCountry) && !hasText(detail.shipToAddress1) + && !hasText(detail.shipToCity) && !hasText(detail.shipToContact)) { + return null; + } + return ShipTo.builder() + .name(detail.shipToContact) + .phone(detail.shipToTelephone) + .countryCode(detail.shipToCountry) + .stateOrProvince(detail.shipToState) + .city(detail.shipToCity) + .addressLine1(detail.shipToAddress1) + .addressLine2(detail.shipToAddress2) + .addressLine3(detail.shipToAddress3) + .postalCode(detail.shipToPostal) + .build(); + } + + /** {@code unexception} 或空视为无异常。 */ + private static String exceptionOf(String errorCode) { + if (!hasText(errorCode) || "unexception".equalsIgnoreCase(errorCode.trim())) { + return null; + } + return errorCode.trim(); + } + + private static Money moneyOrNull(Double amount, String currency) { + if (amount == null) { + return null; + } + return Money.of(java.math.BigDecimal.valueOf(amount), + currency == null || currency.trim().isEmpty() ? "USD" : currency.trim()); + } + + private static boolean hasText(String v) { + return v != null && !v.trim().isEmpty(); } /** 运去哪状态 → 统一状态;未知按 {@link OutboundStatus#SUBMITTED}。待打样核对映射表。 */ 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 bd70e0f..87268d1 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 @@ -181,52 +181,143 @@ public final class YqnDtos { public Long orderId; } - /** 出库单查询请求。 */ - public static final class FindOrderRequest { + /** 订单详情请求(API 128):只按来源单号查。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class FindOneOrderRequest { + /** 订单号;运去哪指我们下发时的 {@code orderNo}(来源单号)。 */ public String orderNo; - public String customerOrderNo; - public String startTime; - public String endTime; - public String status; - public int pageNo; - public int pageSize; } - /** 出库单查询响应。 */ - public static final class FindOrderResponse { + /** + * 订单详情响应 {@code data}(API 128)。 + * + *

注意:这份响应没有 statusCode/status,只有 {@code code/message/data}; + * {@code data} 内也没有 {@code carrier}/{@code trackingNo} 顶层字段, + * 运单与包裹在 {@link #shipmentPackages}。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class OrderDetail { - public List orders; - public int total; - public int pageNo; - public int pageSize; - } + public String orderNo; + /** 支付时间 {@code yyyy-MM-dd HH:mm:ss}。 */ + public String paidAt; + public String shipToContact; + public String shipToAddress1; + public String shipToAddress2; + public String shipToAddress3; + public String shipToCity; + public String shipToState; + public String shipToCountry; + public String shipToPostal; + public String shipToTelephone; + /** 仓 code,可能因分仓规则与下单时不同。 */ + public String warehouseCode; + /** 承运商 code。 */ + public String carrierCode; + public String thirdPartyAccount; + public String currency; + /** 是否签收 0 否 / 1 是。 */ + public Integer isSignature; + /** 是否保价 0 否 / 1 是。 */ + public Integer isInsure; + /** pending / unshipped / approved / assigned / picked / shipped / canceled / refunded。 */ + public String orderStatusEnum; + /** 异常码;无异常为 {@code unexception}。 */ + public String errorCode; + /** 预估运费,默认币种 USD。 */ + public Double estimatedShippingFee; + public List productItems; + public List enclosure; + /** 发货信息;未发货时为 null 或空。 */ + public List shipmentPackages; + /** SKU ORD 列表。 */ + public List ordList; + /** 采集 SN 信息。 */ + public List orderSnInfo; + + /** 商品行。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class DetailProductItem { + public String sku; + public Integer quantity; + public String parentErpsku; + /** 0 单一产品 / 2 箱产品。 */ + public Integer saleType; + public Integer standardQuantity; + public Double skuAmount; + public Double insureAmount; + public String lineNo; + public BatchInfo batchInfo; + } - /** 出库单。 */ - public static final class OrderInfo { + /** 批次信息。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class BatchInfo { + public List planBatchItems; + public List outboundBatchItems; + } - public String orderNo; - public String customerOrderNo; - public String referenceNo; - public String status; - public String trackingNumber; - public String carrier; - public String labelUrl; - /** 拆单后的包裹;运去哪可能一单多包裹(§8.6 第 9 项待核对)。 */ - public List packages; - /** 创建时间。 */ - public String createTime; - /** 出库时间。 */ - public String shipTime; - } + /** 一条批次。 */ + public static final class BatchItem { + public Integer qty; + public List batchParam; + } - /** 包裹。 */ - public static final class Package { + /** 批次属性键值。 */ + public static final class BatchParam { + public String batchAttriKey; + public String batchAttriValue; + } - public String packageNo; - public String trackingNumber; - public String carrier; - public String labelUrl; + /** 附件。 */ + public static final class Enclosure { + public String type; + public String name; + public String url; + } + + /** + * 发货包裹。 + * + *

{@code packageFlag} 0 实际包裹 / 1 面单信息; + * 面单信息行也有 trackingNo,拼包裹时不要重复计数。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ShipmentPackage { + public String trackingNo; + public String carrier; + public String erpSku; + public Double cost; + public Integer shipedQuantity; + public String shipmentDate; + public Integer packageFlag; + public String carrierCode; + public String carrierServiceCode; + } + + /** SKU 的 ORD 列表。 */ + public static final class OrdItem { + public String sku; + public List skuOrdList; + } + + /** 采集的 SN 信息。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class SnInfo { + public String sku; + public String productId; + public List snList; + } + + /** 单条 SN。 */ + public static final class SnItem { + public String sku; + public String snCode; + public String lineNo; + public Integer productId; + public Integer deliverOrderItemId; + } } /** 取消请求。 */ diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java index 431b39c..7fe5f93 100644 --- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java @@ -108,31 +108,45 @@ class YqnAdapterTest { } @Test - void getMapsStatusAndTracking() { + void getMapsStatusTrackingAndLines() { RecordingTransport transport = RecordingTransport.create() - .route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok( - "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orders\":[{\"orderNo\":\"YQN1\"," - + "\"customerOrderNo\":\"OB-3\",\"status\":\"SHIPPED\"," - + "\"trackingNumber\":\"TRK1\",\"carrier\":\"FEDEX\"," - + "\"createTime\":\"2026-11-08 10:00:00\"}]}}")); + .route(YqnConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok( + "{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-3\"," + + "\"paidAt\":\"2026-11-08 09:00:00\",\"orderStatusEnum\":\"shipped\"," + + "\"warehouseCode\":\"RF_NY_US\",\"currency\":\"USD\"," + + "\"carrierCode\":\"WLC-FEDEX\",\"errorCode\":\"unexception\"," + + "\"shipToCountry\":\"US\",\"shipToCity\":\"New York\"," + + "\"estimatedShippingFee\":\"8.5\"," + + "\"productItems\":[{\"sku\":\"DM00001\",\"quantity\":2,\"lineNo\":\"1\"}]," + + "\"shipmentPackages\":[{\"trackingNo\":\"TRK1\",\"carrier\":\"FEDEX\"," + + "\"erpSku\":\"DM00001\",\"shipedQuantity\":2,\"packageFlag\":0," + + "\"shipmentDate\":\"2026-11-08 12:00:00\"}]}}")); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); common.ecommerce.warehouse.model.OutboundOrder order = adapter.get(ctx(), OutboundRef.ofRequestNo("OB-3")); assertEquals("OB-3", order.outboundRequestNo()); - assertEquals("YQN1", order.providerOrderId()); assertEquals(OutboundStatus.SHIPPED, order.status()); assertEquals("TRK1", order.trackingNumber()); - assertEquals(Instant.parse("2026-11-08T02:00:00Z"), order.requestedAt()); + assertEquals("FEDEX", order.carrier()); + assertEquals("WLC-FEDEX", order.carrierCode()); + assertEquals(Instant.parse("2026-11-08T01:00:00Z"), order.paidAt()); + assertEquals(Instant.parse("2026-11-08T04:00:00Z"), order.shippedAt()); + assertEquals(1, order.lines().size()); + assertEquals(2, order.lines().get(0).quantity()); + assertEquals("US", order.shipTo().countryCode()); + assertEquals("8.5", order.estimatedShippingFee().amount().toPlainString()); + assertEquals(null, order.exceptionCode()); + assertFalse(order.hasException()); } @Test void checkCancelBlocksShippedOrder() { RecordingTransport transport = RecordingTransport.create() - .route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok( - "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orders\":[{\"orderNo\":\"YQN1\"," - + "\"customerOrderNo\":\"OB-4\",\"status\":\"SHIPPED\"}]}}")); + .route(YqnConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok( + "{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-4\"," + + "\"orderStatusEnum\":\"shipped\"}}")); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); assertEquals(CancelEligibility.BLOCKED,