package common.ecommerce.hengjian.adapter; import com.fasterxml.jackson.databind.JsonNode; import common.ecommerce.hengjian.HengjianConstants; import common.ecommerce.hengjian.dto.HengjianCancelOrderDtos; import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos; import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; import common.ecommerce.hengjian.dto.HengjianOrderListDtos; import common.ecommerce.hengjian.dto.HengjianProductSaveDtos; import common.ecommerce.hengjian.dto.HengjianTrackingChangeDtos; import common.ecommerce.hengjian.dto.HengjianTrackingChangeQueryDtos; import common.ecommerce.hengjian.dto.HengjianWarehouseDtos; 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.LogisticsProductCapable; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.TrackingChangeCapable; import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.enums.TrackingChangeHandleType; import common.ecommerce.warehouse.enums.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.model.CancelCommand; import common.ecommerce.warehouse.model.CancelResult; 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 { 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"; /** 保存语义没有 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承接门面的幂等守卫(键 {@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 三者必填其一」,所以:
*时间跨度上限 30 天,超过也在本地拒绝。
* *{@code orderRef}(平台单号)恒健没有对应查询参数,不参与查询; * {@code statuses} 恒健列表也没有状态过滤参数,传了就拒绝——静默忽略会让调用方 * 以为过滤生效了。
*/ @Override public Page恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款 / 已删除不再接受取消, * 判为 {@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 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恒健没有独立的包裹接口,发货信息就在详情报文里。按 {@code trackingNo} 去重 * (同一包裹可能同时以「实际包裹」和「面单信息」两行出现),实际包裹 * ({@code packageFlag=0})优先。
*/ @Override public List恒健收的是 UTC 日期({@code yyyy-MM-dd}),不是时间戳;跨度不超过 * {@link HengjianConstants#ORDER_LIST_MAX_DAYS} 天。用「起止都含当天」的口径, * 所以计算跨度时把 end 当天算进去。
*/ private void addDateRange(WarehouseContext ctx, Map恒健的面单就是 {@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返回物流产品代码(如 {@code UPS2DAM_HL}),可直接作为下单的 {@code carrierCode}。 * 按出现顺序去重。
*/ @Override public List恒健这个接口没有仓维度,拿到的是组织级清单;{@code warehouseCode} * 仅用于写进结果字段,便于调用方区分来源。需要「某仓支持哪些渠道」用 * {@link #productsOfWarehouse}。
*/ @Override public List返回形状与 {@link #products} 不同:{@code data} 是以仓代码为键的对象, * 不是数组;只取请求的那个仓,混进别的仓的渠道会让「仓不支持该渠道」 * 变成仓方报错。
*/ public List