Browse Source

feat(yqn): 按 API 189 对接运单物流轨迹

新增 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 <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
d2d2f04a45
  1. 4
      README.md
  2. 9
      sdk-common/src/main/java/common/ecommerce/http/JacksonJsonCodec.java
  3. 18
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingCapable.java
  4. 156
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java
  5. 34
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java
  6. 5
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java
  7. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  8. 21
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  9. 82
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  10. 143
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java
  11. 77
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  12. 178
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java

4
README.md

@ -308,7 +308,7 @@ common.ecommerce @@ -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 @@ -320,7 +320,7 @@ common.ecommerce
│ │ UnmatchedCallbackStore
│ └── sdk WarehouseSdk / WarehouseOperations / WarehouseOutbounds /
│ WarehouseAdapter / WarehouseAdapterFactory / WarehouseContext /
│ WarehouseConnection / WarehouseWriteScope
│ WarehouseConnection(主基址 + 可选辅助基址)/ WarehouseWriteScope
│
├── yqn 运去哪三方仓(warehouse-sdk-yqn)
│ ├── YqnConstants 端点、路径、固定 token 请求头名、限流

9
sdk-common/src/main/java/common/ecommerce/http/JacksonJsonCodec.java

@ -71,6 +71,15 @@ public final class JacksonJsonCodec implements JsonCodec { @@ -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 <T> List<T> listAt(String json, String pointer, Class<T> type) {
JsonNode node = nodeAt(json, pointer);

18
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingCapable.java

@ -1,6 +1,7 @@ @@ -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; @@ -9,6 +10,21 @@ import java.util.List;
/** 物流轨迹能力。信仓无此接口,整体不实现。 */
public interface TrackingCapable extends WarehouseAdapter {
/** 按跟踪号查轨迹。 */
/**
* 按跟踪号查轨迹节点。
*
* @return 节点列表;仓方无轨迹时为空列表(不是错误——运单可能刚生成还没揽收)
*/
List<TrackEvent> track(WarehouseContext ctx, String trackingNumber);
/**
* 按跟踪号查运单级轨迹:除节点外还带最新状态、承运商、签收人与预计妥投。
*
* <p>与 {@link #track} 的关系:本方法返回 {@link TrackingInfo},其中的
* {@code events()} 就是 {@code track} 的返回内容。宿主做 C 端可视化或异常预警时用这个,
* 只需要节点明细时用 {@code track}。</p>
*
* <p>状态值保持仓方原值,不做跨仓归一。</p>
*/
TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber);
}

156
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java

@ -0,0 +1,156 @@ @@ -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;
/**
* 运单物流轨迹查询结果。
*
* <p>由 {@code TrackingCapable.trackShipment()} 返回:整体是<b>一个运单</b>的当前状态 +
* 若干节点,比 {@link TrackEvent}(单条事件)多出承运商、最新状态、签收人与预计妥投。</p>
*
* <p>状态值保持仓方原始字符串,见 {@link #status()};不做跨仓归一——各承运商的节点
* 状态词汇差异太大,强行归一会丢失「派送失败 / 退回中」这类关键区分。</p>
*/
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<TrackEvent> 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<TrackEvent>(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<TrackEvent> 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<TrackEvent> events = new ArrayList<TrackEvent>();
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);
}
}
}

34
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java

