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
index 5676268..101062c 100644
--- 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
@@ -28,6 +28,20 @@ public final class TrackingInfo {
private final Instant estimatedDeliveryAt;
/** 签收人;未签收为 null。 */
private final String signedBy;
+ /**
+ * 上网时间(= 承运商首次揽收扫描);仓方未给为 null。
+ *
+ *
易达云字段:{@code onlineTime}({@code getTrackInfoList})。
+ * 对客服场景意义在于「包裹到底有没有真的交给承运商」——
+ * 有上网时间才说明物流真的启动了。
+ */
+ private final Instant firstOnlineAt;
+ /**
+ * 妥投时间(= 已签收);未妥投为 null。
+ *
+ * 易达云字段:{@code deliveredTime}({@code getTrackInfoList})。
+ */
+ private final Instant deliveredAt;
/** 承运商侧可公开查询的轨迹页地址。 */
private final String publicUrl;
private final List events;
@@ -74,6 +88,8 @@ public final class TrackingInfo {
this.statusDetail = b.statusDetail;
this.estimatedDeliveryAt = b.estimatedDeliveryAt;
this.signedBy = b.signedBy;
+ this.firstOnlineAt = b.firstOnlineAt;
+ this.deliveredAt = b.deliveredAt;
this.publicUrl = b.publicUrl;
this.events = Collections.unmodifiableList(new ArrayList(b.events));
this.parcelWeightGrams = b.parcelWeightGrams;
@@ -118,6 +134,16 @@ public final class TrackingInfo {
return signedBy;
}
+ /** 上网时间(首次揽收扫描);仓方未给为 null。 */
+ public Instant firstOnlineAt() {
+ return firstOnlineAt;
+ }
+
+ /** 妥投时间;未妥投为 null。 */
+ public Instant deliveredAt() {
+ return deliveredAt;
+ }
+
public String publicUrl() {
return publicUrl;
}
@@ -177,6 +203,8 @@ public final class TrackingInfo {
private String statusDetail;
private Instant estimatedDeliveryAt;
private String signedBy;
+ private Instant firstOnlineAt;
+ private Instant deliveredAt;
private String publicUrl;
private final List events = new ArrayList();
private Double parcelWeightGrams;
@@ -222,6 +250,18 @@ public final class TrackingInfo {
return this;
}
+ /** 上网时间(首次揽收扫描)。 */
+ public Builder firstOnlineAt(Instant v) {
+ this.firstOnlineAt = v;
+ return this;
+ }
+
+ /** 妥投时间。 */
+ public Builder deliveredAt(Instant v) {
+ this.deliveredAt = v;
+ return this;
+ }
+
public Builder publicUrl(String v) {
this.publicUrl = v;
return this;
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
index 38a8ebd..8c705dc 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
@@ -20,6 +20,7 @@ import common.ecommerce.edayun.dto.EdayunRentDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
+import common.ecommerce.edayun.dto.EdayunTrackDtos;
import common.ecommerce.edayun.enums.EdayunCancelStatus;
import common.ecommerce.edayun.http.EdayunRequestFactory;
import common.ecommerce.http.HttpRequest;
@@ -37,6 +38,7 @@ import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
+import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
@@ -71,6 +73,8 @@ import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
+import common.ecommerce.warehouse.model.TrackEvent;
+import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@@ -91,7 +95,7 @@ import java.util.List;
*/
public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable,
OutboundCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable,
- InboundCapable, WarehouseReturnCapable, BolCapable, LogisticsProductCapable {
+ InboundCapable, WarehouseReturnCapable, BolCapable, LogisticsProductCapable, TrackingCapable {
/** 物流产品查询的适用业务:1 店铺订单(默认口径)。 */
private static final int APPLICABLE_BUSINESS_STORE_ORDER = 1;
@@ -148,7 +152,7 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE,
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND,
WarehouseCapability.RETURN, WarehouseCapability.BOL,
- WarehouseCapability.LOGISTICS_PRODUCT);
+ WarehouseCapability.LOGISTICS_PRODUCT, WarehouseCapability.TRACKING);
}
/**
@@ -902,6 +906,63 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
parsed == null ? null : parsed.data, ctx.warehouseCode());
}
+ // ------------------------------------------------------------------ 物流轨迹
+
+ /**
+ * 按跟踪号查轨迹节点({@code POST /webApi/track/getTrackInfoList})。
+ *
+ * 请求体是纯字符串数组,文档示例的嵌套对象是错的。
+ * 仓方无轨迹时返回空列表——真机对查不到的跟踪号回
+ * {@code code=500, msg=未匹配到轨迹},那是「没轨迹」不是「调用失败」。
+ */
+ @Override
+ public List track(WarehouseContext ctx, String trackingNumber) {
+ EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track");
+ return EdayunTrackMapper.toTrackEvents(parsed);
+ }
+
+ /**
+ * 按跟踪号查运单级轨迹;除节点外带上网时间与妥投时间。
+ *
+ * 文档说明「主要关注上网时间跟妥投时间」,这两个在
+ * {@link TrackingInfo#firstOnlineAt()} / {@link TrackingInfo#deliveredAt()}。
+ */
+ @Override
+ public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) {
+ EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track.shipment");
+ return EdayunTrackMapper.toTrackingInfo(parsed);
+ }
+
+ /**
+ * 查一条轨迹;查不到返回 null。
+ *
+ * 「未匹配到轨迹」按空结果处理:仓方把这个当业务失败(code=500),
+ * 但对调用方来说和「运单还没揽收」是同一件事——两者都不该抛异常,
+ * 否则宿主无法区分「真失败」和「还没轨迹」。
+ */
+ private EdayunTrackDtos.Track fetchTrack(WarehouseContext ctx, String trackingNumber,
+ String operation) {
+ List body = EdayunTrackMapper.toRequest(
+ java.util.Collections.singletonList(trackingNumber));
+ String bodyJson = json.toJson(body);
+
+ HttpResponse resp = send(ctx, EdayunConstants.PATH_TRACK, bodyJson, operation);
+ EdayunTrackDtos.GetTrackResponse parsed =
+ json.fromJson(resp.body(), EdayunTrackDtos.GetTrackResponse.class);
+ if (parsed != null && isNoTrackFound(parsed.msg)) {
+ return null;
+ }
+ requireSuccess(ctx, parsed == null ? null : parsed.code,
+ parsed == null ? null : parsed.msg, resp, operation);
+
+ return EdayunTrackMapper.find(parsed, trackingNumber);
+ }
+
+ /** 仓方「没有轨迹」的提示语。 */
+ private static boolean isNoTrackFound(String msg) {
+ return msg != null && (msg.contains("未匹配到轨迹") || msg.contains("跟踪号为空"));
+ }
+
// ------------------------------------------------------------------ internals
/** 发业务请求(自动取 token、算签名)。 */
private HttpResponse send(WarehouseContext ctx, String path, String bodyJson, String operation) {
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
new file mode 100644
index 0000000..5726b17
--- /dev/null
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
@@ -0,0 +1,177 @@
+package common.ecommerce.edayun.adapter;
+
+import common.ecommerce.edayun.dto.EdayunTrackDtos;
+import common.ecommerce.warehouse.model.TrackEvent;
+import common.ecommerce.warehouse.model.TrackingInfo;
+
+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;
+
+/**
+ * 易达云物流轨迹映射({@code POST /webApi/track/getTrackInfoList})。
+ *
+ * 请求体是纯字符串数组,没有包装对象。文档示例
+ * {@code [{"": ["aa","bb"]}]} 是自动生成的占位,真机只有纯数组能通。
+ *
+ * 时间字段口径混杂:{@code onlineTime} / {@code deliveredTime} 是
+ * 带时区偏移的字符串,而节点时间 {@code recentDescribeTime} 是毫秒。
+ * 字符串时间要按响应里的 {@code timeZone}(如 {@code GMT-04:00})解释。
+ */
+public final class EdayunTrackMapper {
+
+ private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+
+ private EdayunTrackMapper() {
+ }
+
+ /** 跟踪号 → 请求体(纯字符串数组)。 */
+ public static List toRequest(List trackingNumbers) {
+ if (trackingNumbers == null || trackingNumbers.isEmpty()) {
+ throw new IllegalArgumentException(
+ "edayun track query needs at least one tracking number");
+ }
+ List out = new ArrayList(trackingNumbers.size());
+ for (String tn : trackingNumbers) {
+ if (tn != null && !tn.trim().isEmpty()) {
+ out.add(tn.trim());
+ }
+ }
+ if (out.isEmpty()) {
+ throw new IllegalArgumentException(
+ "edayun track query needs at least one non-blank tracking number");
+ }
+ return out;
+ }
+
+ /**
+ * 一条轨迹 → {@link TrackingInfo}。
+ *
+ * 文档说「主要关注上网时间跟妥投时间」,所以这两个单独落到
+ * {@link TrackingInfo#firstOnlineAt()} / {@link TrackingInfo#deliveredAt()},
+ * 而不是混在节点里。字符串时间按响应里的 {@code timeZone} 解释,解析失败留 null。
+ */
+ public static TrackingInfo toTrackingInfo(EdayunTrackDtos.Track track) {
+ if (track == null || track.trackingNo == null || track.trackingNo.trim().isEmpty()) {
+ return null;
+ }
+ ZoneId zone = zoneOf(track.timeZone);
+ TrackingInfo.Builder builder = TrackingInfo.builder()
+ .trackingNumber(track.trackingNo.trim())
+ .carrier(track.carrierName)
+ // 仓方状态是数字码,码表没给;保留原值而不是猜成某个字符串
+ .status(track.status == null ? null : String.valueOf(track.status))
+ .signedBy(track.receiver)
+ .firstOnlineAt(parseLocal(track.onlineTime, zone))
+ .deliveredAt(parseLocal(track.deliveredTime, zone));
+
+ if (track.trackDetaillVoList != null) {
+ for (EdayunTrackDtos.TrackDetail detail : track.trackDetaillVoList) {
+ if (detail == null) {
+ continue;
+ }
+ builder.event(TrackEvent.builder()
+ .trackingNumber(track.trackingNo.trim())
+ .carrier(track.carrierName)
+ .status(detail.eventStatus != null ? detail.eventStatus
+ : (detail.status == null ? null : String.valueOf(detail.status)))
+ .description(detail.recentDescribe)
+ .occurredAt(instantOf(detail.recentDescribeTime))
+ .build());
+ }
+ }
+ return builder.build();
+ }
+
+ /**
+ * 节点列表:{@code track} 只要节点,不含上网 / 妥投这两条汇总时间。
+ *
+ * 与 {@link #toTrackingInfo} 分开,是因为统一模型把节点列表和运单汇总
+ * 视为两个层次;上网 / 妥投是汇总信息,不塞进节点里。
+ */
+ public static List toTrackEvents(EdayunTrackDtos.Track track) {
+ if (track == null || track.trackDetaillVoList == null) {
+ return java.util.Collections.emptyList();
+ }
+ List out = new ArrayList(track.trackDetaillVoList.size());
+ for (EdayunTrackDtos.TrackDetail detail : track.trackDetaillVoList) {
+ if (detail == null) {
+ continue;
+ }
+ out.add(TrackEvent.builder()
+ .trackingNumber(track.trackingNo)
+ .carrier(track.carrierName)
+ .status(detail.eventStatus != null ? detail.eventStatus
+ : (detail.status == null ? null : String.valueOf(detail.status)))
+ .description(detail.recentDescribe)
+ .occurredAt(instantOf(detail.recentDescribeTime))
+ .build());
+ }
+ return out;
+ }
+
+ /**
+ * 从响应里按跟踪号取一条轨迹。
+ *
+ * 接口一次可查多个跟踪号;{@code track} / {@code trackShipment} 都是单个口径,
+ * 所以按跟踪号精确匹配。找不到返回 null,不抛异常——运单可能刚生成还没轨迹。
+ */
+ public static EdayunTrackDtos.Track find(EdayunTrackDtos.GetTrackResponse response,
+ String trackingNumber) {
+ if (response == null || response.data == null || trackingNumber == null) {
+ return null;
+ }
+ String target = trackingNumber.trim();
+ for (EdayunTrackDtos.Track track : response.data) {
+ if (track != null && track.trackingNo != null
+ && target.equalsIgnoreCase(track.trackingNo.trim())) {
+ return track;
+ }
+ }
+ return null;
+ }
+
+ /**
+ * 解析时区偏移,如 {@code GMT-04:00} / {@code GMT+08:00}。
+ *
+ * 认不出返回 UTC——不猜成仓所在时区(那是另一个概念)。
+ */
+ static ZoneId zoneOf(String gmtOffset) {
+ if (gmtOffset == null || gmtOffset.trim().isEmpty()) {
+ return ZoneOffset.UTC;
+ }
+ String v = gmtOffset.trim().toUpperCase(java.util.Locale.ROOT);
+ if (v.startsWith("GMT")) {
+ v = v.substring(3);
+ } else if (v.startsWith("UTC")) {
+ v = v.substring(3);
+ }
+ try {
+ return ZoneOffset.of(v.isEmpty() ? "Z" : v);
+ } catch (java.time.DateTimeException e) {
+ return ZoneOffset.UTC;
+ }
+ }
+
+ /** 字符串时间({@code yyyy-MM-dd HH:mm:ss})→ Instant;解析失败返回 null。 */
+ static Instant parseLocal(String value, ZoneId zone) {
+ if (value == null || value.trim().isEmpty()) {
+ return null;
+ }
+ try {
+ return LocalDateTime.parse(value.trim(), TIME)
+ .atZone(zone == null ? ZoneOffset.UTC : zone).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ private static Instant instantOf(Long millis) {
+ return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis);
+ }
+}
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunTrackDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunTrackDtos.java
new file mode 100644
index 0000000..7a1d65c
--- /dev/null
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunTrackDtos.java
@@ -0,0 +1,73 @@
+package common.ecommerce.edayun.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+import java.util.List;
+
+/**
+ * 易达云报文结构:查询订单的物流轨迹
+ * ({@code POST /webApi/track/getTrackInfoList})。
+ *
+ * 请求体就是一个字符串数组:{@code ["1Z111","1Z222"]},没有包装对象。
+ * 文档把字段名留空了,示例写成 {@code [{"": ["aa","bb"]}]} 是错的——
+ * 真机实测只有纯数组能通。
+ */
+public final class EdayunTrackDtos {
+
+ private EdayunTrackDtos() {
+ }
+
+ /** 查询响应。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class GetTrackResponse {
+ public Integer code;
+ public String msg;
+ public List