Browse Source

fix(hengjian): 异动单查询补齐未映射字段,并修正 changeRequestNo 语义

服务端字段原先只映射了一部分,排障要看的几组被丢掉了:

- 来源三维各存各的:sourceId / sourceNo / sourceOrderType,
  orderNo 取 sourceNo(我们下发的单号落在那里),upstreamNo 不再合并进来
  ——合并就分不清哪一层出的问题
- 收件人对照:originalRecipient* / newRecipient* 三项都保留,
  换址场景要能看到「原 → 新」
- carrierIsAcceptance 补齐并加 carrierAccepted():恒健是 1 否 / 2 是,
  不是 0/1;缺失或非法值返回 null(未知),不猜
- trackingLabel 补齐并加 recalling()(1 召回中)
- errorStatus 与 errorMessage 分开保留:码用于判断、文本用于展示
- customerRemark / acceptanceRemark 两个字段不合并

修正 changeRequestNo 语义:查询响应里仓方不回 OMS 申请号,
原先把它填成仓单号,会让调用方误以为两者相等。现改为查询结果为 null,
创建结果仍填(那才是真的 OMS 单号)。字段改为允许 null。

验证:mvn test 全量通过,恒健 313 个用例(+8)通过。

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 3 days ago
parent
commit
1325314957
  1. 18
      docs-warehouse/hengjian/README.md
  2. 277
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeOrder.java
  3. 30
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeMapper.java
  4. 109
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeTest.java

18
docs-warehouse/hengjian/README.md

@ -254,6 +254,20 @@
两者各存各的:一张异动单可能「已受理」而运单还在途,不能互相覆盖。 两者各存各的:一张异动单可能「已受理」而运单还在途,不能互相覆盖。
`accepted()` / `failed()` / `cancelled()` 是按 `orderStatus` 的便捷判断。 `accepted()` / `failed()` / `cancelled()` 是按 `orderStatus` 的便捷判断。
**查询响应的字段全部保留**(原先是只映射了一部分):
| 分组 | 字段 | 落点 |
|---|---|---|
| 来源三维 | `sourceId` / `sourceNo` / `sourceOrderType` | 各自独立,`sourceNo` 同时作为 `orderNo` |
| 收件人对照 | `originalRecipient*` / `newRecipient*` | 换址场景要能看到「原 → 新」 |
| 承运商受理 | `carrierIsAcceptance`(**1 否 / 2 是**,不是 0/1) | `carrierAccepted()` 取布尔,缺失或非法值返回 null |
| 召回标记 | `trackingLabel`(0 无 / 1 召回中) | `recalling()` |
| 异常 | `errorStatus` / `errorMessage` | 码与文本分开保留 |
| 备注 | `customerRemark` / `acceptanceRemark` | 两个字段不合并 |
**`changeRequestNo` 在查询结果里为 null**:仓方响应没有这个号,
不拿仓单号顶替——填同一个值会让调用方误以为 OMS 单号等于仓单号。
**未能确认**:`handleType` 文档标 STRING、示例给数字。真机字符串和数字都试过, **未能确认**:`handleType` 文档标 STRING、示例给数字。真机字符串和数字都试过,
两种都能过(都走到后续业务校验),**区分不出**类型要求,按示例发 Integer。 两种都能过(都走到后续业务校验),**区分不出**类型要求,按示例发 Integer。
@ -838,7 +852,7 @@ warehouse-sdk-hengjian/
├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝 ├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝
├── adapter/HengjianOrderQueryTest.java 29 个:详情映射 / 分页 / 排序可配 / 时间窗 / 包裹去重 ├── adapter/HengjianOrderQueryTest.java 29 个:详情映射 / 分页 / 排序可配 / 时间窗 / 包裹去重
├── adapter/HengjianCancelOrderTest.java 10 个:双键补齐 / 精确匹配 / 拒绝路径 / 预判 ├── adapter/HengjianCancelOrderTest.java 10 个:双键补齐 / 精确匹配 / 拒绝路径 / 预判
├── adapter/HengjianTrackingChangeTest.java 19 个:必填拒绝 / 换址三项 / 路径 / 双状态 ├── adapter/HengjianTrackingChangeTest.java 27 个:必填 / 路径 / 双状态 / 收件人对照 / 承运商受理
├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过 ├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过
├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射 ├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射
├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射 ├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射
@ -854,7 +868,7 @@ warehouse-sdk-hengjian/
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true └── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true
``` ```
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(305 个 + 4 个跳过)。 已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(313 个 + 4 个跳过)。
## 5. 探针用法 ## 5. 探针用法

