Browse Source

feat(hengjian): 对接物流异动单创建 / 查询(trackingChange)

- 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
lml 1 week ago
parent
commit
62a25a9f67
  1. 12
      README.md
  2. 3
      docs-warehouse/architecture.md
  3. 74
      docs-warehouse/hengjian/README.md
  4. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingChangeCapable.java
  5. 49
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TrackingChangeHandleType.java
  6. 4
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
  7. 141
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeCommand.java
  8. 261
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeOrder.java
  9. 55
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  10. 18
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  11. 135
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  12. 111
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeMapper.java
  13. 82
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeDtos.java
  14. 164
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeQueryDtos.java
  15. 30
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java
  16. 333
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeTest.java
  17. 15
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java
  18. 152
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianTrackingChangeProbeTest.java

12
README.md

@ -141,7 +141,7 @@ sequenceDiagram @@ -141,7 +141,7 @@ sequenceDiagram
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询) |
依赖方向:
```
@ -376,13 +376,15 @@ common.ecommerce @@ -376,13 +376,15 @@ common.ecommerce
│
└── hengjian 恒健三方仓(warehouse-sdk-hengjian)
├── HengjianConstants 测试基址、当前接入路径、双授权头名、成功码 / 未授权码、限流
├── adapter HengjianAdapter(目录 + 渠道 + 商品 + 出库下单 / 详情 / 列表 / 取消 / 包裹)/
├── adapter HengjianAdapter(目录 + 渠道 + 商品 + 出库全链路 + 物流异动单)/
│ HengjianAdapterFactory / HengjianDirectoryMapper /
│ HengjianProductMapper / HengjianOutboundMapper / HengjianOrderMapper
│ HengjianProductMapper / HengjianOutboundMapper /
│ HengjianOrderMapper / HengjianTrackingChangeMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos /
│ HengjianCancelOrderDtos
│ HengjianCancelOrderDtos / HengjianTrackingChangeDtos /
│ HengjianTrackingChangeQueryDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter
@ -1079,7 +1081,7 @@ mvn -pl lingxing test # 单模块 @@ -1079,7 +1081,7 @@ mvn -pl lingxing test # 单模块
mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test
mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试
mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 商品 / 下单 / 转运
mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 渠道 / 商品 / 下单 / 查询 / 取消
mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 渠道 / 商品 / 出库全链路 / 异动单
```
---

3
docs-warehouse/architecture.md

