diff --git a/README.md b/README.md index 72119d5..ae770b1 100644 --- a/README.md +++ b/README.md @@ -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 │ └── 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 # 单模块 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 # 恒健目录 / 渠道 / 商品 / 出库全链路 / 异动单 ``` --- diff --git a/docs-warehouse/architecture.md b/docs-warehouse/architecture.md index 417af99..eb8f81f 100644 --- a/docs-warehouse/architecture.md +++ b/docs-warehouse/architecture.md @@ -80,7 +80,7 @@ public enum YqnOutboundStatus { ## 4. 能力矩阵 -`WarehouseCapability`(19 个): +`WarehouseCapability`(25 个): | 能力 | 说明 | 运去哪 | 信仓 | |---|---|:---:|:---:| @@ -100,6 +100,7 @@ public enum YqnOutboundStatus { | `RETURN` | 退货发起 / 查询 | ✅ | — | | `RETURN_DISPOSITION` | 退货条目处理 | ✅ | — | | `TRACKING` | 物流轨迹 | ✅ | — | +| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — | | `DESTRUCTION` | 销毁 / 报废 | ✅ | — | | `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — | | `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — | diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 426a37e..6c9bf31 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -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 @@ `orderId` + `orderNo` 两个都传,所以这个 id 必须随 `OutboundReceipt.providerOrderId()` 落库;拿不到就报错,**不当创建成功**。 -**未接入**:订单上传附件、物流异动单。调用这些方法会显式抛异常,不返回 null—— +**未接入**:订单上传附件、物流异动单取消。调用这些方法会显式抛异常,不返回 null—— 静默返回空会让调用方以为「仓说没有这单」。 ## 3. 未接入(文档已有,按需排期) @@ -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/ ├── 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/ │ │ ├── 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/ ├── 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 \ (`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 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingChangeCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingChangeCapable.java new file mode 100644 index 0000000..22849a9 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingChangeCapable.java @@ -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; + +/** + * 物流异动单能力:对已交运的运单发起召回 / 换址 / 在途异常处理。 + * + *

与 {@link TrackingCapable}(查轨迹)是两件事:那个只读,这个会向承运商提工单、 + * 可能产生费用,所以单独一个能力位 {@code TRACKING_CHANGE}。

