package common.ecommerce.hengjian.adapter; import com.fasterxml.jackson.databind.JsonNode; import common.ecommerce.hengjian.HengjianConstants; 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.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.support.Page; import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.OutboundCapable; 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.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseProvider; 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.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 { 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"; /** 保存语义没有 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.DIRECTORY, WarehouseCapability.LOGISTICS_PRODUCT); } // ------------------------------------------------------------------ 出库 /** * 创建销售发货单({@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 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()); } Map params = new LinkedHashMap(); int pageSize = clampRows(query.pageSize()); params.put("rows", pageSize); params.put("sidx", HengjianConstants.ORDER_LIST_SIDX); params.put("sort", HengjianConstants.ORDER_LIST_SORT); params.put("page", pageNumberOf(query.cursor())); 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 { throw validation(ctx, OP_ORDER_QUERY, "hengjian order list requires outboundRequestNo 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: return CancelEligibility.BLOCKED; default: return CancelEligibility.FREE; } } @Override public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { throw unsupportedOutbound("warehouse.outbound.cancel", ctx); } /** * 包裹列表:从详情的 {@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,超出截断而不是让仓方报错。 */ private static int clampRows(int pageSize) { if (pageSize <= 0) { return HengjianConstants.ORDER_LIST_MAX_ROWS; } return Math.min(pageSize, HengjianConstants.ORDER_LIST_MAX_ROWS); } /** 游标是字符串化的页码;空游标表示第 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()); } } private WarehouseException unsupportedOutbound(String operation, WarehouseContext ctx) { return WarehouseException.builder() .message("hengjian does not implement " + operation + " yet") .operation(operation) .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .build(); } /** 原始响应可能含 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; } }