From 1325314957a657d1f1ec701dec205c9dba23341c Mon Sep 17 00:00:00 2001
From: lml <1297555865@qq.com>
Date: Tue, 17 Nov 2026 10:30:10 +0800
Subject: [PATCH] =?UTF-8?q?fix(hengjian):=20=E5=BC=82=E5=8A=A8=E5=8D=95?=
=?UTF-8?q?=E6=9F=A5=E8=AF=A2=E8=A1=A5=E9=BD=90=E6=9C=AA=E6=98=A0=E5=B0=84?=
=?UTF-8?q?=E5=AD=97=E6=AE=B5=EF=BC=8C=E5=B9=B6=E4=BF=AE=E6=AD=A3=20change?=
=?UTF-8?q?RequestNo=20=E8=AF=AD=E4=B9=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
服务端字段原先只映射了一部分,排障要看的几组被丢掉了:
- 来源三维各存各的: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 双号:{@link #changeRequestNo()} 是 OMS 侧的异动申请号(幂等键),
* {@link #providerChangeOrderNo()} 是仓方生成的异动单号(查询 / 取消用它)。 {@link #status()} 是 SDK 归一层(单证受理状态),{@link #logisticsStatus()} 是
+ * 查询结果拿不到 {@code changeRequestNo}:仓方响应里没有这个号,
+ * 所以从 {@code getChange()} 回来的对象该字段为 null。不要拿仓单号去填它——
+ * 两者含义不同,填同一个值会让调用方误以为 OMS 单号等于仓单号。 {@link #rawStatus()} 是异动单的受理状态,{@link #rawLogisticsStatus()} 是
* 运单当前的物流状态——两者不是一回事:一张异动单可能「已受理」而运单还在途。 不归一成枚举:恒健是 0~6 的数字码,运去哪等其它仓的码表完全不同,
* 归一会丢失「受理失败 / 已取消」这类关键区分。需要判断时看
- * {@link #accepted()} / {@link #failed()}。
恒健 {@code errorStatus}:0 无异常 / 1 推送异常。 + * 与 {@link #errorMessage()} 分开:码用于判断,文本用于展示。
+ */ + private final String errorCode; private final String upstreamNo; private final String caseId; /** 完成时间(UTC);未完成时为 null。 */ private final java.time.Instant completedAt; + // ==================== 来源维度(仓方原值)==================== + + /** + * 来源维度。 + * + *恒健 {@code sourceId} / {@code sourceNo} / {@code sourceOrderType}。 + * {@code sourceNo} 与 {@link #orderNo()} 是两个字段:恒健创建时我们传的 + * {@code orderNo} 落在仓方 {@code sourceNo} 上,但响应里还可能另有 {@code upstreamNo} + * (上游单据号)。三者都保留,不做合并——合并后就分不清哪一层出的错。
+ */ + 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; + + /** + * 承运商是否受理的仓方原值;仓方未给为 null。 + * + *恒健 {@code carrierIsAcceptance}:1 否 / 2 是。不是 0/1—— + * 按 0 判断会把「否」误读成未给。用 {@link #carrierAccepted()} 取布尔。
+ */ + private final String carrierIsAcceptance; + + /** + * tracking 标记的仓方原值;仓方未给为 null。 + * + *恒健 {@code trackingLabel}:0 无 / 1 召回中。
+ */ + private final String trackingLabel; + + /** 客户备注;仓方未给为 null。 */ + private final String customerRemark; + /** 受理备注;仓方未给为 null。 */ + private final String acceptanceRemark; + private TrackingChangeOrder(Builder b) { - this.changeRequestNo = require(b.changeRequestNo, "changeRequestNo"); + // changeRequestNo 允许为 null:查询结果里仓方不回这个号 + this.changeRequestNo = b.changeRequestNo; this.providerChangeOrderNo = b.providerChangeOrderNo; this.sourceProvider = b.sourceProvider; this.warehouseCode = b.warehouseCode; @@ -60,16 +120,34 @@ public final class TrackingChangeOrder { this.carrierCode = b.carrierCode; this.carrierServiceCode = b.carrierServiceCode; this.errorMessage = b.errorMessage; + this.errorCode = b.errorCode; this.upstreamNo = b.upstreamNo; this.caseId = b.caseId; 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() { return new Builder(); } - /** OMS 侧的异动申请号;幂等键。 */ + /** + * OMS 侧的异动申请号;幂等键。 + * + *查询结果为 null:仓方响应里没有这个号。创建结果里有值。
+ */ public String changeRequestNo() { return changeRequestNo; } @@ -91,6 +169,7 @@ public final class TrackingChangeOrder { return trackingNumber; } + /** 来源单号(我们下发的出库单号);仓方未给为 null。 */ public String orderNo() { return orderNo; } @@ -122,6 +201,11 @@ public final class TrackingChangeOrder { return errorMessage; } + /** 异常码原值;无异常为 null。 */ + public String errorCode() { + return errorCode; + } + /** 上游单据号。 */ public String upstreamNo() { return upstreamNo; @@ -137,6 +221,94 @@ public final class TrackingChangeOrder { 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(未知,不是「未受理」)。 + * + *恒健的取值是 1 否 / 2 是,不是 0/1。
+ */ + 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(未知,不是「未受理」)。 */ public Boolean accepted() { if (rawStatus == null) { @@ -155,13 +327,6 @@ public final class TrackingChangeOrder { 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; @@ -175,10 +340,25 @@ public final class TrackingChangeOrder { private String carrierCode; private String carrierServiceCode; private String errorMessage; + private String errorCode; private String upstreamNo; private String caseId; 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) { this.changeRequestNo = v; return this; @@ -239,6 +419,12 @@ public final class TrackingChangeOrder { return this; } + /** 异常码原值。 */ + public Builder errorCode(String v) { + this.errorCode = v; + return this; + } + public Builder upstreamNo(String v) { this.upstreamNo = v; return this; @@ -254,6 +440,73 @@ public final class TrackingChangeOrder { 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() { return new TrackingChangeOrder(this); } diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeMapper.java index adb7f0f..692e29c 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeMapper.java @@ -25,6 +25,10 @@ import java.time.format.DateTimeParseException; * *两者各存各的,不能互相覆盖:一张异动单可能「已受理」而运单还在途, * 也可能运单已签收而异动单刚提交。
+ * + *查询响应里没有 OMS 侧的申请号,所以结果里该字段为 null。 + * 不拿仓单号顶替——填同一个值会让调用方误以为两者相等。
*/ final class HengjianTrackingChangeMapper { @@ -42,20 +46,38 @@ final class HengjianTrackingChangeMapper { throw new IllegalArgumentException("hengjian tracking change payload has no trackingChangeOrderNo"); } return TrackingChangeOrder.builder() - .changeRequestNo(changeNo) + // changeRequestNo 不填:仓方响应没有这个号,不拿仓单号顶替 .providerChangeOrderNo(changeNo) .sourceProvider(provider) .warehouseCode(firstNonBlank(detail.orgWarehouseCode, warehouseCode)) .trackingNumber(trimToNull(detail.trackingNo)) - // upstreamNo 是上游单据号;创建时传的 orderNo 会落在 sourceNo 上 - .orderNo(firstNonBlank(detail.sourceNo, detail.upstreamNo)) + // 来源三维各存各的:sourceNo 是我们下发的 orderNo 落点, + // 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)) .rawStatus(trimToNull(detail.orderStatus)) .rawLogisticsStatus(trimToNull(detail.logisticsStatus)) .carrierCode(trimToNull(detail.carrierCode)) .carrierServiceCode(trimToNull(detail.carrierServiceCode)) + // 异常码与异常文本分开:码用于判断、文本用于展示 + .errorCode(trimToNull(detail.errorStatus)) .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)) .completedAt(parseTime(detail.completeAt)) .build(); diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeTest.java index 55a1269..7680182 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeTest.java @@ -236,8 +236,23 @@ class HengjianTrackingChangeTest { + "\"orgWarehouseCode\":\"EFCA\"," + "\"carrierCode\":\"UPS\"," + "\"carrierServiceCode\":\"UPSG_HL\"," - + "\"handleType\":1," + + "\"handleType\":2," + "\"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\"}}"; private static RecordingTransport querying() { @@ -272,10 +287,100 @@ class HengjianTrackingChangeTest { assertEquals("EFCA", order.warehouseCode()); assertEquals("UPS", order.carrierCode()); 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()); } + /** 查询结果拿不到 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 void statusAndLogisticsStatusAreIndependent() {