Browse Source

feat(hengjian): 对接订单取消 /v1/saleOrder/cancel

- 新增 HengjianCancelOrderDtos,实现 OutboundCapable.cancel
- 恒健要求 orderId + orderNo 双键必填,统一模型允许只给一个:
  缺哪个先用列表接口补(详情不回 orderId),补不到则本地拒绝,
  不发必然被仓方拒的取消请求
- 列表补回的结果逐条精确比对单号 / id 才用,避免近似结果取消错单
- orderId 用 Long(文档标 INTEGER,九位 id 用 int 会静默错单)
- 仓方拒绝取消抛 OutboundCancelBlockedException;认证失败不包装成不可取消
- checkCancel 把 UNKNOWN 也判 BLOCKED,认不出的状态不凭猜下写请求
- 移除已无调用方的 unsupportedOutbound 辅助方法
- 写探针补取消与取消预判用例(需 -Dhengjian.probe.cancelOrderNo)

验证:mvn test 全量通过,恒健 109 个用例 + 2 个探针跳过。

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 1 week ago
parent
commit
5fe33db101
  1. 9
      README.md
  2. 65
      docs-warehouse/hengjian/README.md
  3. 9
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  4. 147
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  5. 29
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCancelOrderDtos.java
  6. 12
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java
  7. 218
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCancelOrderTest.java
  8. 55
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java