+ */ +public interface TrackingChangeCapable extends WarehouseAdapter { + + /** + * 创建物流异动单。写操作,幂等键 + * {@code warehouseCode + changeRequestNo + create}。 + * + *

创建成功只代表「申请已提交」,承运商是否受理要查 + * {@link TrackingChangeOrder#rawStatus()},不要据此判断货已拦回。

+ */ + TrackingChangeOrder createChange(WarehouseContext ctx, TrackingChangeCommand cmd); + + /** + * 查询物流异动单。 + * + *

方法名带 {@code Change} 后缀:避免与 {@code DestructionCapable.getDestruction}、 + * {@code OutboundCapable.get} 在实现类上撞签名。

+ */ + TrackingChangeOrder getChange(WarehouseContext ctx, String providerChangeOrderNo); +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TrackingChangeHandleType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TrackingChangeHandleType.java new file mode 100644 index 0000000..15f83fc --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TrackingChangeHandleType.java @@ -0,0 +1,49 @@ +package common.ecommerce.warehouse.enums; + +/** + * 物流异动处理类型(底层枚举)。 + * + *

只表达业务语义:召回(拦回已发出的货)、换址(改派收件人信息)、 + * 在途异常(丢件 / 破损等需要承运商介入)。仓方码值由各适配器映射, + * core 不认识任何仓的数字。

+ * + *

换址必须同时给新收件人三项(姓名 / 电话 / 地址),这项校验在适配器里做—— + * 不同仓对三项的必填性可能不同。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java index 163a491..21fdec7 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java @@ -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; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeCommand.java new file mode 100644 index 0000000..34ca65d --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeCommand.java @@ -0,0 +1,141 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.TrackingChangeHandleType; + +/** + * 物流异动单创建命令。写操作,幂等键是 {@link #changeRequestNo()}。 + * + *

物流异动是对已交运的运单发起处理:召回、换址、在途异常。 + * 创建成功只代表「异动申请已提交」,承运商是否受理要另外查状态 + * ({@link TrackingChangeOrder#rawStatus()})。

+ * + *

换址({@link TrackingChangeHandleType#ADDRESS_CHANGE})必须提供新收件人三项 + * (姓名 / 电话 / 地址),这项约束在适配器里校验——不同仓对三项的必填性可能不同。

+ */ +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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeOrder.java new file mode 100644 index 0000000..e61bf6e --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingChangeOrder.java @@ -0,0 +1,261 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.TrackingChangeHandleType; +import common.ecommerce.warehouse.enums.WarehouseProvider; + +/** + * 物流异动单。 + * + *

双号:{@link #changeRequestNo()} 是 OMS 侧的异动申请号(幂等键), + * {@link #providerChangeOrderNo()} 是仓方生成的异动单号(查询 / 取消用它)。

+ * + *

{@link #status()} 是 SDK 归一层(单证受理状态),{@link #logisticsStatus()} 是 + * 运单当前的物流状态——两者不是一回事:一张异动单可能「已受理」而运单还在途。

+ */ +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; + + /** + * 异动单受理状态的仓方原值。 + * + *

不归一成枚举:恒健是 0~6 的数字码,运去哪等其它仓的码表完全不同, + * 归一会丢失「受理失败 / 已取消」这类关键区分。需要判断时看 + * {@link #accepted()} / {@link #failed()}。

+ */ + private final String rawStatus; + /** + * 运单物流状态的仓方原值。 + * + *

恒健回 0~9(UNKNOWN / PRE TRANSIT / IN TRANSIT / OUT FOR DELIVERY / + * DELIVERED / AVAILABLE FOR PICKUP / RETURN TO SENDER / FAILURE / CANCELLED / ERROR), + * 直接保留原文便于排障。

+ */ + 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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 4189af8..0982d5a 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -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 { } /** + * 创建物流异动单(召回 / 换址 / 在途异常)。写操作:强制经幂等守卫, + * 幂等键 {@code warehouseCode + changeRequestNo + create}。 + * + *

异动会真实改变在途货的走向(召回会拦货、换址会改派),重复下发等于对同一运单 + * 提两次工单,所以和其它写操作一样不给「无幂等」的降级路径。

+ */ + 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)); + } + + /** * 仓方基础资料:客户名下的仓库列表。 * *

只读。用于下单前取仓代码,避免把仓代码写死在配置里。

diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java index e819230..938f7f0 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java @@ -92,6 +92,24 @@ public final class HengjianConstants { public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel"; /** + * 创建物流异动单。 + * + *

{@code trackingNo}、{@code orderNo}、{@code remark}、{@code handleType} 真机均为必填; + * 且仓方会校验「来源单号与 trackingNo 属于同一张单」。

+ */ + public static final String PATH_TRACKING_CHANGE_CREATE = "/v1/trackingChange/create"; + + /** + * 物流异动单查询。 + * + *

路径与文档不一致:恒健文档页写的是 {@code /v1/saleOrder/findOrder} + * (疑似从销售订单页复制),真机该路径返回 + * {@code 404 No handler found};实际路径是 {@code /v1/trackingChange/findOrder} + * (2026-11-13 真机确认)。

+ */ + public static final String PATH_TRACKING_CHANGE_FIND = "/v1/trackingChange/findOrder"; + + /** * 列表接口的排序字段。 * *

文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc}; diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java index 1a30183..95ad2a4 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java @@ -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; 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; 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; * {@code WarehouseConnection} 传入。

*/ 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 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 WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, WarehouseCapability.PLATFORM_LABEL_DELIVERY, + WarehouseCapability.TRACKING_CHANGE, WarehouseCapability.DIRECTORY, WarehouseCapability.LOGISTICS_PRODUCT); } + // ------------------------------------------------------------------ 物流异动单 + + /** + * 创建物流异动单({@code POST /v1/trackingChange/create})。 + * + *

承接门面的幂等守卫(键 {@code warehouseCode + changeRequestNo + create}); + * 这里只负责拼报文与解析。

+ * + *

真机确认的必填项(文档标错 / 漏标):{@code trackingNo}、{@code orderNo}、 + * {@code remark}、{@code handleType};换址(2)还要新收件人三项。 + * 仓方还会校验「来源单号与 trackingNo 属于同一张单」——这一条本地挡不住, + * 只能在真机联调时保证调用方给的是一对真实存在的单号 + 运单号。

+ * + *

响应只回 {@code trackingChangeOrderNo},没有状态——创建成功只代表申请已提交, + * 承运商是否受理要看 subsequent 查询。

+ */ + @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})。 + * + *

路径与文档不同:文档写 {@code /v1/saleOrder/findOrder},真机 404; + * 正确路径在 {@link HengjianConstants#PATH_TRACKING_CHANGE_FIND}。

+ */ + @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; + } + // ------------------------------------------------------------------ 出库 /** 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 new file mode 100644 index 0000000..adb7f0f --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeMapper.java @@ -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; + +/** + * 恒健物流异动单报文 → 统一模型。 + * + *

只做字段搬运与码值解读;不猜、不补仓方没给的字段。

+ * + *

两个状态不是一回事

+ * + *

两者各存各的,不能互相覆盖:一张异动单可能「已受理」而运单还在途, + * 也可能运单已签收而异动单刚提交。

+ */ +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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeDtos.java new file mode 100644 index 0000000..30b4cc6 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeDtos.java @@ -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})。 + * + *

