From 6ba1cb408a6d78c2ffcdbb607d624455bfba5de6 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Mon, 16 Nov 2026 16:16:12 +0800 Subject: [PATCH] =?UTF-8?q?feat(edayun):=20=E5=AF=B9=E6=8E=A5=E7=89=A9?= =?UTF-8?q?=E6=B5=81=E8=BD=A8=E8=BF=B9=E6=9F=A5=E8=AF=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit POST /webApi/track/getTrackInfoList → List / 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 --- .../ecommerce/warehouse/model/TrackingInfo.java | 40 ++++ .../ecommerce/edayun/adapter/EdayunAdapter.java | 65 +++++- .../edayun/adapter/EdayunTrackMapper.java | 177 +++++++++++++++++ .../ecommerce/edayun/dto/EdayunTrackDtos.java | 73 +++++++ .../ecommerce/edayun/adapter/EdayunTrackTest.java | 217 +++++++++++++++++++++ .../edayun/probe/EdayunTrackProbeTest.java | 115 +++++++++++ 6 files changed, 685 insertions(+), 2 deletions(-) create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunTrackDtos.java create mode 100644 warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java create mode 100644 warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunTrackProbeTest.java 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 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 trackDetaillVoList; + + /** 上网时间;字符串,如 {@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; + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java new file mode 100644 index 0000000..407616e --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java @@ -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})映射。 + * + *

重点:请求体是纯字符串数组、上网/妥投时间是带时区的字符串、 + * 「未匹配到轨迹」按空结果处理。

+ */ +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 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.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 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")); + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunTrackProbeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunTrackProbeTest.java new file mode 100644 index 0000000..9b1be57 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunTrackProbeTest.java @@ -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; + +/** + * 物流轨迹联调探针:只读,不会在仓侧产生任何数据。 + * + *
+ * # 只看报文(不联网)
+ * 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
+ * 
+ */ +@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); + } +}