package common.ecommerce.hengjian.adapter; import com.fasterxml.jackson.databind.JsonNode; import common.ecommerce.hengjian.dto.HengjianAddressClassificationDtos; import common.ecommerce.hengjian.dto.HengjianCancelOrderDtos; import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos; import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos; import common.ecommerce.hengjian.dto.HengjianInventoryDtos; import common.ecommerce.hengjian.dto.HengjianInboundCreateDtos; import common.ecommerce.hengjian.dto.HengjianInboundQueryDtos; import common.ecommerce.hengjian.dto.HengjianInventoryMovementDtos; import common.ecommerce.hengjian.dto.HengjianReturnDetailDtos; import common.ecommerce.hengjian.dto.HengjianReturnHandleDtos; import common.ecommerce.hengjian.dto.HengjianReturnListDtos; import common.ecommerce.hengjian.dto.HengjianReturnPlanCreateDtos; import common.ecommerce.hengjian.dto.HengjianTransferDtos; import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; import common.ecommerce.hengjian.dto.HengjianOrderListDtos; import common.ecommerce.hengjian.dto.HengjianProductSaveDtos; import common.ecommerce.hengjian.dto.HengjianStorageFeeDtos; import common.ecommerce.hengjian.dto.HengjianTailDeliveryFeeDtos; import common.ecommerce.hengjian.dto.HengjianTrackingChangeDtos; import common.ecommerce.hengjian.dto.HengjianTrackingChangeQueryDtos; import common.ecommerce.hengjian.dto.HengjianWarehouseDtos; import common.ecommerce.hengjian.HengjianConstants; import common.ecommerce.hengjian.http.HengjianEnvelope; import common.ecommerce.hengjian.http.HengjianRateLimiter; import common.ecommerce.hengjian.http.HengjianRequestFactory; 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.capability.AddressClassificationCapable; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.TrackingChangeCapable; import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; 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.enums.AddressType; import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.enums.ReturnStatus; import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.enums.TrackingChangeHandleType; import common.ecommerce.warehouse.enums.WarehouseCapability; import common.ecommerce.warehouse.enums.SortDirection; import common.ecommerce.warehouse.enums.WarehouseFeeType; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.CancelCommand; import common.ecommerce.warehouse.model.CancelResult; 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.InboundQuery; import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InventoryMovement; import common.ecommerce.warehouse.model.InventoryMovementQuery; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.ReturnCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.TransferQuery; import common.ecommerce.warehouse.model.WarehouseReturn; 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.TrackingChangeCommand; import common.ecommerce.warehouse.model.TrackingChangeOrder; import common.ecommerce.warehouse.model.WarehouseFacility; import common.ecommerce.warehouse.sdk.WarehouseContext; import java.time.ZoneOffset; import java.util.ArrayList; import java.util.EnumSet; import java.util.Iterator; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; /** * 恒健适配器。 * *

已接入:仓库目录、承运商 / 物流产品、按仓的物流渠道(只读), * 以及商品创建 / 编辑({@code /v1/product/save},保存语义)。

* *

出库 / 库存 / 入库 / 退货等接口尚未接入,能力位不声明: * 门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException},不返回空集合。

* *

适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * {@code WarehouseConnection} 传入。

*/ public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable, InboundCapable, TransferCapable, WarehouseReturnCapable { private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; private static final String OP_CARRIERS = "warehouse.directory.carriers"; private static final String OP_LOGISTICS_PRODUCTS = "warehouse.logistics.products"; private static final String OP_PRODUCT_SAVE = "warehouse.product.create"; private static final String OP_ORDER_CREATE = "warehouse.outbound.create"; private static final String OP_ORDER_GET = "warehouse.outbound.get"; private static final String OP_ORDER_QUERY = "warehouse.outbound.query"; private static final String OP_ORDER_CANCEL = "warehouse.outbound.cancel"; private static final String OP_TRACKING_CHANGE_CREATE = "warehouse.tracking.change.create"; private static final String OP_TRACKING_CHANGE_GET = "warehouse.tracking.change.get"; private static final String OP_FEE_STORAGE = "warehouse.fee.storage"; private static final String OP_FEE_TAIL_DELIVERY = "warehouse.fee.tailDelivery"; private static final String OP_FEE_OPERATION = "warehouse.fee.operation"; private static final String OP_FEE_ESTIMATE = "warehouse.fee.estimate"; private static final String OP_ADDRESS_CLASSIFY = "warehouse.address.classify"; private static final String OP_INVENTORY_QUERY = "warehouse.inventory.query"; private static final String OP_INVENTORY_MOVEMENTS = "warehouse.inventory.movements"; private static final String OP_INBOUND_CREATE = "warehouse.inbound.create"; private static final String OP_INBOUND_GET = "warehouse.inbound.get"; private static final String OP_INBOUND_QUERY = "warehouse.inbound.query"; private static final String OP_TRANSFER_CREATE = "warehouse.transfer.create"; private static final String OP_TRANSFER_QUERY = "warehouse.transfer.query"; private static final String OP_TRANSFER_CANCEL = "warehouse.transfer.cancel"; private static final String OP_RETURN_CREATE = "warehouse.return.create"; private static final String OP_RETURN_GET = "warehouse.return.get"; private static final String OP_RETURN_QUERY = "warehouse.return.query"; private static final String OP_RETURN_HANDLES = "warehouse.return.handles"; private static final String OP_RETURN_PROCESS = "warehouse.return.process"; /** 退货列表默认页大小(文档没写,按同站惯例 100)。 */ private static final int PAGE_SIZE_DEFAULT = 100; /** 退货处理单列表默认页大小(文档写默认 20)。 */ private static final int HANDLE_PAGE_SIZE_DEFAULT = 20; /** 保存语义没有 create / update 之分,仓方也不回是哪种。 */ private static final String SAVED = "SAVED"; private final HttpTransport transport; private final JacksonJsonCodec json; private final HengjianRequestFactory requestFactory; private final HengjianRateLimiter rateLimiter; public HengjianAdapter(HttpTransport transport, JacksonJsonCodec json) { this.transport = transport; this.json = json; this.requestFactory = new HengjianRequestFactory(json); this.rateLimiter = new HengjianRateLimiter(); } @Override public String adapterId() { return HengjianConstants.ADAPTER_ID; } @Override public WarehouseProvider provider() { return WarehouseProvider.HENGJIAN; } @Override public EnumSet capabilities() { return EnumSet.of( WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, WarehouseCapability.PLATFORM_LABEL_DELIVERY, WarehouseCapability.TRACKING_CHANGE, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND, WarehouseCapability.TRANSFER, WarehouseCapability.RETURN, WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE, WarehouseCapability.ADDRESS_CLASSIFICATION, WarehouseCapability.DIRECTORY, WarehouseCapability.LOGISTICS_PRODUCT); } // ------------------------------------------------------------------ 退货 /** * 创建退货计划({@code POST /v1/saleReturn/thirdParty/saveReturnPlan})。 * *

承接门面的幂等守卫(键 {@code warehouseCode + returnRequestNo + create})。

* *

请求是双层包裹(业务字段在 {@code params} 下),与其它接口不同。

* *

响应只回头级信息,不回明细行——需要明细要再查详情。

*/ @Override public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) { String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( cmd.warehouseId(), ctx.providerWarehouseId()); HengjianReturnPlanCreateDtos.SaveRequest body = HengjianReturnMapper.toRequest(cmd, warehouseCode); String raw = execute(ctx, HengjianConstants.PATH_RETURN_PLAN_CREATE, body, OP_RETURN_CREATE); HengjianReturnPlanCreateDtos.SaveResponse resp = json.fromJson(raw, HengjianReturnPlanCreateDtos.SaveResponse.class); if (resp == null || resp.data == null || trimToNull(resp.data.returnPlanNo) == null) { // 拿不到仓侧计划单号不能当成功:后续查询 / 处理方式都要它 throw WarehouseException.builder() .message("hengjian return plan returned no returnPlanNo: " + safeRelay(raw)) .operation(OP_RETURN_CREATE) .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .rawResponse(safeRelay(raw)) .build(); } return HengjianReturnMapper.toCreated(cmd, resp.data); } /** * 查退货计划详情({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo})。 * *

请求是双层包裹({@code {"params":{"orderNo"}}})。单号既可是计划单号, * 也可是来源单号——详情响应同时回 {@code returnPlanNo} 与 {@code sourceOrderNo}。

* *

查不到({@code data} 为空)返回 null。

*/ @Override public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) { String orderNo = trimToNull(returnRequestNo); if (orderNo == null) { throw new IllegalArgumentException("hengjian return detail requires an order number"); } HengjianReturnDetailDtos.DetailRequest body = HengjianReturnQueryMapper.toDetailRequest(orderNo); String raw = execute(ctx, HengjianConstants.PATH_RETURN_PLAN_DETAIL, body, OP_RETURN_GET); JsonNode data = json.nodeAt(raw, "data"); if (data == null || data.isNull() || data.isMissingNode()) { return null; } HengjianReturnDetailDtos.PlanDetail detail = json.fromJson(data.toString(), HengjianReturnDetailDtos.PlanDetail.class); return HengjianReturnQueryMapper.toReturn(detail); } /** * 分页查退货计划({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage})。 * *

统一模型这个入口只有游标,恒健的列表支持更多条件;这里把游标当页码, * 其余条件为空——需要按状态 / 时间窗筛时用 {@link #queryReturnsAdvanced}。

*/ @Override public Page queryReturns(WarehouseContext ctx, String cursor) { return queryReturnsAdvanced(ctx, null, null, null, null, null, null, cursor); } /** * 多条件分页查退货计划。 * *

恒健只支持单个状态过滤({@code returnPlanStatus} 是单值不是数组), * 给多个状态时拒绝——静默只取一个会让调用方以为筛全了。

*/ public Page queryReturnsAdvanced(WarehouseContext ctx, List statuses, String startTime, String endTime, Integer queryDataType, String queryType, String queryValue, String cursor) { if (statuses != null && statuses.size() > 1) { throw validation(ctx, OP_RETURN_QUERY, "hengjian return list supports a single status filter, got " + statuses); } ReturnStatus single = statuses == null || statuses.isEmpty() ? null : statuses.get(0); int page = HengjianReturnQueryMapper.pageOf(cursor); int size = HengjianReturnQueryMapper.rowsOf(PAGE_SIZE_DEFAULT); HengjianReturnListDtos.ListRequest body = HengjianReturnQueryMapper.toListRequest( statuses, single, startTime, endTime, queryDataType, queryType, queryValue, null, page, size); String raw = execute(ctx, HengjianConstants.PATH_RETURN_PLAN_PAGE, body, OP_RETURN_QUERY); HengjianReturnListDtos.ListResponse resp = json.fromJson(raw, HengjianReturnListDtos.ListResponse.class); return HengjianReturnQueryMapper.toPage(resp == null ? null : resp.data, cursor, size); } /** * 查退货处理单列表({@code POST /v1/saleReturn/getReturnPlanHandlePage})。 * *

请求是平铺的(无 {@code params} 包裹),与 thirdParty 那两个不同。

* *

恒健没有对应的统一模型:这里返回仓方的处理单行,供宿主填写处理方式与回收照片。

*/ public Page queryReturnHandles( WarehouseContext ctx, List returnPlanNos, List trackingNos, List warehouseCodes, List handlingStatuses, String createdStart, String createdEnd, String cursor) { int page = HengjianReturnQueryMapper.pageOf(cursor); int size = HengjianReturnQueryMapper.handleRowsOf(HANDLE_PAGE_SIZE_DEFAULT); HengjianReturnHandleDtos.HandleListRequest body = HengjianReturnQueryMapper.toHandleListRequest(returnPlanNos, trackingNos, warehouseCodes, handlingStatuses, createdStart, createdEnd, page, size); String raw = execute(ctx, HengjianConstants.PATH_RETURN_HANDLE_PAGE, body, OP_RETURN_HANDLES); HengjianReturnHandleDtos.HandleListResponse resp = json.fromJson(raw, HengjianReturnHandleDtos.HandleListResponse.class); return HengjianReturnQueryMapper.toHandlePage(resp == null ? null : resp.data, cursor, size); } /** * 填写退货处理方式({@code POST /v1/saleReturn/handlingMethod})。 * *

请求平铺,用 {@code returnPlanNo + returnNo + erpSku + tracking} 四项定位, * 不用行 id——与运去哪的条目处理接口不同。

* *

两级处理方式:{@code handlingMethod}(1 继续拍照 / 2 处理方式)是开关, * {@code primaryHandlingMethod}(101~206)是具体动作。core 的 * {@code ReturnProcessDisposition} 只有部分能映射(销毁 / 上架良品 / 换标上架 / 卖家自提), * 拍照类与重新包装必须显式给原值。

*/ @Override public void process(WarehouseContext ctx, ReturnProcessCommand cmd) { HengjianReturnHandleDtos.HandlingMethodRequest body = HengjianReturnQueryMapper.toHandlingMethodRequest(cmd); execute(ctx, HengjianConstants.PATH_RETURN_HANDLING_METHOD, body, OP_RETURN_PROCESS); } // ------------------------------------------------------------------ 调拨 /** * 创建调拨计划({@code POST /v1/transferPlan/create})。 * *

真机确认必填:调出 / 调入仓、期望出库 / 入库时间。 * 响应 {@code data} 是字符串单号(不是对象)。

* *

外部仓库用仓代码 {@code Other} 表达——恒健的约定,适配器不猜。

*/ @Override public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) { HengjianTransferDtos.CreateRequest body = HengjianTransferMapper.toRequest(cmd); String raw = execute(ctx, HengjianConstants.PATH_TRANSFER_CREATE, body, OP_TRANSFER_CREATE); String planNo = json.stringAt(raw, "data"); if (trimToNull(planNo) == null) { // 拿不到单号不能当成功:后续查询 / 取消都要它 throw WarehouseException.builder() .message("hengjian transfer returned no data (plan no): " + safeRelay(raw)) .operation(OP_TRANSFER_CREATE) .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .rawResponse(safeRelay(raw)) .build(); } return HengjianTransferMapper.toCreated(cmd, planNo.trim()); } /** * 多条件分页查调拨计划({@code GET /v1/transferPlan/findByPage})。 * *

恒健的过滤参数都是单值(不是数组),所以统一模型里给了多个单号时 * 只下发第一个——这与其它接口「拒绝多值」的做法不同,因为这里的语义是 * 「按这个单号查」,多给没有意义。文档已注明。

*/ @Override public Page queryTransfers(WarehouseContext ctx, TransferQuery query) { Map params = HengjianTransferMapper.toPageParams(query, query.cursor()); rateLimiter.acquire(HengjianConstants.PATH_TRANSFER_PAGE, HengjianConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), HengjianConstants.PATH_TRANSFER_PAGE, params, ctx.secret(), ctx, OP_TRANSFER_QUERY); String raw = HengjianEnvelope.of(transport.execute(req), json, OP_TRANSFER_QUERY, ctx.warehouseCode(), ctx.requestId()).body(); HengjianTransferDtos.PageResponse resp = json.fromJson(raw, HengjianTransferDtos.PageResponse.class); return HengjianTransferMapper.toPage(resp == null ? null : resp.data, query.cursor()); } /** * 取消调拨计划({@code GET /v1/transferPlan/cancel})。 * *

这是统一模型里 {@link TransferCapable#deleteTransfer} 的落点:恒健叫「取消」, * 语义等价于「撤销这张调拨单」。取消要收费是运去哪的概念,恒健没有。

* *

参数在 query(不是 body);真机确认 {@code sourceNo} 必填。

*/ @Override public void deleteTransfer(WarehouseContext ctx, String providerTransferNo) { String sourceNo = trimToNull(providerTransferNo); if (sourceNo == null) { throw new IllegalArgumentException("hengjian transfer cancel requires sourceNo"); } Map params = new LinkedHashMap(); params.put("sourceNo", sourceNo); rateLimiter.acquire(HengjianConstants.PATH_TRANSFER_CANCEL, HengjianConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), HengjianConstants.PATH_TRANSFER_CANCEL, params, ctx.secret(), ctx, OP_TRANSFER_CANCEL); try { HengjianEnvelope.of(transport.execute(req), json, OP_TRANSFER_CANCEL, ctx.warehouseCode(), ctx.requestId()); } catch (PlatformBusinessException e) { // 取消失败只有 message(如「未查询到对应调拨计划数据」); // 不能细分成状态错还是参数错,原样抛出业务异常 throw e; } } // ------------------------------------------------------------------ 入库 /** * 创建入库计划({@code POST /v1/inbound/createInboundPlan})。 * *

承接门面的幂等守卫(键 {@code warehouseCode + inboundRequestNo + create})。

* *

响应不回仓单号:只有 {@code code / message}。所以 * {@code providerInboundId} 为 null——后续查详情 / 取消只能用来源单号。 * 这里不把来源单号冒充仓单号填进去。

* *

{@code status=0} 是草稿,草稿状态下再调本接口是更新而非新建。 * 由调用方经 {@code InboundCommand.documentStatus()} 决定,适配器不猜。

*/ @Override public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) { String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( cmd.warehouseId(), ctx.providerWarehouseId()); HengjianInboundCreateDtos.CreateRequest body = HengjianInboundMapper.toRequest(cmd, warehouseCode); execute(ctx, HengjianConstants.PATH_INBOUND_CREATE, body, OP_INBOUND_CREATE); // 仓方不回单号:保持 null,不拿来源单号顶替 return InboundReceipt.of(cmd.inboundRequestNo(), null); } /** * 查入库计划详情({@code POST /v1/inbound/getInboundPlanInfo})。 * *

恒健只按单号查,且这个单号可以是仓方计划单号,也可以是来源单号 * (详情响应同时回 {@code inboundPlanOrderNo} 与 {@code sourceNo})。

* *

查不到({@code data} 为空)返回 null——与其它仓一致。

*/ @Override public InboundOrder get(WarehouseContext ctx, String inboundRef) { String orderNo = trimToNull(inboundRef); if (orderNo == null) { throw new IllegalArgumentException("hengjian inbound get requires an order number"); } HengjianInboundQueryDtos.FindOneRequest body = HengjianInboundQueryMapper.toFindOneRequest(orderNo); String raw = execute(ctx, HengjianConstants.PATH_INBOUND_GET, body, OP_INBOUND_GET); JsonNode data = json.nodeAt(raw, "data"); if (data == null || data.isNull() || data.isMissingNode()) { return null; } HengjianInboundQueryDtos.InboundPlan plan = json.fromJson(data.toString(), HengjianInboundQueryDtos.InboundPlan.class); return HengjianInboundQueryMapper.toOrder(plan, fallbackWarehouse(ctx)); } /** * 按游标分页查入库单。 * *

统一模型这个入口只有一个游标,恒健的列表接口支持多条件;这里把游标当页码, * 其余条件为空——需要按状态 / 时间窗筛时用 * {@link #queryInbounds(WarehouseContext, InboundQuery)}。

*/ @Override public Page query(WarehouseContext ctx, String cursor) { return queryInbounds(ctx, InboundQuery.builder().cursor(cursor).build()); } /** * 多条件分页查入库计划({@code POST /v1/inbound/getInboundPlanPage})。 * *

恒健列表支持的维度:仓 / 计划单号 / 来源单号 / 状态码 / 库存类型 / * 七种时间区间(创建 / 更新 / 完成 / 期望到货 / 预计发货 / 预计入库 / 首次接收)/ * Amazon shipmentId。

* *

统一模型只表达其中三种时间窗(创建 / 更新 / 完成)。其余四种恒健独有, * 模型里没有——需要时再经 {@code InboundQuery} 扩字段,不在这里硬塞。

* *

未支持的维度直接拒绝:见 {@link #queryInbounds} 里的校验。

*/ @Override public Page queryInbounds(WarehouseContext ctx, InboundQuery query) { HengjianInboundQueryDtos.PageRequest body = HengjianInboundQueryMapper.toPageRequest(query, ctx.providerWarehouseId()); String raw = execute(ctx, HengjianConstants.PATH_INBOUND_PAGE, body, OP_INBOUND_QUERY); HengjianInboundQueryDtos.PageResponse resp = json.fromJson(raw, HengjianInboundQueryDtos.PageResponse.class); return HengjianInboundQueryMapper.toPage(resp == null ? null : resp.data, fallbackWarehouse(ctx), query.cursor()); } // ------------------------------------------------------------------ 库存 /** * 库存同步策略。 * *

恒健的两个库存接口都不支持按更新时间增量:按 SKU 的全量返回、 * 按仓的分页返回,都没有 {@code updatedAfter} 入参。所以策略是 * {@link InventorySyncStrategy#FULL_PULL_DIFF}——宿主全量拉后自己做差异比对。

* *

流水接口({@code movements})能按日期查,但那是变动明细, * 不是余额,不能拿来重建当前库存。

*/ @Override public InventorySyncStrategy syncStrategy() { return InventorySyncStrategy.FULL_PULL_DIFF; } /** * 查库存。 * *

恒健有两个接口,统一模型只有一个方法,按「给了什么」分流:

*
    *
  • 给了 SKU → {@code POST /v1/inventory/getInventory}(不分页,一次返回全部匹配行);
  • *
  • 只给仓 → {@code GET /v2/inventory/get_inventory_by_page}(分页)。
  • *
* *

两者都给的场景(按仓 + SKU 过滤)恒健没有对应接口,本地拒绝—— * 静默丢掉一个条件会让调用方以为过滤生效了。

* *

{@code updatedAfter} 恒健不支持,传了就拒绝(同上理由)。

*/ @Override public Page query(WarehouseContext ctx, InventoryQuery query) { if (query.updatedAfter() != null) { throw validation(ctx, OP_INVENTORY_QUERY, "hengjian inventory has no updatedAfter filter; full-pull and diff instead"); } boolean bySku = !query.providerSkus().isEmpty(); boolean byWarehouse = !query.warehouseCodes().isEmpty(); if (bySku && byWarehouse) { throw validation(ctx, OP_INVENTORY_QUERY, "hengjian has two separate inventory APIs: one filters by sku, " + "the other by warehouseCodes; combining both is not supported"); } if (query.inventoryType() != null || query.includeZeroStock() != null) { throw validation(ctx, OP_INVENTORY_QUERY, "hengjian inventory has no inventoryType / includeZeroStock filter"); } if (!bySku && !byWarehouse) { // 什么都不给会退化成「整仓全量」;这必须是调用方显式意愿,不能由缺省触发 throw validation(ctx, OP_INVENTORY_QUERY, "hengjian inventory query requires providerSkus or warehouseCodes"); } return bySku ? queryBySku(ctx, query) : queryByPage(ctx, query); } /** 按 SKU 查(不分页)。 */ private Page queryBySku(WarehouseContext ctx, InventoryQuery query) { HengjianInventoryDtos.QueryBySkuRequest body = HengjianInventoryMapper.toBySkuRequest(query); String raw = execute(ctx, HengjianConstants.PATH_INVENTORY_BY_SKU, body, OP_INVENTORY_QUERY); List rows = json.listAt(raw, "data", HengjianInventoryDtos.InventoryRow.class); return Page.last(HengjianInventoryMapper.toSnapshots(rows, fallbackWarehouse(ctx))); } /** 按仓分页查。 */ private Page queryByPage(WarehouseContext ctx, InventoryQuery query) { Map> params = HengjianInventoryMapper.toPageParams(query, ctx.providerWarehouseId()); rateLimiter.acquire(HengjianConstants.PATH_INVENTORY_PAGE, HengjianConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.getMulti(ctx.endpointBaseUrl(), HengjianConstants.PATH_INVENTORY_PAGE, params, ctx.secret(), ctx, OP_INVENTORY_QUERY); String raw = HengjianEnvelope.of(transport.execute(req), json, OP_INVENTORY_QUERY, ctx.warehouseCode(), ctx.requestId()).body(); int rows = HengjianInventoryMapper.rowsOf(query.pageSize()); return HengjianInventoryMapper.toPage(json.nodeAt(raw, "data"), fallbackWarehouse(ctx), rows, json); } /** * 库存变动流水({@code POST /v1/inventory/task/query})。 * *

真机确认:SKU 与日期区间都必填,区间 ≤ 30 个自然日,rows 1~100。

*/ @Override public Page queryMovements(WarehouseContext ctx, InventoryMovementQuery query) { HengjianInventoryMovementDtos.QueryRequest body = HengjianInventoryMapper.toMovementRequest(query); String raw = execute(ctx, HengjianConstants.PATH_INVENTORY_MOVEMENTS, body, OP_INVENTORY_MOVEMENTS); HengjianInventoryMovementDtos.QueryResponse resp = json.fromJson(raw, HengjianInventoryMovementDtos.QueryResponse.class); int rows = HengjianInventoryMapper.movementRowsOf(query.pageSize()); return HengjianInventoryMapper.toMovementPage( resp == null ? null : resp.data, fallbackWarehouse(ctx), rows, query.cursor()); } /** 仓编码兜底:优先仓方编码,其次 OMS 仓编码。 */ private static String fallbackWarehouse(WarehouseContext ctx) { String provider = trimToNull(ctx.providerWarehouseId()); return provider == null ? ctx.warehouseCode() : provider; } // ------------------------------------------------------------------ 试算与地址属性 /** * 运费测算({@code POST /v2/api/shipping/calculate})。 * *

统一模型是 cm / g,恒健也接受 {@code cm} / {@code g},不换算; * 但它的包裹尺寸字段是 INTEGER,所以厘米值四舍五入取整(截断会让报价偏低)。

* *

恒健不按仓维度返回报价,结果只有一个实例, * {@code shipOrgWarehouseCode} 用账户仓填充。

*/ @Override public List estimate(WarehouseContext ctx, FeeEstimateQuery query) { HengjianFeeEstimateDtos.CalculateRequest body = HengjianEstimateMapper.toRequest(query); String raw = execute(ctx, HengjianConstants.PATH_FEE_ESTIMATE, body, OP_FEE_ESTIMATE); HengjianFeeEstimateDtos.CalculateResponse resp = json.fromJson(raw, HengjianFeeEstimateDtos.CalculateResponse.class); String warehouseCode = trimToNull(ctx.providerWarehouseId()) == null ? ctx.warehouseCode() : ctx.providerWarehouseId(); List out = new ArrayList(1); out.add(HengjianEstimateMapper.toResult(resp == null ? null : resp.data, warehouseCode)); return out; } /** * 地址属性识别({@code POST /v2/api/shipping/addressClassification})。 * *

真机确认五项必填({@code street1 / zip / city / state / country}), * 缺任何一项仓方都回参数校验异常,所以本地先挡。

*/ @Override public AddressType classifyAddress(WarehouseContext ctx, String street1, String street2, String city, String state, String postal, String country) { String s1 = requireAddressPart(street1, "street1"); String c = requireAddressPart(city, "city"); String st = requireAddressPart(state, "state"); String zip = requireAddressPart(postal, "postal"); String cy = requireAddressPart(country, "country"); HengjianAddressClassificationDtos.ClassifyRequest body = HengjianEstimateMapper.toClassifyRequest(s1, street2, c, st, zip, cy); String raw = execute(ctx, HengjianConstants.PATH_ADDRESS_CLASSIFICATION, body, OP_ADDRESS_CLASSIFY); HengjianAddressClassificationDtos.ClassifyResponse resp = json.fromJson(raw, HengjianAddressClassificationDtos.ClassifyResponse.class); return HengjianEstimateMapper.addressTypeOf(resp == null ? null : resp.data); } private static String requireAddressPart(String value, String field) { String v = trimToNull(value); if (v == null) { throw new IllegalArgumentException( "hengjian address classification requires " + field); } return v; } // ------------------------------------------------------------------ 计费明细 /** * 拉取计费明细(仓储费 / 尾程费 / 作业费)。 * *

恒健把三类费用拆成三个独立接口,行字段各不相同,统一模型只有一个 * {@code settlements()}。因此必须由调用方用 {@link FeeQuery#costType()} 指定查哪一类:

* * * * * * *
costType接口
{@code STORAGE}{@code getChargingStorageSettlement}
{@code LAST_MILE}{@code getChargingTailDeliverySettlement}
{@code OPERATION}{@code getChargingOperationSettlement}
* *

不指定就拒绝而不是「三个都查再合并」:三类费用的行结构不同、金额口径也不同, * 合并会让调用方以为拿到了一份完整账单,实际少了另外两类。

* *

{@code VALUE_ADDED}(增值服务费)恒健没有对应接口,显式拒绝。

* *

分页

*

三个接口都是分页的,统一方法返回 {@code List}、不带游标,所以分页由调用方驱动: * 用 {@link FeeQuery#toBuilder()}{@code .pageCursor("2")} 翻页。 * 判末页的约定:返回条数小于本次请求的 {@code pageSize} 即末页 * (少于请求量说明后面没有了)。

*/ @Override public List settlements(WarehouseContext ctx, FeeQuery query) { WarehouseFeeType type = query.costType(); if (type == null) { throw validation(ctx, OP_FEE_STORAGE, "hengjian exposes three separate billing APIs; set FeeQuery.costType " + "(STORAGE / LAST_MILE / OPERATION) to pick one"); } switch (type) { case STORAGE: return fetchStorageFees(ctx, query); case LAST_MILE: return fetchTailDeliveryFees(ctx, query); case OPERATION: return fetchOperationFees(ctx, query); default: // VALUE_ADDED:恒健没有增值服务费的独立接口 throw validation(ctx, OP_FEE_STORAGE, "hengjian has no billing API for fee type " + type); } } private List fetchStorageFees(WarehouseContext ctx, FeeQuery query) { HengjianStorageFeeDtos.ListRequest body = new HengjianStorageFeeDtos.ListRequest(); body.page = HengjianFeeMapper.pageOf(query.pageCursor()); body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); body.orgWarehouseCodes = new ArrayList(); body.relOrderNos = new ArrayList(); body.sourceNos = new ArrayList(); body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); String raw = execute(ctx, HengjianConstants.PATH_FEE_STORAGE, body, OP_FEE_STORAGE); HengjianStorageFeeDtos.ListResponse resp = json.fromJson(raw, HengjianStorageFeeDtos.ListResponse.class); if (resp == null || resp.data == null) { return new ArrayList(); } final String warehouseCode = ctx.warehouseCode(); return HengjianFeeMapper.mapAll(resp.data.content, new HengjianFeeMapper.RowMapper() { @Override public BillingDocument map(HengjianStorageFeeDtos.StorageFeeRow row) { return HengjianFeeMapper.toDocument(row, warehouseCode); } }); } private List fetchTailDeliveryFees(WarehouseContext ctx, FeeQuery query) { HengjianTailDeliveryFeeDtos.ListRequest body = new HengjianTailDeliveryFeeDtos.ListRequest(); body.page = HengjianFeeMapper.pageOf(query.pageCursor()); body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); body.orgWarehouseCodes = new ArrayList(); body.relOrderNos = new ArrayList(); body.sourceNos = new ArrayList(); body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); String raw = execute(ctx, HengjianConstants.PATH_FEE_TAIL_DELIVERY, body, OP_FEE_TAIL_DELIVERY); HengjianTailDeliveryFeeDtos.ListResponse resp = json.fromJson(raw, HengjianTailDeliveryFeeDtos.ListResponse.class); if (resp == null || resp.data == null) { return new ArrayList(); } final String warehouseCode = ctx.warehouseCode(); return HengjianFeeMapper.mapAll(resp.data.content, new HengjianFeeMapper.RowMapper() { @Override public BillingDocument map(HengjianTailDeliveryFeeDtos.TailDeliveryFeeRow row) { return HengjianFeeMapper.toDocument(row, warehouseCode); } }); } private List fetchOperationFees(WarehouseContext ctx, FeeQuery query) { HengjianOperationFeeDtos.ListRequest body = new HengjianOperationFeeDtos.ListRequest(); body.page = HengjianFeeMapper.pageOf(query.pageCursor()); body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); body.orgWarehouseCodes = new ArrayList(); body.relOrderNos = new ArrayList(); body.sourceNos = new ArrayList(); body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); String raw = execute(ctx, HengjianConstants.PATH_FEE_OPERATION, body, OP_FEE_OPERATION); HengjianOperationFeeDtos.ListResponse resp = json.fromJson(raw, HengjianOperationFeeDtos.ListResponse.class); if (resp == null || resp.data == null) { return new ArrayList(); } final String warehouseCode = ctx.warehouseCode(); return HengjianFeeMapper.mapAll(resp.data.content, new HengjianFeeMapper.RowMapper() { @Override public BillingDocument map(HengjianOperationFeeDtos.OperationFeeRow row) { return HengjianFeeMapper.toDocument(row, warehouseCode); } }); } // ------------------------------------------------------------------ 物流异动单 /** * 创建物流异动单({@code POST /v1/trackingChange/create})。 * *

承接门面的幂等守卫(键 {@code warehouseCode + changeRequestNo + create}); * 这里只负责拼报文与解析。

* *

真机确认的必填项(文档标错 / 漏标):{@code trackingNo}、{@code orderNo}、 * {@code remark}、{@code handleType};换址(2)还要新收件人三项。 * 仓方还会校验「来源单号与 trackingNo 属于同一张单」——这一条本地挡不住, * 只能在真机联调时保证调用方给的是一对真实存在的单号 + 运单号。

* *

响应只回 {@code trackingChangeOrderNo},没有状态——创建成功只代表申请已提交, * 承运商是否受理要看 subsequent 查询。

*/ @Override public TrackingChangeOrder createChange(WarehouseContext ctx, TrackingChangeCommand cmd) { HengjianTrackingChangeDtos.CreateRequest body = toCreateRequest(cmd); String raw = execute(ctx, HengjianConstants.PATH_TRACKING_CHANGE_CREATE, body, OP_TRACKING_CHANGE_CREATE); HengjianTrackingChangeDtos.CreateResponse resp = json.fromJson(raw, HengjianTrackingChangeDtos.CreateResponse.class); if (resp == null || resp.data == null || trimToNull(resp.data.trackingChangeOrderNo) == null) { throw WarehouseException.builder() .message("hengjian tracking change returned no trackingChangeOrderNo: " + safeRelay(raw)) .operation(OP_TRACKING_CHANGE_CREATE) .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .rawResponse(safeRelay(raw)) .build(); } return TrackingChangeOrder.builder() .changeRequestNo(cmd.changeRequestNo()) .providerChangeOrderNo(resp.data.trackingChangeOrderNo.trim()) .sourceProvider(provider()) .warehouseCode(ctx.warehouseCode()) .trackingNumber(cmd.trackingNumber()) .orderNo(trimToNull(cmd.orderNo())) .handleType(cmd.handleType()) // 创建接口不回状态:保持 null,不拿请求侧的值冒充仓方状态 .build(); } /** * 查询物流异动单({@code POST /v1/trackingChange/findOrder})。 * *

路径与文档不同:文档写 {@code /v1/saleOrder/findOrder},真机 404; * 正确路径在 {@link HengjianConstants#PATH_TRACKING_CHANGE_FIND}。

*/ @Override public TrackingChangeOrder getChange(WarehouseContext ctx, String providerChangeOrderNo) { String changeNo = trimToNull(providerChangeOrderNo); if (changeNo == null) { throw new IllegalArgumentException("providerChangeOrderNo must not be blank"); } HengjianTrackingChangeQueryDtos.FindOrderRequest body = new HengjianTrackingChangeQueryDtos.FindOrderRequest(); body.trackingChangeOrderNo = changeNo; String raw = execute(ctx, HengjianConstants.PATH_TRACKING_CHANGE_FIND, body, OP_TRACKING_CHANGE_GET); JsonNode data = json.nodeAt(raw, "data"); if (data == null || data.isNull() || data.isMissingNode()) { return null; } HengjianTrackingChangeQueryDtos.TrackingChangeDetail detail = json.fromJson(data.toString(), HengjianTrackingChangeQueryDtos.TrackingChangeDetail.class); return HengjianTrackingChangeMapper.toOrder(detail, ctx.warehouseCode(), provider()); } /** 统一命令 → 恒健请求;必填项在本地校验。 */ static HengjianTrackingChangeDtos.CreateRequest toCreateRequest(TrackingChangeCommand cmd) { String trackingNo = requireText(cmd.trackingNumber(), "trackingNumber", cmd.changeRequestNo()); String orderNo = requireText(cmd.orderNo(), "orderNo", cmd.changeRequestNo()); String remark = requireText(cmd.remark(), "remark", cmd.changeRequestNo()); int handleType = handleTypeOf(cmd.handleType()); HengjianTrackingChangeDtos.CreateRequest body = new HengjianTrackingChangeDtos.CreateRequest(); body.trackingNo = trackingNo; body.orderNo = orderNo; body.remark = remark; body.handleType = handleType; if (cmd.handleType() == TrackingChangeHandleType.ADDRESS_CHANGE) { // 换址三项真机必填,缺任一项仓方都会拒;本地先说清楚缺哪个 body.newRecipientName = requireText(cmd.newRecipientName(), "newRecipientName", cmd.changeRequestNo()); body.newRecipientPhone = requireText(cmd.newRecipientPhone(), "newRecipientPhone", cmd.changeRequestNo()); body.newRecipientAddress = requireText(cmd.newRecipientAddress(), "newRecipientAddress", cmd.changeRequestNo()); } return body; } /** 核心枚举 → 恒健 handleType:1 召回 / 2 换址 / 3 在途异常。 */ static int handleTypeOf(TrackingChangeHandleType type) { if (type == null) { throw new IllegalArgumentException("handleType must not be null"); } switch (type) { case RECALL: return 1; case ADDRESS_CHANGE: return 2; case IN_TRANSIT_EXCEPTION: return 3; default: throw new IllegalArgumentException("unsupported handleType: " + type); } } private static String requireText(String value, String field, String changeRequestNo) { String v = trimToNull(value); if (v == null) { throw new IllegalArgumentException("hengjian tracking change " + changeRequestNo + " requires " + field + " (恒健必填)"); } return v; } // ------------------------------------------------------------------ 出库 /** * 创建销售发货单({@code POST /v1/saleOrder/create})。 * *

承接 {@code WarehouseOutbounds.create} 的幂等守卫:同一 * {@code outboundRequestNo} 重复下发由门面拦住,这里只负责拼报文与解析。

* *

响应只回 {@code data.orderId}(仓内部数字 id,不是字符串单号)。 * 恒健的取消接口同时要 {@code orderId} 与 {@code orderNo},所以这个 id * 必须随 {@link OutboundReceipt#providerOrderId()} 落库;缺了它后续取消做不了, * 因此拿不到就报错,不静默当成创建成功。

*/ @Override public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { requirePlatformLabelSupported(cmd); String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( cmd.warehouseId(), ctx.providerWarehouseId()); HengjianCreateOrderDtos.CreateOrderRequest body = HengjianOutboundMapper.toRequest(cmd, warehouseCode, ctx.clock()); String raw = execute(ctx, HengjianConstants.PATH_ORDER_CREATE, body, OP_ORDER_CREATE); HengjianCreateOrderDtos.CreateOrderResponse resp = json.fromJson(raw, HengjianCreateOrderDtos.CreateOrderResponse.class); if (resp == null || resp.data == null || resp.data.orderId == null) { throw WarehouseException.builder() .message("hengjian create order returned no data.orderId: " + safeRelay(raw)) .operation(OP_ORDER_CREATE) .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .rawResponse(safeRelay(raw)) .build(); } return OutboundReceipt.of(cmd.outboundRequestNo(), String.valueOf(resp.data.orderId), resp.message); } /** * 查订单详情({@code POST /v1/saleOrder/findOne})。 * *

恒健只按来源单号查。统一引用里的 {@code outboundRequestNo} 就是来源单号; * {@code providerOrderId} 是仓内部数字 id,这个接口查不了,所以拿来当兜底 * (调用方只给了 id 时照样发出去,仓方会查不到,由仓方报错而不是我们静默返回 null)。

* *

查不到({@code data} 为空)返回 null——与其它仓一致,调用方据此判断「没有这单」。

*/ @Override public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { String orderNo = orderNoOf(ref); HengjianOrderDetailDtos.FindOneRequest body = new HengjianOrderDetailDtos.FindOneRequest(); body.orderNo = orderNo; String raw = execute(ctx, HengjianConstants.PATH_ORDER_FIND_ONE, body, OP_ORDER_GET); JsonNode data = json.nodeAt(raw, "data"); if (data == null || data.isNull() || data.isMissingNode()) { return null; } HengjianOrderDetailDtos.OrderDetail detail = json.fromJson(data.toString(), HengjianOrderDetailDtos.OrderDetail.class); return HengjianOrderMapper.toOrder(detail, ctx.providerWarehouseId()); } /** * 查订单列表({@code GET /v1/saleOrder/findByPage})。 * *

恒健要求「时间、订单号、订单 id 三者必填其一」,所以:

*
    *
  • 给了 {@code outboundRequestNo} → 按 {@code orderNos} 查;
  • *
  • 给了时间窗 → 按 {@code beginDateTime / endDateTime} 查(UTC 日期);
  • *
  • 都没有 → 本地拒绝,不发一个必然被仓方拒的请求。
  • *
* *

时间跨度上限 30 天,超过也在本地拒绝。

* *

{@code orderRef}(平台单号)恒健没有对应查询参数,不参与查询; * {@code statuses} 恒健列表也没有状态过滤参数,传了就拒绝——静默忽略会让调用方 * 以为过滤生效了。

*/ @Override public Page query(WarehouseContext ctx, OutboundQuery query) { if (!query.statuses().isEmpty()) { throw validation(ctx, OP_ORDER_QUERY, "hengjian order list has no status filter; refusing to silently ignore " + query.statuses()); } // orderRef 是平台单号;恒健列表只有 orderNos(来源单号)与 orderIds, // 静默忽略会让调用方以为按平台单号过滤生效了 if (trimToNull(query.orderRef()) != null) { throw validation(ctx, OP_ORDER_QUERY, "hengjian order list cannot filter by platform order number (orderRef=" + query.orderRef() + "); use outboundRequestNo or poNo instead"); } Map params = new LinkedHashMap(); // rows 上限是文档明写的「默认最高 100」,超过即拒绝(不静默截断) int pageSize = requireRows(ctx, query.pageSize()); params.put("rows", pageSize); // 排序:调用方指定优先,未指定才用默认值。文档里 sidx 可写死 id、sort 有 asc/desc 两值 params.put("sidx", sortFieldOf(query.sortField())); params.put("sort", sortDirectionOf(query.sortDirection())); params.put("page", pageNumberOf(query.cursor())); // 可选过滤:仓方支持就透传,不支持的维度已在上方拒绝 putIfPresent(params, "channel", query.channel()); putIfPresent(params, "channelAccount", query.channelAccount()); putIfPresent(params, "poNo", query.poNo()); if (!query.providerOrderIds().isEmpty()) { params.put("orderIds", joinIds(query.providerOrderIds())); } if (query.hasUpdatedRange()) { // 更新时间窗按 UTC 时间戳下发,格式 yyyy-MM-dd HH:mm:ss params.put("updateBeginDate", formatDateTime(query.updatedAfter())); params.put("updateEndDate", formatDateTime(query.updatedBefore())); } // 文档:时间、订单号、订单 id 三者必填其一。 // 「时间」取创建时间窗(beginDateTime/endDateTime);更新时间窗与 PO 单号是可选附加条件, // 不能单独当主键——只给它们时仍按缺少主键拒绝。 String orderNo = trimToNull(query.outboundRequestNo()); if (orderNo != null) { params.put("orderNos", orderNo); } else if (query.after() != null && query.before() != null) { addDateRange(ctx, params, query); } else if (!query.providerOrderIds().isEmpty()) { // orderIds 已在上方放入 params,本身就是合法主键 } else { throw validation(ctx, OP_ORDER_QUERY, "hengjian order list requires outboundRequestNo, providerOrderIds " + "or both after/before (time, order number or order id - at least one)"); } rateLimiter.acquire(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, HengjianConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), HengjianConstants.PATH_ORDER_FIND_BY_PAGE, params, ctx.secret(), ctx, OP_ORDER_QUERY); String raw = HengjianEnvelope.of(transport.execute(req), json, OP_ORDER_QUERY, ctx.warehouseCode(), ctx.requestId()).body(); HengjianOrderListDtos.ListResponse resp = json.fromJson(raw, HengjianOrderListDtos.ListResponse.class); if (resp == null || resp.data == null) { throw validation(ctx, OP_ORDER_QUERY, "hengjian order list returned no data"); } List orders = new ArrayList(); if (resp.data.content != null) { for (HengjianOrderListDtos.OrderRow row : resp.data.content) { if (row == null) { continue; } orders.add(HengjianOrderMapper.toOrder(row, ctx.providerWarehouseId())); } } // 是否最后一页以仓方的 last 为准;缺省时用「本页是否满页」推断, // 不能只看 content 是否为空——空页在两种判断下含义不同 boolean last = resp.data.last != null ? resp.data.last : (resp.data.numberOfElements != null && resp.data.numberOfElements < pageSize); return last ? Page.last(orders) : Page.of(orders, String.valueOf(pageNumberOf(query.cursor()) + 1)); } /** * 取消资格预判:查详情按状态推断。 * *

恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款 / 已删除不再接受取消, * 判为 {@link CancelEligibility#BLOCKED};其余交给取消时仓方判定。

* *

查不到单时返回 BLOCKED,不猜 FREE——猜错会下发出一个注定被拒的取消。

*/ @Override public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) { OutboundOrder order = get(ctx, ref); if (order == null) { return CancelEligibility.BLOCKED; } switch (order.status()) { case SHIPPED: case CANCELLED: case REFUNDED: case DELETED: case UNKNOWN: // UNKNOWN 也判 BLOCKED:恒健的状态词表将来可能加值, // 认不出时不该凭猜下发取消 return CancelEligibility.BLOCKED; default: return CancelEligibility.FREE; } } /** * 取消订单({@code POST /v1/saleOrder/cancel})。 * *

恒健要求 {@code orderId} 与 {@code orderNo} 两个都传,而统一模型的 * {@link CancelCommand} 允许只给其中一个。约定:

*
    *
  • {@code outboundRequestNo} → 恒健 {@code orderNo};
  • *
  • {@code providerOrderId} → 恒健 {@code orderId}(仓内部数字 id)。
  • *
*

缺哪个就用已知的那个去列表接口补一次——这是拿到 {@code orderId} 的正规途径 * (详情接口不回它)。补不到(仓里没有这张单)直接报参数错误, * 不发必然被仓方拒的取消请求。

* *

恒健没有取消费概念,{@link CancelCommand#acceptCharge()} 在这里不生效。 * 仓方拒绝取消时抛 {@link OutboundCancelBlockedException},与参数错误区分开。

*/ @Override public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { String orderNo = trimToNull(cmd.outboundRequestNo()); Long orderId = parseOrderId(cmd.providerOrderId()); if (orderNo == null && orderId == null) { throw new IllegalArgumentException( "hengjian needs outboundRequestNo or providerOrderId to cancel an order"); } if (orderNo == null || orderId == null) { HengjianOrderListDtos.OrderRow row = findRow(ctx, orderNo, orderId); if (row == null) { throw validation(ctx, OP_ORDER_CANCEL, "hengjian order not found, cannot resolve " + (orderNo == null ? "orderNo" : "orderId") + " for " + (orderNo != null ? orderNo : String.valueOf(orderId))); } if (orderNo == null) { orderNo = trimToNull(row.orderNo); } if (orderId == null && row.orderId != null) { orderId = row.orderId; } } if (orderNo == null || orderId == null) { throw validation(ctx, OP_ORDER_CANCEL, "hengjian cancel requires both orderId and orderNo; " + "could not resolve " + (orderNo == null ? "orderNo" : "orderId")); } HengjianCancelOrderDtos.CancelOrderRequest body = new HengjianCancelOrderDtos.CancelOrderRequest(); body.orderId = orderId; body.orderNo = orderNo; String raw; try { raw = execute(ctx, HengjianConstants.PATH_ORDER_CANCEL, body, OP_ORDER_CANCEL); } catch (PlatformBusinessException e) { // 取消失败只有 message,无法细分原因;取消场景统一按「不可取消」表达 throw new OutboundCancelBlockedException(WarehouseException.builder() .message("hengjian refused cancellation: " + e.getMessage()) .operation(OP_ORDER_CANCEL) .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .platformCode(e.platformCode()) .rawResponse(e.rawResponse()) .retryable(false)); } return CancelResult.builder() .outboundRequestNo(orderNo) .providerOrderId(String.valueOf(orderId)) .eligibility(CancelEligibility.FREE) .cancelled(true) .rawStatus(json.stringAt(raw, "message")) .build(); } /** * 按单号或订单 id 查一行,用于补全取消需要的另一个键。 * *

只认精确匹配:列表接口的 {@code orderNos} / {@code orderIds} 过滤是否精确 * 文档没说,取回来再逐条比对,避免拿近似结果去取消别的单。

*/ private HengjianOrderListDtos.OrderRow findRow(WarehouseContext ctx, String orderNo, Long orderId) { Map params = new LinkedHashMap(); params.put("rows", 1); params.put("sidx", HengjianConstants.ORDER_LIST_DEFAULT_SIDX); params.put("sort", HengjianConstants.ORDER_LIST_DEFAULT_SORT); params.put("page", 1); if (orderNo != null) { params.put("orderNos", orderNo); } else { params.put("orderIds", String.valueOf(orderId)); } rateLimiter.acquire(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, HengjianConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), HengjianConstants.PATH_ORDER_FIND_BY_PAGE, params, ctx.secret(), ctx, OP_ORDER_CANCEL); String raw = HengjianEnvelope.of(transport.execute(req), json, OP_ORDER_CANCEL, ctx.warehouseCode(), ctx.requestId()).body(); HengjianOrderListDtos.ListResponse resp = json.fromJson(raw, HengjianOrderListDtos.ListResponse.class); if (resp == null || resp.data == null || resp.data.content == null) { return null; } for (HengjianOrderListDtos.OrderRow row : resp.data.content) { if (row == null) { continue; } boolean matches = orderNo != null ? orderNo.equals(trimToNull(row.orderNo)) : orderId != null && orderId.equals(row.orderId); if (matches) { return row; } } return null; } /** 仓内部订单 id;非数字返回 null(后续按单号补)。 */ private static Long parseOrderId(String providerOrderId) { String v = trimToNull(providerOrderId); if (v == null) { return null; } try { return Long.valueOf(v); } catch (NumberFormatException e) { return null; } } /** * 包裹列表:从详情的 {@code shipmentPackages} 提取。 * *

恒健没有独立的包裹接口,发货信息就在详情报文里。按 {@code trackingNo} 去重 * (同一包裹可能同时以「实际包裹」和「面单信息」两行出现),实际包裹 * ({@code packageFlag=0})优先。

*/ @Override public List packages(WarehouseContext ctx, OutboundRef ref) { String orderNo = orderNoOf(ref); HengjianOrderDetailDtos.FindOneRequest body = new HengjianOrderDetailDtos.FindOneRequest(); body.orderNo = orderNo; String raw = execute(ctx, HengjianConstants.PATH_ORDER_FIND_ONE, body, "warehouse.outbound.packages"); JsonNode data = json.nodeAt(raw, "data"); if (data == null || data.isNull() || data.isMissingNode()) { return new ArrayList(); } HengjianOrderDetailDtos.OrderDetail detail = json.fromJson(data.toString(), HengjianOrderDetailDtos.OrderDetail.class); return toPackages(detail, orderNo); } /** 实际包裹优先、按 trackingNo 去重;没有 trackingNo 时用 SKU 作键。 */ private static List toPackages(HengjianOrderDetailDtos.OrderDetail detail, String orderNo) { List out = new ArrayList(); if (detail.shipmentPackages == null || detail.shipmentPackages.isEmpty()) { return out; } java.util.Set seen = new java.util.LinkedHashSet(); // 两遍:先实际包裹,再面单信息行 for (int pass = 0; pass < 2; pass++) { for (HengjianOrderDetailDtos.OrderDetail.ShipmentPackage p : detail.shipmentPackages) { if (p == null) { continue; } boolean actual = p.packageFlag == null || p.packageFlag == 0; if (actual != (pass == 0)) { continue; } String tracking = trimToNull(p.trackingNo); String key = tracking != null ? tracking : "SKU-" + trimToNull(p.erpSku); if (!seen.add(key)) { continue; } PackageResult.Builder builder = PackageResult.builder() .packageId(key) .outboundRequestNo(orderNo) .trackingNumber(tracking) .carrier(trimToNull(p.carrier)) .erpSku(trimToNull(p.erpSku)) .shippedQuantity(p.shipedQuantity) .shippedAt(HengjianOrderMapper.parseTime(p.shipmentDate)); if (p.cost != null && p.cost > 0) { builder.cost(HengjianOrderMapper.moneyOf(p.cost, detail.currency)); } out.add(builder.build()); } } return out; } /** 统一引用 → 来源单号;两者都空时拒绝。 */ private static String orderNoOf(OutboundRef ref) { String orderNo = trimToNull(ref.outboundRequestNo()); return orderNo != null ? orderNo : trimToNull(ref.providerOrderId()); } /** * 时间窗转恒健的日期参数。 * *

恒健收的是 UTC 日期({@code yyyy-MM-dd}),不是时间戳;跨度不超过 * {@link HengjianConstants#ORDER_LIST_MAX_DAYS} 天。用「起止都含当天」的口径, * 所以计算跨度时把 end 当天算进去。

*/ private void addDateRange(WarehouseContext ctx, Map params, OutboundQuery query) { java.time.LocalDate begin = query.after().atZone(ZoneOffset.UTC).toLocalDate(); java.time.LocalDate end = query.before().atZone(ZoneOffset.UTC).toLocalDate(); long days = java.time.temporal.ChronoUnit.DAYS.between(begin, end); if (days > HengjianConstants.ORDER_LIST_MAX_DAYS) { throw validation(ctx, OP_ORDER_QUERY, "hengjian order list window must not exceed " + HengjianConstants.ORDER_LIST_MAX_DAYS + " days, got " + days); } params.put("beginDateTime", begin.toString()); params.put("endDateTime", end.toString()); } /** * 单页行数。 * *

上限 100 是文档明写的(「一页的行数,默认最高 100」)。超过时 * 显式拒绝而不是静默截断:调用方按自己传的 pageSize 判末页, * 被悄悄改小会误判「还有下一页」。

*/ private int requireRows(WarehouseContext ctx, int pageSize) { if (pageSize <= 0) { return HengjianConstants.ORDER_LIST_MAX_ROWS; } if (pageSize > HengjianConstants.ORDER_LIST_MAX_ROWS) { throw validation(ctx, OP_ORDER_QUERY, "hengjian order list rows must not exceed " + HengjianConstants.ORDER_LIST_MAX_ROWS + ", got " + pageSize); } return pageSize; } /** 逗号拼接(恒健多条单号用逗号分隔)。 */ private static String joinIds(List ids) { StringBuilder sb = new StringBuilder(); for (String id : ids) { if (sb.length() > 0) { sb.append(','); } sb.append(id); } return sb.toString(); } /** UTC 时间 → {@code yyyy-MM-dd HH:mm:ss}(恒健更新时间参数口径)。 */ private static String formatDateTime(java.time.Instant instant) { return instant == null ? null : java.time.LocalDateTime.ofInstant(instant, ZoneOffset.UTC) .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")); } /** null / 空白不放进参数表。 */ private static void putIfPresent(Map params, String key, String value) { String v = trimToNull(value); if (v != null) { params.put(key, v); } } /** 排序字段:调用方指定优先,否则用文档的默认 {@code id}。 */ private static String sortFieldOf(String requested) { String v = trimToNull(requested); return v == null ? HengjianConstants.ORDER_LIST_DEFAULT_SIDX : v; } /** 排序方向:{@code asc} / {@code desc};未指定用默认 {@code desc}。 */ private static String sortDirectionOf(SortDirection direction) { if (direction == null) { return HengjianConstants.ORDER_LIST_DEFAULT_SORT; } return direction == SortDirection.ASC ? "asc" : "desc"; } /** 游标是字符串化的页码;空游标表示第 1 页(恒健是 1 基入参)。 */ private static int pageNumberOf(String cursor) { String v = trimToNull(cursor); if (v == null) { return 1; } try { int page = Integer.parseInt(v); return page < 1 ? 1 : page; } catch (NumberFormatException e) { throw new IllegalArgumentException("hengjian order list cursor must be a page number, got " + v); } } private common.ecommerce.shared.error.ValidationException validation(WarehouseContext ctx, String operation, String message) { return new common.ecommerce.shared.error.ValidationException(WarehouseException.builder() .message(message) .operation(operation) .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false)); } private static String trimToNull(String v) { if (v == null) { return null; } String t = v.trim(); return t.isEmpty() ? null : t; } /** * 平台面单必须真的带文件。 * *

恒健的面单就是 {@code attachInfoItems} 里的一条附件;声明了 * {@code PLATFORM_LABEL_DELIVERY} 却不给文件,仓没有面单可打,等于静默失败。

*/ private static void requirePlatformLabelSupported(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()); } } /** 原始响应可能含 PII,异常里只留短片段。 */ private static String safeRelay(String raw) { if (raw == null) { return null; } return raw.length() <= 300 ? raw : raw.substring(0, 300) + "..."; } // ------------------------------------------------------------------ 商品 /** * 创建 / 编辑商品({@code POST /v1/product/save})。 * *

接口是保存语义:同一 SKU 再调即更新,所以不区分 create 与 update, * 也不像信仓那样先查一次再决定调哪个接口。

* *

响应只有 {@code code / message},没有 data,因此结果里的 * {@code status} 固定为 {@code SAVED}、{@code rawStatus} 取仓方的 message—— * 仓方并不告诉我们这次是新建还是更新,不能替它编。

* * @throws IllegalArgumentException 恒健要求但统一模型未给的非空字段缺失(本地拒绝) */ @Override public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) { HengjianProductSaveDtos.SaveProductRequest body = HengjianProductMapper.toRequest(product); String raw = execute(ctx, HengjianConstants.PATH_PRODUCT_SAVE, body, OP_PRODUCT_SAVE); return ProductResult.of(body.sku, SAVED, json.stringAt(raw, "message")); } // ------------------------------------------------------------------ 仓库目录 /** * 当前组织下的全部仓库({@code POST /v2/warehouse/getWarehouse},无参数)。 * *

返回的 {@code warehouseCode} 可直接用于下单、库存查询等接口。

*/ @Override public List warehouses(WarehouseContext ctx) { String raw = execute(ctx, HengjianConstants.PATH_WAREHOUSE_LIST, null, OP_WAREHOUSE_LIST); List rows = json.listAt(raw, "data", HengjianWarehouseDtos.WarehouseRow.class); return HengjianDirectoryMapper.toWarehouses(rows); } /** * 承运商 / 物流方式代码({@code POST /v2/carrierGroup/getCarrierGroup},无参数)。 * *

返回物流产品代码(如 {@code UPS2DAM_HL}),可直接作为下单的 {@code carrierCode}。 * 按出现顺序去重。

*/ @Override public List carriers(WarehouseContext ctx) { return codesOf(fetchAllServices(ctx)); } /** * 物流产品清单({@code POST /v2/carrierGroup/getCarrierGroup})。 * *

恒健这个接口没有仓维度,拿到的是组织级清单;{@code warehouseCode} * 仅用于写进结果字段,便于调用方区分来源。需要「某仓支持哪些渠道」用 * {@link #productsOfWarehouse}。

*/ @Override public List products(WarehouseContext ctx, String warehouseCode) { return HengjianDirectoryMapper.toProducts(fetchAllServices(ctx), resolveWarehouseCode(ctx, warehouseCode)); } /** * 查询「某仓支持哪些物流渠道」({@code POST * /v2/carrierGroup/getWarehouseCarrierGroupServices})。 * *

返回形状与 {@link #products} 不同:{@code data} 是以仓代码为键的对象, * 不是数组;只取请求的那个仓,混进别的仓的渠道会让「仓不支持该渠道」 * 变成仓方报错。

*/ public List productsOfWarehouse(WarehouseContext ctx, String warehouseCode) { String code = resolveWarehouseCode(ctx, warehouseCode); if (code == null) { throw new IllegalArgumentException( "hengjian warehouse carrier services need a warehouseCode; none given and account has none"); } List codes = new ArrayList(); codes.add(code); Map body = new LinkedHashMap(); body.put("warehouseCodes", codes); String raw = execute(ctx, HengjianConstants.PATH_WAREHOUSE_CARRIER_GROUP, body, OP_LOGISTICS_PRODUCTS); return HengjianDirectoryMapper.toProducts(servicesOfWarehouse(raw, code), code); } // ------------------------------------------------------------------ 内部 private List fetchAllServices(WarehouseContext ctx) { String raw = execute(ctx, HengjianConstants.PATH_CARRIER_GROUP, null, OP_CARRIERS); return json.listAt(raw, "data", HengjianCarrierGroupDtos.CarrierServiceRow.class); } /** {@code data} 是 {@code 仓代码 → 服务数组} 的对象;只取指定仓。 */ private List servicesOfWarehouse(String raw, String warehouseCode) { List rows = new ArrayList(); JsonNode data = json.nodeAt(raw, "data"); if (data == null || !data.isObject()) { return rows; } JsonNode node = data.get(warehouseCode); if (node == null || !node.isArray()) { return rows; } Iterator it = node.elements(); while (it.hasNext()) { rows.add(json.mapper().convertValue(it.next(), HengjianCarrierGroupDtos.CarrierServiceRow.class)); } return rows; } /** 显式仓代码优先,否则用账户配置的;都没有返回 null,由调用方决定是否拒绝。 */ private static String resolveWarehouseCode(WarehouseContext ctx, String warehouseCode) { if (warehouseCode != null && !warehouseCode.trim().isEmpty()) { return warehouseCode.trim(); } String configured = ctx.providerWarehouseId(); return configured == null || configured.trim().isEmpty() ? null : configured.trim(); } private static List codesOf(List rows) { List out = new ArrayList(); if (rows == null) { return out; } for (HengjianCarrierGroupDtos.CarrierServiceRow row : rows) { if (row == null || row.code == null || row.code.trim().isEmpty()) { continue; } String code = row.code.trim(); if (!out.contains(code)) { out.add(code); } } return out; } /** * 发请求并校验信封。 * * @param body null 表示无参数接口,发送空 JSON 对象 */ private String execute(WarehouseContext ctx, String path, Object body, String operation) { rateLimiter.acquire(path, HengjianConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.post(ctx.endpointBaseUrl(), path, body, ctx.secret(), ctx, operation); HttpResponse resp = transport.execute(req); String raw = HengjianEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body(); if (raw == null || raw.trim().isEmpty()) { throw WarehouseException.builder() .message("hengjian " + operation + " returned an empty body") .operation(operation) .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(true) .build(); } return raw; } }