diff --git a/README.md b/README.md index 0b57429..72119d5 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,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 # 单模块 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/hengjian/README.md b/docs-warehouse/hengjian/README.md index 007d0f2..426a37e 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -166,7 +166,7 @@ `orderId` + `orderNo` 两个都传,所以这个 id 必须随 `OutboundReceipt.providerOrderId()` 落库;拿不到就报错,**不当创建成功**。 -**未接入**:查询 / 取消 / 包裹。调用这些方法会显式抛 `WarehouseException`,不返回 null—— +**未接入**:订单上传附件、物流异动单。调用这些方法会显式抛异常,不返回 null—— 静默返回空会让调用方以为「仓说没有这单」。 ## 3. 未接入(文档已有,按需排期) @@ -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 @@ 是否末页以仓方 `last` 为准。 - 列表独有 `amount`(整单销售金额)落 `totalAmount`;`taxPrice` 统一模型无对应字段,不落。 -#### 取消预判(`checkCancel`) - -恒健没有独立的预判接口,按详情状态推断:`shipped` / `canceled` / `refunded` / `deleted` -判 `BLOCKED`,其余 `FREE`。**查不到单时也判 BLOCKED**——猜成 FREE 会发出注定被拒的取消。 - #### 包裹(`packages`) 恒健没有独立包裹接口,从详情 `shipmentPackages` 提取。按 `trackingNo` 去重 @@ -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/ ├── 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/ │ │ ├── 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/ ├── 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 \ -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 \ 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。 + +出库子能力到此全部接完(下单 / 详情 / 列表 / 取消 / 预判 / 包裹)。剩下与出库相关的是 +订单上传附件与物流异动单,都不影响主链路,按需排期。 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 3887f0b..e819230 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 @@ -83,6 +83,15 @@ public final class HengjianConstants { public static final String PATH_ORDER_FIND_BY_PAGE = "/v1/saleOrder/findByPage"; /** + * 订单取消。 + * + *

{@code orderId} 与 {@code orderNo} 都必填。{@code orderId} 只有两条来路: + * 创建接口的响应、列表接口的行。详情接口不回它,所以只拿到单号时, + * 取消前要先用列表接口补一次 id。

+ */ + public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel"; + + /** * 列表接口的排序字段。 * *

文档:{@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 9228e1e..1a30183 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 @@ -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; 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; 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 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 /** * 取消资格预判:查详情按状态推断。 * - *

恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款不再接受取消, + *

恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款 / 已删除不再接受取消, * 判为 {@link CancelEligibility#BLOCKED};其余交给取消时仓方判定。

* *

查不到单时返回 BLOCKED,不猜 FREE——猜错会下发出一个注定被拒的取消。

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

恒健要求 {@code orderId} 与 {@code orderNo} 两个都传,而统一模型的 + * {@link CancelCommand} 允许只给其中一个。约定:

+ * + *

缺哪个就用已知的那个去列表接口补一次——这是拿到 {@code orderId} 的正规途径 + * (详情接口不回它)。补不到(仓里没有这张单)直接报参数错误, + * 不发必然被仓方拒的取消请求。

+ * + *

恒健没有取消费概念,{@link CancelCommand#acceptCharge()} 在这里不生效。 + * 仓方拒绝取消时抛 {@link OutboundCancelBlockedException},与参数错误区分开。

+ */ @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 查一行,用于补全取消需要的另一个键。 + * + *

只认精确匹配:列表接口的 {@code orderNos} / {@code orderIds} 过滤是否精确 + * 文档没说,取回来再逐条比对,避免拿近似结果去取消别的单。

+ */ + private HengjianOrderListDtos.OrderRow findRow(WarehouseContext ctx, String orderNo, Long orderId) { + Map params = new LinkedHashMap(); + 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 } } - 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; } diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCancelOrderDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCancelOrderDtos.java new file mode 100644 index 0000000..ab32f48 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCancelOrderDtos.java @@ -0,0 +1,29 @@ +package common.ecommerce.hengjian.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +/** + * 恒健报文结构:订单取消({@code POST /v1/saleOrder/cancel})。 + * + *

响应没有 data,只有一个 {@code message}(成功时是「取消成功」)。

+ */ +public final class HengjianCancelOrderDtos { + + private HengjianCancelOrderDtos() { + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CancelOrderRequest { + + /** + * 仓方订单 id;必填。 + * + *

文档标 INTEGER,这里用 {@link Long}——id 已经是九位数,放宽一位不会更贵, + * 但真溢出了是静默错单。

+ */ + public Long orderId; + + /** 订单号(来源单号);必填。 */ + public String orderNo; + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java index c2ceae5..e095ad5 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java @@ -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)); } /** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */ diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCancelOrderTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCancelOrderTest.java new file mode 100644 index 0000000..527233f --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCancelOrderTest.java @@ -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})契约测试。 + * + *

重点:恒健要 {@code orderId} + {@code orderNo} 两个都传,而统一模型允许只给一个。 + * 适配器用列表接口补齐,补不到就本地拒绝,不发必然被拒的请求。

+ */ +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"))); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java index 7feaae8..5b2be94 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java @@ -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; * -Dtest=HengjianWriteProbeTest test * * - *

会在仓方测试环境留下真实商品数据:恒健文档里没有删除产品的接口, - * 跑完需要人工在 Efulfill 后台清理。SKU 默认带时间戳,重跑不会撞唯一约束。

+ *

会在仓方测试环境留下真实数据:恒健文档里没有删除产品的接口, + * 跑完需要人工在 Efulfill 后台清理。SKU 默认带时间戳,重跑不会撞唯一约束。 + * 取消探针会真实取消一张单,只对测试环境的探针单用。

* *

输出只打印结果与关键字段,不打印 token。

*/ @@ -163,6 +168,52 @@ class HengjianWriteProbeTest { return "PROBE-OB-" + System.currentTimeMillis(); } + /** + * 取消订单:验证 {@code orderId} + {@code orderNo} 双键必填,以及「只给单号时自动补 id」。 + * + *

需要 {@code -Dhengjian.probe.cancelOrderNo};不给就跳过——探针不去建单再取消, + * 因为建单需要真实存在的 SKU,链路太长、失败点太多。

+ * + *

会真实取消仓方系统里的一张订单,只对测试环境的探针单用。

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