Browse Source
- core 新增能力位 TRACKING_CHANGE、TrackingChangeCapable、TrackingChangeCommand / TrackingChangeOrder、TrackingChangeHandleType(召回 / 换址 / 在途异常) - 门面新增 createTrackingChange(写操作,走幂等守卫)与 getTrackingChange - 恒健新增两个 DTO + HengjianTrackingChangeMapper,实现 createChange / getChange - 纠正查询路径:文档写 /v1/saleOrder/findOrder,真机 404; 实际是 /v1/trackingChange/findOrder(已写入常量与文档) - 真机确认 orderNo 必填(文档标「否」);四项必填本地校验, 换址三项缺哪个报哪个 - 异动单受理状态与运单物流状态分两个字段保存(orderStatus / logisticsStatus), 不互相覆盖 - 修正信封:999999 是通用失败码(参数校验失败也回它),只有 message 含授权 字样时才判认证失败,避免参数错误导致宿主白刷凭据 - 探针:查询(只读)+ 创建(写,需一对真实匹配的单号与运单号) 验证:mvn test 全量通过,恒健 129 个用例 + 4 个探针跳过。 Co-Authored-By: Claude Code <noreply@anthropic.com>master
18 changed files with 1653 additions and 18 deletions
@ -0,0 +1,32 @@
@@ -0,0 +1,32 @@
|
||||
package common.ecommerce.warehouse.capability; |
||||
|
||||
import common.ecommerce.warehouse.model.TrackingChangeCommand; |
||||
import common.ecommerce.warehouse.model.TrackingChangeOrder; |
||||
import common.ecommerce.warehouse.sdk.WarehouseAdapter; |
||||
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||
|
||||
/** |
||||
* 物流异动单能力:对已交运的运单发起召回 / 换址 / 在途异常处理。 |
||||
* |
||||
* <p>与 {@link TrackingCapable}(查轨迹)是两件事:那个只读,这个会向承运商提工单、 |
||||
* 可能产生费用,所以单独一个能力位 {@code TRACKING_CHANGE}。</p> |
||||
*/ |
||||
public interface TrackingChangeCapable extends WarehouseAdapter { |
||||
|
||||
/** |
||||
* 创建物流异动单。<b>写操作</b>,幂等键 |
||||
* {@code warehouseCode + changeRequestNo + create}。 |
||||
* |
||||
* <p>创建成功只代表「申请已提交」,承运商是否受理要查 |
||||
* {@link TrackingChangeOrder#rawStatus()},不要据此判断货已拦回。</p> |
||||
*/ |
||||
TrackingChangeOrder createChange(WarehouseContext ctx, TrackingChangeCommand cmd); |
||||
|
||||
/** |
||||
* 查询物流异动单。 |
||||
* |
||||
* <p>方法名带 {@code Change} 后缀:避免与 {@code DestructionCapable.getDestruction}、 |
||||
* {@code OutboundCapable.get} 在实现类上撞签名。</p> |
||||
*/ |
||||
TrackingChangeOrder getChange(WarehouseContext ctx, String providerChangeOrderNo); |
||||
} |
||||
@ -0,0 +1,49 @@
@@ -0,0 +1,49 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 物流异动处理类型(底层枚举)。 |
||||
* |
||||
* <p>只表达业务语义:<b>召回</b>(拦回已发出的货)、<b>换址</b>(改派收件人信息)、 |
||||
* <b>在途异常</b>(丢件 / 破损等需要承运商介入)。仓方码值由各适配器映射, |
||||
* core 不认识任何仓的数字。</p> |
||||
* |
||||
* <p>换址必须同时给新收件人三项(姓名 / 电话 / 地址),这项校验在适配器里做—— |
||||
* 不同仓对三项的必填性可能不同。</p> |
||||
*/ |
||||
public enum TrackingChangeHandleType { |
||||
|
||||
/** 召回。 */ |
||||
RECALL(10, "召回"), |
||||
/** 更换地址。 */ |
||||
ADDRESS_CHANGE(20, "更换地址"), |
||||
/** 在途异常。 */ |
||||
IN_TRANSIT_EXCEPTION(30, "在途异常"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
TrackingChangeHandleType(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */ |
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
/** 中文显示名。 */ |
||||
public String label() { |
||||
return label; |
||||
} |
||||
|
||||
/** 按落库码反查;未知返回 null。 */ |
||||
public static TrackingChangeHandleType ofCode(int code) { |
||||
for (TrackingChangeHandleType t : values()) { |
||||
if (t.code == code) { |
||||
return t; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
} |
||||
@ -0,0 +1,141 @@
@@ -0,0 +1,141 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
import common.ecommerce.warehouse.enums.TrackingChangeHandleType; |
||||
|
||||
/** |
||||
* 物流异动单创建命令。<b>写操作</b>,幂等键是 {@link #changeRequestNo()}。 |
||||
* |
||||
* <p>物流异动是<b>对已交运的运单</b>发起处理:召回、换址、在途异常。 |
||||
* 创建成功只代表「异动申请已提交」,承运商是否受理要另外查状态 |
||||
* ({@link TrackingChangeOrder#rawStatus()})。</p> |
||||
* |
||||
* <p>换址({@link TrackingChangeHandleType#ADDRESS_CHANGE})必须提供新收件人三项 |
||||
* (姓名 / 电话 / 地址),这项约束在适配器里校验——不同仓对三项的必填性可能不同。</p> |
||||
*/ |
||||
public final class TrackingChangeCommand { |
||||
|
||||
/** OMS 侧的异动申请号,幂等键。 */ |
||||
private final String changeRequestNo; |
||||
/** 运单跟踪号;必填。 */ |
||||
private final String trackingNumber; |
||||
/** 来源单号(我们下发的出库单号);仓方大多必填。 */ |
||||
private final String orderNo; |
||||
/** 处理类型。 */ |
||||
private final TrackingChangeHandleType handleType; |
||||
private final String remark; |
||||
private final String newRecipientName; |
||||
private final String newRecipientPhone; |
||||
private final String newRecipientAddress; |
||||
|
||||
private TrackingChangeCommand(Builder b) { |
||||
this.changeRequestNo = require(b.changeRequestNo, "changeRequestNo"); |
||||
this.trackingNumber = require(b.trackingNumber, "trackingNumber"); |
||||
this.orderNo = b.orderNo; |
||||
this.handleType = java.util.Objects.requireNonNull(b.handleType, "handleType"); |
||||
this.remark = b.remark; |
||||
this.newRecipientName = b.newRecipientName; |
||||
this.newRecipientPhone = b.newRecipientPhone; |
||||
this.newRecipientAddress = b.newRecipientAddress; |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
/** OMS 侧的异动申请号;幂等键。 */ |
||||
public String changeRequestNo() { |
||||
return changeRequestNo; |
||||
} |
||||
|
||||
public String trackingNumber() { |
||||
return trackingNumber; |
||||
} |
||||
|
||||
/** 来源单号;null 表示不传。 */ |
||||
public String orderNo() { |
||||
return orderNo; |
||||
} |
||||
|
||||
public TrackingChangeHandleType handleType() { |
||||
return handleType; |
||||
} |
||||
|
||||
public String remark() { |
||||
return remark; |
||||
} |
||||
|
||||
public String newRecipientName() { |
||||
return newRecipientName; |
||||
} |
||||
|
||||
public String newRecipientPhone() { |
||||
return newRecipientPhone; |
||||
} |
||||
|
||||
public String newRecipientAddress() { |
||||
return newRecipientAddress; |
||||
} |
||||
|
||||
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 changeRequestNo; |
||||
private String trackingNumber; |
||||
private String orderNo; |
||||
private TrackingChangeHandleType handleType; |
||||
private String remark; |
||||
private String newRecipientName; |
||||
private String newRecipientPhone; |
||||
private String newRecipientAddress; |
||||
|
||||
public Builder changeRequestNo(String v) { |
||||
this.changeRequestNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder trackingNumber(String v) { |
||||
this.trackingNumber = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder orderNo(String v) { |
||||
this.orderNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder handleType(TrackingChangeHandleType v) { |
||||
this.handleType = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder remark(String v) { |
||||
this.remark = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder newRecipientName(String v) { |
||||
this.newRecipientName = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder newRecipientPhone(String v) { |
||||
this.newRecipientPhone = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder newRecipientAddress(String v) { |
||||
this.newRecipientAddress = v; |
||||
return this; |
||||
} |
||||
|
||||
public TrackingChangeCommand build() { |
||||
return new TrackingChangeCommand(this); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,261 @@
@@ -0,0 +1,261 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
import common.ecommerce.warehouse.enums.TrackingChangeHandleType; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
|
||||
/** |
||||
* 物流异动单。 |
||||
* |
||||
* <p>双号:{@link #changeRequestNo()} 是 OMS 侧的异动申请号(幂等键), |
||||
* {@link #providerChangeOrderNo()} 是仓方生成的异动单号(查询 / 取消用它)。</p> |
||||
* |
||||
* <p>{@link #status()} 是 SDK 归一层(单证受理状态),{@link #logisticsStatus()} 是 |
||||
* <b>运单</b>当前的物流状态——两者不是一回事:一张异动单可能「已受理」而运单还在途。</p> |
||||
*/ |
||||
public final class TrackingChangeOrder { |
||||
|
||||
private final String changeRequestNo; |
||||
private final String providerChangeOrderNo; |
||||
private final WarehouseProvider sourceProvider; |
||||
private final String warehouseCode; |
||||
private final String trackingNumber; |
||||
private final String orderNo; |
||||
private final TrackingChangeHandleType handleType; |
||||
|
||||
/** |
||||
* 异动单受理状态的<b>仓方原值</b>。 |
||||
* |
||||
* <p>不归一成枚举:恒健是 0~6 的数字码,运去哪等其它仓的码表完全不同, |
||||
* 归一会丢失「受理失败 / 已取消」这类关键区分。需要判断时看 |
||||
* {@link #accepted()} / {@link #failed()}。</p> |
||||
*/ |
||||
private final String rawStatus; |
||||
/** |
||||
* 运单物流状态的<b>仓方原值</b>。 |
||||
* |
||||
* <p>恒健回 0~9(UNKNOWN / PRE TRANSIT / IN TRANSIT / OUT FOR DELIVERY / |
||||
* DELIVERED / AVAILABLE FOR PICKUP / RETURN TO SENDER / FAILURE / CANCELLED / ERROR), |
||||
* 直接保留原文便于排障。</p> |
||||
*/ |
||||
private final String rawLogisticsStatus; |
||||
|
||||
private final String carrierCode; |
||||
private final String carrierServiceCode; |
||||
private final String errorMessage; |
||||
private final String upstreamNo; |
||||
private final String caseId; |
||||
/** 完成时间(UTC);未完成时为 null。 */ |
||||
private final java.time.Instant completedAt; |
||||
|
||||
private TrackingChangeOrder(Builder b) { |
||||
this.changeRequestNo = require(b.changeRequestNo, "changeRequestNo"); |
||||
this.providerChangeOrderNo = b.providerChangeOrderNo; |
||||
this.sourceProvider = b.sourceProvider; |
||||
this.warehouseCode = b.warehouseCode; |
||||
this.trackingNumber = b.trackingNumber; |
||||
this.orderNo = b.orderNo; |
||||
this.handleType = b.handleType; |
||||
this.rawStatus = b.rawStatus; |
||||
this.rawLogisticsStatus = b.rawLogisticsStatus; |
||||
this.carrierCode = b.carrierCode; |
||||
this.carrierServiceCode = b.carrierServiceCode; |
||||
this.errorMessage = b.errorMessage; |
||||
this.upstreamNo = b.upstreamNo; |
||||
this.caseId = b.caseId; |
||||
this.completedAt = b.completedAt; |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
/** OMS 侧的异动申请号;幂等键。 */ |
||||
public String changeRequestNo() { |
||||
return changeRequestNo; |
||||
} |
||||
|
||||
/** 仓方异动单号;创建响应若不回传则为 null。 */ |
||||
public String providerChangeOrderNo() { |
||||
return providerChangeOrderNo; |
||||
} |
||||
|
||||
public WarehouseProvider sourceProvider() { |
||||
return sourceProvider; |
||||
} |
||||
|
||||
public String warehouseCode() { |
||||
return warehouseCode; |
||||
} |
||||
|
||||
public String trackingNumber() { |
||||
return trackingNumber; |
||||
} |
||||
|
||||
public String orderNo() { |
||||
return orderNo; |
||||
} |
||||
|
||||
public TrackingChangeHandleType handleType() { |
||||
return handleType; |
||||
} |
||||
|
||||
/** 异动单受理状态原值。 */ |
||||
public String rawStatus() { |
||||
return rawStatus; |
||||
} |
||||
|
||||
/** 运单物流状态原值。 */ |
||||
public String rawLogisticsStatus() { |
||||
return rawLogisticsStatus; |
||||
} |
||||
|
||||
public String carrierCode() { |
||||
return carrierCode; |
||||
} |
||||
|
||||
public String carrierServiceCode() { |
||||
return carrierServiceCode; |
||||
} |
||||
|
||||
/** 仓方给出的异常信息;无异常为 null。 */ |
||||
public String errorMessage() { |
||||
return errorMessage; |
||||
} |
||||
|
||||
/** 上游单据号。 */ |
||||
public String upstreamNo() { |
||||
return upstreamNo; |
||||
} |
||||
|
||||
/** 承运商 CASE ID。 */ |
||||
public String caseId() { |
||||
return caseId; |
||||
} |
||||
|
||||
/** 完成时间(UTC);未完成时为 null。 */ |
||||
public java.time.Instant completedAt() { |
||||
return completedAt; |
||||
} |
||||
|
||||
/** 仓方是否已受理;状态原值未给时返回 null(未知,不是「未受理」)。 */ |
||||
public Boolean accepted() { |
||||
if (rawStatus == null) { |
||||
return null; |
||||
} |
||||
return "3".equals(rawStatus.trim()) || "4".equals(rawStatus.trim()); |
||||
} |
||||
|
||||
/** 受理是否失败;状态原值未给时返回 false。 */ |
||||
public boolean failed() { |
||||
return rawStatus != null && "5".equals(rawStatus.trim()); |
||||
} |
||||
|
||||
/** 仓方是否已取消;状态原值未给时返回 false。 */ |
||||
public boolean cancelled() { |
||||
return rawStatus != null && "6".equals(rawStatus.trim()); |
||||
} |
||||
|
||||
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 changeRequestNo; |
||||
private String providerChangeOrderNo; |
||||
private WarehouseProvider sourceProvider; |
||||
private String warehouseCode; |
||||
private String trackingNumber; |
||||
private String orderNo; |
||||
private TrackingChangeHandleType handleType; |
||||
private String rawStatus; |
||||
private String rawLogisticsStatus; |
||||
private String carrierCode; |
||||
private String carrierServiceCode; |
||||
private String errorMessage; |
||||
private String upstreamNo; |
||||
private String caseId; |
||||
private java.time.Instant completedAt; |
||||
|
||||
public Builder changeRequestNo(String v) { |
||||
this.changeRequestNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder providerChangeOrderNo(String v) { |
||||
this.providerChangeOrderNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder sourceProvider(WarehouseProvider v) { |
||||
this.sourceProvider = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder warehouseCode(String v) { |
||||
this.warehouseCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder trackingNumber(String v) { |
||||
this.trackingNumber = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder orderNo(String v) { |
||||
this.orderNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder handleType(TrackingChangeHandleType v) { |
||||
this.handleType = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder rawStatus(String v) { |
||||
this.rawStatus = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder rawLogisticsStatus(String v) { |
||||
this.rawLogisticsStatus = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder carrierCode(String v) { |
||||
this.carrierCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder carrierServiceCode(String v) { |
||||
this.carrierServiceCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder errorMessage(String v) { |
||||
this.errorMessage = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder upstreamNo(String v) { |
||||
this.upstreamNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder caseId(String v) { |
||||
this.caseId = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder completedAt(java.time.Instant v) { |
||||
this.completedAt = v; |
||||
return this; |
||||
} |
||||
|
||||
public TrackingChangeOrder build() { |
||||
return new TrackingChangeOrder(this); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,111 @@
@@ -0,0 +1,111 @@
|
||||
package common.ecommerce.hengjian.adapter; |
||||
|
||||
import common.ecommerce.hengjian.dto.HengjianTrackingChangeQueryDtos; |
||||
import common.ecommerce.warehouse.enums.TrackingChangeHandleType; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.TrackingChangeOrder; |
||||
|
||||
import java.time.Instant; |
||||
import java.time.LocalDateTime; |
||||
import java.time.ZoneOffset; |
||||
import java.time.format.DateTimeFormatter; |
||||
import java.time.format.DateTimeParseException; |
||||
|
||||
/** |
||||
* 恒健物流异动单报文 → 统一模型。 |
||||
* |
||||
* <p>只做字段搬运与码值解读;不猜、不补仓方没给的字段。</p> |
||||
* |
||||
* <h2>两个状态不是一回事</h2> |
||||
* <ul> |
||||
* <li>{@code orderStatus}(0~6):<b>异动单的受理状态</b> → |
||||
* {@link TrackingChangeOrder#rawStatus()};</li> |
||||
* <li>{@code logisticsStatus}(0~9):<b>运单的物流状态</b> → |
||||
* {@link TrackingChangeOrder#rawLogisticsStatus()}。</li> |
||||
* </ul> |
||||
* <p>两者各存各的,不能互相覆盖:一张异动单可能「已受理」而运单还在途, |
||||
* 也可能运单已签收而异动单刚提交。</p> |
||||
*/ |
||||
final class HengjianTrackingChangeMapper { |
||||
|
||||
/** 恒健时间格式(UTC,与其它接口一致)。 */ |
||||
private static final DateTimeFormatter TIME_FORMAT = |
||||
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); |
||||
|
||||
private HengjianTrackingChangeMapper() { |
||||
} |
||||
|
||||
static TrackingChangeOrder toOrder(HengjianTrackingChangeQueryDtos.TrackingChangeDetail detail, |
||||
String warehouseCode, WarehouseProvider provider) { |
||||
String changeNo = trimToNull(detail.trackingChangeOrderNo); |
||||
if (changeNo == null) { |
||||
throw new IllegalArgumentException("hengjian tracking change payload has no trackingChangeOrderNo"); |
||||
} |
||||
return TrackingChangeOrder.builder() |
||||
.changeRequestNo(changeNo) |
||||
.providerChangeOrderNo(changeNo) |
||||
.sourceProvider(provider) |
||||
.warehouseCode(firstNonBlank(detail.orgWarehouseCode, warehouseCode)) |
||||
.trackingNumber(trimToNull(detail.trackingNo)) |
||||
// upstreamNo 是上游单据号;创建时传的 orderNo 会落在 sourceNo 上
|
||||
.orderNo(firstNonBlank(detail.sourceNo, detail.upstreamNo)) |
||||
.handleType(handleTypeOf(detail.handleType)) |
||||
.rawStatus(trimToNull(detail.orderStatus)) |
||||
.rawLogisticsStatus(trimToNull(detail.logisticsStatus)) |
||||
.carrierCode(trimToNull(detail.carrierCode)) |
||||
.carrierServiceCode(trimToNull(detail.carrierServiceCode)) |
||||
.errorMessage(trimToNull(detail.errorMessage)) |
||||
.upstreamNo(trimToNull(detail.upstreamNo)) |
||||
.caseId(trimToNull(detail.caseId)) |
||||
.completedAt(parseTime(detail.completeAt)) |
||||
.build(); |
||||
} |
||||
|
||||
/** 恒健 handleType 1/2/3 → 核心枚举;认不出返回 null,不猜。 */ |
||||
static TrackingChangeHandleType handleTypeOf(String raw) { |
||||
String v = trimToNull(raw); |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
switch (v) { |
||||
case "1": |
||||
return TrackingChangeHandleType.RECALL; |
||||
case "2": |
||||
return TrackingChangeHandleType.ADDRESS_CHANGE; |
||||
case "3": |
||||
return TrackingChangeHandleType.IN_TRANSIT_EXCEPTION; |
||||
default: |
||||
return null; |
||||
} |
||||
} |
||||
|
||||
/** 解析 UTC 时间;格式不符返回 null,不因时间格式阻断整单。 */ |
||||
static Instant parseTime(String value) { |
||||
String v = trimToNull(value); |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
try { |
||||
return LocalDateTime.parse(v, TIME_FORMAT).toInstant(ZoneOffset.UTC); |
||||
} catch (DateTimeParseException e) { |
||||
try { |
||||
return Instant.parse(v); |
||||
} catch (DateTimeParseException ignored) { |
||||
return null; |
||||
} |
||||
} |
||||
} |
||||
|
||||
private static String firstNonBlank(String a, String b) { |
||||
String x = trimToNull(a); |
||||
return x != null ? x : trimToNull(b); |
||||
} |
||||
|
||||
private static String trimToNull(String v) { |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
String t = v.trim(); |
||||
return t.isEmpty() ? null : t; |
||||
} |
||||
} |
||||
@ -0,0 +1,82 @@
@@ -0,0 +1,82 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonInclude; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
/** |
||||
* 恒健报文结构:创建物流异动单({@code POST /v1/trackingChange/create})。 |
||||
* |
||||
* <p><b>文档与实际不符(真机 2026-11-13 验证)</b>:</p> |
||||
* <ul> |
||||
* <li>文档把 {@code orderNo} 标成「否」,真机<b>必填</b>:不给会回 |
||||
* {@code 物流异动单创建失败:来源单号不能为空}。</li> |
||||
* <li>真机还会校验「来源单号和 trackingNo 不匹配」——单号与运单必须属于同一张单。 |
||||
* 所以探针必须用仓里真实存在的一对单号 + 运单号,随便编的会被这一步挡住。</li> |
||||
* <li>换址(2)的三项新收件人信息是真机必填,校验顺序是姓名 → 电话 → 地址。</li> |
||||
* <li>失败统一回 {@code code=999999}(<b>通用失败码</b>,不是认证专用码), |
||||
* 掩盖了具体原因,只看 message。</li> |
||||
* </ul> |
||||
* |
||||
* <p><b>未能确认</b>:{@code handleType} 文档标 STRING、示例给数字 {@code 2}。 |
||||
* 真机用字符串和数字都试过,两种都被接收(都走到后续的业务校验), |
||||
* 所以<b>区分不出</b>类型要求。按示例发 Integer,真机若报类型错改成 String。</p> |
||||
*/ |
||||
public final class HengjianTrackingChangeDtos { |
||||
|
||||
private HengjianTrackingChangeDtos() { |
||||
} |
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class CreateRequest { |
||||
|
||||
/** 运单跟踪号;必填。 */ |
||||
public String trackingNo; |
||||
|
||||
/** 来源单号(我们下发的出库单号);<b>真机必填</b>,文档标「否」不可信。 */ |
||||
public String orderNo; |
||||
|
||||
/** 备注;必填。 */ |
||||
public String remark; |
||||
|
||||
/** |
||||
* 处理类型;必填。 |
||||
* |
||||
* <p>1 召回 / 2 更换地址 / 3 在途异常。文档标 STRING、示例给数字; |
||||
* 真机两种都接受,按示例发数字。</p> |
||||
*/ |
||||
public Integer handleType; |
||||
|
||||
/** 新收件人姓名;{@code handleType=2} 时必填。 */ |
||||
public String newRecipientName; |
||||
|
||||
/** 新收件人电话;{@code handleType=2} 时必填。 */ |
||||
public String newRecipientPhone; |
||||
|
||||
/** 新收件人地址;{@code handleType=2} 时必填。 */ |
||||
public String newRecipientAddress; |
||||
} |
||||
|
||||
/** 创建响应:只回异动单号,没有状态。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class CreateResponse { |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public CreateData data; |
||||
} |
||||
|
||||
/** 创建响应 {@code data}。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class CreateData { |
||||
|
||||
/** 仓方异动单号;查询与取消都用它。 */ |
||||
@JsonProperty("trackingChangeOrderNo") |
||||
public String trackingChangeOrderNo; |
||||
} |
||||
} |
||||
@ -0,0 +1,164 @@
@@ -0,0 +1,164 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonInclude; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
/** |
||||
* 恒健报文结构:物流异动单查询({@code POST /v1/trackingChange/findOrder})。 |
||||
* |
||||
* <p><b>路径纠正(真机 2026-11-13)</b>:文档页写的路径是 {@code /v1/saleOrder/findOrder}, |
||||
* 但该路径真机返回 {@code 404 No handler found};正确路径是 |
||||
* <b>{@code /v1/trackingChange/findOrder}</b>(与 create / cancel 同前缀)。 |
||||
* 这是把 saleOrder 的路径误复制到了 trackingChange 的页面上。</p> |
||||
* |
||||
* <p>请求只收 {@code trackingChangeOrderNo};传 {@code orderNo} 等其它字段会被忽略并回 |
||||
* 「物流异动单号不能为空」。</p> |
||||
*/ |
||||
public final class HengjianTrackingChangeQueryDtos { |
||||
|
||||
private HengjianTrackingChangeQueryDtos() { |
||||
} |
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class FindOrderRequest { |
||||
|
||||
/** 仓方异动单号;必填。 */ |
||||
public String trackingChangeOrderNo; |
||||
} |
||||
|
||||
/** 响应外层。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class FindOrderResponse { |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public TrackingChangeDetail data; |
||||
} |
||||
|
||||
/** |
||||
* 异动单详情。 |
||||
* |
||||
* <p><b>注意</b>:文档给了完整字段表,但真机用无效单号查询时 {@code data} 是缺失的 |
||||
* (成功码 + 只有 message),所以这里的每个字段都可能为 null。</p> |
||||
*/ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class TrackingChangeDetail { |
||||
|
||||
/** 仓方异动单号。 */ |
||||
@JsonProperty("trackingChangeOrderNo") |
||||
public String trackingChangeOrderNo; |
||||
|
||||
/** |
||||
* 单据状态:0 草稿 / 1 待受理 / 2 受理中 / 3 已受理 / 4 受理成功 / 5 受理失败 / 6 取消。 |
||||
* |
||||
* <p>文档标 INTEGER,用 String 接住——Jackson 会把数字转成文本, |
||||
* 万一仓方哪天改成字符串也不会炸。</p> |
||||
*/ |
||||
@JsonProperty("orderStatus") |
||||
public String orderStatus; |
||||
|
||||
/** 异常码:0 无异常 / 1 推送异常。 */ |
||||
@JsonProperty("errorStatus") |
||||
public String errorStatus; |
||||
|
||||
/** 异常信息。 */ |
||||
@JsonProperty("errorMessage") |
||||
public String errorMessage; |
||||
|
||||
/** 上游单据 id。 */ |
||||
@JsonProperty("upstreamId") |
||||
public String upstreamId; |
||||
|
||||
/** 上游单据号。 */ |
||||
@JsonProperty("upstreamNo") |
||||
public String upstreamNo; |
||||
|
||||
/** 跟踪号。 */ |
||||
@JsonProperty("trackingNo") |
||||
public String trackingNo; |
||||
|
||||
/** |
||||
* 物流状态:0 UNKNOWN / 1 PRE TRANSIT / 2 IN TRANSIT / 3 OUT FOR DELIVERY / |
||||
* 4 DELIVERED / 5 AVAILABLE FOR PICKUP / 6 RETURN TO SENDER / 7 FAILURE / |
||||
* 8 CANCELLED / 9 ERROR。 |
||||
*/ |
||||
@JsonProperty("logisticsStatus") |
||||
public String logisticsStatus; |
||||
|
||||
/** 来源 id。 */ |
||||
@JsonProperty("sourceId") |
||||
public String sourceId; |
||||
|
||||
/** 来源单号。 */ |
||||
@JsonProperty("sourceNo") |
||||
public String sourceNo; |
||||
|
||||
/** 来源订单类型。 */ |
||||
@JsonProperty("sourceOrderType") |
||||
public String sourceOrderType; |
||||
|
||||
/** 仓库 id。 */ |
||||
@JsonProperty("orgWarehouseId") |
||||
public String orgWarehouseId; |
||||
|
||||
/** 仓库 code。 */ |
||||
@JsonProperty("orgWarehouseCode") |
||||
public String orgWarehouseCode; |
||||
|
||||
/** 承运商代码。 */ |
||||
@JsonProperty("carrierCode") |
||||
public String carrierCode; |
||||
|
||||
/** 承运商服务代码(发货方式)。 */ |
||||
@JsonProperty("carrierServiceCode") |
||||
public String carrierServiceCode; |
||||
|
||||
/** 处理类型:1 召回 / 2 更换地址 / 3 在途异常。 */ |
||||
@JsonProperty("handleType") |
||||
public String handleType; |
||||
|
||||
@JsonProperty("originalRecipientName") |
||||
public String originalRecipientName; |
||||
@JsonProperty("originalRecipientPhone") |
||||
public String originalRecipientPhone; |
||||
@JsonProperty("originalRecipientAddress") |
||||
public String originalRecipientAddress; |
||||
|
||||
@JsonProperty("newRecipientName") |
||||
public String newRecipientName; |
||||
@JsonProperty("newRecipientPhone") |
||||
public String newRecipientPhone; |
||||
@JsonProperty("newRecipientAddress") |
||||
public String newRecipientAddress; |
||||
|
||||
/** 承运商是否受理:1 否 / 2 是。 */ |
||||
@JsonProperty("carrierIsAcceptance") |
||||
public String carrierIsAcceptance; |
||||
|
||||
/** 承运商 CASE ID。 */ |
||||
@JsonProperty("caseId") |
||||
public String caseId; |
||||
|
||||
/** tracking 标记:0 -- / 1 召回中。 */ |
||||
@JsonProperty("trackingLabel") |
||||
public String trackingLabel; |
||||
|
||||
/** 客户备注。 */ |
||||
@JsonProperty("customerRemark") |
||||
public String customerRemark; |
||||
|
||||
/** 受理备注。 */ |
||||
@JsonProperty("acceptanceRemark") |
||||
public String acceptanceRemark; |
||||
|
||||
/** 完成时间;文档未写格式与单位,按原样保留。 */ |
||||
@JsonProperty("completeAt") |
||||
public String completeAt; |
||||
} |
||||
} |
||||
@ -0,0 +1,333 @@
@@ -0,0 +1,333 @@
|
||||
package common.ecommerce.hengjian.adapter; |
||||
|
||||
import common.ecommerce.hengjian.HengjianConstants; |
||||
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.TrackingChangeHandleType; |
||||
import common.ecommerce.warehouse.enums.WarehouseCapability; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.TrackingChangeCommand; |
||||
import common.ecommerce.warehouse.model.TrackingChangeOrder; |
||||
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 static org.junit.jupiter.api.Assertions.assertEquals; |
||||
import static org.junit.jupiter.api.Assertions.assertFalse; |
||||
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 /v1/trackingChange/create} 与 {@code /v1/trackingChange/findOrder})契约测试。 |
||||
*/ |
||||
class HengjianTrackingChangeTest { |
||||
|
||||
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00:00:00Z"), ZoneOffset.UTC); |
||||
|
||||
private static WarehouseContext ctx() { |
||||
return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA", |
||||
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, |
||||
ChannelSecret.builder().appSecret("token-1").build()), |
||||
"req-1", CLOCK); |
||||
} |
||||
|
||||
private static HengjianAdapter adapter(RecordingTransport transport) { |
||||
return new HengjianAdapter(transport, new JacksonJsonCodec()); |
||||
} |
||||
|
||||
private static TrackingChangeCommand.Builder change() { |
||||
return TrackingChangeCommand.builder() |
||||
.changeRequestNo("TC-1") |
||||
.trackingNumber("1Z999AA10123456784") |
||||
.orderNo("OB-1") |
||||
.remark("客户要求召回") |
||||
.handleType(TrackingChangeHandleType.RECALL); |
||||
} |
||||
|
||||
private static RecordingTransport creating() { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_TRACKING_CHANGE_CREATE, req -> Responses.ok( |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"OK\"," |
||||
+ "\"data\":{\"trackingChangeOrderNo\":\"TC-ORDER-9\"}}")); |
||||
} |
||||
|
||||
// ---------------------------------------------------------------- 创建
|
||||
|
||||
@Test |
||||
void createSendsPostToTrackingChangeCreate() { |
||||
RecordingTransport transport = creating(); |
||||
adapter(transport).createChange(ctx(), change().build()); |
||||
|
||||
assertEquals("POST", transport.lastDataRequest().method()); |
||||
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/trackingChange/create", |
||||
transport.lastDataRequest().url()); |
||||
} |
||||
|
||||
/** 真机确认的四个必填项都要出现。 */ |
||||
@Test |
||||
void createSendsMandatoryFields() { |
||||
RecordingTransport transport = creating(); |
||||
adapter(transport).createChange(ctx(), change().build()); |
||||
String body = transport.lastDataRequest().body(); |
||||
|
||||
String[] mandatory = {"trackingNo", "orderNo", "remark", "handleType"}; |
||||
for (String field : mandatory) { |
||||
assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body); |
||||
} |
||||
assertTrue(body.contains("\"trackingNo\":\"1Z999AA10123456784\""), body); |
||||
assertTrue(body.contains("\"orderNo\":\"OB-1\""), body); |
||||
// 文档标 STRING、示例给数字;按示例发数字
|
||||
assertTrue(body.contains("\"handleType\":1"), body); |
||||
} |
||||
|
||||
/** 换址:三项新收件人信息都要发。 */ |
||||
@Test |
||||
void addressChangeSendsNewRecipientFields() { |
||||
RecordingTransport transport = creating(); |
||||
adapter(transport).createChange(ctx(), change() |
||||
.handleType(TrackingChangeHandleType.ADDRESS_CHANGE) |
||||
.newRecipientName("New Name") |
||||
.newRecipientPhone("5550001111") |
||||
.newRecipientAddress("2 New St") |
||||
.build()); |
||||
String body = transport.lastDataRequest().body(); |
||||
|
||||
assertTrue(body.contains("\"handleType\":2"), body); |
||||
assertTrue(body.contains("\"newRecipientName\":\"New Name\""), body); |
||||
assertTrue(body.contains("\"newRecipientPhone\":\"5550001111\""), body); |
||||
assertTrue(body.contains("\"newRecipientAddress\":\"2 New St\""), body); |
||||
} |
||||
|
||||
/** 召回 / 在途异常不带新收件人字段。 */ |
||||
@Test |
||||
void nonAddressChangeOmitsRecipientFields() { |
||||
RecordingTransport transport = creating(); |
||||
adapter(transport).createChange(ctx(), change() |
||||
.handleType(TrackingChangeHandleType.IN_TRANSIT_EXCEPTION).build()); |
||||
String body = transport.lastDataRequest().body(); |
||||
|
||||
assertTrue(body.contains("\"handleType\":3"), body); |
||||
assertFalse(body.contains("newRecipientName"), body); |
||||
assertFalse(body.contains("newRecipientPhone"), body); |
||||
assertFalse(body.contains("newRecipientAddress"), body); |
||||
} |
||||
|
||||
// ---------------------------------------------------------------- 本地必填校验
|
||||
|
||||
/** orderNo 文档标「否」但真机必填:缺了本地就拒,不发出去被仓方挡回来。 */ |
||||
@Test |
||||
void rejectsMissingOrderNo() { |
||||
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, |
||||
() -> adapter(creating()).createChange(ctx(), change().orderNo(null).build())); |
||||
assertTrue(ex.getMessage().contains("orderNo"), ex.getMessage()); |
||||
} |
||||
|
||||
@Test |
||||
void rejectsMissingRemark() { |
||||
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, |
||||
() -> adapter(creating()).createChange(ctx(), change().remark(null).build())); |
||||
assertTrue(ex.getMessage().contains("remark"), ex.getMessage()); |
||||
} |
||||
|
||||
/** 换址缺新收件人信息:逐个字段报出来,不笼统说「参数错」。 */ |
||||
@Test |
||||
void rejectsAddressChangeWithoutRecipientFields() { |
||||
String[] fields = {"newRecipientName", "newRecipientPhone", "newRecipientAddress"}; |
||||
for (String field : fields) { |
||||
TrackingChangeCommand.Builder b = change() |
||||
.handleType(TrackingChangeHandleType.ADDRESS_CHANGE) |
||||
.newRecipientName("N").newRecipientPhone("P").newRecipientAddress("A"); |
||||
if ("newRecipientName".equals(field)) { |
||||
b.newRecipientName(null); |
||||
} else if ("newRecipientPhone".equals(field)) { |
||||
b.newRecipientPhone(null); |
||||
} else { |
||||
b.newRecipientAddress(null); |
||||
} |
||||
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, |
||||
() -> adapter(creating()).createChange(ctx(), b.build()), field); |
||||
assertTrue(ex.getMessage().contains(field), field + " -> " + ex.getMessage()); |
||||
} |
||||
} |
||||
|
||||
@Test |
||||
void noRequestSentWhenValidationFails() { |
||||
RecordingTransport transport = creating(); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> adapter(transport).createChange(ctx(), change().orderNo(null).build())); |
||||
|
||||
assertTrue(transport.dataRequests().isEmpty()); |
||||
} |
||||
|
||||
/** 构造期就要求 changeRequestNo 与 trackingNumber。 */ |
||||
@Test |
||||
void commandRequiresRequestNoAndTrackingNo() { |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> TrackingChangeCommand.builder() |
||||
.trackingNumber("T1").handleType(TrackingChangeHandleType.RECALL).build()); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> TrackingChangeCommand.builder() |
||||
.changeRequestNo("TC-1").handleType(TrackingChangeHandleType.RECALL).build()); |
||||
assertThrows(NullPointerException.class, |
||||
() -> TrackingChangeCommand.builder() |
||||
.changeRequestNo("TC-1").trackingNumber("T1").build()); |
||||
} |
||||
|
||||
// ---------------------------------------------------------------- 响应
|
||||
|
||||
@Test |
||||
void createReturnsProviderChangeOrderNo() { |
||||
RecordingTransport transport = creating(); |
||||
TrackingChangeOrder order = adapter(transport).createChange(ctx(), change().build()); |
||||
|
||||
assertEquals("TC-1", order.changeRequestNo()); |
||||
assertEquals("TC-ORDER-9", order.providerChangeOrderNo()); |
||||
assertEquals("1Z999AA10123456784", order.trackingNumber()); |
||||
assertEquals(TrackingChangeHandleType.RECALL, order.handleType()); |
||||
assertEquals(WarehouseProvider.HENGJIAN, order.sourceProvider()); |
||||
// 创建接口不回状态:保持 null,不拿请求侧的值冒充
|
||||
assertNull(order.rawStatus()); |
||||
} |
||||
|
||||
/** 没有异动单号不能当成功:后续查询 / 取消都要它。 */ |
||||
@Test |
||||
void rejectsResponseWithoutChangeOrderNo() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_TRACKING_CHANGE_CREATE, req -> Responses.ok( |
||||
"{\"code\":200,\"message\":\"OK\"}")); |
||||
|
||||
RuntimeException ex = assertThrows(RuntimeException.class, |
||||
() -> adapter(transport).createChange(ctx(), change().build())); |
||||
assertTrue(ex.getMessage().contains("trackingChangeOrderNo"), ex.getMessage()); |
||||
} |
||||
|
||||
/** 仓方业务失败(含真机那条「来源单号和trackingNo不匹配」)原样透出。 */ |
||||
@Test |
||||
void businessErrorIsPropagated() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_TRACKING_CHANGE_CREATE, req -> Responses.ok( |
||||
"{\"statusCode\":500,\"status\":1,\"code\":999999," |
||||
+ "\"message\":\"物流异动单创建失败:来源单号和trackingNo不匹配\"}")); |
||||
|
||||
RuntimeException ex = assertThrows(RuntimeException.class, |
||||
() -> adapter(transport).createChange(ctx(), change().build())); |
||||
assertTrue(ex.getMessage().contains("来源单号和trackingNo不匹配"), ex.getMessage()); |
||||
// 通用失败码不能当认证失败
|
||||
assertFalse(ex instanceof common.ecommerce.shared.error.AuthException, |
||||
"999999 是通用失败码,不是认证失败"); |
||||
} |
||||
|
||||
// ---------------------------------------------------------------- 查询
|
||||
|
||||
private static final String QUERY_BODY = |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"OK\",\"data\":{" |
||||
+ "\"trackingChangeOrderNo\":\"TC-ORDER-9\"," |
||||
+ "\"orderStatus\":4," |
||||
+ "\"logisticsStatus\":6," |
||||
+ "\"trackingNo\":\"1Z999AA10123456784\"," |
||||
+ "\"sourceNo\":\"OB-1\"," |
||||
+ "\"orgWarehouseCode\":\"EFCA\"," |
||||
+ "\"carrierCode\":\"UPS\"," |
||||
+ "\"carrierServiceCode\":\"UPSG_HL\"," |
||||
+ "\"handleType\":1," |
||||
+ "\"caseId\":\"CASE-77\"," |
||||
+ "\"completeAt\":\"2026-11-12 10:00:00\"}}"; |
||||
|
||||
private static RecordingTransport querying() { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(QUERY_BODY)); |
||||
} |
||||
|
||||
/** 路径用 trackingChange 前缀,不是文档写的 saleOrder(真机 404)。 */ |
||||
@Test |
||||
void queryUsesCorrectPathFromRealProbe() { |
||||
RecordingTransport transport = querying(); |
||||
adapter(transport).getChange(ctx(), "TC-ORDER-9"); |
||||
|
||||
assertEquals("POST", transport.lastDataRequest().method()); |
||||
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/trackingChange/findOrder", |
||||
transport.lastDataRequest().url()); |
||||
assertEquals("{\"trackingChangeOrderNo\":\"TC-ORDER-9\"}", |
||||
transport.lastDataRequest().body()); |
||||
} |
||||
|
||||
@Test |
||||
void queryMapsStatusFields() { |
||||
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9"); |
||||
|
||||
assertEquals("TC-ORDER-9", order.providerChangeOrderNo()); |
||||
assertEquals("4", order.rawStatus(), "orderStatus 是异动单受理状态"); |
||||
assertEquals("6", order.rawLogisticsStatus(), "logisticsStatus 是运单物流状态"); |
||||
assertEquals(Boolean.TRUE, order.accepted()); |
||||
assertFalse(order.failed()); |
||||
assertFalse(order.cancelled()); |
||||
assertEquals("OB-1", order.orderNo()); |
||||
assertEquals("EFCA", order.warehouseCode()); |
||||
assertEquals("UPS", order.carrierCode()); |
||||
assertEquals("CASE-77", order.caseId()); |
||||
assertEquals(TrackingChangeHandleType.RECALL, order.handleType()); |
||||
assertEquals(Instant.parse("2026-11-12T10:00:00Z"), order.completedAt()); |
||||
} |
||||
|
||||
/** 两个状态各存各的:异动单已受理不代表运单已送达。 */ |
||||
@Test |
||||
void statusAndLogisticsStatusAreIndependent() { |
||||
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9"); |
||||
|
||||
assertTrue(order.accepted(), "异动单已受理"); |
||||
assertEquals("6", order.rawLogisticsStatus(), "运单状态是 RETURN TO SENDER,不是「已送达」"); |
||||
} |
||||
|
||||
@Test |
||||
void failedAndCancelledStatuses() { |
||||
RecordingTransport failed = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok( |
||||
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\"," |
||||
+ "\"orderStatus\":5,\"errorMessage\":\"承运商拒绝\"}}")); |
||||
assertTrue(adapter(failed).getChange(ctx(), "TC-1").failed()); |
||||
|
||||
RecordingTransport cancelled = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok( |
||||
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\"," |
||||
+ "\"orderStatus\":6}}")); |
||||
assertTrue(adapter(cancelled).getChange(ctx(), "TC-1").cancelled()); |
||||
} |
||||
|
||||
@Test |
||||
void queryReturnsNullWhenDataMissing() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok( |
||||
"{\"code\":200,\"message\":\"OK\"}")); |
||||
|
||||
assertNull(adapter(transport).getChange(ctx(), "TC-NONE")); |
||||
} |
||||
|
||||
/** 不认识的 handleType 归 null,不猜。 */ |
||||
@Test |
||||
void unknownHandleTypeIsNotGuessed() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok( |
||||
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\"," |
||||
+ "\"handleType\":9}}")); |
||||
|
||||
assertNull(adapter(transport).getChange(ctx(), "TC-1").handleType()); |
||||
} |
||||
|
||||
// ---------------------------------------------------------------- 能力位
|
||||
|
||||
@Test |
||||
void declaresTrackingChangeCapability() { |
||||
assertTrue(adapter(RecordingTransport.create()).capabilities() |
||||
.contains(WarehouseCapability.TRACKING_CHANGE)); |
||||
// 轨迹查询(TRACKING)是另一件事,恒健没接
|
||||
assertFalse(adapter(RecordingTransport.create()).capabilities() |
||||
.contains(WarehouseCapability.TRACKING)); |
||||
} |
||||
} |
||||
@ -0,0 +1,152 @@
@@ -0,0 +1,152 @@
|
||||
package common.ecommerce.hengjian.probe; |
||||
|
||||
import common.ecommerce.hengjian.HengjianConstants; |
||||
import common.ecommerce.hengjian.adapter.HengjianAdapter; |
||||
import common.ecommerce.http.JacksonJsonCodec; |
||||
import common.ecommerce.http.OkHttpTransport; |
||||
import common.ecommerce.shared.spi.ChannelSecret; |
||||
import common.ecommerce.warehouse.enums.TrackingChangeHandleType; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.TrackingChangeCommand; |
||||
import common.ecommerce.warehouse.model.TrackingChangeOrder; |
||||
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; |
||||
|
||||
/** |
||||
* 恒健物流异动单探针:查询 + 创建。 |
||||
* |
||||
* <pre> |
||||
* mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ |
||||
* -Dhengjian.probe=true -Dhengjian.probe.token=你的组织token \ |
||||
* -Dhengjian.probe.changeOrderNo=仓方异动单号 \ |
||||
* -Dtest=HengjianTrackingChangeProbeTest test |
||||
* </pre> |
||||
* |
||||
* <p><b>查询用例只读</b>,用 {@code -Dhengjian.probe.changeOrderNo}。 |
||||
* <b>创建用例是写操作</b>,另需 {@code -Dhengjian.probe.write=true}, |
||||
* 且必须同时给 {@code -Dhengjian.probe.orderNo} 与 {@code -Dhengjian.probe.trackingNo} |
||||
* 一对<b>仓里真实存在且互相匹配</b>的单号——仓方会校验「来源单号和 trackingNo 不匹配」, |
||||
* 编造的会被这一步挡住。</p> |
||||
* |
||||
* <p>真机已验证(2026-11-13,无 token):</p> |
||||
* <ul> |
||||
* <li>查询路径是 {@code /v1/trackingChange/findOrder}, |
||||
* 文档写的 {@code /v1/saleOrder/findOrder} 返回 404;</li> |
||||
* <li>创建的四项必填是 {@code trackingNo / orderNo / remark / handleType}, |
||||
* 其中 {@code orderNo} 文档标「否」,实际必填。</li> |
||||
* </ul> |
||||
*/ |
||||
class HengjianTrackingChangeProbeTest { |
||||
|
||||
private static final String PROBE = "hengjian.probe"; |
||||
private static final String PROBE_WRITE = "hengjian.probe.write"; |
||||
|
||||
private static final String TOKEN = System.getProperty("hengjian.probe.token", ""); |
||||
private static final String BASE_URL = opt("hengjian.probe.baseUrl", HengjianConstants.TEST_BASE_URL); |
||||
private static final String WAREHOUSE_CODE = opt("hengjian.probe.warehouseCode", "HJ-PROBE"); |
||||
private static final String PROVIDER_WAREHOUSE = opt("hengjian.probe.providerWarehouseId", "EFCA"); |
||||
|
||||
private static String opt(String key, String fallback) { |
||||
String v = System.getProperty(key); |
||||
return v == null || v.trim().isEmpty() ? fallback : v.trim(); |
||||
} |
||||
|
||||
private static WarehouseContext ctx() { |
||||
return WarehouseContext.of(WAREHOUSE_CODE, WarehouseProvider.HENGJIAN, PROVIDER_WAREHOUSE, |
||||
WarehouseConnection.of(BASE_URL, |
||||
ChannelSecret.builder().appSecret(TOKEN.trim()).build()), |
||||
"probe-" + System.currentTimeMillis(), Clock.systemUTC()); |
||||
} |
||||
|
||||
private static HengjianAdapter adapter() { |
||||
return new HengjianAdapter(new OkHttpTransport("common-ecommerce-hengjian-probe"), |
||||
new JacksonJsonCodec()); |
||||
} |
||||
|
||||
private static void assumeToken() { |
||||
Assumptions.assumeTrue(!TOKEN.trim().isEmpty(), |
||||
"未提供 -Dhengjian.probe.token,跳过恒健异动单探针"); |
||||
} |
||||
|
||||
/** 查询异动单:验证文档路径是错的、正确路径能通。 */ |
||||
@Test |
||||
@EnabledIfSystemProperty(named = PROBE, matches = "true") |
||||
void probeFindTrackingChange() { |
||||
assumeToken(); |
||||
String changeNo = opt("hengjian.probe.changeOrderNo", ""); |
||||
Assumptions.assumeTrue(!changeNo.isEmpty(), |
||||
"未提供 -Dhengjian.probe.changeOrderNo,跳过异动单查询探针"); |
||||
System.out.println("\n================ hengjian / v1/trackingChange/findOrder ================"); |
||||
System.out.println(" trackingChangeOrderNo=" + changeNo); |
||||
try { |
||||
TrackingChangeOrder order = adapter().getChange(ctx(), changeNo); |
||||
if (order == null) { |
||||
System.out.println(" [空] 未找到该异动单(data 缺失)"); |
||||
return; |
||||
} |
||||
System.out.println(" [OK] orderStatus=" + order.rawStatus() |
||||
+ " logisticsStatus=" + order.rawLogisticsStatus() |
||||
+ " accepted=" + order.accepted() |
||||
+ " failed=" + order.failed() |
||||
+ " handleType=" + order.handleType() |
||||
+ " trackingNo=" + order.trackingNumber() |
||||
+ " caseId=" + order.caseId() |
||||
+ " completeAt=" + order.completedAt()); |
||||
} catch (RuntimeException e) { |
||||
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage()); |
||||
} |
||||
} |
||||
|
||||
/** |
||||
* 创建异动单:<b>写操作</b>,会向承运商真实提工单。 |
||||
* |
||||
* <p>需要一对真实匹配的单号 + 运单号,否则仓方回「来源单号和trackingNo不匹配」。</p> |
||||
*/ |
||||
@Test |
||||
@EnabledIfSystemProperty(named = PROBE_WRITE, matches = "true") |
||||
void probeCreateTrackingChange() { |
||||
assumeToken(); |
||||
String orderNo = opt("hengjian.probe.orderNo", ""); |
||||
String trackingNo = opt("hengjian.probe.trackingNo", ""); |
||||
Assumptions.assumeTrue(!orderNo.isEmpty() && !trackingNo.isEmpty(), |
||||
"未提供 -Dhengjian.probe.orderNo / trackingNo,跳过异动单创建探针"); |
||||
TrackingChangeHandleType type = handleTypeOf(opt("hengjian.probe.handleType", "RECALL")); |
||||
|
||||
System.out.println("\n================ hengjian / v1/trackingChange/create ================"); |
||||
System.out.println(" orderNo=" + orderNo + " trackingNo=" + trackingNo |
||||
+ " handleType=" + type); |
||||
try { |
||||
TrackingChangeOrder order = adapter().createChange(ctx(), |
||||
TrackingChangeCommand.builder() |
||||
.changeRequestNo("PROBE-TC-" + System.currentTimeMillis()) |
||||
.trackingNumber(trackingNo) |
||||
.orderNo(orderNo) |
||||
.remark("SDK 探针,可忽略") |
||||
.handleType(type) |
||||
// 换址时必须给三项;其它类型会被适配器忽略
|
||||
.newRecipientName(opt("hengjian.probe.newRecipientName", "")) |
||||
.newRecipientPhone(opt("hengjian.probe.newRecipientPhone", "")) |
||||
.newRecipientAddress(opt("hengjian.probe.newRecipientAddress", "")) |
||||
.build()); |
||||
System.out.println(" [OK] trackingChangeOrderNo=" + order.providerChangeOrderNo()); |
||||
System.out.println(" ← 创建只代表申请已提交,受理结果要再查一次 findOrder"); |
||||
} catch (RuntimeException e) { |
||||
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage()); |
||||
} |
||||
} |
||||
|
||||
private static TrackingChangeHandleType handleTypeOf(String raw) { |
||||
if ("ADDRESS_CHANGE".equalsIgnoreCase(raw) || "2".equals(raw)) { |
||||
return TrackingChangeHandleType.ADDRESS_CHANGE; |
||||
} |
||||
if ("IN_TRANSIT_EXCEPTION".equalsIgnoreCase(raw) || "3".equals(raw)) { |
||||
return TrackingChangeHandleType.IN_TRANSIT_EXCEPTION; |
||||
} |
||||
return TrackingChangeHandleType.RECALL; |
||||
} |
||||
} |
||||
Loading…
Reference in new issue