From d2d2f04a45bc09f474958ef6a95d7a47deaec020 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 10 Nov 2026 13:57:55 +0800 Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8C=89=20API=20189=20=E5=AF=B9?= =?UTF-8?q?=E6=8E=A5=E8=BF=90=E5=8D=95=E7=89=A9=E6=B5=81=E8=BD=A8=E8=BF=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 TrackEvent 之外的运单级模型 TrackingInfo(最新状态 / 承运商 / 签收人 / 预计妥投 / 公开轨迹页),events() 与既有 track() 返回一致。 TrackingCapable 增加 trackShipment(),门面同步暴露。 两处接口特性与仓接口不同,单独处理: - 主机不同:轨迹在 pr-ship-api.yqn.com,仓接口在 pr-hwc-open-api.yqn.com。 WarehouseConnection 增加可选 auxEndpointBaseUrl,调用方显式传入; 没传时抛 WarehouseUnsupportedCapabilityException,不静默退回主基址 (否则轨迹请求会打到仓接口上,拿到的是看不懂的业务错误) - 成功码不同:文档响应示例是 code=1,不是仓接口的 200。走独立的 YqnConstants.TRACK_SUCCESS_CODE 判定,不复用 YqnEnvelope 状态值保持运去哪原话,不做跨仓归一——承运商的节点状态词汇差异大, 「派送失败 / 退回中」这类区分归一会丢信息。 JacksonJsonCodec 补 intAt(json, pointer, missing):nodeAt + 类型判断, 避免适配器自己持有 ObjectMapper。 Co-Authored-By: Claude --- README.md | 4 +- .../common/ecommerce/http/JacksonJsonCodec.java | 9 ++ .../warehouse/capability/TrackingCapable.java | 18 ++- .../ecommerce/warehouse/model/TrackingInfo.java | 156 ++++++++++++++++++ .../warehouse/sdk/WarehouseConnection.java | 34 +++- .../ecommerce/warehouse/sdk/WarehouseContext.java | 5 + .../warehouse/sdk/WarehouseOperations.java | 20 ++- .../java/common/ecommerce/yqn/YqnConstants.java | 21 ++- .../common/ecommerce/yqn/adapter/YqnAdapter.java | 82 +++++++++- .../ecommerce/yqn/adapter/YqnTrackingMapper.java | 143 +++++++++++++++++ .../java/common/ecommerce/yqn/dto/YqnDtos.java | 77 +++++++++ .../ecommerce/yqn/adapter/YqnTrackingTest.java | 178 +++++++++++++++++++++ 12 files changed, 737 insertions(+), 10 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java create mode 100644 warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java diff --git a/README.md b/README.md index 55c4157..bf7ac01 100644 --- a/README.md +++ b/README.md @@ -308,7 +308,7 @@ common.ecommerce │ │ InboundReceipt / ReturnCommand / ReturnProcessCommand / │ │ WarehouseReturn / TransferCommand / TransferOrder / │ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult / -│ │ TrackEvent / DestructionOrder +│ │ TrackEvent / TrackingInfo / DestructionOrder │ ├── capability OutboundCapable / InventoryCapable / InboundCapable / │ │ WarehouseReturnCapable / WarehouseFeeCapable / │ │ WarehouseFeeEstimateCapable / TransferCapable / @@ -320,7 +320,7 @@ common.ecommerce │ │ UnmatchedCallbackStore │ └── sdk WarehouseSdk / WarehouseOperations / WarehouseOutbounds / │ WarehouseAdapter / WarehouseAdapterFactory / WarehouseContext / -│ WarehouseConnection / WarehouseWriteScope +│ WarehouseConnection(主基址 + 可选辅助基址)/ WarehouseWriteScope │ ├── yqn 运去哪三方仓(warehouse-sdk-yqn) │ ├── YqnConstants 端点、路径、固定 token 请求头名、限流 diff --git a/sdk-common/src/main/java/common/ecommerce/http/JacksonJsonCodec.java b/sdk-common/src/main/java/common/ecommerce/http/JacksonJsonCodec.java index a150775..19ac2c5 100644 --- a/sdk-common/src/main/java/common/ecommerce/http/JacksonJsonCodec.java +++ b/sdk-common/src/main/java/common/ecommerce/http/JacksonJsonCodec.java @@ -71,6 +71,15 @@ public final class JacksonJsonCodec implements JsonCodec { } } + /** 按点路径取整数值;节点缺失、非数字或为 null 时返回哨兵 {@code missing}。 */ + public int intAt(String json, String pointer, int missing) { + JsonNode node = nodeAt(json, pointer); + if (node == null || node.isNull() || !node.canConvertToInt()) { + return missing; + } + return node.asInt(); + } + /** 把点路径下的数组节点反序列化为列表。 */ public List listAt(String json, String pointer, Class type) { JsonNode node = nodeAt(json, pointer); diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingCapable.java index 5d80e12..173007f 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingCapable.java @@ -1,6 +1,7 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.warehouse.model.TrackEvent; +import common.ecommerce.warehouse.model.TrackingInfo; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; @@ -9,6 +10,21 @@ import java.util.List; /** 物流轨迹能力。信仓无此接口,整体不实现。 */ public interface TrackingCapable extends WarehouseAdapter { - /** 按跟踪号查轨迹。 */ + /** + * 按跟踪号查轨迹节点。 + * + * @return 节点列表;仓方无轨迹时为空列表(不是错误——运单可能刚生成还没揽收) + */ List track(WarehouseContext ctx, String trackingNumber); + + /** + * 按跟踪号查运单级轨迹:除节点外还带最新状态、承运商、签收人与预计妥投。 + * + *

与 {@link #track} 的关系:本方法返回 {@link TrackingInfo},其中的 + * {@code events()} 就是 {@code track} 的返回内容。宿主做 C 端可视化或异常预警时用这个, + * 只需要节点明细时用 {@code track}。

+ * + *

状态值保持仓方原值,不做跨仓归一。

+ */ + TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java new file mode 100644 index 0000000..2ef52c9 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java @@ -0,0 +1,156 @@ +package common.ecommerce.warehouse.model; + +import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 运单物流轨迹查询结果。 + * + *

由 {@code TrackingCapable.trackShipment()} 返回:整体是一个运单的当前状态 + + * 若干节点,比 {@link TrackEvent}(单条事件)多出承运商、最新状态、签收人与预计妥投。

+ * + *

状态值保持仓方原始字符串,见 {@link #status()};不做跨仓归一——各承运商的节点 + * 状态词汇差异太大,强行归一会丢失「派送失败 / 退回中」这类关键区分。

+ */ +public final class TrackingInfo { + + private final String trackingNumber; + private final String carrier; + /** 物流服务,如 {@code FedEx_FEDEX_GROUND};仓方未给时为 null。 */ + private final String carrierService; + /** 最新状态(仓方原值)。 */ + private final String status; + /** 最新状态的详细描述。 */ + private final String statusDetail; + /** 预计妥投时间(UTC);仓方未给时为 null。 */ + private final Instant estimatedDeliveryAt; + /** 签收人;未签收为 null。 */ + private final String signedBy; + /** 承运商侧可公开查询的轨迹页地址。 */ + private final String publicUrl; + private final List events; + + private TrackingInfo(Builder b) { + this.trackingNumber = require(b.trackingNumber, "trackingNumber"); + this.carrier = b.carrier; + this.carrierService = b.carrierService; + this.status = b.status; + this.statusDetail = b.statusDetail; + this.estimatedDeliveryAt = b.estimatedDeliveryAt; + this.signedBy = b.signedBy; + this.publicUrl = b.publicUrl; + this.events = Collections.unmodifiableList(new ArrayList(b.events)); + } + + public static Builder builder() { + return new Builder(); + } + + public String trackingNumber() { + return trackingNumber; + } + + public String carrier() { + return carrier; + } + + public String carrierService() { + return carrierService; + } + + /** 最新状态(仓方原值)。 */ + public String status() { + return status; + } + + public String statusDetail() { + return statusDetail; + } + + public Instant estimatedDeliveryAt() { + return estimatedDeliveryAt; + } + + public String signedBy() { + return signedBy; + } + + public String publicUrl() { + return publicUrl; + } + + /** 轨迹节点,按仓方返回顺序;不可变。 */ + public List events() { + return events; + } + + private static String require(String v, String name) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + private String trackingNumber; + private String carrier; + private String carrierService; + private String status; + private String statusDetail; + private Instant estimatedDeliveryAt; + private String signedBy; + private String publicUrl; + private final List events = new ArrayList(); + + public Builder trackingNumber(String v) { + this.trackingNumber = v; + return this; + } + + public Builder carrier(String v) { + this.carrier = v; + return this; + } + + public Builder carrierService(String v) { + this.carrierService = v; + return this; + } + + public Builder status(String v) { + this.status = v; + return this; + } + + public Builder statusDetail(String v) { + this.statusDetail = v; + return this; + } + + public Builder estimatedDeliveryAt(Instant v) { + this.estimatedDeliveryAt = v; + return this; + } + + public Builder signedBy(String v) { + this.signedBy = v; + return this; + } + + public Builder publicUrl(String v) { + this.publicUrl = v; + return this; + } + + public Builder event(TrackEvent v) { + this.events.add(v); + return this; + } + + public TrackingInfo build() { + return new TrackingInfo(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java index d2fced4..a5355d6 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java @@ -18,14 +18,23 @@ public final class WarehouseConnection { /** 目标基址,如 {@code https://pr-hwc-open-api.yqn.com};末尾斜杠会被去掉。 */ private final String endpointBaseUrl; + /** + * 辅助基址:同一仓方把少数接口部署在另一个主机时使用(运去哪的物流轨迹接口在 + * {@code pr-ship-api.yqn.com},与仓接口的 {@code pr-hwc-open-api.yqn.com} 不同主机)。 + * null 表示未配置,需要它的能力会显式拒绝,不静默退回主基址。 + */ + private final String auxEndpointBaseUrl; + /** 凭据。 */ private final ChannelSecret secret; - private WarehouseConnection(String endpointBaseUrl, ChannelSecret secret) { + private WarehouseConnection(String endpointBaseUrl, String auxEndpointBaseUrl, ChannelSecret secret) { if (endpointBaseUrl == null || endpointBaseUrl.trim().isEmpty()) { throw new IllegalArgumentException("endpointBaseUrl must not be blank"); } this.endpointBaseUrl = trimTrailingSlash(endpointBaseUrl.trim()); + this.auxEndpointBaseUrl = auxEndpointBaseUrl == null || auxEndpointBaseUrl.trim().isEmpty() + ? null : trimTrailingSlash(auxEndpointBaseUrl.trim()); Objects.requireNonNull(secret, "secret"); // 端点写回凭据:需要换 token 的仓,TokenManager 的 refresh 回调只拿得到 ChannelSecret this.secret = ChannelSecret.builder() @@ -40,7 +49,23 @@ public final class WarehouseConnection { /** 构造连接:基址去空白、去末尾斜杠,并把基址写回凭据副本。 */ public static WarehouseConnection of(String endpointBaseUrl, ChannelSecret secret) { - return new WarehouseConnection(endpointBaseUrl, secret); + return new WarehouseConnection(endpointBaseUrl, null, secret); + } + + /** + * 构造带辅助基址的连接。 + * + *

仅当仓方把部分接口放在另一个主机时使用。不传时,需要辅助基址的能力会抛 + * {@code WarehouseUnsupportedCapabilityException},不会退回主基址。

+ */ + public static WarehouseConnection of(String endpointBaseUrl, String auxEndpointBaseUrl, + ChannelSecret secret) { + return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret); + } + + /** 复制一份连接,附加辅助基址。 */ + public WarehouseConnection withAuxEndpoint(String auxEndpointBaseUrl) { + return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret); } /** 目标基址,末尾斜杠已去掉。 */ @@ -48,6 +73,11 @@ public final class WarehouseConnection { return endpointBaseUrl; } + /** 辅助基址;未配置时为 null。 */ + public String auxEndpointBaseUrl() { + return auxEndpointBaseUrl; + } + /** 凭据;已携带本次调用使用的端点。 */ public ChannelSecret secret() { return secret; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java index e0adff8..ea1abbd 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java @@ -82,6 +82,11 @@ public final class WarehouseContext implements CallScope { return connection.endpointBaseUrl(); } + /** 辅助基址;仓方把少数接口部署在别的机器时使用,未配置为 null。 */ + public String auxEndpointBaseUrl() { + return connection.auxEndpointBaseUrl(); + } + /** 本次调用的凭据,SDK 不落盘。 */ public common.ecommerce.shared.spi.ChannelSecret secret() { return connection.secret(); diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index daa1537..d60cd51 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -34,6 +34,7 @@ import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.model.TrackEvent; +import common.ecommerce.warehouse.model.TrackingInfo; import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.spi.WarehouseAccount; @@ -146,7 +147,11 @@ public final class WarehouseOperations { return new ReturnView(); } - /** 轨迹。 */ + /** + * 轨迹节点。只读,不走幂等。 + * + * @return 节点列表;无轨迹时为空列表 + */ public List track(String trackingNumber) { require(WarehouseCapability.TRACKING, TrackingCapable.class); return CallSupport.observe(observer, ctx, "warehouse.track", @@ -155,6 +160,19 @@ public final class WarehouseOperations { () -> ((TrackingCapable) adapter).track(ctx, trackingNumber)); } + /** + * 运单级轨迹:最新状态 + 承运商 + 签收人 + 预计妥投 + 节点明细。 + * + *

{@code events()} 与 {@link #track(String)} 的返回一致,只多了一层运单信息。

+ */ + public TrackingInfo trackShipment(String trackingNumber) { + require(WarehouseCapability.TRACKING, TrackingCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.track.shipment", + CallSupport.params("trackingNumber", trackingNumber), + r -> r.events().size(), + () -> ((TrackingCapable) adapter).trackShipment(ctx, trackingNumber)); + } + /** 费用视图。 */ public FeeView fees() { return new FeeView(); diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index 76cba53..ac35a92 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -46,8 +46,25 @@ public final class YqnConstants { public static final String PATH_RETURN_PROCESS = "/v3/saleReturn/addProcessMode"; /** 销毁计划。 */ public static final String PATH_DESTRUCTION_CREATE = "/destroyplan/DestructionPlanCreate"; - /** 物流轨迹。 */ - public static final String PATH_TRACKING = "/cloudship/expressdelivery/GetTrackingStatus"; + /** + * 物流轨迹(API 189):{@code GET /api/v2/orderShipment/track/{trackingNo}}。 + * + *

注意主机不同:这个接口在 {@code pr-ship-api.yqn.com},不是仓接口的 + * {@code pr-hwc-open-api.yqn.com}。调用方需通过 + * {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址, + * 未传时适配器显式拒绝而不是打到主基址上。

+ */ + public static final String PATH_TRACKING = "/api/v2/orderShipment/track/"; + + /** 轨迹接口的 PR 环境基址;与仓接口不同主机,供调用方填 {@code auxEndpointBaseUrl}。 */ + public static final String AUX_BASE_URL_PR = "https://pr-ship-api.yqn.com"; + + /** + * 轨迹接口的成功码。 + * + *

文档响应示例是 {@code "code": 1},与仓接口的 {@code 200} 不同,因此单独定义。

+ */ + public static final int TRACK_SUCCESS_CODE = 1; /** 结算明细(API 133):作业费 / 仓储费 / 增值服务费 / 尾程费。 */ public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail"; /** 订单测算 / 运费试算(API 121):发货前按包裹 + 地址 + 渠道询价。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 64f61ac..6f2f4a9 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -27,7 +27,10 @@ import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable; +import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; +import common.ecommerce.warehouse.model.TrackEvent; +import common.ecommerce.warehouse.model.TrackingInfo; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; import common.ecommerce.warehouse.model.FeeEstimateQuery; import common.ecommerce.warehouse.model.FeeEstimateResult; @@ -70,7 +73,7 @@ import java.util.Map; */ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable, - TransferCapable, WarehouseReturnCapable { + TransferCapable, WarehouseReturnCapable, TrackingCapable { /** 运去哪请求里的时间格式;待核对。 */ private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); @@ -109,7 +112,8 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl WarehouseCapability.INBOUND, WarehouseCapability.TRANSFER, WarehouseCapability.RETURN, - WarehouseCapability.RETURN_DISPOSITION); + WarehouseCapability.RETURN_DISPOSITION, + WarehouseCapability.TRACKING); } // ------------------------------------------------------------------ 商品 @@ -485,6 +489,80 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); } + // ------------------------------------------------------------------ 物流轨迹 + + /** + * 运单轨迹(API 189)。 + * + *

这个接口在另一个主机({@code pr-ship-api.yqn.com}),调用方必须通过 + * {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址; + * 没传时显式拒绝,不退回主基址,避免把轨迹请求打到仓接口上。

+ * + *

信封的成功码是 {@code 1}(不是其它接口的 {@code 200}),所以不走 + * {@code YqnEnvelope},单独解析。

+ */ + @Override + public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) { + YqnDtos.ShipmentTrack track = fetchTrack(ctx, trackingNumber); + return YqnTrackingMapper.toTrackingInfo(track, trackingNumber, zoneOf(ctx)); + } + + @Override + public List track(WarehouseContext ctx, String trackingNumber) { + YqnDtos.ShipmentTrack track = fetchTrack(ctx, trackingNumber); + return YqnTrackingMapper.toTrackEvents(track, trackingNumber, zoneOf(ctx)); + } + + private YqnDtos.ShipmentTrack fetchTrack(WarehouseContext ctx, String trackingNumber) { + if (trackingNumber == null || trackingNumber.trim().isEmpty()) { + throw new IllegalArgumentException("trackingNumber must not be blank"); + } + String baseUrl = ctx.auxEndpointBaseUrl(); + if (baseUrl == null || baseUrl.trim().isEmpty()) { + throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.TRACKING); + } + String path = YqnConstants.PATH_TRACKING + urlEncode(trackingNumber.trim()); + rateLimiter.acquire(YqnConstants.PATH_TRACKING, YqnConstants.PERMITS_PER_SECOND); + HttpRequest req = requestFactory.get(baseUrl, path, null, ctx.secret(), ctx, + "warehouse.track"); + HttpResponse resp = transport.execute(req); + String raw = resp.body(); + if (raw == null || raw.trim().isEmpty()) { + throw WarehouseException.builder() + .message("yqn track returned an empty body") + .operation("warehouse.track") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(true) + .build(); + } + // 这个接口的成功码是 1,不是 200,不能用 YqnEnvelope + int code = json.intAt(raw, "code", -1); + if (code != YqnConstants.TRACK_SUCCESS_CODE) { + throw WarehouseException.builder() + .message("yqn track failed: code=" + code + ", message=" + json.stringAt(raw, "message")) + .operation("warehouse.track") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .platformCode(String.valueOf(code)) + .rawResponse(safeRelay(raw)) + .retryable(false) + .build(); + } + String data = String.valueOf(json.nodeAt(raw, "data")); + return json.fromJson(data, YqnDtos.ShipmentTrack.class); + } + + private static String urlEncode(String v) { + try { + return java.net.URLEncoder.encode(v, "UTF-8"); + } catch (java.io.UnsupportedEncodingException e) { + throw new IllegalStateException(e); + } + } + // ------------------------------------------------------------------ internals /** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java new file mode 100644 index 0000000..c3e1ae6 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java @@ -0,0 +1,143 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.warehouse.model.TrackEvent; +import common.ecommerce.warehouse.model.TrackingInfo; +import common.ecommerce.yqn.dto.YqnDtos; + +import java.time.Instant; +import java.time.LocalDateTime; +import java.time.ZoneId; +import java.time.ZoneOffset; +import java.time.format.DateTimeFormatter; +import java.time.format.DateTimeParseException; +import java.util.ArrayList; +import java.util.List; + +/** + * 运去哪物流轨迹映射(API 189)。 + * + *

状态值一律保持运去哪原话,不做归一:承运商的节点状态词汇差异大, + * 「派送失败 / 退回中」这类区分归一会丢信息。

+ */ +public final class YqnTrackingMapper { + + /** 仓方给的节点时间没带时区,按目的地习惯优先解析;解析不出再看其它格式。 */ + private static final DateTimeFormatter[] DATETIME_FORMATS = { + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"), + DateTimeFormatter.ISO_LOCAL_DATE_TIME, + }; + + private YqnTrackingMapper() { + } + + /** 响应 → 运单级轨迹。 */ + public static TrackingInfo toTrackingInfo(YqnDtos.ShipmentTrack track, String requestedTrackingNo, + ZoneId zone) { + String trackingNo = hasText(track.trackingCode) ? track.trackingCode.trim() : requestedTrackingNo; + YqnDtos.ShipmentTrack.CarrierDetail carrierDetail = track.carrierDetail; + TrackingInfo.Builder builder = TrackingInfo.builder() + .trackingNumber(trackingNo) + .carrier(track.carrier) + .carrierService(carrierDetail == null ? null : carrierDetail.service) + .status(track.status) + .statusDetail(track.statusDetail) + .estimatedDeliveryAt(parseTime(track.estDeliveryDate, zone)) + .signedBy(track.signedBy) + .publicUrl(track.publicUrl); + + List details = track.trackingDetails; + if (details != null) { + for (YqnDtos.ShipmentTrack.TrackDetail detail : details) { + builder.event(toTrackEvent(detail, trackingNo, track.carrier, zone)); + } + } + return builder.build(); + } + + /** 只取节点明细。 */ + public static List toTrackEvents(YqnDtos.ShipmentTrack track, String requestedTrackingNo, + ZoneId zone) { + return toTrackingInfo(track, requestedTrackingNo, zone).events(); + } + + private static TrackEvent toTrackEvent(YqnDtos.ShipmentTrack.TrackDetail detail, String trackingNo, + String carrier, ZoneId zone) { + return TrackEvent.builder() + .trackingNumber(trackingNo) + .carrier(carrier) + .status(detail.status) + .description(hasText(detail.message) ? detail.message : detail.statusDetail) + .location(locationOf(detail.trackingLocation)) + .occurredAt(parseTime(detail.datetime, zone)) + .build(); + } + + /** 位置拼成一行,如 {@code New York, NY, US, 10001};全空返回 null。 */ + private static String locationOf(YqnDtos.ShipmentTrack.TrackingLocation loc) { + if (loc == null) { + return null; + } + List parts = new ArrayList(4); + addIfText(parts, loc.city); + addIfText(parts, loc.state); + addIfText(parts, loc.country); + addIfText(parts, loc.zip); + return parts.isEmpty() ? null : join(parts); + } + + private static void addIfText(List parts, String v) { + if (hasText(v)) { + parts.add(v.trim()); + } + } + + private static String join(List parts) { + StringBuilder sb = new StringBuilder(); + for (int i = 0; i < parts.size(); i++) { + if (i > 0) { + sb.append(", "); + } + sb.append(parts.get(i)); + } + return sb.toString(); + } + + /** + * 解析仓方时间;失败返回 null,不因时间格式阻断轨迹展示。 + * + *

文档未给出 {@code datetime} 的格式,因此按「带时区 ISO → 常见本地格式」依次尝试; + * 都不带时区时按调用方给的 {@code zone} 解释。

+ */ + static Instant parseTime(String value, ZoneId zone) { + if (!hasText(value)) { + return null; + } + String v = value.trim(); + try { + return Instant.parse(v); + } catch (DateTimeParseException ignored) { + // 试本地格式 + } + try { + return java.time.OffsetDateTime.parse(v).toInstant(); + } catch (DateTimeParseException ignored) { + // 试本地格式 + } + for (DateTimeFormatter fmt : DATETIME_FORMATS) { + try { + return LocalDateTime.parse(v, fmt).atZone(zone == null ? ZoneOffset.UTC : zone).toInstant(); + } catch (DateTimeParseException ignored) { + // 下一个格式 + } + } + try { + return java.time.LocalDate.parse(v).atStartOfDay(zone == null ? ZoneOffset.UTC : zone).toInstant(); + } catch (DateTimeParseException ignored) { + return null; + } + } + + private static boolean hasText(String v) { + return v != null && !v.trim().isEmpty(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java index e387b81..c57335c 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java @@ -945,4 +945,81 @@ public final class YqnDtos { public String currency; } } + + // ------------------------------------------------------------------ 物流轨迹(API 189) + + /** + * 运单轨迹响应(API 189 {@code data})。 + * + *

注意:这个接口的外层信封是 {@code code/message},成功码是 + * {@code 1} 而不是其它接口的 {@code 200}(见文档响应示例 {@code "code": 1})。 + * 解析在适配器里单独处理,不走 {@code YqnEnvelope}。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ShipmentTrack { + + /** 运单 id。 */ + public Long id; + public String carrier; + public String trackingCode; + /** 最新状态;取值同 {@code trackingDetails[].status}。 */ + public String status; + /** 状态详情。 */ + public String statusDetail; + /** 预计妥投时间。 */ + public String estDeliveryDate; + /** 签收人。 */ + public String signedBy; + /** 承运商公开查询地址。 */ + public String publicUrl; + public Double weight; + public List trackingDetails; + public Parcel parcel; + public CarrierDetail carrierDetail; + + /** 一个轨迹节点。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class TrackDetail { + public String status; + public String message; + /** 时间点(格式未在文档中给出,按多种格式尝试解析)。 */ + public String datetime; + public String statusDetail; + public String timeZone; + public TrackingLocation trackingLocation; + } + + /** 节点地理位置。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class TrackingLocation { + public String city; + public String state; + public String country; + public String zip; + } + + /** 包裹信息;重量单位 oz、尺寸单位 inch(仓方固定口径)。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class Parcel { + public Double weight; + public Double length; + public Double width; + public Double height; + public String weightUnits; + public String packageDimensionsUnits; + } + + /** 承运商明细。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CarrierDetail { + /** 物流服务。 */ + public String service; + public String containerType; + public String originLocation; + public String destinationLocation; + public String guaranteedDeliveryDate; + public String alternateIdentifier; + public String initialDeliveryAttempt; + } + } } diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java new file mode 100644 index 0000000..9b1d257 --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java @@ -0,0 +1,178 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.TrackEvent; +import common.ecommerce.warehouse.model.TrackingInfo; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.warehouse.sdk.WarehouseAdapter; +import java.util.EnumSet; +import common.ecommerce.yqn.YqnConstants; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 物流轨迹(API 189)契约测试。 + * + *

注意这个接口在另一个主机,且成功码是 {@code 1} 而不是 {@code 200}。

+ */ +class YqnTrackingTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC); + + private static ChannelSecret secret() { + return ChannelSecret.builder().appSecret("key-1").build(); + } + + /** 主基址 + 辅助基址。 */ + private static WarehouseContext ctx() { + return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", + WarehouseConnection.of(YqnConstants.PR_BASE_URL, YqnConstants.AUX_BASE_URL_PR, secret()), + "req-track", CLOCK); + } + + /** 只有主基址。 */ + private static WarehouseContext ctxWithoutAux() { + return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", + WarehouseConnection.of(YqnConstants.PR_BASE_URL, secret()), "req-track", CLOCK); + } + + private static final String OK_BODY = + "{\"code\":1,\"message\":\"success\",\"data\":{" + + "\"id\":9527,\"carrier\":\"FEDEX\",\"trackingCode\":\"TRK123\"," + + "\"status\":\"DELIVERED\",\"statusDetail\":\"已签收\"," + + "\"estDeliveryDate\":\"2026-11-12T10:00:00Z\"," + + "\"signedBy\":\"J SMITH\",\"publicUrl\":\"https://track.example/TRK123\"," + + "\"trackingDetails\":[" + + "{\"status\":\"IN_TRANSIT\",\"message\":\"已离开分拨中心\"," + + "\"datetime\":\"2026-11-09 08:30:00\",\"timeZone\":\"America/New_York\"," + + "\"trackingLocation\":{\"city\":\"Newark\",\"state\":\"NJ\"," + + "\"country\":\"US\",\"zip\":\"07102\"}}," + + "{\"status\":\"DELIVERED\",\"message\":\"delivered\"," + + "\"datetime\":\"2026-11-10T15:20:00Z\",\"signedBy\":null}]," + + "\"carrierDetail\":{\"service\":\"FedEx_FEDEX_GROUND\"}}}"; + + @Test + void callsAuxiliaryHostNotWarehouseHost() { + RecordingTransport transport = RecordingTransport.create() + .route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY)); + new YqnAdapter(transport, new JacksonJsonCodec()).trackShipment(ctx(), "TRK123"); + + String url = transport.lastDataRequest().url(); + assertTrue(url.startsWith(YqnConstants.AUX_BASE_URL_PR), url); + assertTrue(url.contains("/api/v2/orderShipment/track/TRK123"), url); + } + + @Test + void missingAuxEndpointIsRejectedNotSilentlyRetargeted() { + RecordingTransport transport = RecordingTransport.create(); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + assertThrows(common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException.class, + () -> adapter.trackShipment(ctxWithoutAux(), "TRK123")); + assertTrue(transport.recorded().isEmpty(), "不应该发出任何请求"); + } + + @Test + void mapsShipmentLevelFields() { + RecordingTransport transport = RecordingTransport.create() + .route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY)); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + TrackingInfo info = adapter.trackShipment(ctx(), "TRK123"); + + assertEquals("TRK123", info.trackingNumber()); + assertEquals("FEDEX", info.carrier()); + assertEquals("FedEx_FEDEX_GROUND", info.carrierService()); + assertEquals("DELIVERED", info.status()); + assertEquals("已签收", info.statusDetail()); + assertEquals(Instant.parse("2026-11-12T10:00:00Z"), info.estimatedDeliveryAt()); + assertEquals("J SMITH", info.signedBy()); + assertEquals("https://track.example/TRK123", info.publicUrl()); + assertEquals(2, info.events().size()); + } + + @Test + void mapsTrackingDetailsAndLocation() { + RecordingTransport transport = RecordingTransport.create() + .route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY)); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + TrackingInfo info = adapter.trackShipment(ctx(), "TRK123"); + TrackEvent first = info.events().get(0); + + assertEquals("IN_TRANSIT", first.status()); + assertEquals("已离开分拨中心", first.description()); + assertEquals("Newark, NJ, US, 07102", first.location()); + assertEquals("TRK123", first.trackingNumber()); + assertEquals("FEDEX", first.carrier()); + // 带时区的直接解析;本地格式按调用时区解释 + assertEquals(Instant.parse("2026-11-10T15:20:00Z"), info.events().get(1).occurredAt()); + + TrackEvent second = info.events().get(1); + assertEquals("DELIVERED", second.status()); + assertNull(second.location()); + } + + @Test + void trackReturnsSameEventsAsTrackShipment() { + RecordingTransport transport = RecordingTransport.create() + .route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY)); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + List events = adapter.track(ctx(), "TRK123"); + + assertEquals(2, events.size()); + assertEquals("IN_TRANSIT", events.get(0).status()); + } + + /** 成功码是 1;返回 200 之类要按失败处理,不能当成成功去解析 data。 */ + @Test + void nonOneCodeIsFailure() { + RecordingTransport transport = RecordingTransport.create() + .route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok( + "{\"code\":200,\"message\":\"ok\",\"data\":{\"trackingCode\":\"TRK123\"}}")); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter.trackShipment(ctx(), "TRK123")); + assertTrue(ex.getMessage().contains("code=200"), ex.getMessage()); + } + + @Test + void missingCodeIsFailure() { + RecordingTransport transport = RecordingTransport.create() + .route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok( + "{\"message\":\"oops\"}")); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + assertThrows(RuntimeException.class, () -> adapter.trackShipment(ctx(), "TRK123")); + } + + @Test + void declaresTrackingCapability() { + YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + assertTrue(adapter.capabilities().contains(WarehouseCapability.TRACKING)); + } + + @Test + void blankTrackingNumberRejected() { + YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + assertThrows(IllegalArgumentException.class, () -> adapter.trackShipment(ctx(), " ")); + assertThrows(IllegalArgumentException.class, () -> adapter.trackShipment(ctx(), null)); + } +}