Browse Source

feat(yqn): 按 API 128 对接订单详情

- 路径 /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 <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
ac8a164982
  1. 108
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
  2. 45
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/PackageResult.java
  3. 15
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ShipTo.java
  4. 4
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  5. 127
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  6. 201
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
  7. 165
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  8. 36
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java

108
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java

@ -1,8 +1,12 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.WarehouseProvider;
import java.time.Instant; 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 Instant shippedAt;
/** 接入通道。 */ /** 接入通道。 */
private final WarehouseProvider sourceProvider; private final WarehouseProvider sourceProvider;
/** 商品行;查询详情时回填。 */
private final List<OutboundLine> 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) { private OutboundOrder(Builder b) {
this.warehouseCode = requireText(b.warehouseCode, "warehouseCode"); this.warehouseCode = requireText(b.warehouseCode, "warehouseCode");
@ -50,6 +68,14 @@ public final class OutboundOrder {
this.requestedAt = b.requestedAt; this.requestedAt = b.requestedAt;
this.shippedAt = b.shippedAt; this.shippedAt = b.shippedAt;
this.sourceProvider = b.sourceProvider; this.sourceProvider = b.sourceProvider;
this.lines = b.lines == null ? Collections.<OutboundLine>emptyList()
: Collections.unmodifiableList(new ArrayList<OutboundLine>(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() { public static Builder builder() {
@ -104,6 +130,46 @@ public final class OutboundOrder {
return sourceProvider; return sourceProvider;
} }
/** 商品行;未查询详情时为空列表。 */
public List<OutboundLine> 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) { private static String requireText(String value, String name) {
if (value == null || value.trim().isEmpty()) { if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank"); throw new IllegalArgumentException(name + " must not be blank");
@ -125,6 +191,13 @@ public final class OutboundOrder {
private Instant requestedAt; private Instant requestedAt;
private Instant shippedAt; private Instant shippedAt;
private WarehouseProvider sourceProvider; private WarehouseProvider sourceProvider;
private List<OutboundLine> lines;
private ShipTo shipTo;
private String exceptionCode;
private Money estimatedShippingFee;
private Instant paidAt;
private String carrierCode;
private String currency;
public Builder warehouseCode(String warehouseCode) { public Builder warehouseCode(String warehouseCode) {
this.warehouseCode = warehouseCode; this.warehouseCode = warehouseCode;
@ -186,6 +259,41 @@ public final class OutboundOrder {
return this; return this;
} }
public Builder lines(List<OutboundLine> 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() { public OutboundOrder build() {
return new OutboundOrder(this); return new OutboundOrder(this);
} }

45
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 common.ecommerce.shared.support.Money;
import java.time.Instant; 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 String labelRef;
private final Money weight; private final Money weight;
private final Instant shippedAt; 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) { private PackageResult(Builder b) {
this.packageId = requireText(b.packageId, "packageId"); this.packageId = requireText(b.packageId, "packageId");
@ -25,6 +34,9 @@ public final class PackageResult {
this.labelRef = b.labelRef; this.labelRef = b.labelRef;
this.weight = b.weight; this.weight = b.weight;
this.shippedAt = b.shippedAt; this.shippedAt = b.shippedAt;
this.carrierServiceCode = b.carrierServiceCode;
this.erpSku = b.erpSku;
this.shippedQuantity = b.shippedQuantity;
} }
public static Builder builder() { public static Builder builder() {
@ -61,6 +73,21 @@ public final class PackageResult {
return shippedAt; 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) { private static String requireText(String value, String name) {
if (value == null || value.trim().isEmpty()) { if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank"); throw new IllegalArgumentException(name + " must not be blank");
@ -77,6 +104,9 @@ public final class PackageResult {
private String labelRef; private String labelRef;
private Money weight; private Money weight;
private Instant shippedAt; private Instant shippedAt;
private String carrierServiceCode;
private String erpSku;
private Integer shippedQuantity;
public Builder packageId(String packageId) { public Builder packageId(String packageId) {
this.packageId = packageId; this.packageId = packageId;
@ -113,6 +143,21 @@ public final class PackageResult {
return this; 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() { public PackageResult build() {
return new PackageResult(this); return new PackageResult(this);
} }

15
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 addressLine3;
private final String postalCode; private final String postalCode;
/**
* 只做字段搬运,不校验必填。
*
* <p>「哪些字段必填」是<b>仓方协议</b>的约束,由各适配器在下发时校验;
* 这里放宽是为了让查询回来的详情也能原样承载(仓方未返回的字段为 null)。
* 下单时缺必填字段由适配器抛 {@code ValidationException}。</p>
*/
private ShipTo(Builder b) { private ShipTo(Builder b) {
this.name = Objects.requireNonNull(b.name, "name"); this.name = b.name;
this.phone = b.phone; this.phone = b.phone;
this.email = b.email; this.email = b.email;
this.countryCode = Objects.requireNonNull(b.countryCode, "countryCode"); this.countryCode = b.countryCode;
this.stateOrProvince = b.stateOrProvince; this.stateOrProvince = b.stateOrProvince;
this.city = Objects.requireNonNull(b.city, "city"); this.city = b.city;
this.addressLine1 = Objects.requireNonNull(b.addressLine1, "addressLine1"); this.addressLine1 = b.addressLine1;
this.addressLine2 = b.addressLine2; this.addressLine2 = b.addressLine2;
this.addressLine3 = b.addressLine3; this.addressLine3 = b.addressLine3;
this.postalCode = b.postalCode; this.postalCode = b.postalCode;

4
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"; public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/** 创建销售订单(API 123)。 */ /** 创建销售订单(API 123)。 */
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create"; public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/** 出库单查询。 */ /** 订单详情(API 128):按来源单号查完整订单。 */
public static final String PATH_ORDER_FIND = "/saleorder/FindOrderInfor"; public static final String PATH_ORDER_FIND_ONE = "/v1/saleOrder/findOne";
/** 出库单取消。 */ /** 出库单取消。 */
public static final String PATH_ORDER_CANCEL = "/saleorder/OrderCancel"; public static final String PATH_ORDER_CANCEL = "/saleorder/OrderCancel";
/** 批量库存查询。 */ /** 批量库存查询。 */

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

@ -124,39 +124,64 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
@Override @Override
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
Map<String, Object> body = new LinkedHashMap<String, Object>(); // API 128 只按来源单号查;仓内部 id 查不了,调用方要给 outboundRequestNo
body.put("orderNo", ref.providerOrderId()); String orderNo = orderNoOf(ref);
body.put("customerOrderNo", ref.outboundRequestNo()); YqnDtos.OrderDetail detail = findOne(ctx, orderNo, "warehouse.outbound.get");
return detail == null ? null : YqnOutboundMapper.toOrder(detail, ctx.warehouseCode(), zoneOf(ctx));
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));
} }
/**
* 按条件查询。
*
* <p>运去哪的订单查询接口是「按单号取详情」,没有列表/时间窗接口,
* 因此这里按单号逐个取;没有单号时<b>拒绝</b>而不是返回全量,
* 避免误当成增量同步用。</p>
*/
@Override @Override
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) { public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) {
YqnDtos.FindOrderRequest body = new YqnDtos.FindOrderRequest(); String orderNo = firstNonBlank(query.providerOrderId(), query.orderRef());
body.orderNo = query.providerOrderId(); if (orderNo == null) {
body.customerOrderNo = query.orderRef(); throw new common.ecommerce.shared.error.ValidationException(
body.startTime = query.after() == null ? null WarehouseException.builder()
: REQUEST_TIME_FORMAT.format(query.after().atZone(zoneOf(ctx))); .message("yqn has no order list API; query requires providerOrderId or orderRef")
body.endTime = query.before() == null ? null .operation("warehouse.outbound.query")
: REQUEST_TIME_FORMAT.format(query.before().atZone(zoneOf(ctx))); .warehouseCode(ctx.warehouseCode())
body.status = query.statuses().isEmpty() ? null : query.statuses().get(0); .provider(provider().name())
body.pageNo = pageNumber(query.cursor()); .requestId(ctx.requestId())
body.pageSize = query.pageSize(); .retryable(false));
}
YqnDtos.OrderDetail detail = findOne(ctx, orderNo, "warehouse.outbound.query");
return detail == null ? Page.<OutboundOrder>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"); private static String firstNonBlank(String a, String b) {
List<OutboundOrder> orders = new ArrayList<OutboundOrder>(); if (a != null && !a.trim().isEmpty()) {
for (YqnDtos.OrderInfo info : json.listAt(raw, "data.orders", YqnDtos.OrderInfo.class)) { return a.trim();
orders.add(YqnOutboundMapper.toOrder(info, ctx.warehouseCode(), zoneOf(ctx)));
} }
int total = intAt(raw, "data.total"); return b == null || b.trim().isEmpty() ? null : b.trim();
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);
} }
@Override @Override
@ -217,17 +242,9 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
@Override @Override
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) { public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) {
OutboundOrder order = get(ctx, ref); YqnDtos.OrderDetail detail = findOne(ctx, orderNoOf(ref), "warehouse.outbound.packages");
if (order == null) { return detail == null ? java.util.Collections.<PackageResult>emptyList()
return java.util.Collections.emptyList(); : YqnOutboundMapper.toPackages(detail);
}
Map<String, Object> body = new LinkedHashMap<String, Object>();
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.<PackageResult>emptyList()
: YqnOutboundMapper.toPackages(info);
} }
// ------------------------------------------------------------------ internals // ------------------------------------------------------------------ internals
@ -270,40 +287,6 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
return YqnEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body(); return YqnEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body();
} }
private YqnDtos.OrderInfo firstOrder(String raw) {
List<YqnDtos.OrderInfo> 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,异常里只留长度与首段。 */ /** 原始响应可能含 PII 与 token,异常里只留长度与首段。 */
private static String safeRelay(String raw) { private static String safeRelay(String raw) {
if (raw == null) { if (raw == null) {

201
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.time.format.DateTimeParseException;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.Collections; import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List; 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)); return instant == null ? null : TIME_FORMAT.format(instant.atZone(DEFAULT_ZONE));
} }
/** 运去哪出库单 → 统一模型。 */ /** 订单详情 → 统一出库单(API 128)。 */
public static OutboundOrder toOrder(YqnDtos.OrderInfo info, String warehouseCode, ZoneId zone) { public static OutboundOrder toOrder(YqnDtos.OrderDetail detail, String warehouseCode, ZoneId zone) {
List<YqnDtos.OrderDetail.ShipmentPackage> shippedPackages = shippedPackagesOf(detail);
return OutboundOrder.builder() return OutboundOrder.builder()
.warehouseCode(warehouseCode) .warehouseCode(firstNonBlank(detail.warehouseCode, warehouseCode))
.outboundRequestNo(firstNonBlank(info.customerOrderNo, info.orderNo)) .outboundRequestNo(firstNonBlank(detail.orderNo, null))
.providerOrderId(info.orderNo) .orderRef(null) // API 128 不返回平台单号
.orderRef(info.referenceNo) .status(toStatus(detail.orderStatusEnum))
.labelMode(null) // 查询结果不含面单模式,由 OMS 侧记录 .rawStatus(detail.orderStatusEnum)
.status(toStatus(info.status)) .carrier(packagesCarrierOf(shippedPackages, detail.carrierCode))
.rawStatus(info.status) .trackingNumber(firstTrackingOf(shippedPackages))
.carrier(info.carrier) .carrierCode(detail.carrierCode)
.trackingNumber(info.trackingNumber) .currency(detail.currency)
.requestedAt(parseTime(info.createTime, zone)) .paidAt(parseTime(detail.paidAt, zone))
.shippedAt(parseTime(info.shipTime, 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) .sourceProvider(WarehouseProvider.YQN)
.build(); .build();
} }
/** 出库单 → 包裹列表;一单多包裹时逐个返回。 */ /**
public static List<PackageResult> toPackages(YqnDtos.OrderInfo info) { * 发货包裹 → 统一包裹列表(API 128)。
if (info.packages == null || info.packages.isEmpty()) { *
if (info.trackingNumber == null) { * <p>{@code shipmentPackages} 里 {@code packageFlag=1} 是面单信息行,
return Collections.emptyList(); * 同一个 trackingNo 可能与实际包裹重复出现;按 trackingNo 去重,
* 面单行没有 trackingNo 时跳过,避免虚增包裹数。</p>
*/
public static List<PackageResult> toPackages(YqnDtos.OrderDetail detail) {
if (detail.shipmentPackages == null || detail.shipmentPackages.isEmpty()) {
return Collections.emptyList();
}
// 两遍:先放实际包裹(packageFlag=0),再补面单信息行(packageFlag=1),
// 同一个 trackingNo 只保留一条,且以实际包裹为准
Map<String, PackageResult> byKey = new LinkedHashMap<String, PackageResult>();
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<PackageResult> out = new ArrayList<PackageResult>(info.packages.size()); for (YqnDtos.OrderDetail.ShipmentPackage pkg : detail.shipmentPackages) {
for (YqnDtos.Package pkg : info.packages) { if (!isActualPackage(pkg)) {
out.add(PackageResult.builder() putPackage(byKey, pkg, detail.orderNo);
.packageId(firstNonBlank(pkg.packageNo, info.orderNo)) }
.outboundRequestNo(firstNonBlank(info.customerOrderNo, info.orderNo)) }
.trackingNumber(pkg.trackingNumber) return new ArrayList<PackageResult>(byKey.values());
.carrier(pkg.carrier) }
.labelRef(pkg.labelUrl)
private static void putPackage(Map<String, PackageResult> 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<YqnDtos.OrderDetail.ShipmentPackage> shippedPackagesOf(YqnDtos.OrderDetail detail) {
if (detail.shipmentPackages == null) {
return Collections.emptyList();
}
List<YqnDtos.OrderDetail.ShipmentPackage> actual =
new ArrayList<YqnDtos.OrderDetail.ShipmentPackage>();
for (YqnDtos.OrderDetail.ShipmentPackage pkg : detail.shipmentPackages) {
if (isActualPackage(pkg)) {
actual.add(pkg);
}
}
return actual.isEmpty() ? detail.shipmentPackages : actual;
}
private static String packagesCarrierOf(List<YqnDtos.OrderDetail.ShipmentPackage> packages,
String fallbackCarrierCode) {
for (YqnDtos.OrderDetail.ShipmentPackage pkg : packages) {
if (hasText(pkg.carrier)) {
return pkg.carrier;
}
}
return fallbackCarrierCode;
}
private static String firstTrackingOf(List<YqnDtos.OrderDetail.ShipmentPackage> packages) {
for (YqnDtos.OrderDetail.ShipmentPackage pkg : packages) {
if (hasText(pkg.trackingNo)) {
return pkg.trackingNo;
}
}
return null;
}
private static Instant firstShipmentTime(List<YqnDtos.OrderDetail.ShipmentPackage> 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<OutboundLine> toLines(List<YqnDtos.OrderDetail.DetailProductItem> items) {
if (items == null || items.isEmpty()) {
return Collections.emptyList();
}
List<OutboundLine> lines = new ArrayList<OutboundLine>(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()); .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}。待打样核对映射表。 */ /** 运去哪状态 → 统一状态;未知按 {@link OutboundStatus#SUBMITTED}。待打样核对映射表。 */

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

@ -181,52 +181,143 @@ public final class YqnDtos {
public Long orderId; public Long orderId;
} }
/** 出库单查询请求。 */ /** 订单详情请求(API 128):只按来源单号查。 */
public static final class FindOrderRequest { @JsonInclude(JsonInclude.Include.NON_NULL)
public static final class FindOneOrderRequest {
/** 订单号;运去哪指我们下发时的 {@code orderNo}(来源单号)。 */
public String 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)。
*
* <p>注意:这份响应<b>没有 statusCode/status</b>,只有 {@code code/message/data};
* {@code data} 内也没有 {@code carrier}/{@code trackingNo} 顶层字段,
* 运单与包裹在 {@link #shipmentPackages}。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class OrderDetail {
public List<OrderInfo> orders; public String orderNo;
public int total; /** 支付时间 {@code yyyy-MM-dd HH:mm:ss}。 */
public int pageNo; public String paidAt;
public int pageSize; 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<DetailProductItem> productItems;
public List<Enclosure> enclosure;
/** 发货信息;未发货时为 null 或空。 */
public List<ShipmentPackage> shipmentPackages;
/** SKU ORD 列表。 */
public List<OrdItem> ordList;
/** 采集 SN 信息。 */
public List<SnInfo> 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<BatchItem> planBatchItems;
public List<BatchItem> outboundBatchItems;
}
public String orderNo; /** 一条批次。 */
public String customerOrderNo; public static final class BatchItem {
public String referenceNo; public Integer qty;
public String status; public List<BatchParam> batchParam;
public String trackingNumber; }
public String carrier;
public String labelUrl;
/** 拆单后的包裹;运去哪可能一单多包裹(§8.6 第 9 项待核对)。 */
public List<Package> packages;
/** 创建时间。 */
public String createTime;
/** 出库时间。 */
public String shipTime;
}
/** 包裹。 */ /** 批次属性键值。 */
public static final class Package { public static final class BatchParam {
public String batchAttriKey;
public String batchAttriValue;
}
public String packageNo; /** 附件。 */
public String trackingNumber; public static final class Enclosure {
public String carrier; public String type;
public String labelUrl; public String name;
public String url;
}
/**
* 发货包裹。
*
* <p>{@code packageFlag} 0 实际包裹 / 1 面单信息;
* 面单信息行也有 trackingNo,拼包裹时不要重复计数。</p>
*/
@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<String> skuOrdList;
}
/** 采集的 SN 信息。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SnInfo {
public String sku;
public String productId;
public List<SnItem> snList;
}
/** 单条 SN。 */
public static final class SnItem {
public String sku;
public String snCode;
public String lineNo;
public Integer productId;
public Integer deliverOrderItemId;
}
} }
/** 取消请求。 */ /** 取消请求。 */

36
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java

@ -108,31 +108,45 @@ class YqnAdapterTest {
} }
@Test @Test
void getMapsStatusAndTracking() { void getMapsStatusTrackingAndLines() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok( .route(YqnConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orders\":[{\"orderNo\":\"YQN1\"," "{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-3\","
+ "\"customerOrderNo\":\"OB-3\",\"status\":\"SHIPPED\"," + "\"paidAt\":\"2026-11-08 09:00:00\",\"orderStatusEnum\":\"shipped\","
+ "\"trackingNumber\":\"TRK1\",\"carrier\":\"FEDEX\"," + "\"warehouseCode\":\"RF_NY_US\",\"currency\":\"USD\","
+ "\"createTime\":\"2026-11-08 10:00:00\"}]}}")); + "\"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()); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
common.ecommerce.warehouse.model.OutboundOrder order = common.ecommerce.warehouse.model.OutboundOrder order =
adapter.get(ctx(), OutboundRef.ofRequestNo("OB-3")); adapter.get(ctx(), OutboundRef.ofRequestNo("OB-3"));
assertEquals("OB-3", order.outboundRequestNo()); assertEquals("OB-3", order.outboundRequestNo());
assertEquals("YQN1", order.providerOrderId());
assertEquals(OutboundStatus.SHIPPED, order.status()); assertEquals(OutboundStatus.SHIPPED, order.status());
assertEquals("TRK1", order.trackingNumber()); 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 @Test
void checkCancelBlocksShippedOrder() { void checkCancelBlocksShippedOrder() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok( .route(YqnConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orders\":[{\"orderNo\":\"YQN1\"," "{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-4\","
+ "\"customerOrderNo\":\"OB-4\",\"status\":\"SHIPPED\"}]}}")); + "\"orderStatusEnum\":\"shipped\"}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
assertEquals(CancelEligibility.BLOCKED, assertEquals(CancelEligibility.BLOCKED,

Loading…
Cancel
Save