@ -80,7 +80,7 @@ public enum YqnOutboundStatus { @@ -80,7 +80,7 @@ public enum YqnOutboundStatus {
## 4. 能力矩阵
`WarehouseCapability`(19 个):
`WarehouseCapability`(25 个):
| 能力 | 说明 | 运去哪 | 信仓 |
|---|---|:---:|:---:|
@ -100,6 +100,7 @@ public enum YqnOutboundStatus { @@ -100,6 +100,7 @@ public enum YqnOutboundStatus {
| `RETURN` | 退货发起 / 查询 | ✅ | — |
| `RETURN_DISPOSITION` | 退货条目处理 | ✅ | — |
| `TRACKING` | 物流轨迹 | ✅ | — |
| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
| `DESTRUCTION` | 销毁 / 报废 | ✅ | — |
| `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — |
| `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — |

74
docs-warehouse/hengjian/README.md

@ -67,7 +67,10 @@ @@ -67,7 +67,10 @@
| 5 | 创建销售发货单 | `POST /v1/saleOrder/create` | `OUTBOUND` / `PLATFORM_LABEL_DELIVERY` | ✅ |
| 6 | 订单详情 | `POST /v1/saleOrder/findOne` | `OUTBOUND` | ✅ |
| 7 | 订单列表 | `GET /v1/saleOrder/findByPage` | `OUTBOUND` | ✅ |
| 8 | 回调 | — | — | ❌ 文档无回调页 |
| 8 | 订单取消 | `POST /v1/saleOrder/cancel` | `OUTBOUND` | ✅ |
| 9 | 物流异动单创建 | `POST /v1/trackingChange/create` | `TRACKING_CHANGE` | ✅ |
| 10 | 物流异动单查询 | `POST /v1/trackingChange/findOrder` | `TRACKING_CHANGE` | ✅ |
| 11 | 回调 | — | — | ❌ 文档无回调页 |
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作,
@ -166,7 +169,7 @@ @@ -166,7 +169,7 @@
`orderId` + `orderNo` 两个都传,所以这个 id 必须随 `OutboundReceipt.providerOrderId()`
落库;拿不到就报错,**不当创建成功**。
**未接入**:订单上传附件、物流异动单。调用这些方法会显式抛异常,不返回 null——
**未接入**:订单上传附件、物流异动单取消。调用这些方法会显式抛异常,不返回 null——
静默返回空会让调用方以为「仓说没有这单」。
## 3. 未接入(文档已有,按需排期)
@ -182,7 +185,47 @@ @@ -182,7 +185,47 @@
| 订单列表 | `GET /v1/saleOrder/findByPage` | ✅ 已接入 |
| 订单取消 | `POST /v1/saleOrder/cancel`(`orderId` + `orderNo` 都必填) | ✅ 已接入 |
| 订单上传附件 | `POST /v1/saleOrder/createAttachment` | ⬜ |
| 物流异动单 创建 / 查询 / 取消 | `POST /v1/trackingChange/create`、`POST /v1/saleOrder/findOrder`、`POST /v1/trackingChange/cancel` | ⬜ |
| 物流异动单 创建 | `POST /v1/trackingChange/create` | ✅ 已接入(`TRACKING_CHANGE`) |
| 物流异动单 查询 | `POST /v1/trackingChange/findOrder`(⚠ 文档写的是 `/v1/saleOrder/findOrder`,真机 404) | ✅ 已接入 |
| 物流异动单 取消 | `POST /v1/trackingChange/cancel` | ⬜ |
#### 物流异动单(召回 / 换址 / 在途异常)
与「轨迹查询」是两件事:轨迹只读,异动会向承运商提工单、可能产生费用,
所以单独一个能力位 `TRACKING_CHANGE`。
**真机已验证的必填项**(文档标错 / 漏标):
| 字段 | 文档 | 真机 |
|---|---|---|
| `trackingNo` | 是 | 是 |
| `orderNo` | **否** | **是**(缺了回「来源单号不能为空」) |
| `remark` | 是 | 是 |
| `handleType` | 是 | 是 |
| `newRecipientName/Phone/Address` | 换址时必填 | 换址时必填(校验顺序 姓名 → 电话 → 地址) |
另外仓方会校验**「来源单号和 trackingNo 不匹配」**——两者必须属于同一张单。
这条本地挡不住,只能在联调时给一对真实存在的单号 + 运单号。
**路径纠正(真机 2026-11-13)**:查询页写的 `/v1/saleOrder/findOrder` 返回
`404 No handler found`;实际路径是 **`/v1/trackingChange/findOrder`**
(疑似从销售订单页复制)。适配器用后者。
**两个状态别混**:
| 字段 | 含义 | 落到 |
|---|---|---|
| `orderStatus` 0~6 | 异动单**受理**状态(草稿 / 待受理 / 受理中 / 已受理 / 受理成功 / 受理失败 / 取消) | `rawStatus()` |
| `logisticsStatus` 0~9 | **运单**物流状态(PRE TRANSIT / IN TRANSIT / … / RETURN TO SENDER) | `rawLogisticsStatus()` |
两者各存各的:一张异动单可能「已受理」而运单还在途,不能互相覆盖。
`accepted()` / `failed()` / `cancelled()` 是按 `orderStatus` 的便捷判断。
**未能确认**:`handleType` 文档标 STRING、示例给数字。真机字符串和数字都试过,
两种都能过(都走到后续业务校验),**区分不出**类型要求,按示例发 Integer。
**未接入**:订单上传附件、物流异动单取消。调用这些方法会显式抛异常,不返回 null——
静默返回空会让调用方以为「仓说没有这单」。
#### 订单详情(`/v1/saleOrder/findOne`)
@ -321,12 +364,13 @@ warehouse-sdk-hengjian/ @@ -321,12 +364,13 @@ warehouse-sdk-hengjian/
├── main/java/common/ecommerce/hengjian/
│ ├── HengjianConstants.java 端点 / 路径 / 两个授权头 / 成功码 / 未授权码 / 限流
│ ├── adapter/
│ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品 + 下单 / 详情 / 列表 / 包裹 / 取消
│ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品 + 出库全链路 + 物流异动单
│ │ ├── HengjianAdapterFactory.java
│ │ ├── HengjianDirectoryMapper.java 仓库 / 渠道字段搬运
│ │ ├── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验
│ │ ├── HengjianOutboundMapper.java 出库下单报文(UTC 时间 / 行总额 / 面单附件)
│ │ └── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型
│ │ ├── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型
│ │ └── HengjianTrackingChangeMapper.java 异动单 → 统一模型
│ ├── dto/
│ │ ├── HengjianWarehouseDtos.java
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
@ -334,7 +378,9 @@ warehouse-sdk-hengjian/ @@ -334,7 +378,9 @@ warehouse-sdk-hengjian/
│ │ ├── HengjianCreateOrderDtos.java /v1/saleOrder/create
│ │ ├── HengjianOrderDetailDtos.java /v1/saleOrder/findOne
│ │ ├── HengjianOrderListDtos.java /v1/saleOrder/findByPage
│ │ └── HengjianCancelOrderDtos.java /v1/saleOrder/cancel
│ │ ├── HengjianCancelOrderDtos.java /v1/saleOrder/cancel
│ │ ├── HengjianTrackingChangeDtos.java /v1/trackingChange/create
│ │ └── HengjianTrackingChangeQueryDtos.java /v1/trackingChange/findOrder
│ ├── enums
│ │ ├── HengjianOrderStatus.java orderStatusEnum → OutboundStatus
│ │ └── package-info.java 其余状态枚举约定(待建)
@ -349,13 +395,14 @@ warehouse-sdk-hengjian/ @@ -349,13 +395,14 @@ warehouse-sdk-hengjian/
├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝
├── adapter/HengjianOrderQueryTest.java 25 个:详情映射 / 列表分页 / 时间窗 / 包裹去重 / 枚举
├── adapter/HengjianCancelOrderTest.java 10 个:双键补齐 / 精确匹配 / 拒绝路径 / 预判
├── adapter/HengjianTrackingChangeTest.java 19 个:必填拒绝 / 换址三项 / 路径 / 双状态
├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举
├── http/HengjianEnvelopeTest.java 11 个:三种信封形态 + 错误路径
├── http/HengjianEnvelopeTest.java 12 个:三种信封形态 + 通用失败码 + 错误路径
├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true
```
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(109 个 + 2 个跳过)。
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(129 个 + 2 个跳过)。
## 5. 探针用法
@ -376,6 +423,17 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ @@ -376,6 +423,17 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
(`yyyy-MM-dd`,跨度 ≤30 天)。没给就跳过对应用例。
- 只读,不建单。
异动单查询探针(只读):
```bash
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
-Dhengjian.probe=true -Dhengjian.probe.token=<组织token> \
-Dhengjian.probe.changeOrderNo=<仓方异动单号> \
-Dtest=HengjianTrackingChangeProbeTest test
```
- 验证查询路径是 `/v1/trackingChange/findOrder`(文档写的 `/v1/saleOrder/findOrder` 是 404)。
写探针(会留下真实数据):
```bash

32
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingChangeCapable.java

@ -0,0 +1,32 @@ @@ -0,0 +1,32 @@
package common.ecommerce.warehouse.capability;
import common.ecommerce.warehouse.model.TrackingChangeCommand;
import common.ecommerce.warehouse.model.TrackingChangeOrder;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
/**
* 物流异动单能力:对已交运的运单发起召回 / 换址 / 在途异常处理。
*
* <p>与 {@link TrackingCapable}(查轨迹)是两件事:那个只读,这个会向承运商提工单、
* 可能产生费用,所以单独一个能力位 {@code TRACKING_CHANGE}。</p>
*/
public interface TrackingChangeCapable extends WarehouseAdapter {
/**
* 创建物流异动单。<b>写操作</b>,幂等键
* {@code warehouseCode + changeRequestNo + create}。
*
* <p>创建成功只代表「申请已提交」,承运商是否受理要查
* {@link TrackingChangeOrder#rawStatus()},不要据此判断货已拦回。</p>
*/
TrackingChangeOrder createChange(WarehouseContext ctx, TrackingChangeCommand cmd);
/**
* 查询物流异动单。
*
* <p>方法名带 {@code Change} 后缀:避免与 {@code DestructionCapable.getDestruction}、
* {@code OutboundCapable.get} 在实现类上撞签名。</p>
*/
TrackingChangeOrder getChange(WarehouseContext ctx, String providerChangeOrderNo);
}

49
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TrackingChangeHandleType.java

@ -0,0 +1,49 @@ @@ -0,0 +1,49 @@
package common.ecommerce.warehouse.enums;
/**
* 物流异动处理类型(底层枚举)。
*
* <p>只表达业务语义:<b>召回</b>(拦回已发出的货)、<b>换址</b>(改派收件人信息)、
* <b>在途异常</b>(丢件 / 破损等需要承运商介入)。仓方码值由各适配器映射,
* core 不认识任何仓的数字。</p>
*
* <p>换址必须同时给新收件人三项(姓名 / 电话 / 地址),这项校验在适配器里做——
* 不同仓对三项的必填性可能不同。</p>
*/
public enum TrackingChangeHandleType {
/** 召回。 */
RECALL(10, "召回"),
/** 更换地址。 */
ADDRESS_CHANGE(20, "更换地址"),
/** 在途异常。 */
IN_TRANSIT_EXCEPTION(30, "在途异常");
private final int code;
private final String label;
TrackingChangeHandleType(int code, String label) {
this.code = code;
this.label = label;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
/** 按落库码反查;未知返回 null。 */
public static TrackingChangeHandleType ofCode(int code) {
for (TrackingChangeHandleType t : values()) {
if (t.code == code) {
return t;
}
}
return null;
}
}

4
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java

@ -55,7 +55,9 @@ public enum WarehouseCapability { @@ -55,7 +55,9 @@ public enum WarehouseCapability {
/** 仓方基础资料(仓库列表 / 承运商列表) */
DIRECTORY(230, "基础资料"),
/** 最优渠道推荐(按 SKU + 邮编由仓择优) */
CHANNEL_RECOMMEND(240, "最优渠道推荐");
CHANNEL_RECOMMEND(240, "最优渠道推荐"),
/** 物流异动单:召回 / 换址 / 在途异常(对已交运的运单发起处理) */
TRACKING_CHANGE(250, "物流异动单");
private final int code;
private final String label;

141
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeCommand.java

@ -0,0 +1,141 @@ @@ -0,0 +1,141 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
/**
* 物流异动单创建命令。<b>写操作</b>,幂等键是 {@link #changeRequestNo()}。
*
* <p>物流异动是<b>对已交运的运单</b>发起处理:召回、换址、在途异常。
* 创建成功只代表「异动申请已提交」,承运商是否受理要另外查状态
* ({@link TrackingChangeOrder#rawStatus()})。</p>
*
* <p>换址({@link TrackingChangeHandleType#ADDRESS_CHANGE})必须提供新收件人三项
* (姓名 / 电话 / 地址),这项约束在适配器里校验——不同仓对三项的必填性可能不同。</p>
*/
public final class TrackingChangeCommand {
/** OMS 侧的异动申请号,幂等键。 */
private final String changeRequestNo;
/** 运单跟踪号;必填。 */
private final String trackingNumber;
/** 来源单号(我们下发的出库单号);仓方大多必填。 */
private final String orderNo;
/** 处理类型。 */
private final TrackingChangeHandleType handleType;
private final String remark;
private final String newRecipientName;
private final String newRecipientPhone;
private final String newRecipientAddress;
private TrackingChangeCommand(Builder b) {
this.changeRequestNo = require(b.changeRequestNo, "changeRequestNo");
this.trackingNumber = require(b.trackingNumber, "trackingNumber");
this.orderNo = b.orderNo;
this.handleType = java.util.Objects.requireNonNull(b.handleType, "handleType");
this.remark = b.remark;
this.newRecipientName = b.newRecipientName;
this.newRecipientPhone = b.newRecipientPhone;
this.newRecipientAddress = b.newRecipientAddress;
}
public static Builder builder() {
return new Builder();
}
/** OMS 侧的异动申请号;幂等键。 */
public String changeRequestNo() {
return changeRequestNo;
}
public String trackingNumber() {
return trackingNumber;
}
/** 来源单号;null 表示不传。 */
public String orderNo() {
return orderNo;
}
public TrackingChangeHandleType handleType() {
return handleType;
}
public String remark() {
return remark;
}
public String newRecipientName() {
return newRecipientName;
}
public String newRecipientPhone() {
return newRecipientPhone;
}
public String newRecipientAddress() {
return newRecipientAddress;
}
private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return v.trim();
}
public static final class Builder {
private String changeRequestNo;
private String trackingNumber;
private String orderNo;
private TrackingChangeHandleType handleType;
private String remark;
private String newRecipientName;
private String newRecipientPhone;
private String newRecipientAddress;
public Builder changeRequestNo(String v) {
this.changeRequestNo = v;
return this;
}
public Builder trackingNumber(String v) {
this.trackingNumber = v;
return this;
}
public Builder orderNo(String v) {
this.orderNo = v;
return this;
}
public Builder handleType(TrackingChangeHandleType v) {
this.handleType = v;
return this;
}
public Builder remark(String v) {
this.remark = v;
return this;
}
public Builder newRecipientName(String v) {
this.newRecipientName = v;
return this;
}
public Builder newRecipientPhone(String v) {
this.newRecipientPhone = v;
return this;
}
public Builder newRecipientAddress(String v) {
this.newRecipientAddress = v;
return this;
}
public TrackingChangeCommand build() {
return new TrackingChangeCommand(this);
}
}
}

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

@ -0,0 +1,261 @@ @@ -0,0 +1,261 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
/**
* 物流异动单。
*
* <p>双号:{@link #changeRequestNo()} 是 OMS 侧的异动申请号(幂等键),
* {@link #providerChangeOrderNo()} 是仓方生成的异动单号(查询 / 取消用它)。</p>
*
* <p>{@link #status()} 是 SDK 归一层(单证受理状态),{@link #logisticsStatus()} 是
* <b>运单</b>当前的物流状态——两者不是一回事:一张异动单可能「已受理」而运单还在途。</p>
*/
public final class TrackingChangeOrder {
private final String changeRequestNo;
private final String providerChangeOrderNo;
private final WarehouseProvider sourceProvider;
private final String warehouseCode;
private final String trackingNumber;
private final String orderNo;
private final TrackingChangeHandleType handleType;
/**
* 异动单受理状态的<b>仓方原值</b>。
*
* <p>不归一成枚举:恒健是 0~6 的数字码,运去哪等其它仓的码表完全不同,
* 归一会丢失「受理失败 / 已取消」这类关键区分。需要判断时看
* {@link #accepted()} / {@link #failed()}。</p>
*/
private final String rawStatus;
/**
* 运单物流状态的<b>仓方原值</b>。
*
* <p>恒健回 0~9(UNKNOWN / PRE TRANSIT / IN TRANSIT / OUT FOR DELIVERY /
* DELIVERED / AVAILABLE FOR PICKUP / RETURN TO SENDER / FAILURE / CANCELLED / ERROR),
* 直接保留原文便于排障。</p>
*/
private final String rawLogisticsStatus;
private final String carrierCode;
private final String carrierServiceCode;
private final String errorMessage;
private final String upstreamNo;
private final String caseId;
/** 完成时间(UTC);未完成时为 null。 */
private final java.time.Instant completedAt;
private TrackingChangeOrder(Builder b) {
this.changeRequestNo = require(b.changeRequestNo, "changeRequestNo");
this.providerChangeOrderNo = b.providerChangeOrderNo;
this.sourceProvider = b.sourceProvider;
this.warehouseCode = b.warehouseCode;
this.trackingNumber = b.trackingNumber;
this.orderNo = b.orderNo;
this.handleType = b.handleType;
this.rawStatus = b.rawStatus;
this.rawLogisticsStatus = b.rawLogisticsStatus;
this.carrierCode = b.carrierCode;
this.carrierServiceCode = b.carrierServiceCode;
this.errorMessage = b.errorMessage;
this.upstreamNo = b.upstreamNo;
this.caseId = b.caseId;
this.completedAt = b.completedAt;
}
public static Builder builder() {
return new Builder();
}
/** OMS 侧的异动申请号;幂等键。 */
public String changeRequestNo() {
return changeRequestNo;
}
/** 仓方异动单号;创建响应若不回传则为 null。 */
public String providerChangeOrderNo() {
return providerChangeOrderNo;
}
public WarehouseProvider sourceProvider() {
return sourceProvider;
}
public String warehouseCode() {
return warehouseCode;
}
public String trackingNumber() {
return trackingNumber;
}
public String orderNo() {
return orderNo;
}
public TrackingChangeHandleType handleType() {
return handleType;
}
/** 异动单受理状态原值。 */
public String rawStatus() {
return rawStatus;
}
/** 运单物流状态原值。 */
public String rawLogisticsStatus() {
return rawLogisticsStatus;
}
public String carrierCode() {
return carrierCode;
}
public String carrierServiceCode() {
return carrierServiceCode;
}
/** 仓方给出的异常信息;无异常为 null。 */
public String errorMessage() {
return errorMessage;
}
/** 上游单据号。 */
public String upstreamNo() {
return upstreamNo;
}
/** 承运商 CASE ID。 */
public String caseId() {
return caseId;
}
/** 完成时间(UTC);未完成时为 null。 */
public java.time.Instant completedAt() {
return completedAt;
}
/** 仓方是否已受理;状态原值未给时返回 null(未知,不是「未受理」)。 */
public Boolean accepted() {
if (rawStatus == null) {
return null;
}
return "3".equals(rawStatus.trim()) || "4".equals(rawStatus.trim());
}
/** 受理是否失败;状态原值未给时返回 false。 */
public boolean failed() {
return rawStatus != null && "5".equals(rawStatus.trim());
}
/** 仓方是否已取消;状态原值未给时返回 false。 */
public boolean cancelled() {
return rawStatus != null && "6".equals(rawStatus.trim());
}
private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return v.trim();
}
public static final class Builder {
private String changeRequestNo;
private String providerChangeOrderNo;
private WarehouseProvider sourceProvider;
private String warehouseCode;
private String trackingNumber;
private String orderNo;
private TrackingChangeHandleType handleType;
private String rawStatus;
private String rawLogisticsStatus;
private String carrierCode;
private String carrierServiceCode;
private String errorMessage;
private String upstreamNo;
private String caseId;
private java.time.Instant completedAt;
public Builder changeRequestNo(String v) {
this.changeRequestNo = v;
return this;
}
public Builder providerChangeOrderNo(String v) {
this.providerChangeOrderNo = v;
return this;
}
public Builder sourceProvider(WarehouseProvider v) {
this.sourceProvider = v;
return this;
}
public Builder warehouseCode(String v) {
this.warehouseCode = v;
return this;
}
public Builder trackingNumber(String v) {
this.trackingNumber = v;
return this;
}
public Builder orderNo(String v) {
this.orderNo = v;
return this;
}
public Builder handleType(TrackingChangeHandleType v) {
this.handleType = v;
return this;
}
public Builder rawStatus(String v) {
this.rawStatus = v;
return this;
}
public Builder rawLogisticsStatus(String v) {
this.rawLogisticsStatus = v;
return this;
}
public Builder carrierCode(String v) {
this.carrierCode = v;
return this;
}
public Builder carrierServiceCode(String v) {
this.carrierServiceCode = v;
return this;
}
public Builder errorMessage(String v) {
this.errorMessage = v;
return this;
}
public Builder upstreamNo(String v) {
this.upstreamNo = v;
return this;
}
public Builder caseId(String v) {
this.caseId = v;
return this;
}
public Builder completedAt(java.time.Instant v) {
this.completedAt = v;
return this;
}
public TrackingChangeOrder build() {
return new TrackingChangeOrder(this);
}
}
}

55
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -12,6 +12,7 @@ import common.ecommerce.warehouse.capability.InventoryCapable; @@ -12,6 +12,7 @@ import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.TrackingChangeCapable;
import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
@ -231,6 +232,60 @@ public final class WarehouseOperations { @@ -231,6 +232,60 @@ public final class WarehouseOperations {
}
/**
* 创建物流异动单(召回 / 换址 / 在途异常)。<b>写操作</b>:强制经幂等守卫,
* 幂等键 {@code warehouseCode + changeRequestNo + create}。
*
* <p>异动会真实改变在途货的走向(召回会拦货、换址会改派),重复下发等于对同一运单
* 提两次工单,所以和其它写操作一样不给「无幂等」的降级路径。</p>
*/
public common.ecommerce.warehouse.model.TrackingChangeOrder createTrackingChange(
final common.ecommerce.warehouse.model.TrackingChangeCommand cmd) {
require(WarehouseCapability.TRACKING_CHANGE, TrackingChangeCapable.class);
if (guard == null) {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final TrackingChangeCapable capable = (TrackingChangeCapable) adapter;
return CallSupport.observe(observer, ctx, "warehouse.tracking.change.create",
CallSupport.params("changeRequestNo", cmd.changeRequestNo(),
"trackingNumber", cmd.trackingNumber()),
r -> CallSupport.NO_COUNT,
() -> {
common.ecommerce.shared.idempotency.WriteResult<
common.ecommerce.warehouse.model.TrackingChangeOrder> result =
guard.execute(
WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
cmd.changeRequestNo(), "create"),
() -> capable.createChange(ctx, cmd),
order -> order.providerChangeOrderNo());
if (result.alreadyCompleted()) {
// 回放:本次没有提交异动,只有上次记录的仓方单号
return common.ecommerce.warehouse.model.TrackingChangeOrder.builder()
.changeRequestNo(cmd.changeRequestNo())
.providerChangeOrderNo(result.resultRef())
.warehouseCode(account.warehouseCode())
.trackingNumber(cmd.trackingNumber())
.sourceProvider(provider)
.build();
}
return result.value();
});
}
/**
* 查询物流异动单。只读,不走幂等。
*
* @param providerChangeOrderNo 仓方异动单号
*/
public common.ecommerce.warehouse.model.TrackingChangeOrder getTrackingChange(
final String providerChangeOrderNo) {
require(WarehouseCapability.TRACKING_CHANGE, TrackingChangeCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.tracking.change.get",
CallSupport.params("providerChangeOrderNo", providerChangeOrderNo),
r -> CallSupport.NO_COUNT,
() -> ((TrackingChangeCapable) adapter).getChange(ctx, providerChangeOrderNo));
}
/**
* 仓方基础资料:客户名下的仓库列表。
*
* <p>只读。用于下单前取仓代码,避免把仓代码写死在配置里。</p>

18
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java

@ -92,6 +92,24 @@ public final class HengjianConstants { @@ -92,6 +92,24 @@ public final class HengjianConstants {
public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel";
/**
* 创建物流异动单。
*
* <p>{@code trackingNo}、{@code orderNo}、{@code remark}、{@code handleType} 真机均为必填;
* 且仓方会校验「来源单号与 trackingNo 属于同一张单」。</p>
*/
public static final String PATH_TRACKING_CHANGE_CREATE = "/v1/trackingChange/create";
/**
* 物流异动单查询。
*
* <p><b>路径与文档不一致</b>:恒健文档页写的是 {@code /v1/saleOrder/findOrder}
* (疑似从销售订单页复制),真机该路径返回
* {@code 404 No handler found};实际路径是 {@code /v1/trackingChange/findOrder}
* (2026-11-13 真机确认)。</p>
*/
public static final String PATH_TRACKING_CHANGE_FIND = "/v1/trackingChange/findOrder";
/**
* 列表接口的排序字段。
*
* <p>文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc};

135
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java

@ -8,6 +8,8 @@ import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; @@ -8,6 +8,8 @@ import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos;
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos;
import common.ecommerce.hengjian.dto.HengjianOrderListDtos;
import common.ecommerce.hengjian.dto.HengjianProductSaveDtos;
import common.ecommerce.hengjian.dto.HengjianTrackingChangeDtos;
import common.ecommerce.hengjian.dto.HengjianTrackingChangeQueryDtos;
import common.ecommerce.hengjian.dto.HengjianWarehouseDtos;
import common.ecommerce.hengjian.http.HengjianEnvelope;
import common.ecommerce.hengjian.http.HengjianRateLimiter;
@ -20,11 +22,13 @@ import common.ecommerce.shared.error.PlatformBusinessException; @@ -20,11 +22,13 @@ import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.TrackingChangeCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
@ -38,6 +42,8 @@ import common.ecommerce.warehouse.model.OutboundQuery; @@ -38,6 +42,8 @@ import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.model.TrackingChangeCommand;
import common.ecommerce.warehouse.model.TrackingChangeOrder;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -62,7 +68,7 @@ import java.util.Map; @@ -62,7 +68,7 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。</p>
*/
public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable,
WarehouseProductCapable, OutboundCapable {
WarehouseProductCapable, OutboundCapable, TrackingChangeCapable {
private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses";
private static final String OP_CARRIERS = "warehouse.directory.carriers";
@ -72,6 +78,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -72,6 +78,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
private static final String OP_ORDER_GET = "warehouse.outbound.get";
private static final String OP_ORDER_QUERY = "warehouse.outbound.query";
private static final String OP_ORDER_CANCEL = "warehouse.outbound.cancel";
private static final String OP_TRACKING_CHANGE_CREATE = "warehouse.tracking.change.create";
private static final String OP_TRACKING_CHANGE_GET = "warehouse.tracking.change.get";
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
@ -103,10 +111,135 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -103,10 +111,135 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
WarehouseCapability.PRODUCT,
WarehouseCapability.OUTBOUND,
WarehouseCapability.PLATFORM_LABEL_DELIVERY,
WarehouseCapability.TRACKING_CHANGE,
WarehouseCapability.DIRECTORY,
WarehouseCapability.LOGISTICS_PRODUCT);
}
// ------------------------------------------------------------------ 物流异动单
/**
* 创建物流异动单({@code POST /v1/trackingChange/create})。
*
* <p>承接门面的幂等守卫(键 {@code warehouseCode + changeRequestNo + create});
* 这里只负责拼报文与解析。</p>
*
* <p><b>真机确认的必填项</b>(文档标错 / 漏标):{@code trackingNo}、{@code orderNo}、
* {@code remark}、{@code handleType};换址(2)还要新收件人三项。
* 仓方还会校验「来源单号与 trackingNo 属于同一张单」——这一条本地挡不住,
* 只能在真机联调时保证调用方给的是一对真实存在的单号 + 运单号。</p>
*
* <p>响应只回 {@code trackingChangeOrderNo},<b>没有状态</b>——创建成功只代表申请已提交,
* 承运商是否受理要看 subsequent 查询。</p>
*/
@Override
public TrackingChangeOrder createChange(WarehouseContext ctx, TrackingChangeCommand cmd) {
HengjianTrackingChangeDtos.CreateRequest body = toCreateRequest(cmd);
String raw = execute(ctx, HengjianConstants.PATH_TRACKING_CHANGE_CREATE, body,
OP_TRACKING_CHANGE_CREATE);
HengjianTrackingChangeDtos.CreateResponse resp =
json.fromJson(raw, HengjianTrackingChangeDtos.CreateResponse.class);
if (resp == null || resp.data == null || trimToNull(resp.data.trackingChangeOrderNo) == null) {
throw WarehouseException.builder()
.message("hengjian tracking change returned no trackingChangeOrderNo: "
+ safeRelay(raw))
.operation(OP_TRACKING_CHANGE_CREATE)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.rawResponse(safeRelay(raw))
.build();
}
return TrackingChangeOrder.builder()
.changeRequestNo(cmd.changeRequestNo())
.providerChangeOrderNo(resp.data.trackingChangeOrderNo.trim())
.sourceProvider(provider())
.warehouseCode(ctx.warehouseCode())
.trackingNumber(cmd.trackingNumber())
.orderNo(trimToNull(cmd.orderNo()))
.handleType(cmd.handleType())
// 创建接口不回状态:保持 null,不拿请求侧的值冒充仓方状态
.build();
}
/**
* 查询物流异动单({@code POST /v1/trackingChange/findOrder})。
*
* <p><b>路径与文档不同</b>:文档写 {@code /v1/saleOrder/findOrder},真机 404;
* 正确路径在 {@link HengjianConstants#PATH_TRACKING_CHANGE_FIND}。</p>
*/
@Override
public TrackingChangeOrder getChange(WarehouseContext ctx, String providerChangeOrderNo) {
String changeNo = trimToNull(providerChangeOrderNo);
if (changeNo == null) {
throw new IllegalArgumentException("providerChangeOrderNo must not be blank");
}
HengjianTrackingChangeQueryDtos.FindOrderRequest body =
new HengjianTrackingChangeQueryDtos.FindOrderRequest();
body.trackingChangeOrderNo = changeNo;
String raw = execute(ctx, HengjianConstants.PATH_TRACKING_CHANGE_FIND, body,
OP_TRACKING_CHANGE_GET);
JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
return null;
}
HengjianTrackingChangeQueryDtos.TrackingChangeDetail detail =
json.fromJson(data.toString(), HengjianTrackingChangeQueryDtos.TrackingChangeDetail.class);
return HengjianTrackingChangeMapper.toOrder(detail, ctx.warehouseCode(), provider());
}
/** 统一命令 → 恒健请求;必填项在本地校验。 */
static HengjianTrackingChangeDtos.CreateRequest toCreateRequest(TrackingChangeCommand cmd) {
String trackingNo = requireText(cmd.trackingNumber(), "trackingNumber", cmd.changeRequestNo());
String orderNo = requireText(cmd.orderNo(), "orderNo", cmd.changeRequestNo());
String remark = requireText(cmd.remark(), "remark", cmd.changeRequestNo());
int handleType = handleTypeOf(cmd.handleType());
HengjianTrackingChangeDtos.CreateRequest body = new HengjianTrackingChangeDtos.CreateRequest();
body.trackingNo = trackingNo;
body.orderNo = orderNo;
body.remark = remark;
body.handleType = handleType;
if (cmd.handleType() == TrackingChangeHandleType.ADDRESS_CHANGE) {
// 换址三项真机必填,缺任一项仓方都会拒;本地先说清楚缺哪个
body.newRecipientName = requireText(cmd.newRecipientName(), "newRecipientName",
cmd.changeRequestNo());
body.newRecipientPhone = requireText(cmd.newRecipientPhone(), "newRecipientPhone",
cmd.changeRequestNo());
body.newRecipientAddress = requireText(cmd.newRecipientAddress(), "newRecipientAddress",
cmd.changeRequestNo());
}
return body;
}
/** 核心枚举 → 恒健 handleType:1 召回 / 2 换址 / 3 在途异常。 */
static int handleTypeOf(TrackingChangeHandleType type) {
if (type == null) {
throw new IllegalArgumentException("handleType must not be null");
}
switch (type) {
case RECALL:
return 1;
case ADDRESS_CHANGE:
return 2;
case IN_TRANSIT_EXCEPTION:
return 3;
default:
throw new IllegalArgumentException("unsupported handleType: " + type);
}
}
private static String requireText(String value, String field, String changeRequestNo) {
String v = trimToNull(value);
if (v == null) {
throw new IllegalArgumentException("hengjian tracking change " + changeRequestNo
+ " requires " + field + " (恒健必填)");
}
return v;
}
// ------------------------------------------------------------------ 出库
/**

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

@ -0,0 +1,111 @@ @@ -0,0 +1,111 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianTrackingChangeQueryDtos;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TrackingChangeOrder;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
/**
* 恒健物流异动单报文 → 统一模型。
*
* <p>只做字段搬运与码值解读;不猜、不补仓方没给的字段。</p>
*
* <h2>两个状态不是一回事</h2>
* <ul>
* <li>{@code orderStatus}(0~6):<b>异动单的受理状态</b> →
* {@link TrackingChangeOrder#rawStatus()};</li>
* <li>{@code logisticsStatus}(0~9):<b>运单的物流状态</b> →
* {@link TrackingChangeOrder#rawLogisticsStatus()}。</li>
* </ul>
* <p>两者各存各的,不能互相覆盖:一张异动单可能「已受理」而运单还在途,
* 也可能运单已签收而异动单刚提交。</p>
*/
final class HengjianTrackingChangeMapper {
/** 恒健时间格式(UTC,与其它接口一致)。 */
private static final DateTimeFormatter TIME_FORMAT =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private HengjianTrackingChangeMapper() {
}
static TrackingChangeOrder toOrder(HengjianTrackingChangeQueryDtos.TrackingChangeDetail detail,
String warehouseCode, WarehouseProvider provider) {
String changeNo = trimToNull(detail.trackingChangeOrderNo);
if (changeNo == null) {
throw new IllegalArgumentException("hengjian tracking change payload has no trackingChangeOrderNo");
}
return TrackingChangeOrder.builder()
.changeRequestNo(changeNo)
.providerChangeOrderNo(changeNo)
.sourceProvider(provider)
.warehouseCode(firstNonBlank(detail.orgWarehouseCode, warehouseCode))
.trackingNumber(trimToNull(detail.trackingNo))
// upstreamNo 是上游单据号;创建时传的 orderNo 会落在 sourceNo 上
.orderNo(firstNonBlank(detail.sourceNo, detail.upstreamNo))
.handleType(handleTypeOf(detail.handleType))
.rawStatus(trimToNull(detail.orderStatus))
.rawLogisticsStatus(trimToNull(detail.logisticsStatus))
.carrierCode(trimToNull(detail.carrierCode))
.carrierServiceCode(trimToNull(detail.carrierServiceCode))
.errorMessage(trimToNull(detail.errorMessage))
.upstreamNo(trimToNull(detail.upstreamNo))
.caseId(trimToNull(detail.caseId))
.completedAt(parseTime(detail.completeAt))
.build();
}
/** 恒健 handleType 1/2/3 → 核心枚举;认不出返回 null,不猜。 */
static TrackingChangeHandleType handleTypeOf(String raw) {
String v = trimToNull(raw);
if (v == null) {
return null;
}
switch (v) {
case "1":
return TrackingChangeHandleType.RECALL;
case "2":
return TrackingChangeHandleType.ADDRESS_CHANGE;
case "3":
return TrackingChangeHandleType.IN_TRANSIT_EXCEPTION;
default:
return null;
}
}
/** 解析 UTC 时间;格式不符返回 null,不因时间格式阻断整单。 */
static Instant parseTime(String value) {
String v = trimToNull(value);
if (v == null) {
return null;
}
try {
return LocalDateTime.parse(v, TIME_FORMAT).toInstant(ZoneOffset.UTC);
} catch (DateTimeParseException e) {
try {
return Instant.parse(v);
} catch (DateTimeParseException ignored) {
return null;
}
}
}
private static String firstNonBlank(String a, String b) {
String x = trimToNull(a);
return x != null ? x : trimToNull(b);
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String t = v.trim();
return t.isEmpty() ? null : t;
}
}

82
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeDtos.java

@ -0,0 +1,82 @@ @@ -0,0 +1,82 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 恒健报文结构:创建物流异动单({@code POST /v1/trackingChange/create})。
*
* <p><b>文档与实际不符(真机 2026-11-13 验证)</b>:</p>
* <ul>
* <li>文档把 {@code orderNo} 标成「否」,真机<b>必填</b>:不给会回
* {@code 物流异动单创建失败:来源单号不能为空}。</li>
* <li>真机还会校验「来源单号和 trackingNo 不匹配」——单号与运单必须属于同一张单。
* 所以探针必须用仓里真实存在的一对单号 + 运单号,随便编的会被这一步挡住。</li>
* <li>换址(2)的三项新收件人信息是真机必填,校验顺序是姓名 → 电话 → 地址。</li>
* <li>失败统一回 {@code code=999999}(<b>通用失败码</b>,不是认证专用码),
* 掩盖了具体原因,只看 message。</li>
* </ul>
*
* <p><b>未能确认</b>:{@code handleType} 文档标 STRING、示例给数字 {@code 2}。
* 真机用字符串和数字都试过,两种都被接收(都走到后续的业务校验),
* 所以<b>区分不出</b>类型要求。按示例发 Integer,真机若报类型错改成 String。</p>
*/
public final class HengjianTrackingChangeDtos {
private HengjianTrackingChangeDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CreateRequest {
/** 运单跟踪号;必填。 */
public String trackingNo;
/** 来源单号(我们下发的出库单号);<b>真机必填</b>,文档标「否」不可信。 */
public String orderNo;
/** 备注;必填。 */
public String remark;
/**
* 处理类型;必填。
*
* <p>1 召回 / 2 更换地址 / 3 在途异常。文档标 STRING、示例给数字;
* 真机两种都接受,按示例发数字。</p>
*/
public Integer handleType;
/** 新收件人姓名;{@code handleType=2} 时必填。 */
public String newRecipientName;
/** 新收件人电话;{@code handleType=2} 时必填。 */
public String newRecipientPhone;
/** 新收件人地址;{@code handleType=2} 时必填。 */
public String newRecipientAddress;
}
/** 创建响应:只回异动单号,没有状态。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CreateResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public CreateData data;
}
/** 创建响应 {@code data}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CreateData {
/** 仓方异动单号;查询与取消都用它。 */
@JsonProperty("trackingChangeOrderNo")
public String trackingChangeOrderNo;
}
}

164
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeQueryDtos.java

@ -0,0 +1,164 @@ @@ -0,0 +1,164 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 恒健报文结构:物流异动单查询({@code POST /v1/trackingChange/findOrder})。
*
* <p><b>路径纠正(真机 2026-11-13)</b>:文档页写的路径是 {@code /v1/saleOrder/findOrder},
* 但该路径真机返回 {@code 404 No handler found};正确路径是
* <b>{@code /v1/trackingChange/findOrder}</b>(与 create / cancel 同前缀)。
* 这是把 saleOrder 的路径误复制到了 trackingChange 的页面上。</p>
*
* <p>请求只收 {@code trackingChangeOrderNo};传 {@code orderNo} 等其它字段会被忽略并回
* 「物流异动单号不能为空」。</p>
*/
public final class HengjianTrackingChangeQueryDtos {
private HengjianTrackingChangeQueryDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class FindOrderRequest {
/** 仓方异动单号;必填。 */
public String trackingChangeOrderNo;
}
/** 响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class FindOrderResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public TrackingChangeDetail data;
}
/**
* 异动单详情。
*
* <p><b>注意</b>:文档给了完整字段表,但真机用无效单号查询时 {@code data} 是缺失的
* (成功码 + 只有 message),所以这里的每个字段都可能为 null。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TrackingChangeDetail {
/** 仓方异动单号。 */
@JsonProperty("trackingChangeOrderNo")
public String trackingChangeOrderNo;
/**
* 单据状态:0 草稿 / 1 待受理 / 2 受理中 / 3 已受理 / 4 受理成功 / 5 受理失败 / 6 取消。
*
* <p>文档标 INTEGER,用 String 接住——Jackson 会把数字转成文本,
* 万一仓方哪天改成字符串也不会炸。</p>
*/
@JsonProperty("orderStatus")
public String orderStatus;
/** 异常码:0 无异常 / 1 推送异常。 */
@JsonProperty("errorStatus")
public String errorStatus;
/** 异常信息。 */
@JsonProperty("errorMessage")
public String errorMessage;
/** 上游单据 id。 */
@JsonProperty("upstreamId")
public String upstreamId;
/** 上游单据号。 */
@JsonProperty("upstreamNo")
public String upstreamNo;
/** 跟踪号。 */
@JsonProperty("trackingNo")
public String trackingNo;
/**
* 物流状态:0 UNKNOWN / 1 PRE TRANSIT / 2 IN TRANSIT / 3 OUT FOR DELIVERY /
* 4 DELIVERED / 5 AVAILABLE FOR PICKUP / 6 RETURN TO SENDER / 7 FAILURE /
* 8 CANCELLED / 9 ERROR。
*/
@JsonProperty("logisticsStatus")
public String logisticsStatus;
/** 来源 id。 */
@JsonProperty("sourceId")
public String sourceId;
/** 来源单号。 */
@JsonProperty("sourceNo")
public String sourceNo;
/** 来源订单类型。 */
@JsonProperty("sourceOrderType")
public String sourceOrderType;
/** 仓库 id。 */
@JsonProperty("orgWarehouseId")
public String orgWarehouseId;
/** 仓库 code。 */
@JsonProperty("orgWarehouseCode")
public String orgWarehouseCode;
/** 承运商代码。 */
@JsonProperty("carrierCode")
public String carrierCode;
/** 承运商服务代码(发货方式)。 */
@JsonProperty("carrierServiceCode")
public String carrierServiceCode;
/** 处理类型:1 召回 / 2 更换地址 / 3 在途异常。 */
@JsonProperty("handleType")
public String handleType;
@JsonProperty("originalRecipientName")
public String originalRecipientName;
@JsonProperty("originalRecipientPhone")
public String originalRecipientPhone;
@JsonProperty("originalRecipientAddress")
public String originalRecipientAddress;
@JsonProperty("newRecipientName")
public String newRecipientName;
@JsonProperty("newRecipientPhone")
public String newRecipientPhone;
@JsonProperty("newRecipientAddress")
public String newRecipientAddress;
/** 承运商是否受理:1 否 / 2 是。 */
@JsonProperty("carrierIsAcceptance")
public String carrierIsAcceptance;
/** 承运商 CASE ID。 */
@JsonProperty("caseId")
public String caseId;
/** tracking 标记:0 -- / 1 召回中。 */
@JsonProperty("trackingLabel")
public String trackingLabel;
/** 客户备注。 */
@JsonProperty("customerRemark")
public String customerRemark;
/** 受理备注。 */
@JsonProperty("acceptanceRemark")
public String acceptanceRemark;
/** 完成时间;文档未写格式与单位,按原样保留。 */
@JsonProperty("completeAt")
public String completeAt;
}
}

30
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java

@ -108,8 +108,17 @@ public final class HengjianEnvelope { @@ -108,8 +108,17 @@ public final class HengjianEnvelope {
.retryable(false));
}
if (code == HengjianConstants.UNAUTHORIZED_CODE) {
throw new AuthException(base(operation, warehouseCode, requestId)
.message("hengjian unauthorized: code=" + code + ", message=" + messageOf(json, body))
// 999999 是仓方的**通用失败码**,不是认证专用码:空参数的建单 / 建异动单也回它。
// 只有 message 里出现授权字样时才按认证失败处理,否则宿主会为参数错误去刷新凭据。
if (mentionsAuth(messageOf(json, body))) {
throw new AuthException(base(operation, warehouseCode, requestId)
.message("hengjian unauthorized: code=" + code + ", message=" + messageOf(json, body))
.platformCode(String.valueOf(code))
.rawResponse(truncate(body))
.retryable(false));
}
throw new PlatformBusinessException(base(operation, warehouseCode, requestId)
.message("hengjian business error: code=" + code + ", message=" + messageOf(json, body))
.platformCode(String.valueOf(code))
.rawResponse(truncate(body))
.retryable(false));
@ -149,6 +158,23 @@ public final class HengjianEnvelope { @@ -149,6 +158,23 @@ public final class HengjianEnvelope {
return message != null && message.contains("未知的账户");
}
/**
* 业务码 999999 是否其实是认证失败。
*
* <p>真机观察:999999 是<b>通用失败码</b>,缺参数的业务校验也回它
* (如 {@code 物流异动单创建失败:来源单号不能为空});认证失败时 message 里会出现
* {@code Unauthorized} 或 {@code 未知的账户}。只看码会把参数错误误判成认证问题,
* 宿主就会白刷一次凭据。</p>
*/
private static boolean mentionsAuth(String message) {
if (message == null) {
return false;
}
String lower = message.toLowerCase(java.util.Locale.ROOT);
return lower.contains("unauthorized") || message.contains("未知的账户")
|| lower.contains("token") && lower.contains("invalid");
}
/** 业务提示语;恒健用 {@code message}。 */
private static String messageOf(JacksonJsonCodec json, String body) {
String message = json.stringAt(body, "message");

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

@ -0,0 +1,333 @@ @@ -0,0 +1,333 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TrackingChangeCommand;
import common.ecommerce.warehouse.model.TrackingChangeOrder;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 物流异动单({@code /v1/trackingChange/create} 与 {@code /v1/trackingChange/findOrder})契约测试。
*/
class HengjianTrackingChangeTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build()),
"req-1", CLOCK);
}
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
private static TrackingChangeCommand.Builder change() {
return TrackingChangeCommand.builder()
.changeRequestNo("TC-1")
.trackingNumber("1Z999AA10123456784")
.orderNo("OB-1")
.remark("客户要求召回")
.handleType(TrackingChangeHandleType.RECALL);
}
private static RecordingTransport creating() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_CREATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"OK\","
+ "\"data\":{\"trackingChangeOrderNo\":\"TC-ORDER-9\"}}"));
}
// ---------------------------------------------------------------- 创建
@Test
void createSendsPostToTrackingChangeCreate() {
RecordingTransport transport = creating();
adapter(transport).createChange(ctx(), change().build());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/trackingChange/create",
transport.lastDataRequest().url());
}
/** 真机确认的四个必填项都要出现。 */
@Test
void createSendsMandatoryFields() {
RecordingTransport transport = creating();
adapter(transport).createChange(ctx(), change().build());
String body = transport.lastDataRequest().body();
String[] mandatory = {"trackingNo", "orderNo", "remark", "handleType"};
for (String field : mandatory) {
assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body);
}
assertTrue(body.contains("\"trackingNo\":\"1Z999AA10123456784\""), body);
assertTrue(body.contains("\"orderNo\":\"OB-1\""), body);
// 文档标 STRING、示例给数字;按示例发数字
assertTrue(body.contains("\"handleType\":1"), body);
}
/** 换址:三项新收件人信息都要发。 */
@Test
void addressChangeSendsNewRecipientFields() {
RecordingTransport transport = creating();
adapter(transport).createChange(ctx(), change()
.handleType(TrackingChangeHandleType.ADDRESS_CHANGE)
.newRecipientName("New Name")
.newRecipientPhone("5550001111")
.newRecipientAddress("2 New St")
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"handleType\":2"), body);
assertTrue(body.contains("\"newRecipientName\":\"New Name\""), body);
assertTrue(body.contains("\"newRecipientPhone\":\"5550001111\""), body);
assertTrue(body.contains("\"newRecipientAddress\":\"2 New St\""), body);
}
/** 召回 / 在途异常不带新收件人字段。 */
@Test
void nonAddressChangeOmitsRecipientFields() {
RecordingTransport transport = creating();
adapter(transport).createChange(ctx(), change()
.handleType(TrackingChangeHandleType.IN_TRANSIT_EXCEPTION).build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"handleType\":3"), body);
assertFalse(body.contains("newRecipientName"), body);
assertFalse(body.contains("newRecipientPhone"), body);
assertFalse(body.contains("newRecipientAddress"), body);
}
// ---------------------------------------------------------------- 本地必填校验
/** orderNo 文档标「否」但真机必填:缺了本地就拒,不发出去被仓方挡回来。 */
@Test
void rejectsMissingOrderNo() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(creating()).createChange(ctx(), change().orderNo(null).build()));
assertTrue(ex.getMessage().contains("orderNo"), ex.getMessage());
}
@Test
void rejectsMissingRemark() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(creating()).createChange(ctx(), change().remark(null).build()));
assertTrue(ex.getMessage().contains("remark"), ex.getMessage());
}
/** 换址缺新收件人信息:逐个字段报出来,不笼统说「参数错」。 */
@Test
void rejectsAddressChangeWithoutRecipientFields() {
String[] fields = {"newRecipientName", "newRecipientPhone", "newRecipientAddress"};
for (String field : fields) {
TrackingChangeCommand.Builder b = change()
.handleType(TrackingChangeHandleType.ADDRESS_CHANGE)
.newRecipientName("N").newRecipientPhone("P").newRecipientAddress("A");
if ("newRecipientName".equals(field)) {
b.newRecipientName(null);
} else if ("newRecipientPhone".equals(field)) {
b.newRecipientPhone(null);
} else {
b.newRecipientAddress(null);
}
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(creating()).createChange(ctx(), b.build()), field);
assertTrue(ex.getMessage().contains(field), field + " -> " + ex.getMessage());
}
}
@Test
void noRequestSentWhenValidationFails() {
RecordingTransport transport = creating();
assertThrows(IllegalArgumentException.class,
() -> adapter(transport).createChange(ctx(), change().orderNo(null).build()));
assertTrue(transport.dataRequests().isEmpty());
}
/** 构造期就要求 changeRequestNo 与 trackingNumber。 */
@Test
void commandRequiresRequestNoAndTrackingNo() {
assertThrows(IllegalArgumentException.class,
() -> TrackingChangeCommand.builder()
.trackingNumber("T1").handleType(TrackingChangeHandleType.RECALL).build());
assertThrows(IllegalArgumentException.class,
() -> TrackingChangeCommand.builder()
.changeRequestNo("TC-1").handleType(TrackingChangeHandleType.RECALL).build());
assertThrows(NullPointerException.class,
() -> TrackingChangeCommand.builder()
.changeRequestNo("TC-1").trackingNumber("T1").build());
}
// ---------------------------------------------------------------- 响应
@Test
void createReturnsProviderChangeOrderNo() {
RecordingTransport transport = creating();
TrackingChangeOrder order = adapter(transport).createChange(ctx(), change().build());
assertEquals("TC-1", order.changeRequestNo());
assertEquals("TC-ORDER-9", order.providerChangeOrderNo());
assertEquals("1Z999AA10123456784", order.trackingNumber());
assertEquals(TrackingChangeHandleType.RECALL, order.handleType());
assertEquals(WarehouseProvider.HENGJIAN, order.sourceProvider());
// 创建接口不回状态:保持 null,不拿请求侧的值冒充
assertNull(order.rawStatus());
}
/** 没有异动单号不能当成功:后续查询 / 取消都要它。 */
@Test
void rejectsResponseWithoutChangeOrderNo() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_CREATE, req -> Responses.ok(
"{\"code\":200,\"message\":\"OK\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).createChange(ctx(), change().build()));
assertTrue(ex.getMessage().contains("trackingChangeOrderNo"), ex.getMessage());
}
/** 仓方业务失败(含真机那条「来源单号和trackingNo不匹配」)原样透出。 */
@Test
void businessErrorIsPropagated() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_CREATE, req -> Responses.ok(
"{\"statusCode\":500,\"status\":1,\"code\":999999,"
+ "\"message\":\"物流异动单创建失败:来源单号和trackingNo不匹配\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).createChange(ctx(), change().build()));
assertTrue(ex.getMessage().contains("来源单号和trackingNo不匹配"), ex.getMessage());
// 通用失败码不能当认证失败
assertFalse(ex instanceof common.ecommerce.shared.error.AuthException,
"999999 是通用失败码,不是认证失败");
}
// ---------------------------------------------------------------- 查询
private static final String QUERY_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"OK\",\"data\":{"
+ "\"trackingChangeOrderNo\":\"TC-ORDER-9\","
+ "\"orderStatus\":4,"
+ "\"logisticsStatus\":6,"
+ "\"trackingNo\":\"1Z999AA10123456784\","
+ "\"sourceNo\":\"OB-1\","
+ "\"orgWarehouseCode\":\"EFCA\","
+ "\"carrierCode\":\"UPS\","
+ "\"carrierServiceCode\":\"UPSG_HL\","
+ "\"handleType\":1,"
+ "\"caseId\":\"CASE-77\","
+ "\"completeAt\":\"2026-11-12 10:00:00\"}}";
private static RecordingTransport querying() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(QUERY_BODY));
}
/** 路径用 trackingChange 前缀,不是文档写的 saleOrder(真机 404)。 */
@Test
void queryUsesCorrectPathFromRealProbe() {
RecordingTransport transport = querying();
adapter(transport).getChange(ctx(), "TC-ORDER-9");
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/trackingChange/findOrder",
transport.lastDataRequest().url());
assertEquals("{\"trackingChangeOrderNo\":\"TC-ORDER-9\"}",
transport.lastDataRequest().body());
}
@Test
void queryMapsStatusFields() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertEquals("TC-ORDER-9", order.providerChangeOrderNo());
assertEquals("4", order.rawStatus(), "orderStatus 是异动单受理状态");
assertEquals("6", order.rawLogisticsStatus(), "logisticsStatus 是运单物流状态");
assertEquals(Boolean.TRUE, order.accepted());
assertFalse(order.failed());
assertFalse(order.cancelled());
assertEquals("OB-1", order.orderNo());
assertEquals("EFCA", order.warehouseCode());
assertEquals("UPS", order.carrierCode());
assertEquals("CASE-77", order.caseId());
assertEquals(TrackingChangeHandleType.RECALL, order.handleType());
assertEquals(Instant.parse("2026-11-12T10:00:00Z"), order.completedAt());
}
/** 两个状态各存各的:异动单已受理不代表运单已送达。 */
@Test
void statusAndLogisticsStatusAreIndependent() {
TrackingChangeOrder order = adapter(querying()).getChange(ctx(), "TC-ORDER-9");
assertTrue(order.accepted(), "异动单已受理");
assertEquals("6", order.rawLogisticsStatus(), "运单状态是 RETURN TO SENDER,不是「已送达」");
}
@Test
void failedAndCancelledStatuses() {
RecordingTransport failed = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\","
+ "\"orderStatus\":5,\"errorMessage\":\"承运商拒绝\"}}"));
assertTrue(adapter(failed).getChange(ctx(), "TC-1").failed());
RecordingTransport cancelled = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\","
+ "\"orderStatus\":6}}"));
assertTrue(adapter(cancelled).getChange(ctx(), "TC-1").cancelled());
}
@Test
void queryReturnsNullWhenDataMissing() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(
"{\"code\":200,\"message\":\"OK\"}"));
assertNull(adapter(transport).getChange(ctx(), "TC-NONE"));
}
/** 不认识的 handleType 归 null,不猜。 */
@Test
void unknownHandleTypeIsNotGuessed() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_TRACKING_CHANGE_FIND, req -> Responses.ok(
"{\"code\":200,\"data\":{\"trackingChangeOrderNo\":\"TC-1\","
+ "\"handleType\":9}}"));
assertNull(adapter(transport).getChange(ctx(), "TC-1").handleType());
}
// ---------------------------------------------------------------- 能力位
@Test
void declaresTrackingChangeCapability() {
assertTrue(adapter(RecordingTransport.create()).capabilities()
.contains(WarehouseCapability.TRACKING_CHANGE));
// 轨迹查询(TRACKING)是另一件事,恒健没接
assertFalse(adapter(RecordingTransport.create()).capabilities()
.contains(WarehouseCapability.TRACKING));
}
}

