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 出库闭环)。 * *
实现 {@code OutboundCapable}:创建 / 查询 / 取消 / 包裹。库存、入库、退货、销毁 * 等在 P2/P3 接入,未实现的能力位不声明,门面调用会显式拒绝。
* *字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」, * 字段差异收敛在 {@code Yqn*Dtos}(按接口拆分) 与 {@link YqnOutboundMapper}。
*/ 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接口本身是保存语义(同 SKU 再调即更新),因此不区分 create 与 update。 * 响应只有 {@code code/message},没有 data,所以结果里只回填请求侧 SKU。
*/ @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)); } /** * 按条件查询。 * *运去哪的订单查询接口是「按单号取详情」,没有列表/时间窗接口, * 因此这里按单号逐个取;没有单号时拒绝而不是返回全量, * 避免误当成增量同步用。
*/ @Override public Page运去哪没有收费取消的概念,也没有取消费预判:入参只有 {@code orderNo}, * 响应只有 {@code code/message}。因此 {@link CancelCommand#acceptCharge()} 在这里 * 不生效;仓判定为不可取消(已拣货 / 已出库)时返回非 200 业务码。
* *「不可取消」按 {@link OutboundCancelBlockedException} 抛出, * 而不是笼统的业务异常,方便调用方区分「状态不对」与「参数错」。
*/ @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预估与实际由 {@code settlementType} 区分(1 实际 / 2 预估), * 映射到 {@link BillingDocument#estimated()}。仓一般发货后可查预估, * 收货约一周后才出实际账单。
*/ @Override public List读接口,不走幂等。结果按仓库维度返回,一个仓下可能有多个渠道报价。 * 报价仅供参考,实际费用以结算明细(API 133)为准。
*/ @Override public List宿主按 {@link #syncStrategy()} 决定落库策略:这里永远是 * {@link InventorySyncStrategy#FULL_PULL_DIFF},不要按 updatedAfter 做增量。
*/ @Override public InventorySyncStrategy syncStrategy() { return InventorySyncStrategy.FULL_PULL_DIFF; } /** * 批量查询库存(API 107)。 * *文档把参数写在「Body 参数」里,但方法是 GET;这里按重复 query 参数下发 * (见 {@link YqnRequestFactory#getMulti})。
*/ @Override public Page响应只回 {@code data.inboundPlanOrderNo}(字符串计划单号), * 正好可直接作为 {@code providerInboundId} 落库。
*/ @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)。 * *入参是入库单号或来源单号,两者都能传;我们下发的来源单号即 * {@code inboundRequestNo}。
*/ @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}(入库单号 / 来源单号)单条查。 * *{@code cursor} 在这里被当作 {@code orderNo} 使用;不给就拒绝,不返回全量—— * 否则容易被误当成增量同步入口。
*/ @Override public Page响应是一个完整对象,但只有 {@code transferOutboundPlanNo} / * {@code transferOutboundPlanStatus} / {@code totalQuantity} 这几个字段有用。 * 类型不回传,从请求侧带过去。
*/ @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)。 * *响应只有 code/message,没有单号:所以返回的 * {@code providerReturnId} 是 null。退货的仓侧单号只能靠后续查询或回调补。 * 这会影响「按仓单号做幂等 / 回查」的用法——按文档我们只能用来源单号。
*/ @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)。 * *运去哪没有退还货条目的「取消 / 撤回」,这里只做处理方式。
*/ @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信封不同:这个接口的响应文档只给 {@code status / message / data}, * 没有 {@code code},而 {@code YqnEnvelope} 要求业务码存在且为 200。 * 所以这里不走 envelope,按 {@code status} 判定,并对 {@code code} 做兼容。
*/ @Override public List文档把参数写成 {@code query.warehouseCode} 放在「Body 参数」里但方法是 GET, * 与库存接口同样按 query 参数下发。
*/ @Override public List仓方异步生成文件:响应只有 {@code taskNo},没有文件内容,下载地址要另外查 * 任务中心。所以返回的 {@link LabelPrintTask#label()} 恒为 null。
*/ @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)。 * *同样是异步任务:响应只有 {@code taskNo},文件要另外查任务中心。
*/ @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)。 * *响应只回 {@code destroyPlanOrderNo},没有状态。创建成功只代表申请已提交, * 不代表仓方已执行销毁。
*/ @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)。 * *这个接口在另一个主机({@code pr-ship-api.yqn.com}),调用方必须通过 * {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址; * 没传时显式拒绝,不退回主基址,避免把轨迹请求打到仓接口上。
* *信封的成功码是 {@code 1}(不是其它接口的 {@code 200}),所以不走 * {@code YqnEnvelope},单独解析。
*/ @Override public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) { YqnTrackingDtos.ShipmentTrack track = fetchTrack(ctx, trackingNumber); return YqnTrackingMapper.toTrackingInfo(track, trackingNumber, zoneOf(ctx)); } @Override public List