9
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,12 +376,13 @@ common.ecommerce @@ -376,12 +376,13 @@ common.ecommerce
│
└── hengjian 恒健三方仓(warehouse-sdk-hengjian)
├── HengjianConstants 测试基址、当前接入路径、双授权头名、成功码 / 未授权码、限流
├── adapter HengjianAdapter(目录 + 渠道 + 商品保存 + 出库下单 / 详情 / 列表 / 包裹)/
├── adapter HengjianAdapter(目录 + 渠道 + 商品 + 出库下单 / 详情 / 列表 / 取消 / 包裹)/
│ HengjianAdapterFactory / HengjianDirectoryMapper /
│ HengjianProductMapper / HengjianOutboundMapper / HengjianOrderMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos
│ HengjianOrderDetailDtos / HengjianOrderListDtos /
│ HengjianCancelOrderDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter
@ -1078,7 +1079,7 @@ mvn -pl lingxing test # 单模块 @@ -1078,7 +1079,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 # 恒健目录 / 渠道 / 商品 / 下单 / 查询 / 取消
```
---

65
docs-warehouse/hengjian/README.md

@ -166,7 +166,7 @@ @@ -166,7 +166,7 @@
`orderId` + `orderNo` 两个都传,所以这个 id 必须随 `OutboundReceipt.providerOrderId()`
落库;拿不到就报错,**不当创建成功**。
**未接入**:查询 / 取消 / 包裹。调用这些方法会显式抛 `WarehouseException`,不返回 null——
**未接入**:订单上传附件、物流异动单。调用这些方法会显式抛异常,不返回 null——
静默返回空会让调用方以为「仓说没有这单」。
## 3. 未接入(文档已有,按需排期)
@ -180,7 +180,7 @@ @@ -180,7 +180,7 @@
| 创建销售发货单(中文页「带附件」/ 英文页 "With Label",同路径) | `POST /v1/saleOrder/create` → `data.orderId` | ✅ 已接入 |
| 订单详情 | `POST /v1/saleOrder/findOne` | ✅ 已接入 |
| 订单列表 | `GET /v1/saleOrder/findByPage` | ✅ 已接入 |
| 订单取消 | `POST /v1/saleOrder/cancel`(`orderId` + `orderNo` 都必填) | ⬜ |
| 订单取消 | `POST /v1/saleOrder/cancel`(`orderId` + `orderNo` 都必填) | ✅ 已接入 |
| 订单上传附件 | `POST /v1/saleOrder/createAttachment` | ⬜ |
| 物流异动单 创建 / 查询 / 取消 | `POST /v1/trackingChange/create`、`POST /v1/saleOrder/findOrder`、`POST /v1/trackingChange/cancel` | ⬜ |
@ -213,11 +213,6 @@ @@ -213,11 +213,6 @@
是否末页以仓方 `last` 为准。
- 列表独有 `amount`(整单销售金额)落 `totalAmount`;`taxPrice` 统一模型无对应字段,不落。
#### 取消预判(`checkCancel`)
恒健没有独立的预判接口,按详情状态推断:`shipped` / `canceled` / `refunded` / `deleted`
判 `BLOCKED`,其余 `FREE`。**查不到单时也判 BLOCKED**——猜成 FREE 会发出注定被拒的取消。
#### 包裹(`packages`)
恒健没有独立包裹接口,从详情 `shipmentPackages` 提取。按 `trackingNo` 去重
@ -244,11 +239,32 @@ @@ -244,11 +239,32 @@
**精确匹配**,不用 `contains`;`unshipped` 与 `shipped` 是前缀关系,
用子串判断会把未发货判成交运。
#### 待接:取消
#### 订单取消(`/v1/saleOrder/cancel`)
`POST /v1/saleOrder/cancel` 要 `orderId` + `orderNo` 两个都传,目前 `cancel()`
显式抛不支持异常。接入时注意:`orderId` 只有**创建响应**与**列表接口**给,
详情接口不给。
恒健要求 **`orderId` + `orderNo` 两个都传**,而统一模型的 `CancelCommand` 允许只给一个。
适配器的处理:
| 给了什么 | 行为 |
|---|---|
| `outboundRequestNo` + `providerOrderId` | 直接用,只发一次取消请求 |
| 只有 `outboundRequestNo` | 先按 `orderNos` 查列表补 `orderId`,再取消 |
| 只有 `providerOrderId` | 先按 `orderIds` 查列表补 `orderNo`,再取消 |
| 两个都没有 | 构造期就拒绝 |
| 列表补不到(仓里没有这单) | **本地拒绝**,不发必然被拒的取消请求 |
- 列表查回来的结果要**逐条精确比对**单号 / id 之后才用——`orderNos` 是否精确匹配文档没写,
拿近似结果去取消会取消错单。
- `orderId` 用 `Long`(文档标 INTEGER):九位数的 id 用 int 迟早出事,溢出是静默错单。
- 恒健没有取消费概念,`CancelCommand.acceptCharge()` 不生效。
- 仓方拒绝取消 → `OutboundCancelBlockedException`;**认证失败不会被包装**成不可取消,
否则宿主不会去刷新凭据。
#### 取消预判(`checkCancel`)
恒健没有独立的预判接口,按详情状态推断:`shipped` / `canceled` / `refunded` / `deleted`
以及 **`UNKNOWN`** 判 `BLOCKED`,其余 `FREE`。查不到单时也判 `BLOCKED`——
猜成 FREE 会发出注定被拒的取消。`UNKNOWN` 一并挡住,是因为恒健的词表将来可能加值,
认不出时不该凭猜下写请求。
### 库存(`INVENTORY_QUERY`)
@ -305,7 +321,7 @@ warehouse-sdk-hengjian/ @@ -305,7 +321,7 @@ warehouse-sdk-hengjian/
├── main/java/common/ecommerce/hengjian/
│ ├── HengjianConstants.java 端点 / 路径 / 两个授权头 / 成功码 / 未授权码 / 限流
│ ├── adapter/
│ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品保存 + 出库下单 / 详情 / 列表 / 包裹
│ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品 + 下单 / 详情 / 列表 / 包裹 / 取消
│ │ ├── HengjianAdapterFactory.java
│ │ ├── HengjianDirectoryMapper.java 仓库 / 渠道字段搬运
│ │ ├── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验
@ -317,7 +333,8 @@ warehouse-sdk-hengjian/ @@ -317,7 +333,8 @@ warehouse-sdk-hengjian/
│ │ ├── HengjianProductSaveDtos.java /v1/product/save
│ │ ├── HengjianCreateOrderDtos.java /v1/saleOrder/create
│ │ ├── HengjianOrderDetailDtos.java /v1/saleOrder/findOne
│ │ └── HengjianOrderListDtos.java /v1/saleOrder/findByPage
│ │ ├── HengjianOrderListDtos.java /v1/saleOrder/findByPage
│ │ └── HengjianCancelOrderDtos.java /v1/saleOrder/cancel
│ ├── enums
│ │ ├── HengjianOrderStatus.java orderStatusEnum → OutboundStatus
│ │ └── package-info.java 其余状态枚举约定(待建)
@ -331,13 +348,14 @@ warehouse-sdk-hengjian/ @@ -331,13 +348,14 @@ warehouse-sdk-hengjian/
├── adapter/HengjianProductSaveTest.java 20 个:必填拒绝 / 三组尺寸 / 不编造字段
├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝
├── adapter/HengjianOrderQueryTest.java 25 个:详情映射 / 列表分页 / 时间窗 / 包裹去重 / 枚举
├── adapter/HengjianCancelOrderTest.java 10 个:双键补齐 / 精确匹配 / 拒绝路径 / 预判
├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举
├── http/HengjianEnvelopeTest.java 11 个:三种信封形态 + 错误路径
├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true
```
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(99 个 + 2 个跳过)。
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(109 个 + 2 个跳过)。
## 5. 探针用法
@ -366,14 +384,18 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ @@ -366,14 +384,18 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
-Dhengjian.probe.token=<组织token> \
-Dhengjian.probe.sku=PROBE-SKU-001 \
-Dhengjian.probe.postcode=90001 \
-Dhengjian.probe.cancelOrderNo=<要取消的探针单号> \
-Dtest=HengjianWriteProbeTest test
```
- 两个开关同时打开才跑;SKU 默认带时间戳,重跑不撞唯一约束。
- 3 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)、建销售发货单
(需额外给 `-Dhengjian.probe.postcode`;可选 `carrierCode` / `shopName` / `state` / `city`)。
- 5 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)、建销售发货单、
取消订单、取消预判。
- 建单需 `-Dhengjian.probe.postcode`(可选 `carrierCode` / `shopName` / `state` / `city`);
- 取消与预判需 `-Dhengjian.probe.cancelOrderNo`,取消只在给了单号时执行
(验证「只给单号自动补 orderId」这条路)。
- **恒健没有删除产品的接口**,跑完需要人工在 Efulfill 后台清理;
建单探针也不自动取消——取消接口尚未接入。
**取消探针会真实取消一张单**,只对测试环境的探针单用。
## 6. 待确认(交给业务方 / 恒健)
@ -400,9 +422,10 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ @@ -400,9 +422,10 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
1. 拿到 token 后跑 `HengjianReadOnlyProbeTest` 与 `HengjianWriteProbeTest`,把结论补进本文档
「文档与实际不一致」表;重点验商品保存的必填组合、保存语义、建单的必填组合与 `orderId` 回传、
详情 / 列表的分页与时间口径。
详情 / 列表的分页与时间口径、取消的双键与预判。
2. 按 [onboarding-checklist.md](../onboarding-checklist.md) 阶段 2 逐接口接入,建议顺序:
**订单取消 → 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2**。
**库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2 → 订单上传附件 / 物流异动单**。
3. 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
4. 接取消(`/v1/saleOrder/cancel`)时注意:`orderId` 只有**创建响应**与**列表接口**给,
详情不给;只拿到单号时要先查一次列表补 id。
出库子能力到此全部接完(下单 / 详情 / 列表 / 取消 / 预判 / 包裹)。剩下与出库相关的是
订单上传附件与物流异动单,都不影响主链路,按需排期。

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

@ -83,6 +83,15 @@ public final class HengjianConstants { @@ -83,6 +83,15 @@ public final class HengjianConstants {
public static final String PATH_ORDER_FIND_BY_PAGE = "/v1/saleOrder/findByPage";
/**
* 订单取消。
*
* <p><b>{@code orderId} 与 {@code orderNo} 都必填</b>。{@code orderId} 只有两条来路:
* 创建接口的响应、列表接口的行。详情接口不回它,所以只拿到单号时,
* 取消前要先用列表接口补一次 id。</p>
*/
public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel";
/**
* 列表接口的排序字段。
*
* <p>文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc};

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

@ -2,6 +2,7 @@ package common.ecommerce.hengjian.adapter; @@ -2,6 +2,7 @@ package common.ecommerce.hengjian.adapter;
import com.fasterxml.jackson.databind.JsonNode;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.dto.HengjianCancelOrderDtos;
import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos;
import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos;
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos;
@ -15,6 +16,7 @@ import common.ecommerce.http.HttpRequest; @@ -15,6 +16,7 @@ import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
@ -25,6 +27,7 @@ import common.ecommerce.warehouse.enums.CancelEligibility; @@ -25,6 +27,7 @@ import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelResult;
@ -68,6 +71,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -68,6 +71,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
private static final String OP_ORDER_CREATE = "warehouse.outbound.create";
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";
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
@ -239,7 +243,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -239,7 +243,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
/**
* 取消资格预判:查详情按状态推断。
*
* <p>恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款不再接受取消,
* <p>恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款 / 已删除不再接受取消,
* 判为 {@link CancelEligibility#BLOCKED};其余交给取消时仓方判定。</p>
*
* <p>查不到单时返回 BLOCKED,不猜 FREE——猜错会下发出一个注定被拒的取消。</p>
@ -255,15 +259,140 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -255,15 +259,140 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
case CANCELLED:
case REFUNDED:
case DELETED:
case UNKNOWN:
// UNKNOWN 也判 BLOCKED:恒健的状态词表将来可能加值,
// 认不出时不该凭猜下发取消
return CancelEligibility.BLOCKED;
default:
return CancelEligibility.FREE;
}
}
/**
* 取消订单({@code POST /v1/saleOrder/cancel})。
*
* <p>恒健要求 {@code orderId} 与 {@code orderNo} <b>两个都传</b>,而统一模型的
* {@link CancelCommand} 允许只给其中一个。约定:</p>
* <ul>
* <li>{@code outboundRequestNo} → 恒健 {@code orderNo};</li>
* <li>{@code providerOrderId} → 恒健 {@code orderId}(仓内部数字 id)。</li>
* </ul>
* <p>缺哪个就用已知的那个去<b>列表接口</b>补一次——这是拿到 {@code orderId} 的正规途径
* (详情接口不回它)。补不到(仓里没有这张单)直接报参数错误,
* <b>不发</b>必然被仓方拒的取消请求。</p>
*
* <p>恒健没有取消费概念,{@link CancelCommand#acceptCharge()} 在这里不生效。
* 仓方拒绝取消时抛 {@link OutboundCancelBlockedException},与参数错误区分开。</p>
*/
@Override
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) {
throw unsupportedOutbound("warehouse.outbound.cancel", ctx);
String orderNo = trimToNull(cmd.outboundRequestNo());
Long orderId = parseOrderId(cmd.providerOrderId());
if (orderNo == null && orderId == null) {
throw new IllegalArgumentException(
"hengjian needs outboundRequestNo or providerOrderId to cancel an order");
}
if (orderNo == null || orderId == null) {
HengjianOrderListDtos.OrderRow row = findRow(ctx, orderNo, orderId);
if (row == null) {
throw validation(ctx, OP_ORDER_CANCEL,
"hengjian order not found, cannot resolve " + (orderNo == null ? "orderNo" : "orderId")
+ " for " + (orderNo != null ? orderNo : String.valueOf(orderId)));
}
if (orderNo == null) {
orderNo = trimToNull(row.orderNo);
}
if (orderId == null && row.orderId != null) {
orderId = row.orderId;
}
}
if (orderNo == null || orderId == null) {
throw validation(ctx, OP_ORDER_CANCEL,
"hengjian cancel requires both orderId and orderNo; "
+ "could not resolve " + (orderNo == null ? "orderNo" : "orderId"));
}
HengjianCancelOrderDtos.CancelOrderRequest body = new HengjianCancelOrderDtos.CancelOrderRequest();
body.orderId = orderId;
body.orderNo = orderNo;
String raw;
try {
raw = execute(ctx, HengjianConstants.PATH_ORDER_CANCEL, body, OP_ORDER_CANCEL);
} catch (PlatformBusinessException e) {
// 取消失败只有 message,无法细分原因;取消场景统一按「不可取消」表达
throw new OutboundCancelBlockedException(WarehouseException.builder()
.message("hengjian refused cancellation: " + e.getMessage())
.operation(OP_ORDER_CANCEL)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.platformCode(e.platformCode())
.rawResponse(e.rawResponse())
.retryable(false));
}
return CancelResult.builder()
.outboundRequestNo(orderNo)
.providerOrderId(String.valueOf(orderId))
.eligibility(CancelEligibility.FREE)
.cancelled(true)
.rawStatus(json.stringAt(raw, "message"))
.build();
}
/**
* 按单号或订单 id 查一行,用于补全取消需要的另一个键。
*
* <p>只认<b>精确匹配</b>:列表接口的 {@code orderNos} / {@code orderIds} 过滤是否精确
* 文档没说,取回来再逐条比对,避免拿近似结果去取消别的单。</p>
*/
private HengjianOrderListDtos.OrderRow findRow(WarehouseContext ctx, String orderNo, Long orderId) {
Map<String, Object> params = new LinkedHashMap<String, Object>();
params.put("rows", 1);
params.put("sidx", HengjianConstants.ORDER_LIST_SIDX);
params.put("sort", HengjianConstants.ORDER_LIST_SORT);
params.put("page", 1);
if (orderNo != null) {
params.put("orderNos", orderNo);
} else {
params.put("orderIds", String.valueOf(orderId));
}
rateLimiter.acquire(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, HengjianConstants.PERMITS_PER_SECOND);
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(),
HengjianConstants.PATH_ORDER_FIND_BY_PAGE, params, ctx.secret(), ctx, OP_ORDER_CANCEL);
String raw = HengjianEnvelope.of(transport.execute(req), json, OP_ORDER_CANCEL,
ctx.warehouseCode(), ctx.requestId()).body();
HengjianOrderListDtos.ListResponse resp =
json.fromJson(raw, HengjianOrderListDtos.ListResponse.class);
if (resp == null || resp.data == null || resp.data.content == null) {
return null;
}
for (HengjianOrderListDtos.OrderRow row : resp.data.content) {
if (row == null) {
continue;
}
boolean matches = orderNo != null
? orderNo.equals(trimToNull(row.orderNo))
: orderId != null && orderId.equals(row.orderId);
if (matches) {
return row;
}
}
return null;
}
/** 仓内部订单 id;非数字返回 null(后续按单号补)。 */
private static Long parseOrderId(String providerOrderId) {
String v = trimToNull(providerOrderId);
if (v == null) {
return null;
}
try {
return Long.valueOf(v);
} catch (NumberFormatException e) {
return null;
}
}
/**
@ -410,19 +539,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -410,19 +539,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
}
}
private WarehouseException unsupportedOutbound(String operation, WarehouseContext ctx) {
return WarehouseException.builder()
.message("hengjian does not implement " + operation + " yet")
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.build();
}
/** 原始响应可能含 PII,异常里只留短片段。 */
private static String safeRelay(String raw) {
/** 原始响应可能含 PII,异常里只留短片段。 */ private static String safeRelay(String raw) {
if (raw == null) {
return null;
}

29
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCancelOrderDtos.java

@ -0,0 +1,29 @@ @@ -0,0 +1,29 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
/**
* 恒健报文结构:订单取消({@code POST /v1/saleOrder/cancel})。
*
* <p>响应<b>没有 data</b>,只有一个 {@code message}(成功时是「取消成功」)。</p>
*/
public final class HengjianCancelOrderDtos {
private HengjianCancelOrderDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CancelOrderRequest {
/**
* 仓方订单 id;<b>必填</b>。
*
* <p>文档标 INTEGER,这里用 {@link Long}——id 已经是九位数,放宽一位不会更贵,
* 但真溢出了是静默错单。</p>
*/
public Long orderId;
/** 订单号(来源单号);<b>必填</b>。 */
public String orderNo;
}
}

12
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java

@ -63,17 +63,15 @@ class HengjianAdapterTest { @@ -63,17 +63,15 @@ class HengjianAdapterTest {
}
/**
* 下单 / 查询 / 包裹已接、取消未接:门面能力检查放行 {@code OUTBOUND},
* 适配器对未实现的 {@code cancel} 显式抛异常,不返回 null。
* 出库的五个方法(下单 / 查询 / 预判 / 取消 / 包裹)都已接入,
* 门面能力检查放行 {@code OUTBOUND},不经能力位拒绝。
*/
@Test
void unimplementedCancelIsRejected() {
void outboundCapabilityIsFullyWired() {
WarehouseSdk sdk = sdk();
assertThrows(common.ecommerce.warehouse.error.WarehouseException.class,
() -> sdk.warehouses(WH, conn()).outbound().cancel(
common.ecommerce.warehouse.model.CancelCommand.builder()
.outboundRequestNo("OB-1").build()));
assertTrue(sdk.capabilities(WH).supports(
common.ecommerce.warehouse.enums.WarehouseCapability.OUTBOUND));
}
/** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */

218
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCancelOrderTest.java

@ -0,0 +1,218 @@ @@ -0,0 +1,218 @@
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.CancelEligibility;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelResult;
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.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 订单取消({@code POST /v1/saleOrder/cancel})契约测试。
*
* <p>重点:恒健要 {@code orderId} + {@code orderNo} 两个都传,而统一模型允许只给一个。
* 适配器用列表接口补齐,补不到就本地拒绝,不发必然被拒的请求。</p>
*/
class HengjianCancelOrderTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00:00:00Z"), ZoneOffset.UTC);
private static final String CANCEL_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"取消成功\"}";
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());
}
/** 列表补 id 用的响应:一条精确匹配的单。 */
private static final String LOOKUP_BODY =
"{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":true,\"numberOfElements\":1,"
+ "\"content\":[{\"orderId\":193252852,\"orderNo\":\"OB-1\","
+ "\"orderStatusEnum\":\"unshipped\"}]}}";
private static RecordingTransport cancelling() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, req -> Responses.ok(LOOKUP_BODY))
.route(HengjianConstants.PATH_ORDER_CANCEL, req -> Responses.ok(CANCEL_BODY));
}
// ---------------------------------------------------------------- 两个键都齐
@Test
void cancelSendsBothKeys() {
RecordingTransport transport = cancelling();
CancelResult result = adapter(transport).cancel(ctx(), CancelCommand.builder()
.outboundRequestNo("OB-1")
.providerOrderId("193252852")
.build());
// 两个键都给时不需要查列表,只有一次取消请求
assertEquals(1, transport.dataRequests().size());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/saleOrder/cancel",
transport.lastDataRequest().url());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"orderId\":193252852"), body);
assertTrue(body.contains("\"orderNo\":\"OB-1\""), body);
assertEquals("OB-1", result.outboundRequestNo());
assertEquals("193252852", result.providerOrderId());
assertEquals(CancelEligibility.FREE, result.eligibility());
assertTrue(result.cancelled());
assertEquals("取消成功", result.rawStatus());
}
/** orderId 必须是数字:恒健标 INTEGER,字符串会绑不上。 */
@Test
void orderIdIsSentAsNumber() {
RecordingTransport transport = cancelling();
adapter(transport).cancel(ctx(), CancelCommand.builder()
.outboundRequestNo("OB-1").providerOrderId("193252852").build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"orderId\":193252852"), body);
assertTrue(!body.contains("\"orderId\":\"193252852\""), "不能发成字符串,body=" + body);
}
// ---------------------------------------------------------------- 只给一个键
/** 只有单号:先用列表补 orderId,再取消。 */
@Test
void cancelResolvesOrderIdFromListWhenOnlyOrderNoGiven() {
RecordingTransport transport = cancelling();
CancelResult result = adapter(transport).cancel(ctx(), CancelCommand.builder()
.outboundRequestNo("OB-1").build());
assertEquals(2, transport.dataRequests().size(), "先查列表补 id,再取消");
String lookupUrl = transport.dataRequests().get(0).url();
assertTrue(lookupUrl.contains("/v1/saleOrder/findByPage"), lookupUrl);
assertTrue(lookupUrl.contains("orderNos=OB-1"), lookupUrl);
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"orderId\":193252852"), body);
assertEquals("193252852", result.providerOrderId());
}
/** 只有 orderId:先用列表补单号,再取消。 */
@Test
void cancelResolvesOrderNoFromListWhenOnlyOrderIdGiven() {
RecordingTransport transport = cancelling();
CancelResult result = adapter(transport).cancel(ctx(), CancelCommand.builder()
.providerOrderId("193252852").build());
String lookupUrl = transport.dataRequests().get(0).url();
assertTrue(lookupUrl.contains("orderIds=193252852"), lookupUrl);
assertEquals("OB-1", result.outboundRequestNo());
assertTrue(transport.lastDataRequest().body().contains("\"orderNo\":\"OB-1\""));
}
/** 列表查不到这单:本地拒绝,绝不发取消请求。 */
@Test
void cancelRejectsWhenOrderCannotBeFound() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":true,"
+ "\"numberOfElements\":0,\"content\":[]}}"))
.route(HengjianConstants.PATH_ORDER_CANCEL, req -> Responses.ok(CANCEL_BODY));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).cancel(ctx(), CancelCommand.builder()
.outboundRequestNo("OB-NONE").build()));
assertTrue(ex.getMessage().contains("not found"), ex.getMessage());
assertTrue(transport.lastDataRequest().url().contains("findByPage"),
"只能查过列表,不能发取消");
}
/** 列表回的是近似结果(单号不相等):不能被拿去取消别的单。 */
@Test
void cancelDoesNotAcceptApproximateMatch() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":true,"
+ "\"numberOfElements\":1,\"content\":["
+ "{\"orderId\":1,\"orderNo\":\"OB-123\",\"orderStatusEnum\":\"unshipped\"}]}}"))
.route(HengjianConstants.PATH_ORDER_CANCEL, req -> Responses.ok(CANCEL_BODY));
assertThrows(RuntimeException.class, () -> adapter(transport).cancel(ctx(),
CancelCommand.builder().outboundRequestNo("OB-1").build()));
assertTrue(transport.lastDataRequest().url().contains("findByPage"));
}
/** 两个键都没有时直接拒绝(构造期其实已经挡住,这里验证兜底)。 */
@Test
void cancelRejectsWithoutAnyKey() {
RecordingTransport transport = cancelling();
assertThrows(RuntimeException.class,
() -> adapter(transport).cancel(ctx(), CancelCommand.builder()
.outboundRequestNo(null).providerOrderId(null).build()));
assertTrue(transport.dataRequests().isEmpty());
}
// ---------------------------------------------------------------- 失败路径
/** 仓方拒绝取消:按 OutboundCancelBlockedException 抛,便于与参数错区分。 */
@Test
void businessRejectionIsBlockedException() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_CANCEL, req -> Responses.ok(
"{\"code\":500,\"message\":\"订单已发货,不能取消\"}"));
OutboundCancelBlockedException ex = assertThrows(OutboundCancelBlockedException.class,
() -> adapter(transport).cancel(ctx(), CancelCommand.builder()
.outboundRequestNo("OB-1").providerOrderId("193252852").build()));
assertTrue(ex.getMessage().contains("订单已发货"), ex.getMessage());
assertTrue(!ex.retryable());
}
/** 认证失败不能被当成「不可取消」:那是凭据问题,要宿主去刷新。 */
@Test
void authFailureIsNotReportedAsBlocked() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_CANCEL, req -> Responses.ok(
"{\"statusCode\":500,\"status\":1,\"code\":999999,"
+ "\"message\":\"查询失败Unauthorized\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).cancel(ctx(), CancelCommand.builder()
.outboundRequestNo("OB-1").providerOrderId("193252852").build()));
assertTrue(!(ex instanceof OutboundCancelBlockedException),
"认证失败不能包装成不可取消,实际是 " + ex.getClass().getSimpleName());
}
// ---------------------------------------------------------------- 预判
/** 认不出的状态也判 BLOCKED:恒健词表将来可能加值,不能凭猜下发取消。 */
@Test
void unknownStatusIsBlocked() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-1\","
+ "\"orderStatusEnum\":\"returned\"}}"));
assertEquals(CancelEligibility.BLOCKED,
adapter(transport).checkCancel(ctx(),
common.ecommerce.warehouse.model.OutboundRef.ofRequestNo("OB-1")));
}
}

55
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java

@ -9,10 +9,14 @@ import common.ecommerce.shared.spi.ChannelSecret; @@ -9,10 +9,14 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -34,8 +38,9 @@ import java.time.Clock; @@ -34,8 +38,9 @@ import java.time.Clock;
* -Dtest=HengjianWriteProbeTest test
* </pre>
*
* <p><b>会在仓方测试环境留下真实商品数据</b>:恒健文档里没有删除产品的接口,
* 跑完需要人工在 Efulfill 后台清理。SKU 默认带时间戳,重跑不会撞唯一约束。</p>
* <p><b>会在仓方测试环境留下真实数据</b>:恒健文档里没有删除产品的接口,
* 跑完需要人工在 Efulfill 后台清理。SKU 默认带时间戳,重跑不会撞唯一约束。
* 取消探针会真实取消一张单,只对测试环境的探针单用。</p>
*
* <p>输出只打印结果与关键字段,不打印 token。</p>
*/
@ -163,6 +168,52 @@ class HengjianWriteProbeTest { @@ -163,6 +168,52 @@ class HengjianWriteProbeTest {
return "PROBE-OB-" + System.currentTimeMillis();
}
/**
* 取消订单:验证 {@code orderId} + {@code orderNo} 双键必填,以及「只给单号时自动补 id」。
*
* <p>需要 {@code -Dhengjian.probe.cancelOrderNo};不给就跳过——探针不去建单再取消,
* 因为建单需要真实存在的 SKU,链路太长、失败点太多。</p>
*
* <p><b>会真实取消仓方系统里的一张订单</b>,只对测试环境的探针单用。</p>
*/
@Test
void probeCancelOrder() {
assumeToken();
final String cancelNo = opt("hengjian.probe.cancelOrderNo", "");
Assumptions.assumeTrue(!cancelNo.isEmpty(),
"未提供 -Dhengjian.probe.cancelOrderNo,跳过取消探针");
System.out.println("\n================ hengjian / v1/saleOrder/cancel ================");
System.out.println(" orderNo=" + cancelNo + "(只给单号,验证自动补 orderId)");
try {
CancelResult result = adapter().cancel(ctx(), CancelCommand.builder()
.outboundRequestNo(cancelNo).build());
System.out.println(" [OK] cancelled=" + result.cancelled()
+ " eligibility=" + result.eligibility()
+ " orderId=" + result.providerOrderId()
+ " rawStatus=" + result.rawStatus());
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage());
}
}
/** 先预判再取消:核对 checkCancel 的判定与实际取消结果是否一致。 */
@Test
void probeCheckCancelBeforeCancel() {
assumeToken();
final String cancelNo = opt("hengjian.probe.cancelOrderNo", "");
Assumptions.assumeTrue(!cancelNo.isEmpty(),
"未提供 -Dhengjian.probe.cancelOrderNo,跳过取消预判探针");
System.out.println("\n================ hengjian / checkCancel ================");
try {
CancelEligibility eligibility = adapter().checkCancel(ctx(),
OutboundRef.ofRequestNo(cancelNo));
System.out.println(" [OK] eligibility=" + eligibility);
System.out.println(" ← BLOCKED 表示已发货 / 已取消 / 已退款 / 已删除 / 状态认不出");
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage());
}
}
private static OutboundCommand command(String postcode) {
return OutboundCommand.builder()
.outboundRequestNo(orderNo())

Loading…
Cancel
Save