15
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java

@ -78,6 +78,21 @@ class HengjianEnvelopeTest { @@ -78,6 +78,21 @@ class HengjianEnvelopeTest {
}
/**
* 真机(2026-11-13):999999 是<b>通用失败码</b>,参数校验失败也回它。
*
* <p>不能见到 999999 就当认证失败——否则参数错误会让宿主白刷一次凭据。
* 只有 message 里出现授权字样才算。此处方法名沿用旧名以保持用例数不变。</p>
*/
@Test
void genericFailureCodeIsNotAuthFailure() {
PlatformBusinessException ex = assertThrows(PlatformBusinessException.class, () -> parse(ok(
"{\"statusCode\":500,\"status\":1,\"code\":999999,"
+ "\"message\":\"物流异动单创建失败:来源单号不能为空\"}")));
assertEquals("999999", ex.platformCode());
assertTrue(!ex.retryable());
}
/**
* 真机:只带一个授权头 / token 无效时 HTTP 500 + Spring 错误页。
* 消息虽是 500,根因是凭据,按认证失败处理,避免宿主无意义重试。
*/

152
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianTrackingChangeProbeTest.java

@ -0,0 +1,152 @@ @@ -0,0 +1,152 @@
package common.ecommerce.hengjian.probe;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.adapter.HengjianAdapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TrackingChangeCommand;
import common.ecommerce.warehouse.model.TrackingChangeOrder;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
import java.time.Clock;
/**
* 恒健物流异动单探针:查询 + 创建。
*
* <pre>
* mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
* -Dhengjian.probe=true -Dhengjian.probe.token=你的组织token \
* -Dhengjian.probe.changeOrderNo=仓方异动单号 \
* -Dtest=HengjianTrackingChangeProbeTest test
* </pre>
*
* <p><b>查询用例只读</b>,用 {@code -Dhengjian.probe.changeOrderNo}。
* <b>创建用例是写操作</b>,另需 {@code -Dhengjian.probe.write=true},
* 且必须同时给 {@code -Dhengjian.probe.orderNo} 与 {@code -Dhengjian.probe.trackingNo}
* 一对<b>仓里真实存在且互相匹配</b>的单号——仓方会校验「来源单号和 trackingNo 不匹配」,
* 编造的会被这一步挡住。</p>
*
* <p>真机已验证(2026-11-13,无 token):</p>
* <ul>
* <li>查询路径是 {@code /v1/trackingChange/findOrder},
* 文档写的 {@code /v1/saleOrder/findOrder} 返回 404;</li>
* <li>创建的四项必填是 {@code trackingNo / orderNo / remark / handleType},
* 其中 {@code orderNo} 文档标「否」,实际必填。</li>
* </ul>
*/
class HengjianTrackingChangeProbeTest {
private static final String PROBE = "hengjian.probe";
private static final String PROBE_WRITE = "hengjian.probe.write";
private static final String TOKEN = System.getProperty("hengjian.probe.token", "");
private static final String BASE_URL = opt("hengjian.probe.baseUrl", HengjianConstants.TEST_BASE_URL);
private static final String WAREHOUSE_CODE = opt("hengjian.probe.warehouseCode", "HJ-PROBE");
private static final String PROVIDER_WAREHOUSE = opt("hengjian.probe.providerWarehouseId", "EFCA");
private static String opt(String key, String fallback) {
String v = System.getProperty(key);
return v == null || v.trim().isEmpty() ? fallback : v.trim();
}
private static WarehouseContext ctx() {
return WarehouseContext.of(WAREHOUSE_CODE, WarehouseProvider.HENGJIAN, PROVIDER_WAREHOUSE,
WarehouseConnection.of(BASE_URL,
ChannelSecret.builder().appSecret(TOKEN.trim()).build()),
"probe-" + System.currentTimeMillis(), Clock.systemUTC());
}
private static HengjianAdapter adapter() {
return new HengjianAdapter(new OkHttpTransport("common-ecommerce-hengjian-probe"),
new JacksonJsonCodec());
}
private static void assumeToken() {
Assumptions.assumeTrue(!TOKEN.trim().isEmpty(),
"未提供 -Dhengjian.probe.token,跳过恒健异动单探针");
}
/** 查询异动单:验证文档路径是错的、正确路径能通。 */
@Test
@EnabledIfSystemProperty(named = PROBE, matches = "true")
void probeFindTrackingChange() {
assumeToken();
String changeNo = opt("hengjian.probe.changeOrderNo", "");
Assumptions.assumeTrue(!changeNo.isEmpty(),
"未提供 -Dhengjian.probe.changeOrderNo,跳过异动单查询探针");
System.out.println("\n================ hengjian / v1/trackingChange/findOrder ================");
System.out.println(" trackingChangeOrderNo=" + changeNo);
try {
TrackingChangeOrder order = adapter().getChange(ctx(), changeNo);
if (order == null) {
System.out.println(" [空] 未找到该异动单(data 缺失)");
return;
}
System.out.println(" [OK] orderStatus=" + order.rawStatus()
+ " logisticsStatus=" + order.rawLogisticsStatus()
+ " accepted=" + order.accepted()
+ " failed=" + order.failed()
+ " handleType=" + order.handleType()
+ " trackingNo=" + order.trackingNumber()
+ " caseId=" + order.caseId()
+ " completeAt=" + order.completedAt());
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage());
}
}
/**
* 创建异动单:<b>写操作</b>,会向承运商真实提工单。
*
* <p>需要一对真实匹配的单号 + 运单号,否则仓方回「来源单号和trackingNo不匹配」。</p>
*/
@Test
@EnabledIfSystemProperty(named = PROBE_WRITE, matches = "true")
void probeCreateTrackingChange() {
assumeToken();
String orderNo = opt("hengjian.probe.orderNo", "");
String trackingNo = opt("hengjian.probe.trackingNo", "");
Assumptions.assumeTrue(!orderNo.isEmpty() && !trackingNo.isEmpty(),
"未提供 -Dhengjian.probe.orderNo / trackingNo,跳过异动单创建探针");
TrackingChangeHandleType type = handleTypeOf(opt("hengjian.probe.handleType", "RECALL"));
System.out.println("\n================ hengjian / v1/trackingChange/create ================");
System.out.println(" orderNo=" + orderNo + " trackingNo=" + trackingNo
+ " handleType=" + type);
try {
TrackingChangeOrder order = adapter().createChange(ctx(),
TrackingChangeCommand.builder()
.changeRequestNo("PROBE-TC-" + System.currentTimeMillis())
.trackingNumber(trackingNo)
.orderNo(orderNo)
.remark("SDK 探针,可忽略")
.handleType(type)
// 换址时必须给三项;其它类型会被适配器忽略
.newRecipientName(opt("hengjian.probe.newRecipientName", ""))
.newRecipientPhone(opt("hengjian.probe.newRecipientPhone", ""))
.newRecipientAddress(opt("hengjian.probe.newRecipientAddress", ""))
.build());
System.out.println(" [OK] trackingChangeOrderNo=" + order.providerChangeOrderNo());
System.out.println(" ← 创建只代表申请已提交,受理结果要再查一次 findOrder");
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage());
}
}
private static TrackingChangeHandleType handleTypeOf(String raw) {
if ("ADDRESS_CHANGE".equalsIgnoreCase(raw) || "2".equals(raw)) {
return TrackingChangeHandleType.ADDRESS_CHANGE;
}
if ("IN_TRANSIT_EXCEPTION".equalsIgnoreCase(raw) || "3".equals(raw)) {
return TrackingChangeHandleType.IN_TRANSIT_EXCEPTION;
}
return TrackingChangeHandleType.RECALL;
}
}
Loading…
Cancel
Save