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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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