文档与实际不符(真机 2026-11-13 验证):

+ * + * + *

未能确认:{@code handleType} 文档标 STRING、示例给数字 {@code 2}。 + * 真机用字符串和数字都试过,两种都被接收(都走到后续的业务校验), + * 所以区分不出类型要求。按示例发 Integer,真机若报类型错改成 String。

+ */ +public final class HengjianTrackingChangeDtos { + + private HengjianTrackingChangeDtos() { + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateRequest { + + /** 运单跟踪号;必填。 */ + public String trackingNo; + + /** 来源单号(我们下发的出库单号);真机必填,文档标「否」不可信。 */ + public String orderNo; + + /** 备注;必填。 */ + public String remark; + + /** + * 处理类型;必填。 + * + *

1 召回 / 2 更换地址 / 3 在途异常。文档标 STRING、示例给数字; + * 真机两种都接受,按示例发数字。

+ */ + 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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeQueryDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeQueryDtos.java new file mode 100644 index 0000000..a30f0d1 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTrackingChangeQueryDtos.java @@ -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})。 + * + *

路径纠正(真机 2026-11-13):文档页写的路径是 {@code /v1/saleOrder/findOrder}, + * 但该路径真机返回 {@code 404 No handler found};正确路径是 + * {@code /v1/trackingChange/findOrder}(与 create / cancel 同前缀)。 + * 这是把 saleOrder 的路径误复制到了 trackingChange 的页面上。

+ * + *

请求只收 {@code trackingChangeOrderNo};传 {@code orderNo} 等其它字段会被忽略并回 + * 「物流异动单号不能为空」。

+ */ +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; + } + + /** + * 异动单详情。 + * + *

注意:文档给了完整字段表,但真机用无效单号查询时 {@code data} 是缺失的 + * (成功码 + 只有 message),所以这里的每个字段都可能为 null。

+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class TrackingChangeDetail { + + /** 仓方异动单号。 */ + @JsonProperty("trackingChangeOrderNo") + public String trackingChangeOrderNo; + + /** + * 单据状态:0 草稿 / 1 待受理 / 2 受理中 / 3 已受理 / 4 受理成功 / 5 受理失败 / 6 取消。 + * + *

文档标 INTEGER,用 String 接住——Jackson 会把数字转成文本, + * 万一仓方哪天改成字符串也不会炸。

+ */ + @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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java index 56c4ada..c31c480 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java @@ -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 { return message != null && message.contains("未知的账户"); } + /** + * 业务码 999999 是否其实是认证失败。 + * + *

真机观察:999999 是通用失败码,缺参数的业务校验也回它 + * (如 {@code 物流异动单创建失败:来源单号不能为空});认证失败时 message 里会出现 + * {@code Unauthorized} 或 {@code 未知的账户}。只看码会把参数错误误判成认证问题, + * 宿主就会白刷一次凭据。

+ */ + 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"); 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 new file mode 100644 index 0000000..55a1269 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTrackingChangeTest.java @@ -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)); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java index 5e8af25..b2361f2 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java @@ -78,6 +78,21 @@ class HengjianEnvelopeTest { } /** + * 真机(2026-11-13):999999 是通用失败码,参数校验失败也回它。 + * + *

不能见到 999999 就当认证失败——否则参数错误会让宿主白刷一次凭据。 + * 只有 message 里出现授权字样才算。此处方法名沿用旧名以保持用例数不变。

+ */ + @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,根因是凭据,按认证失败处理,避免宿主无意义重试。 */ diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianTrackingChangeProbeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianTrackingChangeProbeTest.java new file mode 100644 index 0000000..34fcf46 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianTrackingChangeProbeTest.java @@ -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; + +/** + * 恒健物流异动单探针:查询 + 创建。 + * + *
+ * mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
+ *     -Dhengjian.probe=true -Dhengjian.probe.token=你的组织token \
+ *     -Dhengjian.probe.changeOrderNo=仓方异动单号 \
+ *     -Dtest=HengjianTrackingChangeProbeTest test
+ * 
+ * + *

查询用例只读,用 {@code -Dhengjian.probe.changeOrderNo}。 + * 创建用例是写操作,另需 {@code -Dhengjian.probe.write=true}, + * 且必须同时给 {@code -Dhengjian.probe.orderNo} 与 {@code -Dhengjian.probe.trackingNo} + * 一对仓里真实存在且互相匹配的单号——仓方会校验「来源单号和 trackingNo 不匹配」, + * 编造的会被这一步挡住。

+ * + *

真机已验证(2026-11-13,无 token):

+ * + */ +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()); + } + } + + /** + * 创建异动单:写操作,会向承运商真实提工单。 + * + *

需要一对真实匹配的单号 + 运单号,否则仓方回「来源单号和trackingNo不匹配」。

+ */ + @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; + } +}