@ -18,14 +18,23 @@ public final class WarehouseConnection { @@ -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 表示未配置,需要它的能力会显式拒绝,<b>不静默退回主基址</b>。
*/
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 { @@ -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);
}
/**
* 构造带辅助基址的连接。
*
* <p>仅当仓方把部分接口放在另一个主机时使用。不传时,需要辅助基址的能力会抛
* {@code WarehouseUnsupportedCapabilityException},不会退回主基址。</p>
*/
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 { @@ -48,6 +73,11 @@ public final class WarehouseConnection {
return endpointBaseUrl;
}
/** 辅助基址;未配置时为 null。 */
public String auxEndpointBaseUrl() {
return auxEndpointBaseUrl;
}
/** 凭据;已携带本次调用使用的端点。 */
public ChannelSecret secret() {
return secret;

5
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java

@ -82,6 +82,11 @@ public final class WarehouseContext implements CallScope { @@ -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();

20
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -34,6 +34,7 @@ import common.ecommerce.warehouse.model.InventoryQuery; @@ -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 { @@ -146,7 +147,11 @@ public final class WarehouseOperations {
return new ReturnView();
}
/** 轨迹。 */
/**
* 轨迹节点。只读,不走幂等。
*
* @return 节点列表;无轨迹时为空列表
*/
public List<TrackEvent> track(String trackingNumber) {
require(WarehouseCapability.TRACKING, TrackingCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.track",
@ -155,6 +160,19 @@ public final class WarehouseOperations { @@ -155,6 +160,19 @@ public final class WarehouseOperations {
() -> ((TrackingCapable) adapter).track(ctx, trackingNumber));
}
/**
* 运单级轨迹:最新状态 + 承运商 + 签收人 + 预计妥投 + 节点明细。
*
* <p>{@code events()} 与 {@link #track(String)} 的返回一致,只多了一层运单信息。</p>
*/
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();

21
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -46,8 +46,25 @@ public final class YqnConstants { @@ -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}}。
*
* <p><b>注意主机不同</b>:这个接口在 {@code pr-ship-api.yqn.com},不是仓接口的
* {@code pr-hwc-open-api.yqn.com}。调用方需通过
* {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址,
* 未传时适配器显式拒绝而不是打到主基址上。</p>
*/
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";
/**
* 轨迹接口的成功码。
*
* <p>文档响应示例是 {@code "code": 1},与仓接口的 {@code 200} 不同,因此单独定义。</p>
*/
public static final int TRACK_SUCCESS_CODE = 1;
/** 结算明细(API 133):作业费 / 仓储费 / 增值服务费 / 尾程费。 */
public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail";
/** 订单测算 / 运费试算(API 121):发货前按包裹 + 地址 + 渠道询价。 */

82
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -27,7 +27,10 @@ import common.ecommerce.warehouse.capability.WarehouseProduct; @@ -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; @@ -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 @@ -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 @@ -485,6 +489,80 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
}
// ------------------------------------------------------------------ 物流轨迹
/**
* 运单轨迹(API 189)。
*
* <p>这个接口在<b>另一个主机</b>({@code pr-ship-api.yqn.com}),调用方必须通过
* {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址;
* 没传时显式拒绝,不退回主基址,避免把轨迹请求打到仓接口上。</p>
*
* <p>信封的成功码是 {@code 1}(不是其它接口的 {@code 200}),所以不走
* {@code YqnEnvelope},单独解析。</p>
*/
@Override
public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) {
YqnDtos.ShipmentTrack track = fetchTrack(ctx, trackingNumber);
return YqnTrackingMapper.toTrackingInfo(track, trackingNumber, zoneOf(ctx));
}
@Override
public List<TrackEvent> 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
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */

143
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java

@ -0,0 +1,143 @@ @@ -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)。
*
* <p>状态值一律保持运去哪原话,不做归一:承运商的节点状态词汇差异大,
* 「派送失败 / 退回中」这类区分归一会丢信息。</p>
*/
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<YqnDtos.ShipmentTrack.TrackDetail> 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<TrackEvent> 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<String> parts = new ArrayList<String>(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<String> parts, String v) {
if (hasText(v)) {
parts.add(v.trim());
}
}
private static String join(List<String> 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,不因时间格式阻断轨迹展示。
*
* <p>文档未给出 {@code datetime} 的格式,因此按「带时区 ISO → 常见本地格式」依次尝试;
* 都不带时区时按调用方给的 {@code zone} 解释。</p>
*/
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();
}
}

77
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -945,4 +945,81 @@ public final class YqnDtos { @@ -945,4 +945,81 @@ public final class YqnDtos {
public String currency;
}
}
// ------------------------------------------------------------------ 物流轨迹(API 189)
/**
* 运单轨迹响应(API 189 {@code data})。
*
* <p><b>注意</b>:这个接口的外层信封是 {@code code/message},成功码是
* <b>{@code 1}</b> 而不是其它接口的 {@code 200}(见文档响应示例 {@code "code": 1})。
* 解析在适配器里单独处理,不走 {@code YqnEnvelope}。</p>
*/
@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<TrackDetail> 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;
}
}
}

178
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java

@ -0,0 +1,178 @@ @@ -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)契约测试。
*
* <p>注意这个接口在<b>另一个主机</b>,且成功码是 {@code 1} 而不是 {@code 200}。</p>
*/
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<TrackEvent> 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));
}
}
Loading…
Cancel
Save