package common.ecommerce.yqn.adapter; 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.WarehouseCapability; import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException; import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.model.CancelCommand; import common.ecommerce.warehouse.model.CancelEligibility; import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.LabelMode; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundQuery; import common.ecommerce.warehouse.model.OutboundReceipt; import common.ecommerce.warehouse.model.OutboundRef; import common.ecommerce.warehouse.model.PackageResult; import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.yqn.YqnConstants; import common.ecommerce.yqn.dto.YqnDtos; import common.ecommerce.yqn.http.YqnEnvelope; import common.ecommerce.yqn.http.YqnRateLimiter; import common.ecommerce.yqn.http.YqnRequestFactory; import java.time.ZoneId; import java.time.format.DateTimeFormatter; import java.util.ArrayList; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; /** * 运去哪适配器(P1 出库闭环)。 * *

实现 {@code OutboundCapable}:创建 / 查询 / 取消 / 包裹。库存、入库、退货、销毁 * 等在 P2/P3 接入,未实现的能力位不声明,门面调用会显式拒绝。

* *

字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」, * 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。

*/ public final class YqnAdapter implements OutboundCapable { /** 运去哪请求里的时间格式;待核对。 */ private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); private final HttpTransport transport; private final JacksonJsonCodec json; private final YqnRequestFactory requestFactory; private final YqnRateLimiter rateLimiter; public YqnAdapter(HttpTransport transport, JacksonJsonCodec json) { this.transport = transport; this.json = json; this.requestFactory = new YqnRequestFactory(json); this.rateLimiter = new YqnRateLimiter(); } @Override public String adapterId() { return YqnConstants.ADAPTER_ID; } @Override public WarehouseProvider provider() { return WarehouseProvider.YQN; } @Override public java.util.EnumSet capabilities() { return java.util.EnumSet.of( WarehouseCapability.OUTBOUND, WarehouseCapability.SPLIT); } // ------------------------------------------------------------------ 出库 @Override public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { requirePlatformLabelSupported(ctx, cmd.labelMode()); YqnDtos.CreateOrderRequest body = YqnOutboundMapper.toRequest(cmd, warehouseId(ctx, cmd.warehouseId())); String raw = execute(ctx, YqnConstants.PATH_ORDER_CREATE, body, "warehouse.outbound.create"); String providerOrderId = json.stringAt(raw, "data.orderNo"); if (providerOrderId == null || providerOrderId.trim().isEmpty()) { // 仓未返回单号时不能静默成功:幂等键记了成功但没法回查 throw WarehouseException.builder() .message("yqn create returned no orderNo: " + safeRelay(raw)) .operation("warehouse.outbound.create") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .rawResponse(safeRelay(raw)) .build(); } return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderId, json.stringAt(raw, "data.status")); } @Override public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { Map body = new LinkedHashMap(); body.put("orderNo", ref.providerOrderId()); body.put("customerOrderNo", ref.outboundRequestNo()); String raw = execute(ctx, YqnConstants.PATH_ORDER_FIND, body, "warehouse.outbound.get"); YqnDtos.OrderInfo info = firstOrder(raw); return info == null ? null : YqnOutboundMapper.toOrder(info, ctx.warehouseCode(), zoneOf(ctx)); } @Override public Page query(WarehouseContext ctx, OutboundQuery query) { YqnDtos.FindOrderRequest body = new YqnDtos.FindOrderRequest(); body.orderNo = query.providerOrderId(); body.customerOrderNo = query.orderRef(); body.startTime = query.after() == null ? null : REQUEST_TIME_FORMAT.format(query.after().atZone(zoneOf(ctx))); body.endTime = query.before() == null ? null : REQUEST_TIME_FORMAT.format(query.before().atZone(zoneOf(ctx))); body.status = query.statuses().isEmpty() ? null : query.statuses().get(0); body.pageNo = pageNumber(query.cursor()); body.pageSize = query.pageSize(); String raw = execute(ctx, YqnConstants.PATH_ORDER_FIND, body, "warehouse.outbound.query"); List orders = new ArrayList(); for (YqnDtos.OrderInfo info : json.listAt(raw, "data.orders", YqnDtos.OrderInfo.class)) { orders.add(YqnOutboundMapper.toOrder(info, ctx.warehouseCode(), zoneOf(ctx))); } int total = intAt(raw, "data.total"); int pageNo = body.pageNo; int fetched = orders.size(); String next = pageNo * body.pageSize < total && fetched > 0 ? String.valueOf(pageNo + 1) : null; return Page.of(orders, next); } @Override public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) { // 运去哪没有独立的取消预判接口(Spec §8.6 第 5 项待核对): // 先查单状态,已出库/已取消的一律 BLOCKED;其余交给 cancel 时仓判定。 OutboundOrder order = get(ctx, ref); if (order == null) { return CancelEligibility.BLOCKED; } switch (order.status()) { case SHIPPED: case CANCELLED: return CancelEligibility.BLOCKED; default: return CancelEligibility.FREE; } } @Override public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { YqnDtos.CancelOrderRequest body = new YqnDtos.CancelOrderRequest(); body.orderNo = cmd.providerOrderId(); body.customerOrderNo = cmd.outboundRequestNo(); body.acceptCharge = cmd.acceptCharge(); body.cancelReason = cmd.reason(); String raw = execute(ctx, YqnConstants.PATH_ORDER_CANCEL, body, "warehouse.outbound.cancel"); String cancelType = json.stringAt(raw, "data.cancelType"); CancelEligibility eligibility = YqnOutboundMapper.toEligibility(cancelType); if (eligibility == CancelEligibility.BLOCKED) { throw new OutboundCancelBlockedException(WarehouseException.builder() .message("yqn refused cancellation: " + safeRelay(raw)) .operation("warehouse.outbound.cancel") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .rawResponse(safeRelay(raw))); } if (eligibility == CancelEligibility.CHARGED && !cmd.acceptCharge()) { throw new OutboundCancelChargeRequiredException(WarehouseException.builder() .message("yqn cancellation is charged, acceptCharge required") .operation("warehouse.outbound.cancel") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()), json.stringAt(raw, "data.cancelFee"), json.stringAt(raw, "data.currency")); } return CancelResult.builder() .outboundRequestNo(cmd.outboundRequestNo()) .providerOrderId(cmd.providerOrderId()) .eligibility(eligibility) .cancelled(true) .rawStatus(cancelType) .build(); } @Override public List packages(WarehouseContext ctx, OutboundRef ref) { OutboundOrder order = get(ctx, ref); if (order == null) { return java.util.Collections.emptyList(); } Map body = new LinkedHashMap(); body.put("orderNo", ref.providerOrderId()); body.put("customerOrderNo", ref.outboundRequestNo()); String raw = execute(ctx, YqnConstants.PATH_ORDER_FIND, body, "warehouse.outbound.packages"); YqnDtos.OrderInfo info = firstOrder(raw); return info == null ? java.util.Collections.emptyList() : YqnOutboundMapper.toPackages(info); } // ------------------------------------------------------------------ internals /** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */ private void requirePlatformLabelSupported(WarehouseContext ctx, LabelMode mode) { if (mode == LabelMode.PLATFORM_LABEL && !supports(ctx.warehouseCode(), WarehouseCapability.PLATFORM_LABEL_DELIVERY)) { throw WarehouseException.builder() .message("yqn account does not declare PLATFORM_LABEL_DELIVERY; " + "refusing to silently fall back to warehouse label") .operation("warehouse.outbound.create") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .build(); } } /** 仓方仓编码:命令显式指定优先,否则用账户配置。 */ private static String warehouseId(WarehouseContext ctx, String fromCommand) { if (fromCommand != null && !fromCommand.trim().isEmpty()) { return fromCommand.trim(); } return ctx.providerWarehouseId(); } private static ZoneId zoneOf(WarehouseContext ctx) { // 账户时区由 WarehouseAccount 提供;上下文没带时回退北京 return ZoneId.of("Asia/Shanghai"); } /** 发请求并校验信封。 */ private String execute(WarehouseContext ctx, String path, Object body, String operation) { rateLimiter.acquire(path, YqnConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.postJson(ctx.endpointBaseUrl(), path, json.toJson(body), ctx.secret(), ctx, operation); HttpResponse resp = transport.execute(req); return YqnEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body(); } private YqnDtos.OrderInfo firstOrder(String raw) { List rows = json.listAt(raw, "data.orders", YqnDtos.OrderInfo.class); if (!rows.isEmpty()) { return rows.get(0); } // 单条返回时 data 就是订单对象 com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data"); if (data == null || data.isNull() || data.isMissingNode()) { return null; } YqnDtos.OrderInfo info = json.fromJson(data.toString(), YqnDtos.OrderInfo.class); return info == null || info.orderNo == null ? null : info; } private static int pageNumber(String cursor) { if (cursor == null || cursor.trim().isEmpty()) { return 1; } try { return Integer.parseInt(cursor.trim()); } catch (NumberFormatException e) { return 1; } } private int intAt(String raw, String path) { try { String v = json.stringAt(raw, path); return v == null || v.trim().isEmpty() ? 0 : Integer.parseInt(v.trim()); } catch (RuntimeException e) { return 0; } } /** 原始响应可能含 PII 与 token,异常里只留长度与首段。 */ private static String safeRelay(String raw) { if (raw == null) { return null; } return raw.length() <= 300 ? raw : raw.substring(0, 300) + "..."; } }