Browse Source

feat(edayun): 对接物流轨迹查询

POST /webApi/track/getTrackInfoList → List<TrackEvent> / TrackingInfo

请求体是纯字符串数组 [1Z111,1Z222],没有包装对象——文档把字段名留空了,
示例 [{"": [...]}] 是自动生成的占位,真机只有纯数组能通。

「未匹配到轨迹」按空结果处理:仓方回 code=500,但对调用方来说和
「运单刚生成、还没揽收」是同一件事,抛异常会让宿主无法区分真失败与还没轨迹。
track 返回空列表,trackShipment 返回 null;其它 500 仍抛。

TrackingInfo 新增 firstOnlineAt / deliveredAt:文档说「主要关注上网时间跟妥投时间」,
这两个是带时区的字符串(GMT-04:00),而节点时间是毫秒,同一响应里口径混杂。
字符串按 timeZone 解析,解析失败留 null;认不出时区按 UTC,不猜成仓所在时区。

真机(2026-11-16):文档示例单号、出库单里的真实跟踪号、账户流水里的 20 个单号
全部「未匹配到轨迹」,PR 环境没有可查到的轨迹,映射只有单测覆盖。

Co-Authored-By: Claude <noreply@anthropic.com>
master
chenchuchuan 4 days ago
parent
commit
6ba1cb408a
  1. 40
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java
  2. 65
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  3. 177
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
  4. 73
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunTrackDtos.java
  5. 217
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java
  6. 115
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunTrackProbeTest.java

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