277
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeOrder.java

@ -9,16 +9,22 @@ import common.ecommerce.warehouse.enums.WarehouseProvider;
* <p>双号:{@link #changeRequestNo()} 是 OMS 侧的异动申请号(幂等键), * <p>双号:{@link #changeRequestNo()} 是 OMS 侧的异动申请号(幂等键),
* {@link #providerChangeOrderNo()} 是仓方生成的异动单号(查询 / 取消用它)。</p> * {@link #providerChangeOrderNo()} 是仓方生成的异动单号(查询 / 取消用它)。</p>
* *
* <p>{@link #status()} 是 SDK 归一层(单证受理状态),{@link #logisticsStatus()} 是 * <p><b>查询结果拿不到 {@code changeRequestNo}</b>:仓方响应里没有这个号,
* 所以从 {@code getChange()} 回来的对象该字段为 <b>null</b>。不要拿仓单号去填它——
* 两者含义不同,填同一个值会让调用方误以为 OMS 单号等于仓单号。</p>
*
* <p>{@link #rawStatus()} 是异动单的<b>受理状态</b>,{@link #rawLogisticsStatus()} 是
* <b>运单</b>当前的物流状态——两者不是一回事:一张异动单可能「已受理」而运单还在途。</p> * <b>运单</b>当前的物流状态——两者不是一回事:一张异动单可能「已受理」而运单还在途。</p>
*/ */
public final class TrackingChangeOrder { public final class TrackingChangeOrder {
/** OMS 侧的异动申请号;查询结果里为 null(仓方不回这个号)。 */
private final String changeRequestNo; private final String changeRequestNo;
private final String providerChangeOrderNo; private final String providerChangeOrderNo;
private final WarehouseProvider sourceProvider; private final WarehouseProvider sourceProvider;
private final String warehouseCode; private final String warehouseCode;
private final String trackingNumber; private final String trackingNumber;
/** 来源单号(我们下发的出库单号);仓方未给为 null。 */
private final String orderNo; private final String orderNo;
private final TrackingChangeHandleType handleType; private final TrackingChangeHandleType handleType;
@ -27,7 +33,7 @@ public final class TrackingChangeOrder {
* *
* <p>不归一成枚举:恒健是 0~6 的数字码,运去哪等其它仓的码表完全不同, * <p>不归一成枚举:恒健是 0~6 的数字码,运去哪等其它仓的码表完全不同,
* 归一会丢失「受理失败 / 已取消」这类关键区分。需要判断时看 * 归一会丢失「受理失败 / 已取消」这类关键区分。需要判断时看
* {@link #accepted()} / {@link #failed()}。</p> * {@link #accepted()} / {@link #failed()} / {@link #cancelled()}。</p>
*/ */
private final String rawStatus; private final String rawStatus;
/** /**
@ -41,14 +47,68 @@ public final class TrackingChangeOrder {
private final String carrierCode; private final String carrierCode;
private final String carrierServiceCode; private final String carrierServiceCode;
/** 仓方原始异常信息文本;无异常为 null。 */
private final String errorMessage; private final String errorMessage;
/**
* 异常码的<b>仓方原值</b>;无异常为 null。
*
* <p>恒健 {@code errorStatus}:0 无异常 / 1 推送异常。
* 与 {@link #errorMessage()} 分开:码用于判断,文本用于展示。</p>
*/
private final String errorCode;
private final String upstreamNo; private final String upstreamNo;
private final String caseId; private final String caseId;
/** 完成时间(UTC);未完成时为 null。 */ /** 完成时间(UTC);未完成时为 null。 */
private final java.time.Instant completedAt; private final java.time.Instant completedAt;
// ==================== 来源维度(仓方原值)====================
/**
* 来源维度。
*
* <p>恒健 {@code sourceId} / {@code sourceNo} / {@code sourceOrderType}。
* {@code sourceNo} 与 {@link #orderNo()} 是<b>两个</b>字段:恒健创建时我们传的
* {@code orderNo} 落在仓方 {@code sourceNo} 上,但响应里还可能另有 {@code upstreamNo}
* (上游单据号)。三者都保留,不做合并——合并后就分不清哪一层出的错。</p>
*/
private final String sourceId;
private final String sourceNo;
private final String sourceOrderType;
// ==================== 收件人对照(换址场景的核心)====================
/** 原收件人姓名;仓方未给为 null。 */
private final String originalRecipientName;
private final String originalRecipientPhone;
private final String originalRecipientAddress;
/** 新收件人姓名(换址场景);未换址为 null。 */
private final String newRecipientName;
private final String newRecipientPhone;
private final String newRecipientAddress;
/**
* 承运商是否受理的<b>仓方原值</b>;仓方未给为 null。
*
* <p>恒健 {@code carrierIsAcceptance}:1 否 / 2 是。<b>不是 0/1</b>——
* 按 0 判断会把「否」误读成未给。用 {@link #carrierAccepted()} 取布尔。</p>
*/
private final String carrierIsAcceptance;
/**
* tracking 标记的<b>仓方原值</b>;仓方未给为 null。
*
* <p>恒健 {@code trackingLabel}:0 无 / 1 召回中。</p>
*/
private final String trackingLabel;
/** 客户备注;仓方未给为 null。 */
private final String customerRemark;
/** 受理备注;仓方未给为 null。 */
private final String acceptanceRemark;
private TrackingChangeOrder(Builder b) { private TrackingChangeOrder(Builder b) {
this.changeRequestNo = require(b.changeRequestNo, "changeRequestNo"); // changeRequestNo 允许为 null:查询结果里仓方不回这个号
this.changeRequestNo = b.changeRequestNo;
this.providerChangeOrderNo = b.providerChangeOrderNo; this.providerChangeOrderNo = b.providerChangeOrderNo;
this.sourceProvider = b.sourceProvider; this.sourceProvider = b.sourceProvider;
this.warehouseCode = b.warehouseCode; this.warehouseCode = b.warehouseCode;
@ -60,16 +120,34 @@ public final class TrackingChangeOrder {
this.carrierCode = b.carrierCode; this.carrierCode = b.carrierCode;
this.carrierServiceCode = b.carrierServiceCode; this.carrierServiceCode = b.carrierServiceCode;
this.errorMessage = b.errorMessage; this.errorMessage = b.errorMessage;
this.errorCode = b.errorCode;
this.upstreamNo = b.upstreamNo; this.upstreamNo = b.upstreamNo;
this.caseId = b.caseId; this.caseId = b.caseId;
this.completedAt = b.completedAt; this.completedAt = b.completedAt;
this.sourceId = b.sourceId;
this.sourceNo = b.sourceNo;
this.sourceOrderType = b.sourceOrderType;
this.originalRecipientName = b.originalRecipientName;
this.originalRecipientPhone = b.originalRecipientPhone;
this.originalRecipientAddress = b.originalRecipientAddress;
this.newRecipientName = b.newRecipientName;
this.newRecipientPhone = b.newRecipientPhone;
this.newRecipientAddress = b.newRecipientAddress;
this.carrierIsAcceptance = b.carrierIsAcceptance;
this.trackingLabel = b.trackingLabel;
this.customerRemark = b.customerRemark;
this.acceptanceRemark = b.acceptanceRemark;
} }
public static Builder builder() { public static Builder builder() {
return new Builder(); return new Builder();
} }
/** OMS 侧的异动申请号;幂等键。 */ /**
* OMS 侧的异动申请号;幂等键。
*
* <p><b>查询结果为 null</b>:仓方响应里没有这个号。创建结果里有值。</p>
*/
public String changeRequestNo() { public String changeRequestNo() {
return changeRequestNo; return changeRequestNo;
} }
@ -91,6 +169,7 @@ public final class TrackingChangeOrder {
return trackingNumber; return trackingNumber;
} }
/** 来源单号(我们下发的出库单号);仓方未给为 null。 */
public String orderNo() { public String orderNo() {
return orderNo; return orderNo;
} }
@ -122,6 +201,11 @@ public final class TrackingChangeOrder {
return errorMessage; return errorMessage;
} }
/** 异常码原值;无异常为 null。 */
public String errorCode() {
return errorCode;
}
/** 上游单据号。 */ /** 上游单据号。 */
public String upstreamNo() { public String upstreamNo() {
return upstreamNo; return upstreamNo;
@ -137,6 +221,94 @@ public final class TrackingChangeOrder {
return completedAt; return completedAt;
} }
/** 来源 id 原值;仓方未给为 null。 */
public String sourceId() {
return sourceId;
}
/** 来源单号原值;仓方未给为 null。 */
public String sourceNo() {
return sourceNo;
}
/** 来源订单类型原值;仓方未给为 null。 */
public String sourceOrderType() {
return sourceOrderType;
}
/** 原收件人姓名;未给为 null。 */
public String originalRecipientName() {
return originalRecipientName;
}
public String originalRecipientPhone() {
return originalRecipientPhone;
}
public String originalRecipientAddress() {
return originalRecipientAddress;
}
/** 新收件人姓名(换址场景);未换址为 null。 */
public String newRecipientName() {
return newRecipientName;
}
public String newRecipientPhone() {
return newRecipientPhone;
}
public String newRecipientAddress() {
return newRecipientAddress;
}
/** 承运商是否受理的原值(1 否 / 2 是);未给为 null。 */
public String carrierIsAcceptance() {
return carrierIsAcceptance;
}
/**
* 承运商是否受理;未给返回 null(未知,不是「未受理」)。
*
* <p>恒健的取值是 <b>1 否 / 2 是</b>,不是 0/1。</p>
*/
public Boolean carrierAccepted() {
if (carrierIsAcceptance == null) {
return null;
}
String v = carrierIsAcceptance.trim();
if ("2".equals(v)) {
return Boolean.TRUE;
}
if ("1".equals(v)) {
return Boolean.FALSE;
}
return null;
}
/** tracking 标记原值(0 无 / 1 召回中);未给为 null。 */
public String trackingLabel() {
return trackingLabel;
}
/** 是否召回中;未给返回 null。 */
public Boolean recalling() {
if (trackingLabel == null) {
return null;
}
return "1".equals(trackingLabel.trim());
}
/** 客户备注。 */
public String customerRemark() {
return customerRemark;
}
/** 受理备注。 */
public String acceptanceRemark() {
return acceptanceRemark;
}
/** 仓方是否已受理;状态原值未给时返回 null(未知,不是「未受理」)。 */ /** 仓方是否已受理;状态原值未给时返回 null(未知,不是「未受理」)。 */
public Boolean accepted() { public Boolean accepted() {
if (rawStatus == null) { if (rawStatus == null) {
@ -155,13 +327,6 @@ public final class TrackingChangeOrder {
return rawStatus != null && "6".equals(rawStatus.trim()); 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 { public static final class Builder {
private String changeRequestNo; private String changeRequestNo;
private String providerChangeOrderNo; private String providerChangeOrderNo;
@ -175,10 +340,25 @@ public final class TrackingChangeOrder {
private String carrierCode; private String carrierCode;
private String carrierServiceCode; private String carrierServiceCode;
private String errorMessage; private String errorMessage;
private String errorCode;
private String upstreamNo; private String upstreamNo;
private String caseId; private String caseId;
private java.time.Instant completedAt; private java.time.Instant completedAt;
private String sourceId;
private String sourceNo;
private String sourceOrderType;
private String originalRecipientName;
private String originalRecipientPhone;
private String originalRecipientAddress;
private String newRecipientName;
private String newRecipientPhone;
private String newRecipientAddress;
private String carrierIsAcceptance;
private String trackingLabel;
private String customerRemark;
private String acceptanceRemark;
/** OMS 侧的异动申请号;查询结果不要填(仓方不回这个号)。 */
public Builder changeRequestNo(String v) { public Builder changeRequestNo(String v) {
this.changeRequestNo = v; this.changeRequestNo = v;
return this; return this;
@ -239,6 +419,12 @@ public final class TrackingChangeOrder {
return this; return this;
} }
/** 异常码原值。 */
public Builder errorCode(String v) {
this.errorCode = v;
return this;
}
public Builder upstreamNo(String v) { public Builder upstreamNo(String v) {
this.upstreamNo = v; this.upstreamNo = v;
return this; return this;
@ -254,6 +440,73 @@ public final class TrackingChangeOrder {
return this; return this;
} }
public Builder sourceId(String v) {
this.sourceId = v;
return this;
}
public Builder sourceNo(String v) {
this.sourceNo = v;
return this;
}
public Builder sourceOrderType(String v) {
this.sourceOrderType = v;
return this;
}
public Builder originalRecipientName(String v) {
this.originalRecipientName = v;
return this;
}
public Builder originalRecipientPhone(String v) {
this.originalRecipientPhone = v;
return this;
}
public Builder originalRecipientAddress(String v) {
this.originalRecipientAddress = 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;
}
/** 承运商是否受理原值(1 否 / 2 是)。 */
public Builder carrierIsAcceptance(String v) {
this.carrierIsAcceptance = v;
return this;
}
/** tracking 标记原值(0 无 / 1 召回中)。 */
public Builder trackingLabel(String v) {
this.trackingLabel = v;
return this;
}
public Builder customerRemark(String v) {
this.customerRemark = v;
return this;
}
public Builder acceptanceRemark(String v) {
this.acceptanceRemark = v;
return this;
}
public TrackingChangeOrder build() { public TrackingChangeOrder build() {
return new TrackingChangeOrder(this); return new TrackingChangeOrder(this);
} }

30
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeMapper.java

@ -25,6 +25,10 @@ import java.time.format.DateTimeParseException;
* </ul> * </ul>
* <p>两者各存各的,不能互相覆盖:一张异动单可能「已受理」而运单还在途, * <p>两者各存各的,不能互相覆盖:一张异动单可能「已受理」而运单还在途,
* 也可能运单已签收而异动单刚提交。</p> * 也可能运单已签收而异动单刚提交。</p>
*
* <h2>{@code changeRequestNo} 故意不填</h2>
* <p>查询响应里没有 OMS 侧的申请号,所以结果里该字段为 <b>null</b>。
* 不拿仓单号顶替——填同一个值会让调用方误以为两者相等。</p>
*/ */
final class HengjianTrackingChangeMapper { final class HengjianTrackingChangeMapper {
@ -42,20 +46,38 @@ final class HengjianTrackingChangeMapper {
throw new IllegalArgumentException("hengjian tracking change payload has no trackingChangeOrderNo"); throw new IllegalArgumentException("hengjian tracking change payload has no trackingChangeOrderNo");
} }
return TrackingChangeOrder.builder() return TrackingChangeOrder.builder()
.changeRequestNo(changeNo) // changeRequestNo 不填:仓方响应没有这个号,不拿仓单号顶替
.providerChangeOrderNo(changeNo) .providerChangeOrderNo(changeNo)
.sourceProvider(provider) .sourceProvider(provider)
.warehouseCode(firstNonBlank(detail.orgWarehouseCode, warehouseCode)) .warehouseCode(firstNonBlank(detail.orgWarehouseCode, warehouseCode))
.trackingNumber(trimToNull(detail.trackingNo)) .trackingNumber(trimToNull(detail.trackingNo))
// upstreamNo 是上游单据号;创建时传的 orderNo 会落在 sourceNo 上 // 来源三维各存各的:sourceNo 是我们下发的 orderNo 落点,
.orderNo(firstNonBlank(detail.sourceNo, detail.upstreamNo)) // upstreamNo 是上游单据号,合并就分不清哪一层出问题
.orderNo(trimToNull(detail.sourceNo))
.sourceId(trimToNull(detail.sourceId))
.sourceNo(trimToNull(detail.sourceNo))
.sourceOrderType(trimToNull(detail.sourceOrderType))
.upstreamNo(trimToNull(detail.upstreamNo))
.handleType(handleTypeOf(detail.handleType)) .handleType(handleTypeOf(detail.handleType))
.rawStatus(trimToNull(detail.orderStatus)) .rawStatus(trimToNull(detail.orderStatus))
.rawLogisticsStatus(trimToNull(detail.logisticsStatus)) .rawLogisticsStatus(trimToNull(detail.logisticsStatus))
.carrierCode(trimToNull(detail.carrierCode)) .carrierCode(trimToNull(detail.carrierCode))
.carrierServiceCode(trimToNull(detail.carrierServiceCode)) .carrierServiceCode(trimToNull(detail.carrierServiceCode))
// 异常码与异常文本分开:码用于判断、文本用于展示
.errorCode(trimToNull(detail.errorStatus))
.errorMessage(trimToNull(detail.errorMessage)) .errorMessage(trimToNull(detail.errorMessage))
.upstreamNo(trimToNull(detail.upstreamNo)) // 收件人对照:换址场景要能看到「原 → 新」
.originalRecipientName(trimToNull(detail.originalRecipientName))
.originalRecipientPhone(trimToNull(detail.originalRecipientPhone))
.originalRecipientAddress(trimToNull(detail.originalRecipientAddress))
.newRecipientName(trimToNull(detail.newRecipientName))
.newRecipientPhone(trimToNull(detail.newRecipientPhone))
.newRecipientAddress(trimToNull(detail.newRecipientAddress))
// 承运商受理(1 否 / 2 是)与召回标记(0 无 / 1 召回中)
.carrierIsAcceptance(trimToNull(detail.carrierIsAcceptance))
.trackingLabel(trimToNull(detail.trackingLabel))
.customerRemark(trimToNull(detail.customerRemark))
.acceptanceRemark(trimToNull(detail.acceptanceRemark))
.caseId(trimToNull(detail.caseId)) .caseId(trimToNull(detail.caseId))
.completedAt(parseTime(detail.completeAt)) .completedAt(parseTime(detail.completeAt))
.build(); .build();

109
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeTest.java

@ -236,8 +236,23 @@ class HengjianTrackingChangeTest {
+ "\"orgWarehouseCode\":\"EFCA\"," + "\"orgWarehouseCode\":\"EFCA\","
+ "\"carrierCode\":\"UPS\"," + "\"carrierCode\":\"UPS\","
+ "\"carrierServiceCode\":\"UPSG_HL\"," + "\"carrierServiceCode\":\"UPSG_HL\","
+ "\"handleType\":1," + "\"handleType\":2,"
+ "\"caseId\":\"CASE-77\"," + "\"caseId\":\"CASE-77\","
+ "\"sourceId\":\"88001\","
+ "\"sourceOrderType\":\"3\","
+ "\"upstreamNo\":\"UP-9\","
+ "\"originalRecipientName\":\"张三\","
+ "\"originalRecipientPhone\":\"555-0001\","
+ "\"originalRecipientAddress\":\"1 Old St\","
+ "\"newRecipientName\":\"李四\","
+ "\"newRecipientPhone\":\"555-0002\","
+ "\"newRecipientAddress\":\"2 New St\","
+ "\"carrierIsAcceptance\":2,"
+ "\"trackingLabel\":1,"
+ "\"customerRemark\":\"客户要求改址\","
+ "\"acceptanceRemark\":\"已受理\","
+ "\"errorStatus\":1,"
+ "\"errorMessage\":\"推送异常\","
+ "\"completeAt\":\"2026-11-12 10:00:00\"}}"; + "\"completeAt\":\"2026-11-12 10:00:00\"}}";
private static RecordingTransport querying() { private static RecordingTransport querying() {
@ -272,10 +287,100 @@ class HengjianTrackingChangeTest {
assertEquals("EFCA", order.warehouseCode()); assertEquals("EFCA", order.warehouseCode());
assertEquals("UPS", order.carrierCode()); assertEquals("UPS", order.carrierCode());
assertEquals("CASE-77", order.caseId()); assertEquals("CASE-77", order.caseId());
assertEquals(TrackingChangeHandleType.RECALL, order.handleType()); assertEquals(TrackingChangeHandleType.ADDRESS_CHANGE, order.handleType());
assertEquals(Instant.parse("2026-11-12T10:00:00Z"), order.completedAt()); assertEquals(Instant.parse("2026-11-12T10:00:00Z"), order.completedAt());
} }
/** 查询结果拿不到 OMS 申请号:保持 null,不拿仓单号顶替。 */
@Test
void queryDoesNotFakeChangeRequestNo() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertNull(order.changeRequestNo(), "仓方不回 OMS 申请号,不能用仓单号冒充");
assertEquals("TC-ORDER-9", order.providerChangeOrderNo());
}
/** 来源三维各存各的:sourceNo / sourceId / sourceOrderType 与 upstreamNo 分开。 */
@Test
void keepsSourceDimensionsSeparate() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertEquals("OB-1", order.sourceNo());
assertEquals("OB-1", order.orderNo(), "orderNo 取 sourceNo(我们下发的单号落在这里)");
assertEquals("88001", order.sourceId());
assertEquals("3", order.sourceOrderType());
assertEquals("UP-9", order.upstreamNo(), "上游单据号单独保留,不合并进 sourceNo");
}
/** 换址场景要能看到「原 → 新」对照。 */
@Test
void mapsRecipientChangeForBothSides() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertEquals("张三", order.originalRecipientName());
assertEquals("555-0001", order.originalRecipientPhone());
assertEquals("1 Old St", order.originalRecipientAddress());
assertEquals("李四", order.newRecipientName());
assertEquals("555-0002", order.newRecipientPhone());
assertEquals("2 New St", order.newRecipientAddress());
}
/** 承运商受理恒健用 1 否 / 2 是,不是 0/1。 */
@Test
void carrierAcceptanceUsesOneNoTwoYes() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertEquals("2", order.carrierIsAcceptance());
assertEquals(Boolean.TRUE, order.carrierAccepted());
}
@Test
void carrierAcceptanceNotGuessed() {
RecordingTransport notAccepted = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\","
+ "\"carrierIsAcceptance\":1}}"));
assertEquals(Boolean.FALSE, adapter(notAccepted).getChange(ctx(), "TC-1").carrierAccepted());
RecordingTransport missing = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\"}}"));
assertNull(adapter(missing).getChange(ctx(), "TC-1").carrierAccepted(), "未给即未知");
RecordingTransport weird = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\","
+ "\"carrierIsAcceptance\":0}}"));
assertNull(adapter(weird).getChange(ctx(), "TC-1").carrierAccepted(), "0 不是有效值,归未知");
}
/** 召回标记:1 表示召回中。 */
@Test
void mapsTrackingLabelAndRecalling() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertEquals("1", order.trackingLabel());
assertEquals(Boolean.TRUE, order.recalling());
}
/** 异常码与异常文本分开保留。 */
@Test
void keepsErrorCodeAndMessageSeparate() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertEquals("1", order.errorCode());
assertEquals("推送异常", order.errorMessage());
}
/** 备注:客户备注与受理备注是两个字段。 */
@Test
void mapsBothRemarks() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertEquals("客户要求改址", order.customerRemark());
assertEquals("已受理", order.acceptanceRemark());
}
/** 两个状态各存各的:异动单已受理不代表运单已送达。 */ /** 两个状态各存各的:异动单已受理不代表运单已送达。 */
@Test @Test
void statusAndLogisticsStatusAreIndependent() { void statusAndLogisticsStatusAreIndependent() {

Loading…
Cancel
Save