You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
810 lines
39 KiB
810 lines
39 KiB
package common.ecommerce.yqn.adapter; |
|
|
|
import common.ecommerce.yqn.dto.YqnBoxLabelDtos; |
|
import common.ecommerce.yqn.dto.YqnCancelOrderDtos; |
|
import common.ecommerce.yqn.dto.YqnCreateInboundDtos; |
|
import common.ecommerce.yqn.dto.YqnCreateOrderDtos; |
|
import common.ecommerce.yqn.dto.YqnCreateSaleReturnDtos; |
|
import common.ecommerce.yqn.dto.YqnDestroyPlanDtos; |
|
import common.ecommerce.yqn.dto.YqnFeeDetailDtos; |
|
import common.ecommerce.yqn.dto.YqnFeeEstimateDtos; |
|
import common.ecommerce.yqn.dto.YqnInboundPlanDtos; |
|
import common.ecommerce.yqn.dto.YqnInventoryDtos; |
|
import common.ecommerce.yqn.dto.YqnLogisticsProductDtos; |
|
import common.ecommerce.yqn.dto.YqnOrderDetailDtos; |
|
import common.ecommerce.yqn.dto.YqnProductDtos; |
|
import common.ecommerce.yqn.dto.YqnReturnProcessDtos; |
|
import common.ecommerce.yqn.dto.YqnSkuLabelDtos; |
|
import common.ecommerce.yqn.dto.YqnTrackingDtos; |
|
import common.ecommerce.yqn.dto.YqnTransferDtos; |
|
import common.ecommerce.yqn.dto.YqnWarehouseDtos; |
|
import common.ecommerce.http.HttpRequest; |
|
import common.ecommerce.http.HttpResponse; |
|
import common.ecommerce.http.HttpTransport; |
|
import common.ecommerce.http.JacksonJsonCodec; |
|
import common.ecommerce.shared.error.PlatformBusinessException; |
|
import common.ecommerce.shared.support.Page; |
|
import common.ecommerce.warehouse.enums.WarehouseCapability; |
|
import common.ecommerce.warehouse.enums.WarehouseProvider; |
|
import common.ecommerce.warehouse.capability.OutboundCapable; |
|
import common.ecommerce.warehouse.model.BillingDocument; |
|
import common.ecommerce.warehouse.model.FeeQuery; |
|
import common.ecommerce.warehouse.capability.InboundCapable; |
|
import common.ecommerce.warehouse.model.InboundCommand; |
|
import common.ecommerce.warehouse.model.InboundOrder; |
|
import common.ecommerce.warehouse.model.InboundReceipt; |
|
import common.ecommerce.warehouse.model.InventoryQuery; |
|
import common.ecommerce.warehouse.model.ReturnCommand; |
|
import common.ecommerce.warehouse.model.ReturnProcessCommand; |
|
import common.ecommerce.warehouse.model.TransferCommand; |
|
import common.ecommerce.warehouse.model.WarehouseReturn; |
|
import common.ecommerce.warehouse.model.TransferOrder; |
|
import common.ecommerce.warehouse.model.InventorySnapshot; |
|
import common.ecommerce.warehouse.enums.InventorySyncStrategy; |
|
import common.ecommerce.warehouse.capability.WarehouseProduct; |
|
import common.ecommerce.warehouse.capability.InventoryCapable; |
|
import common.ecommerce.warehouse.capability.LogisticsProductCapable; |
|
import common.ecommerce.warehouse.capability.TransferCapable; |
|
import common.ecommerce.warehouse.capability.WarehouseReturnCapable; |
|
import common.ecommerce.warehouse.capability.DestructionCapable; |
|
import common.ecommerce.warehouse.capability.TrackingCapable; |
|
import common.ecommerce.warehouse.capability.WarehouseFeeCapable; |
|
import common.ecommerce.warehouse.model.BoxLabelCommand; |
|
import common.ecommerce.warehouse.model.DestructionCommand; |
|
import common.ecommerce.warehouse.model.DestructionOrder; |
|
import common.ecommerce.warehouse.model.LabelPrintTask; |
|
import common.ecommerce.warehouse.model.LogisticsProduct; |
|
import common.ecommerce.warehouse.model.WarehouseInfo; |
|
import common.ecommerce.warehouse.model.SkuLabelCommand; |
|
import common.ecommerce.warehouse.model.TrackEvent; |
|
import common.ecommerce.warehouse.model.TrackingInfo; |
|
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; |
|
import common.ecommerce.warehouse.model.FeeEstimateQuery; |
|
import common.ecommerce.warehouse.model.FeeEstimateResult; |
|
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; |
|
import common.ecommerce.warehouse.capability.WarehouseProductCapable; |
|
import common.ecommerce.warehouse.error.OutboundCancelBlockedException; |
|
import common.ecommerce.warehouse.error.WarehouseException; |
|
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; |
|
import common.ecommerce.warehouse.model.CancelCommand; |
|
import common.ecommerce.warehouse.enums.CancelEligibility; |
|
import common.ecommerce.warehouse.model.CancelResult; |
|
import common.ecommerce.warehouse.enums.LabelMode; |
|
import common.ecommerce.warehouse.model.OutboundCommand; |
|
import common.ecommerce.warehouse.model.OutboundOrder; |
|
import common.ecommerce.warehouse.model.OutboundQuery; |
|
import common.ecommerce.warehouse.model.OutboundReceipt; |
|
import common.ecommerce.warehouse.model.OutboundRef; |
|
import common.ecommerce.warehouse.model.PackageResult; |
|
import common.ecommerce.warehouse.sdk.WarehouseContext; |
|
import common.ecommerce.yqn.YqnConstants; |
|
import common.ecommerce.yqn.http.YqnEnvelope; |
|
import common.ecommerce.yqn.http.YqnRateLimiter; |
|
import common.ecommerce.yqn.http.YqnRequestFactory; |
|
|
|
import java.time.ZoneId; |
|
import java.time.format.DateTimeFormatter; |
|
import java.util.ArrayList; |
|
import java.util.LinkedHashMap; |
|
import java.util.List; |
|
import java.util.Map; |
|
|
|
/** |
|
* 运去哪适配器(P1 出库闭环)。 |
|
* |
|
* <p>实现 {@code OutboundCapable}:创建 / 查询 / 取消 / 包裹。库存、入库、退货、销毁 |
|
* 等在 P2/P3 接入,未实现的能力位不声明,门面调用会显式拒绝。</p> |
|
* |
|
* <p>字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」, |
|
* 字段差异收敛在 {@code Yqn*Dtos}(按接口拆分) 与 {@link YqnOutboundMapper}。</p> |
|
*/ |
|
public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, |
|
WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable, |
|
TransferCapable, WarehouseReturnCapable, TrackingCapable, DestructionCapable, |
|
LogisticsProductCapable, WarehouseDirectoryCapable { |
|
|
|
/** 运去哪请求里的时间格式;待核对。 */ |
|
private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); |
|
|
|
private final HttpTransport transport; |
|
private final JacksonJsonCodec json; |
|
private final YqnRequestFactory requestFactory; |
|
private final YqnRateLimiter rateLimiter; |
|
|
|
public YqnAdapter(HttpTransport transport, JacksonJsonCodec json) { |
|
this.transport = transport; |
|
this.json = json; |
|
this.requestFactory = new YqnRequestFactory(json); |
|
this.rateLimiter = new YqnRateLimiter(); |
|
} |
|
|
|
@Override |
|
public String adapterId() { |
|
return YqnConstants.ADAPTER_ID; |
|
} |
|
|
|
@Override |
|
public WarehouseProvider provider() { |
|
return WarehouseProvider.YQN; |
|
} |
|
|
|
@Override |
|
public java.util.EnumSet<WarehouseCapability> capabilities() { |
|
return java.util.EnumSet.of( |
|
WarehouseCapability.PRODUCT, |
|
WarehouseCapability.OUTBOUND, |
|
WarehouseCapability.FEE_SETTLEMENT, |
|
WarehouseCapability.FEE_ESTIMATE, |
|
WarehouseCapability.INVENTORY_QUERY, |
|
WarehouseCapability.INBOUND, |
|
WarehouseCapability.BOX_LABEL, |
|
WarehouseCapability.SKU_LABEL, |
|
WarehouseCapability.PLATFORM_LABEL_DELIVERY, |
|
WarehouseCapability.LOGISTICS_PRODUCT, |
|
WarehouseCapability.WAREHOUSE_DIRECTORY, |
|
WarehouseCapability.TRANSFER, |
|
WarehouseCapability.RETURN, |
|
WarehouseCapability.RETURN_DISPOSITION, |
|
WarehouseCapability.TRACKING, |
|
WarehouseCapability.DESTRUCTION); |
|
} |
|
|
|
// ------------------------------------------------------------------ 商品 |
|
|
|
/** |
|
* 创建 / 编辑商品(API 115,{@code /v1/product/save})。 |
|
* |
|
* <p>接口本身是保存语义(同 SKU 再调即更新),因此不区分 create 与 update。 |
|
* 响应只有 {@code code/message},没有 data,所以结果里只回填请求侧 SKU。</p> |
|
*/ |
|
@Override |
|
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) { |
|
YqnProductDtos.SaveProductRequest body = YqnProductMapper.toRequest(product); |
|
String raw = execute(ctx, YqnConstants.PATH_PRODUCT_SAVE, body, "warehouse.product.create"); |
|
return ProductResult.of(YqnProductMapper.skuOf(product), "SAVED", |
|
json.stringAt(raw, "message")); |
|
} |
|
|
|
// ------------------------------------------------------------------ 出库 |
|
|
|
@Override |
|
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { |
|
requirePlatformLabelSupported(ctx, cmd.labelMode()); |
|
requireLabelContentForPlatformLabel(cmd); |
|
YqnCreateOrderDtos.CreateOrderRequest body = YqnOutboundMapper.toRequest(cmd, warehouseId(ctx, cmd.warehouseId())); |
|
|
|
String raw = execute(ctx, YqnConstants.PATH_ORDER_CREATE, body, "warehouse.outbound.create"); |
|
// API 123 只回 data.orderId(仓内部数字 id),不回字符串单号 |
|
String providerOrderId = json.stringAt(raw, "data.orderId"); |
|
if (providerOrderId == null || providerOrderId.trim().isEmpty()) { |
|
// 仓未返回 id 时不能静默成功:幂等键记了成功但没法回查 |
|
throw WarehouseException.builder() |
|
.message("yqn create returned no data.orderId: " + safeRelay(raw)) |
|
.operation("warehouse.outbound.create") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false) |
|
.rawResponse(safeRelay(raw)) |
|
.build(); |
|
} |
|
return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderId, null); |
|
} |
|
|
|
@Override |
|
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { |
|
// API 128 只按来源单号查;仓内部 id 查不了,调用方要给 outboundRequestNo |
|
String orderNo = orderNoOf(ref); |
|
YqnOrderDetailDtos.OrderDetail detail = findOne(ctx, orderNo, "warehouse.outbound.get"); |
|
return detail == null ? null |
|
: YqnOutboundMapper.toOrder(detail, null, null, ctx.warehouseCode(), zoneOf(ctx)); |
|
} |
|
|
|
/** |
|
* 按条件查询。 |
|
* |
|
* <p>运去哪的订单查询接口是「按单号取详情」,没有列表/时间窗接口, |
|
* 因此这里按单号逐个取;没有单号时<b>拒绝</b>而不是返回全量, |
|
* 避免误当成增量同步用。</p> |
|
*/ |
|
@Override |
|
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) { |
|
// API 128 只能按「来源单号」查:仓内部 id 与平台单号都查不了。 |
|
// orderRef 是平台单号,拿它当来源单号查会查不到或查错单,因此不参与查询。 |
|
String orderNo = firstNonBlank(query.providerOrderId(), null); |
|
if (orderNo == null) { |
|
throw new common.ecommerce.shared.error.ValidationException( |
|
WarehouseException.builder() |
|
.message("yqn has no order list API; query requires providerOrderId " |
|
+ "(orderRef is a platform order number and is not queryable here)") |
|
.operation("warehouse.outbound.query") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false)); |
|
} |
|
YqnOrderDetailDtos.OrderDetail detail = findOne(ctx, orderNo, "warehouse.outbound.query"); |
|
return detail == null ? Page.<OutboundOrder>empty() |
|
: Page.last(java.util.Collections.singletonList( |
|
YqnOutboundMapper.toOrder(detail, null, null, ctx.warehouseCode(), zoneOf(ctx)))); |
|
} |
|
|
|
/** 调 findOne 并解析 data;订单不存在时返回 null。 */ |
|
private YqnOrderDetailDtos.OrderDetail findOne(WarehouseContext ctx, String orderNo, String operation) { |
|
YqnOrderDetailDtos.FindOneOrderRequest body = new YqnOrderDetailDtos.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(), YqnOrderDetailDtos.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; |
|
} |
|
|
|
private static String firstNonBlank(String a, String b) { |
|
if (a != null && !a.trim().isEmpty()) { |
|
return a.trim(); |
|
} |
|
return b == null || b.trim().isEmpty() ? null : b.trim(); |
|
} |
|
|
|
@Override |
|
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) { |
|
// 运去哪没有独立的取消预判接口(Spec §8.6 第 5 项待核对): |
|
// 先查单状态,已出库/已取消的一律 BLOCKED;其余交给 cancel 时仓判定。 |
|
OutboundOrder order = get(ctx, ref); |
|
if (order == null) { |
|
return CancelEligibility.BLOCKED; |
|
} |
|
switch (order.status()) { |
|
case SHIPPED: |
|
case CANCELLED: |
|
return CancelEligibility.BLOCKED; |
|
default: |
|
return CancelEligibility.FREE; |
|
} |
|
} |
|
|
|
/** |
|
* 取消销售订单(API 122)。 |
|
* |
|
* <p>运去哪没有收费取消的概念,也没有取消费预判:入参只有 {@code orderNo}, |
|
* 响应只有 {@code code/message}。因此 {@link CancelCommand#acceptCharge()} 在这里 |
|
* 不生效;仓判定为不可取消(已拣货 / 已出库)时返回非 200 业务码。</p> |
|
* |
|
* <p>「不可取消」按 {@link OutboundCancelBlockedException} 抛出, |
|
* 而不是笼统的业务异常,方便调用方区分「状态不对」与「参数错」。</p> |
|
*/ |
|
@Override |
|
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { |
|
YqnCancelOrderDtos.CancelOrderRequest body = new YqnCancelOrderDtos.CancelOrderRequest(); |
|
body.orderNo = orderNoOf(cmd); |
|
|
|
String raw; |
|
try { |
|
raw = execute(ctx, YqnConstants.PATH_ORDER_CANCEL, body, "warehouse.outbound.cancel"); |
|
} catch (PlatformBusinessException e) { |
|
// API 122 的失败原因只有 message,无法细分;取消场景统一按「不可取消」表达 |
|
throw new OutboundCancelBlockedException(WarehouseException.builder() |
|
.message("yqn refused cancellation: " + e.getMessage()) |
|
.operation("warehouse.outbound.cancel") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.platformCode(e.platformCode()) |
|
.rawResponse(e.rawResponse()) |
|
.retryable(false)); |
|
} |
|
return CancelResult.builder() |
|
.outboundRequestNo(cmd.outboundRequestNo()) |
|
.providerOrderId(cmd.providerOrderId()) |
|
.eligibility(CancelEligibility.FREE) |
|
.cancelled(true) |
|
.rawStatus(json.stringAt(raw, "message")) |
|
.build(); |
|
} |
|
|
|
/** 取消命令 → 运去哪订单号:优先来源单号,其次仓单号。 */ |
|
private static String orderNoOf(CancelCommand cmd) { |
|
String orderNo = firstNonBlank(cmd.outboundRequestNo(), cmd.providerOrderId()); |
|
if (orderNo == null) { |
|
throw new IllegalArgumentException("yqn needs outboundRequestNo to cancel an order"); |
|
} |
|
return orderNo; |
|
} |
|
|
|
@Override |
|
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) { |
|
YqnOrderDetailDtos.OrderDetail detail = findOne(ctx, orderNoOf(ref), "warehouse.outbound.packages"); |
|
return detail == null ? java.util.Collections.<PackageResult>emptyList() |
|
: YqnOutboundMapper.toPackages(detail); |
|
} |
|
|
|
// ------------------------------------------------------------------ 费用 |
|
|
|
/** |
|
* 结算明细(API 133)。 |
|
* |
|
* <p>预估与实际由 {@code settlementType} 区分(1 实际 / 2 预估), |
|
* 映射到 {@link BillingDocument#estimated()}。仓一般发货后可查预估, |
|
* 收货约一周后才出实际账单。</p> |
|
*/ |
|
@Override |
|
public List<BillingDocument> settlements(WarehouseContext ctx, FeeQuery query) { |
|
YqnFeeDetailDtos.CostDetailRequest body = YqnFeeMapper.toRequest(query); |
|
String raw = execute(ctx, YqnConstants.PATH_FEE_DETAIL, body, "warehouse.fee.settlements"); |
|
List<YqnFeeDetailDtos.CostDetail> rows = json.listAt(raw, "data", YqnFeeDetailDtos.CostDetail.class); |
|
List<BillingDocument> out = new ArrayList<BillingDocument>(rows.size()); |
|
for (YqnFeeDetailDtos.CostDetail row : rows) { |
|
out.add(YqnFeeMapper.toDocument(row, ctx.warehouseCode(), zoneOf(ctx))); |
|
} |
|
return out; |
|
} |
|
|
|
/** |
|
* 订单测算(API 121):发货前按包裹尺寸重量 + 收件地址 + 物流渠道询价。 |
|
* |
|
* <p>读接口,不走幂等。结果按仓库维度返回,一个仓下可能有多个渠道报价。 |
|
* 报价仅供参考,实际费用以结算明细(API 133)为准。</p> |
|
*/ |
|
@Override |
|
public List<FeeEstimateResult> estimate(WarehouseContext ctx, FeeEstimateQuery query) { |
|
YqnFeeEstimateDtos.CalculateRequest body = |
|
YqnFeeEstimateMapper.toRequest(query, ctx.providerWarehouseId()); |
|
String raw = execute(ctx, YqnConstants.PATH_FEE_ESTIMATE, body, "warehouse.fee.estimate"); |
|
List<YqnFeeEstimateDtos.CalculateResult> rows = json.listAt(raw, "data", YqnFeeEstimateDtos.CalculateResult.class); |
|
List<FeeEstimateResult> out = new ArrayList<FeeEstimateResult>(rows.size()); |
|
for (YqnFeeEstimateDtos.CalculateResult row : rows) { |
|
out.add(YqnFeeEstimateMapper.toResult(row)); |
|
} |
|
return out; |
|
} |
|
|
|
// ------------------------------------------------------------------ 库存 |
|
|
|
/** |
|
* 运去哪只能全量分页拉,没有按时间增量。 |
|
* |
|
* <p>宿主按 {@link #syncStrategy()} 决定落库策略:这里永远是 |
|
* {@link InventorySyncStrategy#FULL_PULL_DIFF},不要按 updatedAfter 做增量。</p> |
|
*/ |
|
@Override |
|
public InventorySyncStrategy syncStrategy() { |
|
return InventorySyncStrategy.FULL_PULL_DIFF; |
|
} |
|
|
|
/** |
|
* 批量查询库存(API 107)。 |
|
* |
|
* <p>文档把参数写在「Body 参数」里,但方法是 GET;这里按重复 query 参数下发 |
|
* (见 {@link YqnRequestFactory#getMulti})。</p> |
|
*/ |
|
@Override |
|
public Page<InventorySnapshot> query(WarehouseContext ctx, InventoryQuery query) { |
|
Map<String, List<String>> params = YqnInventoryMapper.toParams(query, ctx.providerWarehouseId()); |
|
rateLimiter.acquire(YqnConstants.PATH_INVENTORY_PAGE, YqnConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.getMulti(ctx.endpointBaseUrl(), YqnConstants.PATH_INVENTORY_PAGE, |
|
params, ctx.secret(), ctx, "warehouse.inventory.query"); |
|
HttpResponse resp = transport.execute(req); |
|
String raw = YqnEnvelope.of(resp, json, "warehouse.inventory.query", |
|
ctx.warehouseCode(), ctx.requestId()).body(); |
|
YqnInventoryDtos.InventoryPage page = json.fromJson(raw, YqnInventoryDtos.InventoryPage.class); |
|
return YqnInventoryMapper.toPage(page, ctx.providerWarehouseId(), zoneOf(ctx), query.cursor()); |
|
} |
|
|
|
// ------------------------------------------------------------------ 入库 |
|
|
|
/** |
|
* 创建入库计划单(API 97)。 |
|
* |
|
* <p>响应只回 {@code data.inboundPlanOrderNo}(字符串计划单号), |
|
* 正好可直接作为 {@code providerInboundId} 落库。</p> |
|
*/ |
|
@Override |
|
public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) { |
|
String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId()); |
|
YqnCreateInboundDtos.CreateInboundPlanRequest body = YqnInboundMapper.toRequest(cmd, warehouseCode); |
|
String raw = execute(ctx, YqnConstants.PATH_INBOUND_CREATE, body, "warehouse.inbound.create"); |
|
String planNo = json.stringAt(raw, "data.inboundPlanOrderNo"); |
|
return InboundReceipt.of(cmd.inboundRequestNo(), planNo); |
|
} |
|
|
|
/** |
|
* 查入库计划详情(API 101)。 |
|
* |
|
* <p>入参是入库单号或来源单号,两者都能传;我们下发的来源单号即 |
|
* {@code inboundRequestNo}。</p> |
|
*/ |
|
@Override |
|
public InboundOrder get(WarehouseContext ctx, String inboundRef) { |
|
YqnInboundPlanDtos.GetInboundPlanRequest body = new YqnInboundPlanDtos.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; |
|
} |
|
YqnInboundPlanDtos.InboundPlanInfo info = json.fromJson(data.toString(), YqnInboundPlanDtos.InboundPlanInfo.class); |
|
return YqnInboundMapper.toOrder(info, ctx.warehouseCode(), zoneOf(ctx)); |
|
} |
|
|
|
/** |
|
* API 101 不支持时间查询,只支持按 {@code orderNo}(入库单号 / 来源单号)单条查。 |
|
* |
|
* <p>{@code cursor} 在这里被当作 {@code orderNo} 使用;不给就拒绝,不返回全量—— |
|
* 否则容易被误当成增量同步入口。</p> |
|
*/ |
|
@Override |
|
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)); |
|
} |
|
|
|
// ------------------------------------------------------------------ 调拨 |
|
|
|
/** |
|
* 创建调拨单(API 139)。 |
|
* |
|
* <p>响应是一个完整对象,但只有 {@code transferOutboundPlanNo} / |
|
* {@code transferOutboundPlanStatus} / {@code totalQuantity} 这几个字段有用。 |
|
* 类型不回传,从请求侧带过去。</p> |
|
*/ |
|
@Override |
|
public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) { |
|
YqnTransferDtos.CreateTransferPlanRequest body = YqnTransferMapper.toRequest(cmd); |
|
String raw = execute(ctx, YqnConstants.PATH_TRANSFER_CREATE, body, "warehouse.transfer.create"); |
|
com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data"); |
|
if (data == null || data.isNull() || data.isMissingNode()) { |
|
throw WarehouseException.builder() |
|
.message("yqn create transfer returned no data: " + safeRelay(raw)) |
|
.operation("warehouse.transfer.create") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false) |
|
.rawResponse(safeRelay(raw)) |
|
.build(); |
|
} |
|
YqnTransferDtos.CreateTransferPlanResponse resp = |
|
json.fromJson(data.toString(), YqnTransferDtos.CreateTransferPlanResponse.class); |
|
return YqnTransferMapper.toOrder(resp, cmd.type(), cmd.transferRequestNo(), zoneOf(ctx)); |
|
} |
|
|
|
// ------------------------------------------------------------------ 退货 |
|
|
|
/** |
|
* 创建销售退货预约(API 81)。 |
|
* |
|
* <p><b>响应只有 code/message,没有单号</b>:所以返回的 |
|
* {@code providerReturnId} 是 null。退货的仓侧单号只能靠后续查询或回调补。 |
|
* 这会影响「按仓单号做幂等 / 回查」的用法——按文档我们只能用来源单号。</p> |
|
*/ |
|
@Override |
|
public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) { |
|
String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId()); |
|
YqnCreateSaleReturnDtos.CreateSaleReturnRequest body = YqnReturnMapper.toRequest(cmd, warehouseCode); |
|
execute(ctx, YqnConstants.PATH_RETURN_CREATE, body, "warehouse.return.create"); |
|
return YqnReturnMapper.toCreated(cmd, warehouseCode); |
|
} |
|
|
|
/** |
|
* 按明细行设置检验后处理方式(API 77)。 |
|
* |
|
* <p>运去哪没有退还货条目的「取消 / 撤回」,这里只做处理方式。</p> |
|
*/ |
|
@Override |
|
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) { |
|
YqnReturnProcessDtos.SaleReturnProcessRequest body = YqnReturnMapper.toProcessRequest(cmd); |
|
execute(ctx, YqnConstants.PATH_RETURN_PROCESS, body, "warehouse.return.process"); |
|
} |
|
|
|
/** 退货查询未接入:文档只给了创建(81)与条目处理(77)。 */ |
|
@Override |
|
public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) { |
|
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); |
|
} |
|
|
|
@Override |
|
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor) { |
|
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); |
|
} |
|
|
|
// ------------------------------------------------------------------ 仓库目录 |
|
|
|
/** |
|
* 查询仓库(API 134)。 |
|
* |
|
* <p><b>信封不同</b>:这个接口的响应文档只给 {@code status / message / data}, |
|
* <b>没有 {@code code}</b>,而 {@code YqnEnvelope} 要求业务码存在且为 200。 |
|
* 所以这里不走 envelope,按 {@code status} 判定,并对 {@code code} 做兼容。</p> |
|
*/ |
|
@Override |
|
public List<WarehouseInfo> warehouses(WarehouseContext ctx) { |
|
rateLimiter.acquire(YqnConstants.PATH_WAREHOUSE_FIND_ALL, YqnConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), |
|
YqnConstants.PATH_WAREHOUSE_FIND_ALL, null, ctx.secret(), ctx, |
|
"warehouse.directory.list"); |
|
HttpResponse resp = transport.execute(req); |
|
String raw = resp.body(); |
|
if (raw == null || raw.trim().isEmpty()) { |
|
throw WarehouseException.builder() |
|
.message("yqn warehouse list returned an empty body") |
|
.operation("warehouse.directory.list") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(true) |
|
.build(); |
|
} |
|
requireWarehouseListSuccess(ctx, raw); |
|
List<YqnWarehouseDtos.WarehouseRow> rows = json.listAt(raw, "data", YqnWarehouseDtos.WarehouseRow.class); |
|
return YqnWarehouseMapper.toWarehouses(rows); |
|
} |
|
|
|
/** |
|
* 这个接口的业务码判定:有 {@code code} 时按 200 校验;没有则退回看 {@code status} |
|
* (文档示例 {@code status: 1} 表示成功)。 |
|
*/ |
|
private void requireWarehouseListSuccess(WarehouseContext ctx, String raw) { |
|
int code = json.intAt(raw, "code", Integer.MIN_VALUE); |
|
boolean ok; |
|
String detail; |
|
if (code != Integer.MIN_VALUE) { |
|
ok = code == YqnEnvelope.SUCCESS_CODE; |
|
detail = "code=" + code; |
|
} else { |
|
int status = json.intAt(raw, "status", Integer.MIN_VALUE); |
|
ok = status == YqnConstants.WAREHOUSE_LIST_SUCCESS_STATUS; |
|
detail = "status=" + status; |
|
} |
|
if (!ok) { |
|
throw WarehouseException.builder() |
|
.message("yqn warehouse list failed: " + detail |
|
+ ", message=" + json.stringAt(raw, "message")) |
|
.operation("warehouse.directory.list") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false) |
|
.rawResponse(safeRelay(raw)) |
|
.build(); |
|
} |
|
} |
|
|
|
// ------------------------------------------------------------------ 物流产品 |
|
|
|
/** |
|
* 物流产品服务清单(API 135)。 |
|
* |
|
* <p>文档把参数写成 {@code query.warehouseCode} 放在「Body 参数」里但方法是 GET, |
|
* 与库存接口同样按 query 参数下发。</p> |
|
*/ |
|
@Override |
|
public List<LogisticsProduct> products(WarehouseContext ctx, String warehouseCode) { |
|
String code = YqnLogisticsProductMapper.resolveWarehouseCode(warehouseCode, |
|
ctx.providerWarehouseId()); |
|
Map<String, List<String>> params = YqnLogisticsProductMapper.toParams(code, null); |
|
rateLimiter.acquire(YqnConstants.PATH_LOGISTICS_PRODUCTS, YqnConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.getMulti(ctx.endpointBaseUrl(), |
|
YqnConstants.PATH_LOGISTICS_PRODUCTS, params, ctx.secret(), ctx, |
|
"warehouse.logistics.products"); |
|
HttpResponse resp = transport.execute(req); |
|
String raw = YqnEnvelope.of(resp, json, "warehouse.logistics.products", |
|
ctx.warehouseCode(), ctx.requestId()).body(); |
|
List<YqnLogisticsProductDtos.CarrierGroup> rows = json.listAt(raw, "data", YqnLogisticsProductDtos.CarrierGroup.class); |
|
return YqnLogisticsProductMapper.toProducts(rows, code); |
|
} |
|
|
|
// ------------------------------------------------------------------ 入库箱标 |
|
|
|
/** |
|
* 打印入库计划单箱标(API 99)。 |
|
* |
|
* <p>仓方异步生成文件:响应只有 {@code taskNo},没有文件内容,下载地址要另外查 |
|
* 任务中心。所以返回的 {@link LabelPrintTask#label()} 恒为 null。</p> |
|
*/ |
|
@Override |
|
public LabelPrintTask printBoxLabel(WarehouseContext ctx, BoxLabelCommand cmd) { |
|
YqnBoxLabelDtos.BoxLabelRequest body = YqnBoxLabelMapper.toRequest(cmd); |
|
String raw = execute(ctx, YqnConstants.PATH_INBOUND_BOX_LABEL, body, |
|
"warehouse.inbound.boxLabel"); |
|
YqnBoxLabelDtos.BoxLabelResponse resp = |
|
json.fromJson(String.valueOf(json.nodeAt(raw, "data")), YqnBoxLabelDtos.BoxLabelResponse.class); |
|
return YqnBoxLabelMapper.toTask(resp, cmd); |
|
} |
|
|
|
/** |
|
* 打印入库计划单 SKU 标(API 100)。 |
|
* |
|
* <p>同样是异步任务:响应只有 {@code taskNo},文件要另外查任务中心。</p> |
|
*/ |
|
@Override |
|
public LabelPrintTask printSkuLabel(WarehouseContext ctx, SkuLabelCommand cmd) { |
|
YqnSkuLabelDtos.SkuLabelRequest body = YqnSkuLabelMapper.toRequest(cmd); |
|
String raw = execute(ctx, YqnConstants.PATH_INBOUND_SKU_LABEL, body, |
|
"warehouse.inbound.skuLabel"); |
|
YqnBoxLabelDtos.BoxLabelResponse resp = |
|
json.fromJson(String.valueOf(json.nodeAt(raw, "data")), YqnBoxLabelDtos.BoxLabelResponse.class); |
|
return YqnSkuLabelMapper.toTask(resp, cmd); |
|
} |
|
|
|
// ------------------------------------------------------------------ 销毁 |
|
|
|
/** |
|
* 创建销毁计划(API 88)。 |
|
* |
|
* <p>响应只回 {@code destroyPlanOrderNo},没有状态。创建成功只代表申请已提交, |
|
* 不代表仓方已执行销毁。</p> |
|
*/ |
|
@Override |
|
public DestructionOrder create(WarehouseContext ctx, DestructionCommand cmd) { |
|
String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId()); |
|
YqnDestroyPlanDtos.CreateDestroyPlanRequest body = |
|
YqnDestructionMapper.toRequest(cmd, ctx.providerWarehouseId()); |
|
String raw = execute(ctx, YqnConstants.PATH_DESTRUCTION_CREATE, body, |
|
"warehouse.destruction.create"); |
|
String providerNo = json.stringAt(raw, "data.destroyPlanOrderNo"); |
|
return YqnDestructionMapper.toCreated(cmd, warehouseCode, providerNo); |
|
} |
|
|
|
/** 销毁计划查询未接入:文档只给了创建(API 88)。 */ |
|
@Override |
|
public DestructionOrder getDestruction(WarehouseContext ctx, String destructionNo) { |
|
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.DESTRUCTION); |
|
} |
|
|
|
// ------------------------------------------------------------------ 物流轨迹 |
|
|
|
/** |
|
* 运单轨迹(API 189)。 |
|
* |
|
* <p>这个接口在<b>另一个主机</b>({@code pr-ship-api.yqn.com}),调用方必须通过 |
|
* {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址; |
|
* 没传时显式拒绝,不退回主基址,避免把轨迹请求打到仓接口上。</p> |
|
* |
|
* <p>信封的成功码是 {@code 1}(不是其它接口的 {@code 200}),所以不走 |
|
* {@code YqnEnvelope},单独解析。</p> |
|
*/ |
|
@Override |
|
public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) { |
|
YqnTrackingDtos.ShipmentTrack track = fetchTrack(ctx, trackingNumber); |
|
return YqnTrackingMapper.toTrackingInfo(track, trackingNumber, zoneOf(ctx)); |
|
} |
|
|
|
@Override |
|
public List<TrackEvent> track(WarehouseContext ctx, String trackingNumber) { |
|
YqnTrackingDtos.ShipmentTrack track = fetchTrack(ctx, trackingNumber); |
|
return YqnTrackingMapper.toTrackEvents(track, trackingNumber, zoneOf(ctx)); |
|
} |
|
|
|
private YqnTrackingDtos.ShipmentTrack fetchTrack(WarehouseContext ctx, String trackingNumber) { |
|
if (trackingNumber == null || trackingNumber.trim().isEmpty()) { |
|
throw new IllegalArgumentException("trackingNumber must not be blank"); |
|
} |
|
String baseUrl = ctx.auxEndpointBaseUrl(); |
|
if (baseUrl == null || baseUrl.trim().isEmpty()) { |
|
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.TRACKING); |
|
} |
|
String path = YqnConstants.PATH_TRACKING + urlEncode(trackingNumber.trim()); |
|
rateLimiter.acquire(YqnConstants.PATH_TRACKING, YqnConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.get(baseUrl, path, null, ctx.secret(), ctx, |
|
"warehouse.track"); |
|
HttpResponse resp = transport.execute(req); |
|
String raw = resp.body(); |
|
if (raw == null || raw.trim().isEmpty()) { |
|
throw WarehouseException.builder() |
|
.message("yqn track returned an empty body") |
|
.operation("warehouse.track") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(true) |
|
.build(); |
|
} |
|
// 这个接口的成功码是 1,不是 200,不能用 YqnEnvelope |
|
int code = json.intAt(raw, "code", -1); |
|
if (!YqnConstants.isTrackSuccess(code)) { |
|
throw WarehouseException.builder() |
|
.message("yqn track failed: code=" + code + ", message=" + json.stringAt(raw, "message")) |
|
.operation("warehouse.track") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.platformCode(String.valueOf(code)) |
|
.rawResponse(safeRelay(raw)) |
|
.retryable(false) |
|
.build(); |
|
} |
|
String data = String.valueOf(json.nodeAt(raw, "data")); |
|
return json.fromJson(data, YqnTrackingDtos.ShipmentTrack.class); |
|
} |
|
|
|
private static String urlEncode(String v) { |
|
try { |
|
return java.net.URLEncoder.encode(v, "UTF-8"); |
|
} catch (java.io.UnsupportedEncodingException e) { |
|
throw new IllegalStateException(e); |
|
} |
|
} |
|
|
|
// ------------------------------------------------------------------ internals |
|
|
|
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */ |
|
/** |
|
* 平台面单必须带面单文件:只声明 {@code PLATFORM_LABEL} 却不给 |
|
* {@code labelContentBase64},仓没有面单可打,等于静默失败。 |
|
*/ |
|
private static void requireLabelContentForPlatformLabel(OutboundCommand cmd) { |
|
if (cmd.labelMode() == LabelMode.PLATFORM_LABEL |
|
&& (cmd.labelContentBase64() == null || cmd.labelContentBase64().trim().isEmpty())) { |
|
throw new IllegalArgumentException( |
|
"labelContentBase64 is required when labelMode=PLATFORM_LABEL for " |
|
+ cmd.outboundRequestNo()); |
|
} |
|
} |
|
|
|
private void requirePlatformLabelSupported(WarehouseContext ctx, LabelMode mode) { |
|
if (mode == LabelMode.PLATFORM_LABEL && !supports(ctx.warehouseCode(), |
|
WarehouseCapability.PLATFORM_LABEL_DELIVERY)) { |
|
throw WarehouseException.builder() |
|
.message("yqn account does not declare PLATFORM_LABEL_DELIVERY; " |
|
+ "refusing to silently fall back to warehouse label") |
|
.operation("warehouse.outbound.create") |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false) |
|
.build(); |
|
} |
|
} |
|
|
|
/** 仓方仓编码:命令显式指定优先,否则用账户配置。 */ |
|
private static String warehouseId(WarehouseContext ctx, String fromCommand) { |
|
if (fromCommand != null && !fromCommand.trim().isEmpty()) { |
|
return fromCommand.trim(); |
|
} |
|
return ctx.providerWarehouseId(); |
|
} |
|
|
|
private static ZoneId zoneOf(WarehouseContext ctx) { |
|
// 账户时区由 WarehouseAccount 提供;上下文没带时回退北京 |
|
return ZoneId.of("Asia/Shanghai"); |
|
} |
|
|
|
/** 发请求并校验信封。 */ |
|
private String execute(WarehouseContext ctx, String path, Object body, String operation) { |
|
rateLimiter.acquire(path, YqnConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.postJson(ctx.endpointBaseUrl(), path, |
|
json.toJson(body), ctx.secret(), ctx, operation); |
|
HttpResponse resp = transport.execute(req); |
|
return YqnEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body(); |
|
} |
|
|
|
/** 原始响应可能含 PII 与 token,异常里只留长度与首段。 */ |
|
private static String safeRelay(String raw) { |
|
if (raw == null) { |
|
return null; |
|
} |
|
return raw.length() <= 300 ? raw : raw.substring(0, 300) + "..."; |
|
} |
|
}
|
|
|