@ -28,6 +28,20 @@ public final class TrackingInfo { @@ -28,6 +28,20 @@ public final class TrackingInfo {
private final Instant estimatedDeliveryAt;
/** 签收人;未签收为 null。 */
private final String signedBy;
/**
* 上网时间(= 承运商首次揽收扫描);仓方未给为 null。
*
* <p>易达云字段:{@code onlineTime}({@code getTrackInfoList})。
* 对客服场景意义在于「包裹到底有没有真的交给承运商」——
* 有上网时间才说明物流真的启动了。</p>
*/
private final Instant firstOnlineAt;
/**
* 妥投时间(= 已签收);未妥投为 null。
*
* <p>易达云字段:{@code deliveredTime}({@code getTrackInfoList})。</p>
*/
private final Instant deliveredAt;
/** 承运商侧可公开查询的轨迹页地址。 */
private final String publicUrl;
private final List<TrackEvent> events;
@ -74,6 +88,8 @@ public final class TrackingInfo { @@ -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<TrackEvent>(b.events));
this.parcelWeightGrams = b.parcelWeightGrams;
@ -118,6 +134,16 @@ public final class TrackingInfo { @@ -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 { @@ -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<TrackEvent> events = new ArrayList<TrackEvent>();
private Double parcelWeightGrams;
@ -222,6 +250,18 @@ public final class TrackingInfo { @@ -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;

65
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java

@ -20,6 +20,7 @@ import common.ecommerce.edayun.dto.EdayunRentDetailDtos; @@ -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; @@ -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; @@ -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; @@ -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 @@ -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 @@ -902,6 +906,63 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
parsed == null ? null : parsed.data, ctx.warehouseCode());
}
// ------------------------------------------------------------------ 物流轨迹
/**
* 按跟踪号查轨迹节点({@code POST /webApi/track/getTrackInfoList})。
*
* <p>请求体是<b>纯字符串数组</b>,文档示例的嵌套对象是错的。
* 仓方无轨迹时返回<b>空列表</b>——真机对查不到的跟踪号回
* {@code code=500, msg=未匹配到轨迹},那是「没轨迹」不是「调用失败」。</p>
*/
@Override
public List<TrackEvent> track(WarehouseContext ctx, String trackingNumber) {
EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track");
return EdayunTrackMapper.toTrackEvents(parsed);
}
/**
* 按跟踪号查运单级轨迹;除节点外带上网时间与妥投时间。
*
* <p>文档说明「主要关注上网时间跟妥投时间」,这两个在
* {@link TrackingInfo#firstOnlineAt()} / {@link TrackingInfo#deliveredAt()}。</p>
*/
@Override
public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) {
EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track.shipment");
return EdayunTrackMapper.toTrackingInfo(parsed);
}
/**
* 查一条轨迹;查不到返回 null。
*
* <p><b>「未匹配到轨迹」按空结果处理</b>:仓方把这个当业务失败(code=500),
* 但对调用方来说和「运单还没揽收」是同一件事——两者都不该抛异常,
* 否则宿主无法区分「真失败」和「还没轨迹」。</p>
*/
private EdayunTrackDtos.Track fetchTrack(WarehouseContext ctx, String trackingNumber,
String operation) {
List<String> 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) {

177
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java

@ -0,0 +1,177 @@ @@ -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})。
*
* <p><b>请求体是纯字符串数组</b>,没有包装对象。文档示例
* {@code [{"": ["aa","bb"]}]} 是自动生成的占位,真机只有纯数组能通。</p>
*
* <p>时间字段口径混杂:{@code onlineTime} / {@code deliveredTime} 是
* <b>带时区偏移的字符串</b>,而节点时间 {@code recentDescribeTime} 是毫秒。
* 字符串时间要按响应里的 {@code timeZone}(如 {@code GMT-04:00})解释。</p>
*/
public final class EdayunTrackMapper {
private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private EdayunTrackMapper() {
}
/** 跟踪号 → 请求体(纯字符串数组)。 */
public static List<String> toRequest(List<String> trackingNumbers) {
if (trackingNumbers == null || trackingNumbers.isEmpty()) {
throw new IllegalArgumentException(
"edayun track query needs at least one tracking number");
}
List<String> out = new ArrayList<String>(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}。
*
* <p>文档说「主要关注上网时间跟妥投时间」,所以这两个单独落到
* {@link TrackingInfo#firstOnlineAt()} / {@link TrackingInfo#deliveredAt()},
* 而不是混在节点里。字符串时间按响应里的 {@code timeZone} 解释,解析失败留 null。</p>
*/
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} 只要节点,不含上网 / 妥投这两条汇总时间。
*
* <p>与 {@link #toTrackingInfo} 分开,是因为统一模型把节点列表和运单汇总
* 视为两个层次;上网 / 妥投是汇总信息,不塞进节点里。</p>
*/
public static List<TrackEvent> toTrackEvents(EdayunTrackDtos.Track track) {
if (track == null || track.trackDetaillVoList == null) {
return java.util.Collections.emptyList();
}
List<TrackEvent> out = new ArrayList<TrackEvent>(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;
}
/**
* 从响应里按跟踪号取一条轨迹。
*
* <p>接口一次可查多个跟踪号;{@code track} / {@code trackShipment} 都是单个口径,
* 所以按跟踪号精确匹配。找不到返回 null,不抛异常——运单可能刚生成还没轨迹。</p>
*/
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}。
*
* <p>认不出返回 UTC——不猜成仓所在时区(那是另一个概念)。</p>
*/
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);
}
}

73
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunTrackDtos.java

@ -0,0 +1,73 @@ @@ -0,0 +1,73 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:查询订单的物流轨迹
* ({@code POST /webApi/track/getTrackInfoList})。
*
* <p><b>请求体就是一个字符串数组</b>:{@code ["1Z111","1Z222"]},没有包装对象。
* 文档把字段名留空了,示例写成 {@code [{"": ["aa","bb"]}]} 是错的——
* 真机实测只有纯数组能通。</p>
*/
public final class EdayunTrackDtos {
private EdayunTrackDtos() {
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetTrackResponse {
public Integer code;
public String msg;
public List<Track> data;
public String traceId;
}
/** 一个跟踪号的轨迹。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Track {
public Long trackId;
public String trackingNo;
/** 轨迹状态;码表未给。 */
public Integer status;
/** 承运商,如 {@code fedex}。 */
public String carrierName;
/** 始发国。 */
public String startCountryName;
/** 目的国。 */
public String endCountryName;
/** 收件人。 */
public String receiver;
/** 轨迹明细节点。 */
public List<TrackDetail> trackDetaillVoList;
/** 上网时间;<b>字符串</b>,如 {@code 2025-08-19 08:17:00}。 */
public String onlineTime;
/** 妥投时间;字符串,同上。 */
public String deliveredTime;
/** 时区偏移,如 {@code GMT-04:00}——解释上面两个时间要用它。 */
public String timeZone;
}
/** 一个轨迹节点。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class TrackDetail {
public String trackingNo;
/** 节点状态;码表未给。 */
public Integer status;
/** 节点描述,如「上网」。 */
public String recentDescribe;
/** 节点时间(毫秒)。 */
public Long recentDescribeTime;
/** 创建时间(毫秒)。 */
public Long createTime;
/** 事件状态原值。 */
public String eventStatus;
}
}

