package common.ecommerce.edayun.adapter; import common.ecommerce.edayun.EdayunConstants; import common.ecommerce.edayun.auth.EdayunTokenClient; import common.ecommerce.edayun.dto.EdayunAccountFlowDtos; import common.ecommerce.edayun.dto.EdayunBolDtos; import common.ecommerce.edayun.dto.EdayunCarrierDtos; import common.ecommerce.edayun.dto.EdayunCancelDtos; import common.ecommerce.edayun.dto.EdayunCancelReturnDtos; import common.ecommerce.edayun.dto.EdayunCaseMarkDtos; import common.ecommerce.edayun.dto.EdayunCreateOrderDtos; import common.ecommerce.edayun.dto.EdayunCreateProductDtos; import common.ecommerce.edayun.dto.EdayunFeeEstimateDtos; import common.ecommerce.edayun.dto.EdayunGetOrderDtos; import common.ecommerce.edayun.dto.EdayunGetOrderLabelDtos; import common.ecommerce.edayun.dto.EdayunInboundDtos; import common.ecommerce.edayun.dto.EdayunInboundQueryDtos; import common.ecommerce.edayun.dto.EdayunInventoryDtos; import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos; import common.ecommerce.edayun.dto.EdayunOrderCostDtos; import common.ecommerce.edayun.dto.EdayunProductQueryDtos; import common.ecommerce.edayun.dto.EdayunRentDetailDtos; import common.ecommerce.edayun.dto.EdayunReturnDetailDtos; import common.ecommerce.edayun.dto.EdayunReturnDtos; import common.ecommerce.edayun.dto.EdayunRmaListDtos; import common.ecommerce.edayun.dto.EdayunSkuLabelDtos; import common.ecommerce.edayun.dto.EdayunTrackDtos; import common.ecommerce.edayun.dto.EdayunWarehouseDtos; import common.ecommerce.edayun.enums.EdayunCancelStatus; import common.ecommerce.edayun.http.EdayunRequestFactory; import common.ecommerce.http.HttpRequest; import common.ecommerce.http.HttpResponse; import common.ecommerce.http.HttpTransport; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.http.TokenManager; import common.ecommerce.shared.spi.AccessToken; import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.TokenStore; import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.BolCapable; import common.ecommerce.warehouse.capability.CaseMarkPrintCapable; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.enums.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.BolDocument; import common.ecommerce.warehouse.model.BoxLabelCommand; import common.ecommerce.warehouse.model.CancelCommand; import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.CaseMarkPrintCommand; import common.ecommerce.warehouse.model.FeeEstimateQuery; import common.ecommerce.warehouse.model.FeeEstimateResult; import common.ecommerce.warehouse.model.FeeQuery; 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.InventorySnapshot; import common.ecommerce.warehouse.model.LogisticsProduct; 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.model.ProductQuery; import common.ecommerce.warehouse.model.ProductInfo; import common.ecommerce.warehouse.model.ReturnCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.ReturnQuery; import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.TrackingInfo; import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.model.WarehouseCarrier; import common.ecommerce.warehouse.model.WarehouseFacility; import common.ecommerce.warehouse.model.WarehouseLabel; import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; import java.time.Clock; import java.util.ArrayList; import java.util.EnumSet; import java.util.List; /** * 易达云适配器。 * *
已实现的能力见 {@link #capabilities()};没声明的能力门面会显式抛 * {@code WarehouseUnsupportedCapabilityException},不返回空集合。
* *适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * {@code WarehouseConnection} 传入。
*/ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable, OutboundCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable, WarehouseReturnCapable, BolCapable, LogisticsProductCapable, TrackingCapable, CaseMarkPrintCapable, WarehouseDirectoryCapable { /** 物流产品查询的适用业务:1 店铺订单(默认口径)。 */ private static final int APPLICABLE_BUSINESS_STORE_ORDER = 1; private final HttpTransport transport; private final JacksonJsonCodec json; private final EdayunRequestFactory requestFactory; private final EdayunTokenClient tokenClient; private final TokenManager tokenManager; public EdayunAdapter(HttpTransport transport, JacksonJsonCodec json) { this(transport, json, null, null, Clock.systemUTC()); } /** * @param tokenStore 令牌缓存;为 null 时 {@link #token(WarehouseContext)} 每次都重新登录 * @param lockProvider 防击穿锁;与 tokenStore 成对提供 */ public EdayunAdapter(HttpTransport transport, JacksonJsonCodec json, TokenStore tokenStore, LockProvider lockProvider, Clock clock) { this.transport = transport; this.json = json; this.requestFactory = new EdayunRequestFactory(json); this.tokenClient = new EdayunTokenClient(transport, json, clock); this.tokenManager = tokenStore == null || lockProvider == null ? null : new TokenManager(tokenStore, lockProvider, clock, EdayunConstants.TOKEN_EARLY_REFRESH_SECONDS) { @Override protected AccessToken refresh(ChannelSecret secret, AccessToken previous) { return tokenClient.fetch(secret.endpointBaseUrl(), secret.clientId(), secret.clientSecret()); } }; } @Override public String adapterId() { return EdayunConstants.ADAPTER_ID; } @Override public WarehouseProvider provider() { return WarehouseProvider.EDAYUN; } /** * 不提供默认地址:生产域名尚未确定({@code EdayunConstants.PRODUCTION_BASE_URL} 仍是占位)。 * *在账户上配置 {@code endpointBaseUrl} 后即可使用免连接重载; * 未配置时会明确报错,不会悄悄连到测试环境。
*/ @Override public String defaultEndpointBaseUrl() { return null; } /** * 已实现的能力。 * *声明了就必须有实现,否则调用方看能力位会以为能用。
*/ @Override public EnumSettoken 按 {@code appKey + clientId} 维度缓存——同一 OMS 授权账号下多个仓共用一个。
*/ public AccessToken token(WarehouseContext ctx) { ChannelSecret secret = ctx.secret(); if (tokenManager == null) { return tokenClient.fetch(ctx.endpointBaseUrl(), secret.clientId(), secret.clientSecret()); } return tokenManager.getOrRefresh(tokenKey(secret), secret); } /** 令牌缓存维度。 */ static String tokenKey(ChannelSecret secret) { return EdayunConstants.ADAPTER_ID + ":" + secret.appKey() + ":" + secret.clientId(); } // ------------------------------------------------------------------ 商品 /** * 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。 * *易达云是「创建」语义,不是「保存」——同 SKU 重复调用大概率报错而不是更新。 * 结果里带仓侧 {@code skuId},宿主可据此判断是否需要后续更新。
*/ @Override public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) { EdayunCreateProductDtos.CreateProductRequest body = EdayunProductMapper.toCreateRequest(product); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_PRODUCT_CREATE, bodyJson, "warehouse.product.create"); EdayunCreateProductDtos.CreateProductResponse parsed = json.fromJson(resp.body(), EdayunCreateProductDtos.CreateProductResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.product.create"); String skuCode = parsed.data != null && parsed.data.skuCode != null ? parsed.data.skuCode : body.skuCode; return ProductResult.of(skuCode, "CREATED", parsed.data == null ? null : parsed.data.skuId); } /** * 批量查询仓侧商品资料({@code POST /webApi/skuInfo/v1/listProductPage})。 * *入参 SKU 是仓侧 SKU,即建档时下发到 {@code skuCode} 字段的那串 * ({@link EdayunProductMapper} 的 {@code skuOf}),不一定等于 OMS SKU。 * 易达云的 {@code skuCode} 是逗号拼接的 * 单个字符串且一次最多 50 个,超了本地拒绝(不截断)。 * 审核时间窗统一模型没有对应字段,不传。
* *查询条件全空时仓方默认按创建时间查最近一个月——这一点由仓方兜底, * 本地不补默认值。
*/ @Override public Page仓侧幂等键是 {@code poNumber}(我们映射自 {@code orderRef})——文档要求 * 「取消重推时平台单号保持不变」。
*/ @Override public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { requireLabelUrl(cmd); EdayunCreateOrderDtos.CreateOrderRequest body = EdayunOrderMapper.toCreateRequest(cmd, ctx.providerWarehouseId()); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_CREATE, bodyJson, "warehouse.outbound.create"); EdayunCreateOrderDtos.CreateOrderResponse parsed = json.fromJson(resp.body(), EdayunCreateOrderDtos.CreateOrderResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.outbound.create"); String providerOrderNo = parsed.data == null ? null : parsed.data.orderNo; if (providerOrderNo == null || providerOrderNo.trim().isEmpty()) { throw WarehouseException.builder() .message("edayun createOrder returned no data.orderNo") .operation("warehouse.outbound.create") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .rawResponse(safeRelay(resp.body())) .retryable(false) .build(); } return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderNo.trim(), null); } /** * 平台面单:易达云要的是文件 URL,不是 base64。 * *在本地就拒绝 base64,避免发出去被仓方以「面单不可访问」拒绝后难以定位。
*/ private static void requireLabelUrl(OutboundCommand cmd) { if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) { return; } String content = cmd.labelContentBase64(); if (content == null || content.trim().isEmpty()) { return; } if (!content.startsWith("http://") && !content.startsWith("https://")) { throw new IllegalArgumentException( "edayun requires a label FILE URL (not base64) for " + cmd.outboundRequestNo() + "; upload the file and pass its https URL"); } } /** * 查询出库单信息({@code POST /webApi/order/v1/getOrderInfo})。 * *{@code orderNo} 与 {@code poNumber} 二选一。我们优先用来源单号当 * {@code poNumber} 查(那是创建时下发的),没有来源单号才用仓侧单号。
*/ @Override public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { EdayunGetOrderDtos.GetOrderRequest body = new EdayunGetOrderDtos.GetOrderRequest(); if (hasText(ref.outboundRequestNo())) { body.poNumber = ref.outboundRequestNo().trim(); } else if (hasText(ref.providerOrderId())) { body.orderNo = ref.providerOrderId().trim(); } else { throw new IllegalArgumentException( "edayun needs outboundRequestNo (as poNumber) or providerOrderId (as orderNo)"); } String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_GET, bodyJson, "warehouse.outbound.get"); EdayunGetOrderDtos.GetOrderResponse parsed = json.fromJson(resp.body(), EdayunGetOrderDtos.GetOrderResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.outbound.get"); if (parsed.data == null) { return null; } return EdayunOrderQueryMapper.toOrder(parsed.data, ctx.warehouseCode(), ref.outboundRequestNo()); } @Override public Page返回能不能不收费取消:{@code Published} 免费 / {@code Shipment} 收费 / * 其余(含无法识别)按不可取消。
*/ @Override public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) { EdayunCancelDtos.CancelRequest body = cancelRequestOf( ref.outboundRequestNo(), ref.providerOrderId()); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_CHECK_CANCEL, bodyJson, "warehouse.outbound.checkCancel"); EdayunCancelDtos.CheckCancelResponse parsed = json.fromJson(resp.body(), EdayunCancelDtos.CheckCancelResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.outbound.checkCancel"); return EdayunCancelStatus.toCore(parsed.data); } /** * 取消订单({@code POST /webApi/order/v1/cancelOrder})。 * *文档说明仓库操作后会收取取消费,可以先用 {@link #checkCancel} 判定。 * 这里不做「收费必须 acceptCharge」的强制拦截——因为校验与实际取消是两次调用, * 中间状态可能变化;是否调用由宿主决定。收费与否通过 {@link CancelResult#cancelFee()} * 之外的 {@code rawStatus} 与后续账单体现。
*/ @Override public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { EdayunCancelDtos.CancelRequest body = cancelRequestOf( cmd.outboundRequestNo(), cmd.providerOrderId()); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_CANCEL, bodyJson, "warehouse.outbound.cancel"); EdayunCancelDtos.CancelOrderResponse parsed = json.fromJson(resp.body(), EdayunCancelDtos.CancelOrderResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.outbound.cancel"); boolean cancelled = parsed.data != null && parsed.data; return CancelResult.builder() .outboundRequestNo(cmd.outboundRequestNo()) .providerOrderId(cmd.providerOrderId()) // data=false 表示仓侧拒绝,具体原因在 msg 里 .cancelled(cancelled) .eligibility(cancelled ? CancelEligibility.FREE : CancelEligibility.BLOCKED) .rawStatus(parsed.msg) .build(); } /** * 取消类请求体:{@code orderNo}(仓侧)优先级高于 {@code poNumber}(我们的单号)。 * *与文档一致:「ORD 单号优先级更高」。
*/ private static EdayunCancelDtos.CancelRequest cancelRequestOf(String outboundRequestNo, String providerOrderId) { EdayunCancelDtos.CancelRequest body = new EdayunCancelDtos.CancelRequest(); if (hasText(providerOrderId)) { body.orderNo = providerOrderId.trim(); } if (hasText(outboundRequestNo)) { body.poNumber = outboundRequestNo.trim(); } if (body.orderNo == null && body.poNumber == null) { throw new IllegalArgumentException( "edayun cancel needs outboundRequestNo (poNumber) or providerOrderId (orderNo)"); } return body; } /** * 查面单({@code POST /webApi/order/v1/getOrderLabel})。 * *返回的 {@code labels} 与 {@code trackingNo} 都是逗号拼接、按位置对应; * 一个包裹(trackingNo)对应一个面单 URL。
*/ @Override public List一次调用直接发布,不走「先存草稿再发布」两步——文档里发布是保存的一部分。 * 快递类(海快 / 空运 / 快递)发布时仓方还要求 {@code shipCompany + waybill}, * 卡车类要求 {@code estimatedDepartureTime},标准模型没有这几个字段, * 缺了由仓方报错,不在本地编造。
*/ @Override public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) { EdayunInboundDtos.SaveEntryRequest body = EdayunInboundMapper.toRequest( cmd, EdayunInboundMapper.SAVE_PUBLISH, null, ctx.providerWarehouseId()); return saveEntry(ctx, body, cmd.inboundRequestNo(), "warehouse.inbound.create"); } /** * 编辑自发入库单({@code saveType=1})。 * * @param inboundRef 仓侧入库单号({@code entryCode}),不是我们的来源单号 */ @Override public void improve(WarehouseContext ctx, String inboundRef, InboundCommand cmd) { EdayunInboundDtos.SaveEntryRequest body = EdayunInboundMapper.toRequest( cmd, EdayunInboundMapper.SAVE_UPDATE, inboundRef, ctx.providerWarehouseId()); saveEntry(ctx, body, cmd.inboundRequestNo(), "warehouse.inbound.improve"); } private InboundReceipt saveEntry(WarehouseContext ctx, EdayunInboundDtos.SaveEntryRequest body, String inboundRequestNo, String operation) { HttpResponse resp = send(ctx, EdayunConstants.PATH_INBOUND_SAVE, json.toJson(body), operation); EdayunInboundDtos.SaveEntryResponse parsed = json.fromJson(resp.body(), EdayunInboundDtos.SaveEntryResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, operation); String entryCode = parsed.data == null ? null : parsed.data.entryCode; return InboundReceipt.of(inboundRequestNo, entryCode); } /** * 查入库单({@code POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail})。 * *接口按 SKU 逐行返回,这里翻完所有页合并成一张单。 * 只认仓侧 {@code entryCode}(REV 单号)——接口不支持按客户单号查。
* *接口只回 SKU 级数据:仓库编码取 OMS 配置的仓,单头状态由各 SKU 状态汇总 * (还有 SKU 没上架,整单就不算完成)。
*/ @Override public InboundOrder get(WarehouseContext ctx, String inboundRef) { List宿主按本值做全量 diff,不要指望 {@code updatedAfter} 生效。
*/ @Override public InventorySyncStrategy syncStrategy() { return InventorySyncStrategy.FULL_PULL_DIFF; } /** * 库存查询({@code POST /webApi/userSkuStock/v1/queryInventory})。 * *一行 = 一个 SKU 在一个仓的汇总。默认只返回总库存大于 0 的数据, * 需要零库存时由调用方传 {@code includeZeroStock(true)}。
* *分页按页码游标:单页最多 500 条,{@code total} 是总行数。
*/ @Override public Page文档说明「同一个单号的某个计费项有多条数据」,所以不做去重, * 每条流水都映射成一条 {@link BillingDocument},靠 {@code serialNumber} 区分。
* *分页:文档要求 {@code pageNum} / {@code pageSize} 必填,当前只取第一页 * (200 条);超过时截断——待确认是否需要翻页。
*/ @Override public List与 {@link #settlements}(账户流水)不同:这个按订单拆费用, * 带应收 / 折扣 / 实付与计费重。落库金额取实付。 * *
一个订单可能展开成多条 {@link BillingDocument}(逐计费项)。
*/ @Override public List与 {@link #settlements}(账户流水)、{@link #orderCosts}(按订单拆费用)都不同: * 这个只出仓储费,按 SKU + 计费日逐条,带租期天数与计费体积。
* *文档要求计费时间窗必填且不超过 3 个月,所以按时间窗 + 翻页拉: * 一页 200 条,最多 {@link EdayunRentDetailMapper#MAX_PAGES} 页。仍有剩余时 * 显式失败而不是截断——少算仓租会让对账金额偏小。
*/ @Override public List只做「按包裹」这一种预估——标准模型只带包裹尺寸重量。 * 真机实测:按 SKU 预估要求 SKU 在仓侧已建档,虚拟包裹在 PR 环境直接 * 「内部服务器错误」,两者都不适合作为默认路径。
* *响应分 {@code successItems} / {@code failItems},只映射前者; * 全部失败时返回一个 {@code carriers()} 为空的结果(表示该仓无法承运)。 * 渠道的无报价原因(如「不支持派送」)只在原报文里,不同步到统一模型。
*/ @Override public List统一模型只对应「自行退回」({@code returnType=2}):它要求退货运单号, * 正好是买家自己寄回的场景。未妥投 / 返邮 / FBA 退回要退货人地址或亚马逊单号, * 标准模型没有——见 TODO。
* *与运去哪不同,响应 {@code data} 就是仓侧退货单号,可直接落 * {@code providerReturnId};状态不回,只能后续人工或回调补。
*/ @Override public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) { EdayunReturnDtos.SaveReturnRequest body = EdayunReturnMapper.toRequest(cmd, ctx.providerWarehouseId()); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_CREATE, bodyJson, "warehouse.return.create"); EdayunReturnDtos.SaveReturnResponse parsed = json.fromJson(resp.body(), EdayunReturnDtos.SaveReturnResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.return.create"); if (parsed.data == null || parsed.data.trim().isEmpty()) { throw WarehouseException.builder() .message("edayun return create returned no return order no") .operation("warehouse.return.create") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .rawResponse(safeRelay(resp.body())) .retryable(false) .build(); } return EdayunReturnMapper.toCreated(cmd, parsed.data.trim(), ctx.warehouseCode()); } /** * 获取退货单详情({@code POST /webApi/rma/info/v1/getOrderDetail})。 * *{@code returnRequestNo} 可以是 OMS 退货单号,也可以是仓方 RMA 号—— * 仓方只认 {@code rmaCode},所以非 RMA 号要先有创建时拿到的 * {@code providerReturnId}。这里原样传,查不到由仓方报错。
* *明细行优先取仓的检验结果({@code checkList}),没有才退回预报 * ({@code skuList})——对账以实际收到为准。
*/ @Override public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) { EdayunReturnDetailDtos.GetReturnRequest body = EdayunReturnDetailMapper.toRequest(returnRequestNo); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_DETAIL, bodyJson, "warehouse.return.get"); EdayunReturnDetailDtos.GetReturnResponse parsed = json.fromJson(resp.body(), EdayunReturnDetailDtos.GetReturnResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.return.get"); if (parsed.data == null) { // 单号不存在时仓方可能回 code=200 + data=null,按「查不到」返回 null return null; } return EdayunReturnDetailMapper.toReturn(parsed.data, ctx.warehouseCode(), body.rmaCode); } /** * 取消退货单({@code POST /webApi/rma/info/v1/cancel})。 * *只认仓方 {@code rmaCode},所以传的必须是创建时拿到的 * {@code providerReturnId}——用 OMS 单号会被仓方查不到。
* *响应 {@code data=true} 才算成功。{@code code=200} + {@code data=false} * 是仓方拒绝(如已收货),这里抛异常而不是静默返回 false—— * 取消退货是状态变更,调用方必须知道没成功。
*/ @Override public boolean cancel(WarehouseContext ctx, String providerReturnNo) { if (!hasText(providerReturnNo)) { throw new IllegalArgumentException( "edayun return cancel needs the provider return no (rmaCode)"); } EdayunCancelReturnDtos.CancelReturnRequest body = new EdayunCancelReturnDtos.CancelReturnRequest(); body.rmaCode = providerReturnNo.trim(); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_CANCEL, bodyJson, "warehouse.return.cancel"); EdayunCancelReturnDtos.CancelReturnResponse parsed = json.fromJson(resp.body(), EdayunCancelReturnDtos.CancelReturnResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.return.cancel"); if (parsed.data == null || !parsed.data) { throw WarehouseException.builder() .message("edayun return cancel rejected: " + parsed.msg) .operation("warehouse.return.cancel") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .rawResponse(safeRelay(resp.body())) .retryable(false) .build(); } return true; } /** * 查询退货单列表({@code POST /webApi/rma/info/v1/selectRmaInfoList})。 * *只回单头,没有明细行与退货人地址;要明细请用 {@link #getReturn}。
* *时间窗不传时仓方默认近一个月——这一点由仓方兜底,本地不补默认值, * 免得「没给时间窗」和「显式要近一个月」两种情况被混掉。
*/ @Override public Page需要仓侧明细行 id,而查退货单的接口还没有——无法构造,显式拒绝。
*/ @Override public void process(WarehouseContext ctx, ReturnProcessCommand cmd) { throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN_DISPOSITION); } // ------------------------------------------------------------------ BOL / 物流产品 /** * 查询 BOL(提单 / 提货凭证) * ({@code POST /webApi/fbaOrder/v1/getOrderBolList})。 * *店铺订单与平台仓订单共用,{@code orderNo} 传 EDA 的平台仓订单号 * (如 {@code FBA473182144})。没有 BOL 时返回空列表,不是错误。
*/ @Override public List{@code productId = -998}(使用分物流规则)不是真实产品,映射时跳过。
*/ @Override public List请求体是纯字符串数组,文档示例的嵌套对象是错的。 * 仓方无轨迹时返回空列表——真机对查不到的跟踪号回 * {@code code=500, msg=未匹配到轨迹},那是「没轨迹」不是「调用失败」。
*/ @Override public List文档说明「主要关注上网时间跟妥投时间」,这两个在 * {@link TrackingInfo#firstOnlineAt()} / {@link TrackingInfo#deliveredAt()}。
*/ @Override public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) { EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track.shipment"); return EdayunTrackMapper.toTrackingInfo(parsed); } /** * 查一条轨迹;查不到返回 null。 * *「未匹配到轨迹」按空结果处理:仓方把这个当业务失败(code=500), * 但对调用方来说和「运单还没揽收」是同一件事——两者都不该抛异常, * 否则宿主无法区分「真失败」和「还没轨迹」。
*/ private EdayunTrackDtos.Track fetchTrack(WarehouseContext ctx, String trackingNumber, String operation) { List端点名叫 printBarcode,但实际打的是箱唛(外箱标)——已与仓方确认。 * 真正的 SKU 标走 {@code printSkuLabel}(端点 {@code newPrintCaseMark})。
* *与入库箱标({@code inbound().printBoxLabel})不同:那个是运去哪风格的 * 异步任务(只回任务号),易达云这个同步返回 PDF 地址。
* *真机实测的仓方校验:{@code productInfos} 为空报「产品信息不能为空」, * 缺 {@code pageSize} 报「纸张尺寸不能为空」,{@code pageSize} 非 0~3 报 * 「内部服务器错误」,{@code num=0} 同样「内部服务器错误」,超过 50 个 SKU * 报「最多打印50个SKU」。本地已提前挡住后两者。
*/ @Override public WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd) { EdayunCaseMarkDtos.PrintCaseMarkRequest body = EdayunCaseMarkMapper.toRequest(cmd); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_CASE_MARK_PRINT, bodyJson, "warehouse.caseMark.print"); EdayunCaseMarkDtos.PrintCaseMarkResponse parsed = json.fromJson(resp.body(), EdayunCaseMarkDtos.PrintCaseMarkResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.caseMark.print"); if (parsed.data == null || parsed.data.trim().isEmpty()) { throw WarehouseException.builder() .message("edayun printBarcode returned no file url") .operation("warehouse.caseMark.print") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .rawResponse(safeRelay(resp.body())) .retryable(false) .build(); } return EdayunCaseMarkMapper.toLabel(parsed.data.trim(), cmd); } // ------------------------------------------------------------------ SKU 标 /** * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。 * *端点名叫 newPrintCaseMark,但实际打的是 SKU 标——已与仓方确认。 * 箱唛走 {@code printCaseMarks}(端点 {@code printBarcode})。
* *统一模型的 {@code BoxLabelCommand} 没有「选哪些箱」的字段, * 所以默认整单打印;要打部分箱用重载。
* *刻意不是 public、也没声明 {@code SKU_LABEL} 能力位:该接口在 PR 环境 * 参数齐全后一律「内部服务器错误」(路径已确认存在,缺参数有中文校验提示), * 属于仓方服务端异常。放成 public 会让调用方以为门面够得到,实际门面按 * {@code SKU_LABEL} 门控、会直接抛不支持。等仓方修复后再提升可见性并声明能力位。 * 见 docs-warehouse/edayun/TODO.md #68。
*/ WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) { EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd); return sendSkuLabel(ctx, body); } /** * 打印 SKU 标(可选箱)。 * * @param selection 选箱条件;四选一,全空时本地拒绝 */ WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd, EdayunSkuLabelMapper.CaseSelection selection) { EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd, selection); return sendSkuLabel(ctx, body); } private WarehouseLabel sendSkuLabel(WarehouseContext ctx, EdayunSkuLabelDtos.PrintSkuLabelRequest body) { String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_SKU_LABEL_PRINT, bodyJson, "warehouse.skuLabel.print"); EdayunSkuLabelDtos.PrintSkuLabelResponse parsed = json.fromJson(resp.body(), EdayunSkuLabelDtos.PrintSkuLabelResponse.class); requireSuccess(ctx, parsed == null ? null : parsed.code, parsed == null ? null : parsed.msg, resp, "warehouse.skuLabel.print"); if (parsed.data == null || parsed.data.trim().isEmpty()) { throw WarehouseException.builder() .message("edayun newPrintCaseMark returned no file url") .operation("warehouse.skuLabel.print") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .rawResponse(safeRelay(resp.body())) .retryable(false) .build(); } return EdayunSkuLabelMapper.toLabel(parsed.data.trim()); } // ------------------------------------------------------------------ 承运商 /** * 客户名下有权限的仓库列表 * ({@code POST /webApi/warehouse/listWarehouseHasPerm})。 * *用这个,不要用 listActive:listActive 是平台全量激活仓(118 条), * 含当前客户没授权的;这个只返回有权限的(69 条)。
* *{@code -999}(智能分仓)是哨兵值,映射时已跳过。
*/ @Override public List与 {@link #warehouses} 的区别:那个只返回有权限的仓;这个是平台 * 全量(实测 118 条 vs 69 条),含当前客户没授权的——不要用它给客户选仓。
* *实测:{@code warehouseOperationType=0} 尾程仓 111 条、{@code =1} 头程仓 7 条、 * 不传则两者之和 118 条(文档说必填,实际不传也通)。
*/ public List返回「承运商 → 物流服务」两层。{@code warehouseId} 只认数字; * 非数字或为空时不下发,仓方会返回所有服务商。
* *真机(2026-11-16):仓 2 → 11 个承运商;不传仓 → 22 个; * 只按国家 US → 10 个。{@code ownLogisticList} 实测是数组(文档写成对象)。
*/ @Override public List