217
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java

@ -0,0 +1,217 @@ @@ -0,0 +1,217 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunTrackDtos;
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.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 org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.Arrays;
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;
/**
* 物流轨迹({@code /webApi/track/getTrackInfoList})映射。
*
* <p>重点:请求体是纯字符串数组、上网/妥投时间是带时区的字符串、
* 「未匹配到轨迹」按空结果处理。</p>
*/
class EdayunTrackTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, "2",
WarehouseConnection.of("https://test.example/openapi",
ChannelSecret.builder().appKey("k").appSecret("s")
.clientId("c").clientSecret("cs").build()),
"req-track", CLOCK);
}
private static RecordingTransport stub(String body) {
return RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_TRACK,
req -> Responses.ok(body));
}
// ------------------------------------------------------------ 请求
/** 请求体是纯字符串数组,不是包装对象。 */
@Test
void requestBodyIsPlainArray() {
List<String> body = EdayunTrackMapper.toRequest(Arrays.asList("1Z111", " 1Z222 "));
assertEquals(Arrays.asList("1Z111", "1Z222"), body);
assertTrue(new JacksonJsonCodec().toJson(body).startsWith("["));
}
@Test
void blankTrackingNumbersRejected() {
assertThrows(IllegalArgumentException.class,
() -> EdayunTrackMapper.toRequest(null));
assertThrows(IllegalArgumentException.class,
() -> EdayunTrackMapper.toRequest(java.util.Collections.<String>emptyList()));
assertThrows(IllegalArgumentException.class,
() -> EdayunTrackMapper.toRequest(Arrays.asList(" ", "")));
}
// ------------------------------------------------------------ 响应
private static EdayunTrackDtos.Track track() {
EdayunTrackDtos.TrackDetail detail = new EdayunTrackDtos.TrackDetail();
detail.trackingNo = "LF-1741871641090";
detail.status = 1;
detail.recentDescribe = "上网";
detail.recentDescribeTime = 1741145821000L;
detail.eventStatus = "IN_TRANSIT";
EdayunTrackDtos.Track track = new EdayunTrackDtos.Track();
track.trackId = 123L;
track.trackingNo = "LF-1741871641090";
track.status = 1;
track.carrierName = "fedex";
track.startCountryName = "中国";
track.endCountryName = "美国";
track.receiver = "123";
track.trackDetaillVoList = java.util.Collections.singletonList(detail);
track.onlineTime = "2025-08-19 08:17:00";
track.deliveredTime = "2025-08-20 10:00:00";
track.timeZone = "GMT-04:00";
return track;
}
@Test
void mapsTrackingInfo() {
TrackingInfo info = EdayunTrackMapper.toTrackingInfo(track());
assertEquals("LF-1741871641090", info.trackingNumber());
assertEquals("fedex", info.carrier());
assertEquals("1", info.status());
assertEquals("123", info.signedBy());
// 上网 / 妥投时间按 GMT-04:00 解释
assertEquals(Instant.parse("2025-08-19T12:17:00Z"), info.firstOnlineAt());
assertEquals(Instant.parse("2025-08-20T14:00:00Z"), info.deliveredAt());
assertEquals(1, info.events().size());
}
/** 节点状态优先用 eventStatus,缺失才退回数字码。 */
@Test
void eventStatusFallsBackToCode() {
EdayunTrackDtos.Track t = track();
t.trackDetaillVoList.get(0).eventStatus = null;
assertEquals("1", EdayunTrackMapper.toTrackEvents(t).get(0).status());
t.trackDetaillVoList.get(0).eventStatus = "DELIVERED";
assertEquals("DELIVERED", EdayunTrackMapper.toTrackEvents(t).get(0).status());
}
@Test
void mapsEvents() {
List<TrackEvent> events = EdayunTrackMapper.toTrackEvents(track());
assertEquals(1, events.size());
TrackEvent e = events.get(0);
assertEquals("LF-1741871641090", e.trackingNumber());
assertEquals("fedex", e.carrier());
assertEquals("上网", e.description());
assertEquals(Instant.ofEpochMilli(1741145821000L), e.occurredAt());
}
/** 时间字符串解析失败留 null,不抛异常。 */
@Test
void unparsableTimesStayNull() {
EdayunTrackDtos.Track t = track();
t.onlineTime = "not-a-time";
t.deliveredTime = null;
TrackingInfo info = EdayunTrackMapper.toTrackingInfo(t);
assertNull(info.firstOnlineAt());
assertNull(info.deliveredAt());
}
/** 时区偏移解析:GMT±HH:mm、UTC±HH:mm、空值。 */
@Test
void zoneParsing() {
assertEquals(ZoneOffset.of("-04:00"), EdayunTrackMapper.zoneOf("GMT-04:00"));
assertEquals(ZoneOffset.of("+08:00"), EdayunTrackMapper.zoneOf("UTC+08:00"));
assertEquals(ZoneOffset.of("+08:00"), EdayunTrackMapper.zoneOf("+08:00"));
assertEquals(ZoneOffset.UTC, EdayunTrackMapper.zoneOf(null));
assertEquals(ZoneOffset.UTC, EdayunTrackMapper.zoneOf("bogus"));
}
/** 一次查多个跟踪号时按单号精确匹配。 */
@Test
void findMatchesByTrackingNumber() {
EdayunTrackDtos.Track other = track();
other.trackingNo = "OTHER-1";
EdayunTrackDtos.GetTrackResponse resp = new EdayunTrackDtos.GetTrackResponse();
resp.code = 200;
resp.data = Arrays.asList(other, track());
assertEquals("LF-1741871641090",
EdayunTrackMapper.find(resp, "lf-1741871641090").trackingNo);
assertNull(EdayunTrackMapper.find(resp, "NOPE"));
assertNull(EdayunTrackMapper.find(null, "X"));
}
// ------------------------------------------------------------ 门面
@Test
void adapterTracksShipment() {
RecordingTransport transport = stub("{\"code\":200,\"msg\":\"ok\",\"data\":[{"
+ "\"trackingNo\":\"LF-1\",\"status\":1,\"carrierName\":\"fedex\","
+ "\"onlineTime\":\"2025-08-19 08:17:00\",\"deliveredTime\":null,"
+ "\"timeZone\":\"GMT+08:00\",\"trackDetaillVoList\":["
+ "{\"recentDescribe\":\"上网\",\"recentDescribeTime\":1741145821000}]}]}");
TrackingInfo info = new EdayunAdapter(transport, new JacksonJsonCodec())
.trackShipment(ctx(), "LF-1");
assertEquals("LF-1", info.trackingNumber());
assertEquals(Instant.parse("2025-08-19T00:17:00Z"), info.firstOnlineAt());
assertNull(info.deliveredAt());
// 请求体是纯数组
assertEquals("[\"LF-1\"]", transport.lastDataRequest().body());
}
/**
* 「未匹配到轨迹」是「还没轨迹」,不是调用失败:返回空列表 / null,不抛异常。
*/
@Test
void noTrackFoundYieldsEmpty() {
RecordingTransport transport = stub(
"{\"code\":500,\"msg\":\"未匹配到轨迹\",\"data\":null}");
assertTrue(new EdayunAdapter(transport, new JacksonJsonCodec())
.track(ctx(), "NOPE").isEmpty());
assertNull(new EdayunAdapter(transport, new JacksonJsonCodec())
.trackShipment(ctx(), "NOPE"));
}
/** 其它业务错误仍要抛异常。 */
@Test
void otherErrorsStillThrow() {
RecordingTransport transport = stub("{\"code\":500,\"msg\":\"系统异常\"}");
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec()).track(ctx(), "X"));
}
}

115
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunTrackProbeTest.java

@ -0,0 +1,115 @@ @@ -0,0 +1,115 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunTrackMapper;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.spi.ChannelSecret;
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 org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
import java.time.Clock;
import java.util.Collections;
import java.util.UUID;
/**
* 物流轨迹联调探针:<b>只读</b>,不会在仓侧产生任何数据。
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.track=true -Dtest=EdayunTrackProbeTest test
*
* # 真查(只读)
* ... -Dedayun.probe.track=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* -Dedayun.probe.trackingNo=1Z84V7X00397803717
* </pre>
*/
@EnabledIfSystemProperty(named = "edayun.probe.track", matches = "true")
class EdayunTrackProbeTest {
private static final String BASE_URL = opt("edayun.probe.baseUrl", EdayunConstants.PR_BASE_URL);
private static final String CLIENT_ID = System.getProperty("edayun.probe.clientId", "");
private static final String CLIENT_SECRET = System.getProperty("edayun.probe.clientSecret", "");
private static final String APP_KEY = System.getProperty("edayun.probe.appKey", "");
private static final String APP_SECRET = System.getProperty("edayun.probe.appSecret", "");
private static final String TRACKING_NO =
opt("edayun.probe.trackingNo", "1Z84V7X00397803717");
private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probeTrack() {
String bodyJson = new JacksonJsonCodec().toJson(
EdayunTrackMapper.toRequest(Collections.singletonList(TRACKING_NO)));
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_TRACK + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL + " trackingNo=" + mask(TRACKING_NO));
System.out.println("[request] " + bodyJson);
Assumptions.assumeTrue(CALL, "dry-run:未加 -Dedayun.probe.call=true,不实际调用");
Assumptions.assumeTrue(!CLIENT_ID.trim().isEmpty() && !CLIENT_SECRET.trim().isEmpty()
&& !APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(),
"真查需要 -Dedayun.probe.clientId / clientSecret / appKey / appSecret");
try {
WarehouseContext ctx = WarehouseContext.of("EDY-PROBE", WarehouseProvider.EDAYUN, null,
WarehouseConnection.of(BASE_URL,
ChannelSecret.builder()
.appKey(APP_KEY).appSecret(APP_SECRET)
.clientId(CLIENT_ID).clientSecret(CLIENT_SECRET)
.build()),
"probe-" + UUID.randomUUID(), Clock.systemUTC());
EdayunAdapter adapter = new EdayunAdapter(
new OkHttpTransport("common-ecommerce/1.0.0 (edayun-probe)", 10_000, 60_000),
new JacksonJsonCodec());
TrackingInfo info = adapter.trackShipment(ctx, TRACKING_NO);
if (info == null) {
System.out.println("[EMPTY] 仓方未匹配到轨迹");
return;
}
System.out.println("[OK] " + info.trackingNumber() + " carrier=" + info.carrier()
+ " status=" + info.status()
+ " online=" + info.firstOnlineAt() + " delivered=" + info.deliveredAt()
+ " events=" + info.events().size());
for (TrackEvent e : info.events()) {
System.out.println(" " + e.occurredAt() + " [" + e.status() + "] "
+ e.description());
}
} catch (RuntimeException e) {
String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage();
System.out.println("[ERROR] " + e.getClass().getSimpleName() + ": "
+ (msg.length() <= 800 ? msg : msg.substring(0, 800) + "…"));
if (e instanceof ChannelException) {
ChannelException ce = (ChannelException) e;
System.out.println(" platformCode=" + ce.platformCode()
+ " retryable=" + ce.retryable());
}
}
}
private static String opt(String name, String fallback) {
String value = System.getProperty(name, "");
String trimmed = value == null ? "" : value.trim();
return trimmed.isEmpty() ? fallback : trimmed;
}
private static String mask(String v) {
if (v == null || v.trim().isEmpty()) {
return "(empty)";
}
String t = v.trim();
return t.length() <= 6 ? "***" : t.substring(0, 3) + "***" + t.substring(t.length() - 2);
}
}
Loading…
Cancel
Save