diff --git a/README.md b/README.md index 11f76ff..5cf582e 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;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货 / 订单附件 / 销毁) | 依赖方向: ``` @@ -383,7 +383,8 @@ common.ecommerce │ HengjianFeeMapper / HengjianEstimateMapper / │ HengjianInventoryMapper / HengjianInboundMapper / │ HengjianInboundQueryMapper / HengjianTransferMapper / - │ HengjianReturnMapper / HengjianReturnQueryMapper + │ HengjianReturnMapper / HengjianReturnQueryMapper / + │ HengjianDestructionMapper ├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos / │ HengjianProductSaveDtos / HengjianCreateOrderDtos / │ HengjianOrderDetailDtos / HengjianOrderListDtos / @@ -395,7 +396,8 @@ common.ecommerce │ HengjianInboundCreateDtos / HengjianInboundQueryDtos / │ HengjianTransferDtos / HengjianReturnPlanCreateDtos / │ HengjianReturnDetailDtos / HengjianReturnListDtos / - │ HengjianReturnHandleDtos / HengjianOrderAttachmentDtos + │ HengjianReturnHandleDtos / HengjianOrderAttachmentDtos / + │ HengjianDestructionDtos ├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus); │ 其余状态枚举约定见 package-info,待建 ├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 6c96011..b33f113 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -90,7 +90,9 @@ | 28 | 退货处理单列表 | `POST /v1/saleReturn/getReturnPlanHandlePage` | `RETURN` | ✅ | | 29 | 填写退货处理方式 | `POST /v1/saleReturn/handlingMethod` | `RETURN` | ✅ | | 30 | 订单上传附件 | `POST /v1/saleOrder/createAttachment` | `OUTBOUND` | ✅ | -| 31 | 回调 | — | — | ❌ 文档无回调页 | +| 31 | 销毁计划创建 | `POST /v2/destroyPlanOrder/create`(⚠ **真机 404**) | `DESTRUCTION` | ⚠ 路径待确认 | +| 32 | 销毁计划查询 | `POST /v2/destroyPlanOrder/find`(⚠ **真机 404**) | `DESTRUCTION` | ⚠ 路径待确认 | +| 33 | 回调 | — | — | ❌ 文档无回调页 | 前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, @@ -444,6 +446,47 @@ productItems(入库产品明细必须填写) **未接入**:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。 +### 销毁(`DESTRUCTION`)—— 已接入,**路径未真机确认** + +> **⚠ 重要**:2026-11-17 在测试环境对文档路径及 **26 个变体**请求, +> **全部返回 `404 No handler found`**;同环境其它接口(`/v1/saleOrder/create`、 +> `/v1/trackingChange/findOrder`)正常响应,说明不是网络问题。 +> +> 可能是接口未上线 / 只在生产部署 / 命名体系完全不同。代码按文档实现, +> **联调时必须先核对路径**,若不同只改 `HengjianConstants` 一处常量。 + +#### 创建(`/v2/destroyPlanOrder/create`) + +- **字段笔误照抄**:`hopeDestroyData`(**Data 不是 Date**),创建与查询两侧都是这个拼写。 + 写成 `hopeDestroyDate` 仓方会当成没传。 +- **`orderNo` 不传**:文档标必填,但请求示例里没有;我们下发的 OMS 销毁单号走 `sourceNo`, + 仓方自己生成计划单号。 +- **响应无 data**:只有 `code / message`,**不回仓单号也不回状态**。所以 + `providerDestructionId` 与 `status` 都留 null——不拿来源单号冒充仓单号, + 也不把「已提交」当「已执行」。 + +#### 查询(`/v2/destroyPlanOrder/find`) + +- **请求体是裸数组** `["单号1","单号2"]`,不是对象包装。 +- 响应 `data` 也是数组;**查不到的单号不返回**(不是返回空对象)。 +- 文档说传「销毁计划单单号集合」,但示例里数组的值正是响应里的 `sourceNo`—— + 所以按**来源单号**(我们下发的 `destructionNo`)查。适配器还允许传仓方计划单号, + 因为两边都逐条比对。 +- 适配器只查一个单号,返回匹配的那条,没有则 null。 + +#### 状态码表(`HengjianDestructionStatus`) + +0 草稿 / 1 提交待审核 / 2 已审核待销毁 / 3 审核不通过 / 4 销毁中 / 5 完成 / 10 取消。 + +**core 没有销毁状态的底层枚举**,所以这里保留仓方码 + 中文名,不硬造一套跨仓枚举 +(运去哪的销毁接口根本不回状态)。`DestructionOrder.status()` 填中文名、 +`rawStatus()` 填原值数字。 + +#### 为这两个接口给 core 加的字段 + +`DestructionCommand`:`lineName`(项目名称,原先没有入口) +`DestructionOrder`:`lineName` / `hopeDestroyDate` / `createdAt` + ### 退货查询与处理方式 —— 已接入 #### 请求形态有两套,不能混 @@ -862,13 +905,14 @@ warehouse-sdk-hengjian/ ├── adapter/HengjianReturnCreateTest.java 16 个:params 包裹 / 行级四项 / 跟踪号回退 / 8 状态 ├── adapter/HengjianReturnQueryTest.java 18 个:两套形态 / 三套码表 / 四项定位 / 处理方式映射 ├── adapter/HengjianOrderAttachmentTest.java 12 个:平铺 / 类型整数 / base64 优先 / 本地校验 + ├── adapter/HengjianDestructionTest.java 16 个:Data 拼写 / 裸数组 / 7 状态 / 无仓单号 ├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举 ├── http/HengjianEnvelopeTest.java 12 个:三种信封形态 + 通用失败码 + 错误路径 ├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性 └── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true ``` -已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(313 个 + 4 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(329 个 + 4 个跳过)。 ## 5. 探针用法 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java index b87dd16..9bc3620 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java @@ -19,6 +19,8 @@ public final class DestructionCommand { private final String destructionNo; /** 销毁仓 code;null 时用账户配置的仓。 */ private final String warehouseId; + /** 项目名称;仓方按项目分账 / 路由时使用,null 表示不传。 */ + private final String lineName; /** 库存类型:0 可售 / 1 不可售。 */ private final int inventoryType; /** 期望销毁日期。 */ @@ -30,6 +32,7 @@ public final class DestructionCommand { private DestructionCommand(Builder b) { this.destructionNo = require(b.destructionNo, "destructionNo"); this.warehouseId = b.warehouseId; + this.lineName = b.lineName; if (b.inventoryType != 0 && b.inventoryType != 1) { throw new IllegalArgumentException("inventoryType must be 0 (sellable) or 1 (unsellable)"); } @@ -60,6 +63,11 @@ public final class DestructionCommand { return warehouseId; } + /** 项目名称;null 表示不传。 */ + public String lineNameOrNull() { + return lineName; + } + /** 库存类型:0 可售 / 1 不可售。 */ public int inventoryType() { return inventoryType; @@ -189,6 +197,7 @@ public final class DestructionCommand { public static final class Builder { private String destructionNo; private String warehouseId; + private String lineName; private int inventoryType; private LocalDate hopeDestroyDate; private String remark; @@ -205,6 +214,12 @@ public final class DestructionCommand { return this; } + /** 项目名称;null 表示不传。 */ + public Builder lineName(String v) { + this.lineName = v; + return this; + } + public Builder inventoryType(int v) { this.inventoryType = v; return this; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java index 1f82502..9f82e36 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java @@ -20,6 +20,12 @@ public final class DestructionOrder { private final String rawStatus; /** 该单据来自哪家仓;用于解释 {@link #rawStatus()}。 */ private final WarehouseProvider sourceProvider; + /** 项目名称;仓方未给为 null。 */ + private final String lineName; + /** 期望销毁日期;仓方未给为 null。 */ + private final java.time.LocalDate hopeDestroyDate; + /** 创建时间(UTC);仓方未给为 null。 */ + private final java.time.Instant createdAt; private DestructionOrder(Builder b) { if (b.destructionNo == null || b.destructionNo.trim().isEmpty()) { @@ -31,6 +37,9 @@ public final class DestructionOrder { this.status = b.status; this.rawStatus = b.rawStatus; this.sourceProvider = b.sourceProvider; + this.lineName = b.lineName; + this.hopeDestroyDate = b.hopeDestroyDate; + this.createdAt = b.createdAt; } public static Builder builder() { @@ -62,6 +71,21 @@ public final class DestructionOrder { return sourceProvider; } + /** 项目名称;null 表示仓方未给。 */ + public String lineName() { + return lineName; + } + + /** 期望销毁日期;null 表示仓方未给。 */ + public java.time.LocalDate hopeDestroyDate() { + return hopeDestroyDate; + } + + /** 创建时间(UTC);null 表示仓方未给。 */ + public java.time.Instant createdAt() { + return createdAt; + } + public static final class Builder { private String destructionNo; private String providerDestructionId; @@ -69,6 +93,9 @@ public final class DestructionOrder { private String status; private String rawStatus; private WarehouseProvider sourceProvider; + private String lineName; + private java.time.LocalDate hopeDestroyDate; + private java.time.Instant createdAt; public Builder destructionNo(String v) { this.destructionNo = v; @@ -100,6 +127,24 @@ public final class DestructionOrder { return this; } + /** 项目名称。 */ + public Builder lineName(String v) { + this.lineName = v; + return this; + } + + /** 期望销毁日期。 */ + public Builder hopeDestroyDate(java.time.LocalDate v) { + this.hopeDestroyDate = v; + return this; + } + + /** 创建时间(UTC)。 */ + public Builder createdAt(java.time.Instant v) { + this.createdAt = v; + return this; + } + public DestructionOrder build() { return new DestructionOrder(this); } 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 3dd3b30..b6d7d60 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 @@ -292,6 +292,22 @@ public final class HengjianConstants { public static final String PATH_RETURN_HANDLING_METHOD = "/v1/saleReturn/handlingMethod"; /** + * 销毁计划创建({@code POST})。 + * + *
⚠ 路径未经真机确认(2026-11-17):测试环境对该路径及 26 个变体全部返回 + * {@code 404 No handler found},而同环境其它接口正常响应。文档原文用的就是这个路径, + * 先按文档实现;联调时必须核对,若仓方另有路径只改这一处。
+ */ + public static final String PATH_DESTRUCTION_CREATE = "/v2/destroyPlanOrder/create"; + + /** + * 销毁计划查询({@code POST},请求体是裸数组)。 + * + *⚠ 路径未经真机确认,原因同上。
+ */ + public static final String PATH_DESTRUCTION_FIND = "/v2/destroyPlanOrder/find"; + + /** * {@code btChargeAt} 的日期区间分隔符。 * *文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。
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 c109322..a266224 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 @@ -5,6 +5,7 @@ import common.ecommerce.hengjian.dto.HengjianAddressClassificationDtos; import common.ecommerce.hengjian.dto.HengjianCancelOrderDtos; import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos; import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; +import common.ecommerce.hengjian.dto.HengjianDestructionDtos; import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos; import common.ecommerce.hengjian.dto.HengjianInventoryDtos; import common.ecommerce.hengjian.dto.HengjianInboundCreateDtos; @@ -36,6 +37,7 @@ import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.shared.error.PlatformBusinessException; import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.AddressClassificationCapable; +import common.ecommerce.warehouse.capability.DestructionCapable; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TransferCapable; @@ -62,6 +64,8 @@ import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.CancelCommand; +import common.ecommerce.warehouse.model.DestructionCommand; +import common.ecommerce.warehouse.model.DestructionOrder; import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.FeeEstimateQuery; import common.ecommerce.warehouse.model.FeeEstimateResult; @@ -117,7 +121,7 @@ import java.util.Map; public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable, - InboundCapable, TransferCapable, WarehouseReturnCapable { + InboundCapable, TransferCapable, WarehouseReturnCapable, DestructionCapable { private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; private static final String OP_CARRIERS = "warehouse.directory.carriers"; @@ -144,6 +148,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti private static final String OP_TRANSFER_QUERY = "warehouse.transfer.query"; private static final String OP_TRANSFER_CANCEL = "warehouse.transfer.cancel"; private static final String OP_RETURN_CREATE = "warehouse.return.create"; + private static final String OP_DESTRUCTION_CREATE = "warehouse.destruction.create"; + private static final String OP_DESTRUCTION_GET = "warehouse.destruction.get"; private static final String OP_RETURN_GET = "warehouse.return.get"; private static final String OP_RETURN_QUERY = "warehouse.return.query"; private static final String OP_RETURN_HANDLES = "warehouse.return.handles"; @@ -188,6 +194,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.INBOUND, WarehouseCapability.TRANSFER, WarehouseCapability.RETURN, + WarehouseCapability.DESTRUCTION, WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE, WarehouseCapability.ADDRESS_CLASSIFICATION, @@ -195,6 +202,45 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.LOGISTICS_PRODUCT); } + // ------------------------------------------------------------------ 销毁 + + /** + * 创建销毁计划({@code POST /v2/destroyPlanOrder/create})。 + * + *⚠ 路径未真机确认,见 {@link HengjianConstants#PATH_DESTRUCTION_CREATE}。
+ * + *响应无 data:只有 {@code code / message},不回仓单号也不回状态。 + * 所以 {@code providerDestructionId} 与 {@code status} 都留 null——不拿来源单号冒充仓单号, + * 也不把「已提交」当「已执行」。
+ */ + @Override + public DestructionOrder create(WarehouseContext ctx, DestructionCommand cmd) { + String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( + cmd.warehouseId(), ctx.providerWarehouseId()); + HengjianDestructionDtos.CreateRequest body = + HengjianDestructionMapper.toRequest(cmd, warehouseCode); + execute(ctx, HengjianConstants.PATH_DESTRUCTION_CREATE, body, OP_DESTRUCTION_CREATE); + return HengjianDestructionMapper.toCreated(cmd, warehouseCode); + } + + /** + * 查销毁计划({@code POST /v2/destroyPlanOrder/find})。 + * + *⚠ 路径未真机确认,见 {@link HengjianConstants#PATH_DESTRUCTION_FIND}。
+ * + *请求体是裸数组;响应 {@code data} 也是数组,查不到的单号不返回 + * (不是返回空对象)。这里只查一个单号,返回匹配的那条,没有则 null。
+ */ + @Override + public DestructionOrder getDestruction(WarehouseContext ctx, String destructionNo) { + List创建请求有两个单号字段:{@code orderNo}(销毁计划单号)与 {@code sourceNo}(来源单号)。 + * 文档的请求示例里没有 {@code orderNo},而查询响应同时回 + * {@code destroyPlanOrderNo} 与 {@code sourceNo}。所以:
+ *文档说传「销毁计划单单号集合」,但示例里请求数组的值 + * ({@code AAAAAAAA} / {@code XXXXXXXX})正是响应里的 {@code sourceNo}。 + * 所以按来源单号查——也就是我们下发的 {@code destructionNo}。
+ * + *{@code hopeDestroyData}(不是 {@code Date})在创建与查询两侧都是这个拼写,照抄。
+ */ +public final class HengjianDestructionMapper { + + private static final DateTimeFormatter DATE_TIME = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + + private HengjianDestructionMapper() { + } + + // ================================================================ 创建 + + /** + * 统一命令 → 恒健创建请求。 + * + * @param warehouseCode 仓 code(命令显式指定优先,其次账户配置) + * @throws IllegalArgumentException 缺必填项 + */ + public static HengjianDestructionDtos.CreateRequest toRequest(DestructionCommand cmd, + String warehouseCode) { + String wh = trimToNull(warehouseCode); + if (wh == null) { + throw new IllegalArgumentException( + "hengjian destruction needs an orgWarehouseCode; none given and account has none"); + } + if (cmd.lines().isEmpty()) { + throw new IllegalArgumentException( + "hengjian destruction plan requires at least one sku"); + } + if (cmd.hopeDestroyDate() == null) { + throw new IllegalArgumentException( + "hengjian destruction plan requires hopeDestroyDate"); + } + + HengjianDestructionDtos.CreateRequest req = new HengjianDestructionDtos.CreateRequest(); + req.orgWarehouseCode = wh; + // 我们下发的单号是「来源单号」;orderNo 由仓方生成,不传 + req.sourceNo = cmd.destructionNo(); + req.lineName = trimToNull(cmd.lineNameOrNull()); + req.inventoryType = cmd.inventoryType(); + req.hopeDestroyData = cmd.hopeDestroyDate().toString(); + req.remark = trimToNull(cmd.remark()); + req.destroyPlanOrderItems = toItems(cmd.lines()); + return req; + } + + private static List创建响应没有 data,不回仓单号,也不回状态。所以 + * {@code providerDestructionId} 与 {@code status} 都留 null——不拿来源单号冒充仓单号, + * 也不把「提交成功」当「已执行」。
+ */ + public static DestructionOrder toCreated(DestructionCommand cmd, String warehouseCode) { + return DestructionOrder.builder() + .destructionNo(cmd.destructionNo()) + .warehouseCode(warehouseCode) + .sourceProvider(WarehouseProvider.HENGJIAN) + .build(); + } + + // ================================================================ 查询 + + /** 查询请求:裸数组(不是对象包装)。 */ + public static List⚠ 路径未在真机确认:2026-11-17 在测试环境对文档路径及 26 个变体 + * 全部返回 {@code 404 No handler found}(同环境其它接口正常响应)。 + * 代码按文档实现,路径常量需在联调时核对。
+ * + *字段名有笔误:{@code hopeDestroyData}——文档里就是 {@code Data} 不是 {@code Date}, + * 照抄。
+ *响应无 data:只有 {@code code / message},不回仓单号。
+ * + *请求体是裸数组({@code ["单号1","单号2"]}),不是对象包装。
+ *响应 {@code data} 是数组;每个单号一条,查不到的单号不返回(不是返回空对象)。
+ */ +public final class HengjianDestructionDtos { + + private HengjianDestructionDtos() { + } + + // ================================================================ 创建 + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateRequest { + + /** 销毁计划单号(文档标必填,但示例里没有——按选填实现,见类注释)。 */ + public String orderNo; + + /** 组织仓 code;必填。 */ + public String orgWarehouseCode; + + /** 项目名称。 */ + public String lineName; + + /** 来源单号(我们下发的销毁单号)。 */ + public String sourceNo; + + /** 库存类型:0 可售 / 1 不可售;必填。 */ + public Integer inventoryType; + + /** + * 期望销毁日期 {@code YYYY-MM-DD};必填。 + * + *字段名是 {@code Data} 不是 {@code Date}——文档原文如此,照抄。 + * 写成 {@code hopeDestroyDate} 仓方会当成没传。
+ */ + public String hopeDestroyData; + + public String remark; + + /** 产品信息;必填。 */ + public List用 String 接住——文档标 INTEGER,但同站其它接口出现过数字串。
+ */ + @JsonProperty("status") + public String status; + + @JsonProperty("remark") + public String remark; + + @JsonProperty("createdAt") + public String createdAt; + @JsonProperty("updatedAt") + public String updatedAt; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianDestructionStatus.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianDestructionStatus.java new file mode 100644 index 0000000..45c185b --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianDestructionStatus.java @@ -0,0 +1,69 @@ +package common.ecommerce.hengjian.enums; + +/** + * 恒健销毁计划单状态({@code status})。 + * + *码表来自《销毁计划查询》: + * 0 草稿 / 1 提交待审核 / 2 已审核待销毁 / 3 审核不通过 / 4 销毁中 / 5 完成 / 10 取消。
+ * + *为什么是独立枚举而不是 {@code DestructionOrder.status()} 的字符串:恒健的 + * {@code status} 是 INTEGER,运去哪创建接口不回状态、查询接口也还没接, + * 两家码表没有交集。这里保留仓方码 + 中文名,不映射到 core 枚举—— + * core 目前没有销毁状态的底层枚举,为一个仓硬造一套会污染其它仓。
+ * + *精确匹配,未知归 {@link #UNKNOWN} 不猜。
+ */ +public enum HengjianDestructionStatus { + + /** 0 草稿。 */ + DRAFT("0", "草稿"), + /** 1 提交 / 待审核。 */ + PENDING_REVIEW("1", "提交待审核"), + /** 2 已审核 / 待销毁。 */ + APPROVED("2", "已审核待销毁"), + /** 3 审核不通过 / 审核拒回。 */ + REJECTED("3", "审核不通过"), + /** 4 销毁中。 */ + DESTROYING("4", "销毁中"), + /** 5 完成。 */ + COMPLETED("5", "完成"), + /** 10 取消。 */ + CANCELLED("10", "取消"), + /** 无法识别。 */ + UNKNOWN(null, null); + + private final String rawCode; + private final String rawName; + + HengjianDestructionStatus(String rawCode, String rawName) { + this.rawCode = rawCode; + this.rawName = rawName; + } + + /** 仓方数字码;UNKNOWN 为 null。 */ + public String rawCode() { + return rawCode; + } + + /** 仓方中文名;UNKNOWN 为 null。 */ + public String rawName() { + return rawName; + } + + /** 精确匹配(忽略首尾空白);空值 / 未收录归 {@link #UNKNOWN}。 */ + public static HengjianDestructionStatus of(String raw) { + if (raw == null) { + return UNKNOWN; + } + String s = raw.trim(); + if (s.isEmpty()) { + return UNKNOWN; + } + for (HengjianDestructionStatus v : values()) { + if (v.rawCode != null && s.equals(v.rawCode)) { + return v; + } + } + return UNKNOWN; + } +} 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 cbd2b50..a729152 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 @@ -74,13 +74,13 @@ class HengjianAdapterTest { common.ecommerce.warehouse.enums.WarehouseCapability.OUTBOUND)); } - /** 销毁 / 箱标仍未接入:门面按能力位直接拒绝。 */ + /** 轨迹查询仍未接入:门面按能力位直接拒绝(只读,不会先撞幂等守卫)。 */ @Test void undeclaredCapabilityIsRejected() { WarehouseSdk sdk = sdk(); assertThrows(WarehouseUnsupportedCapabilityException.class, - () -> sdk.warehouses(WH, conn()).createDestruction(null)); + () -> sdk.warehouses(WH, conn()).track("1Z999")); } /** 能力矩阵查询本身可用(不触发真实 API)。 */ @@ -88,9 +88,9 @@ class HengjianAdapterTest { void capabilityQueryIsOffline() { HengjianAdapter adapter = new HengjianAdapter(RecordingTransport.create(), new JacksonJsonCodec()); - // 库存 / 入库 / 退货已接入;销毁仍是未接状态 + // 库存 / 入库 / 退货 / 销毁已接入;轨迹查询仍未接 assertTrue(!adapter.capabilities().contains( - common.ecommerce.warehouse.enums.WarehouseCapability.DESTRUCTION)); + common.ecommerce.warehouse.enums.WarehouseCapability.TRACKING)); } @Test diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java index 6a69130..41ac27e 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java @@ -484,7 +484,7 @@ class HengjianCreateOrderTest { .outboundRequestNo("OB-1").build())); } - /** 未声明的能力位仍然被门面挡住(DESTRUCTION 还没接)。 */ + /** 未声明的能力位仍然被门面挡住(TRACKING 还没接)。 */ @Test void undeclaredCapabilityIsRejectedByFacade() { WarehouseSdk sdk = WarehouseSdk.builder() @@ -504,6 +504,6 @@ class HengjianCreateOrderTest { HengjianConstants.TEST_BASE_URL, ChannelSecret.builder().appSecret("t").build(), ZoneOffset.UTC)) - .createDestruction(null)); + .track("1Z999")); } } diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDestructionTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDestructionTest.java new file mode 100644 index 0000000..35c93f4 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDestructionTest.java @@ -0,0 +1,263 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.hengjian.enums.HengjianDestructionStatus; +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.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.DestructionCommand; +import common.ecommerce.warehouse.model.DestructionOrder; +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.LocalDate; +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; + +/** + * 销毁计划创建 / 查询契约测试。 + * + *注意:这两个路径在测试环境真机返回 404(见 {@code HengjianConstants}), + * 所以本测试只能验证「按文档拼报文 + 解析响应」的行为,不能证明路径可用。
+ */ +class HengjianDestructionTest { + + private static final WarehouseContext CTX = WarehouseContext.of( + "HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA", + WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("token-1").build()), + "req-1", Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC)); + + private static HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + private static DestructionCommand.Builder command() { + return DestructionCommand.builder() + .destructionNo("DT-2026-0001") + .warehouseId("EFCA") + .inventoryType(1) + .hopeDestroyDate(LocalDate.parse("2026-12-01")) + .remark("过期报废") + .lineName("项目A") + .line("SKU-A", 3) + .line("SKU-B", 1); + } + + // ================================================================ 创建 + + private static RecordingTransport creating() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_DESTRUCTION_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"OK\"}")); + } + + @Test + void createPostsToDestroyPlanOrder() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/destroyPlanOrder/create", + transport.lastDataRequest().url()); + } + + /** 文档字段名 {@code hopeDestroyData} 是 Data 不是 Date,照抄。 */ + @Test + void createSendsDocumentedFields() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"orgWarehouseCode\":\"EFCA\""), body); + assertTrue(body.contains("\"sourceNo\":\"DT-2026-0001\""), body); + assertTrue(body.contains("\"inventoryType\":1"), body); + assertTrue(body.contains("\"hopeDestroyData\":\"2026-12-01\""), body); + assertTrue(body.contains("\"lineName\":\"项目A\""), body); + assertTrue(body.contains("\"remark\":\"过期报废\""), body); + assertTrue(body.contains("\"destroyPlanOrderItems\":["), body); + assertTrue(body.contains("\"sku\":\"SKU-A\""), body); + assertTrue(body.contains("\"planQty\":3"), body); + // orderNo 由仓方生成,我们不传 + assertFalse(body.contains("\"orderNo\""), "orderNo 应由仓方生成,不传,body=" + body); + } + + /** 创建响应无 data:不拿来源单号冒充仓单号,也不编状态。 */ + @Test + void createdHasNoProviderIdOrStatus() { + DestructionOrder order = adapter(creating()).create(CTX, command().build()); + + assertEquals("DT-2026-0001", order.destructionNo()); + assertNull(order.providerDestructionId(), "响应不回仓单号"); + assertNull(order.status(), "创建只代表已提交,不能当已执行"); + assertNull(order.rawStatus()); + assertEquals("EFCA", order.warehouseCode()); + assertEquals(WarehouseProvider.HENGJIAN, order.sourceProvider()); + } + + @Test + void createRequiresLines() { + RecordingTransport transport = creating(); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(CTX, DestructionCommand.builder() + .destructionNo("DT-X").warehouseId("EFCA").inventoryType(0) + .hopeDestroyDate(LocalDate.parse("2026-12-01")).build())); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 命令没给仓、账户也没配仓 id 时拒绝。 */ + @Test + void createRequiresWarehouseCode() { + WarehouseContext noWarehouse = WarehouseContext.of( + "HJ-NO-WH", WarehouseProvider.HENGJIAN, null, + WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("token-1").build()), + "req-2", Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC)); + RecordingTransport transport = creating(); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(noWarehouse, DestructionCommand.builder() + .destructionNo("DT-X").inventoryType(0) + .hopeDestroyDate(LocalDate.parse("2026-12-01")) + .line("SKU-A", 1).build())); + assertTrue(transport.dataRequests().isEmpty()); + } + + @Test + void businessErrorIsPropagated() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_DESTRUCTION_CREATE, req -> Responses.ok( + "{\"statusCode\":500,\"status\":1,\"code\":999999," + + "\"message\":\"组织仓库不存在!\"}")); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).create(CTX, command().build())); + assertTrue(ex.getMessage().contains("组织仓库不存在"), ex.getMessage()); + } + + // ================================================================ 查询 + + private static final String FIND_BODY = + "{\"status\":200,\"message\":\"OK\",\"data\":[{" + + "\"createdAt\":\"2024-11-07 02:03:00\"," + + "\"updatedAt\":\"2024-12-06 09:15:49\"," + + "\"destroyPlanOrderNo\":\"DPAAAAAAA\"," + + "\"orgWarehouseId\":12345,\"orgWarehouseCode\":\"EFCA\"," + + "\"orgWarehouseName\":\"EF-CA\",\"lineName\":\"项目A\"," + + "\"sourceNo\":\"DT-2026-0001\",\"inventoryType\":1," + + "\"hopeDestroyData\":\"2026-12-01\",\"status\":1," + + "\"remark\":\"过期报废\"}]}"; + + private static RecordingTransport finding() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_DESTRUCTION_FIND, req -> Responses.ok(FIND_BODY)); + } + + /** 查询请求是裸数组,不是对象包装。 */ + @Test + void findSendsBareArray() { + RecordingTransport transport = finding(); + adapter(transport).getDestruction(CTX, "DT-2026-0001"); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/destroyPlanOrder/find", + transport.lastDataRequest().url()); + assertEquals("[\"DT-2026-0001\"]", transport.lastDataRequest().body()); + } + + @Test + void findMapsPlan() { + DestructionOrder order = adapter(finding()).getDestruction(CTX, "DT-2026-0001"); + + assertEquals("DT-2026-0001", order.destructionNo(), "来源单号优先"); + assertEquals("DPAAAAAAA", order.providerDestructionId()); + assertEquals("EFCA", order.warehouseCode()); + assertEquals("提交待审核", order.status(), "1 → 提交待审核"); + assertEquals("1", order.rawStatus()); + assertEquals("项目A", order.lineName()); + assertEquals(LocalDate.parse("2026-12-01"), order.hopeDestroyDate()); + assertEquals(Instant.parse("2024-11-07T02:03:00Z"), order.createdAt()); + assertEquals(WarehouseProvider.HENGJIAN, order.sourceProvider()); + } + + /** 文档里的 7 个状态值都要映射对。 */ + @Test + void allDocumentedStatusesMap() { + assertEquals("草稿", HengjianDestructionStatus.of("0").rawName()); + assertEquals("提交待审核", HengjianDestructionStatus.of("1").rawName()); + assertEquals("已审核待销毁", HengjianDestructionStatus.of("2").rawName()); + assertEquals("审核不通过", HengjianDestructionStatus.of("3").rawName()); + assertEquals("销毁中", HengjianDestructionStatus.of("4").rawName()); + assertEquals("完成", HengjianDestructionStatus.of("5").rawName()); + assertEquals("取消", HengjianDestructionStatus.of("10").rawName()); + } + + @Test + void unknownStatusIsNotGuessed() { + assertEquals(HengjianDestructionStatus.UNKNOWN, HengjianDestructionStatus.of("9")); + assertEquals(HengjianDestructionStatus.UNKNOWN, HengjianDestructionStatus.of(null)); + } + + /** 查不到的单号仓方不返回:结果里没有就是 null。 */ + @Test + void findReturnsNullWhenNotListed() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_DESTRUCTION_FIND, req -> Responses.ok( + "{\"status\":200,\"message\":\"OK\",\"data\":[]}")); + + assertNull(adapter(transport).getDestruction(CTX, "DT-NONE")); + } + + /** data 缺失也返回 null,不抛。 */ + @Test + void findReturnsNullWhenDataMissing() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_DESTRUCTION_FIND, req -> Responses.ok( + "{\"status\":200,\"message\":\"OK\"}")); + + assertNull(adapter(transport).getDestruction(CTX, "DT-NONE")); + } + + /** 按仓方计划单号查也能命中(同样回数组,逐条比对)。 */ + @Test + void findMatchesProviderPlanNo() { + DestructionOrder order = adapter(finding()).getDestruction(CTX, "DPAAAAAAA"); + + assertEquals("DT-2026-0001", order.destructionNo(), "命中后仍以来源单号作业务键"); + assertEquals("DPAAAAAAA", order.providerDestructionId()); + } + + @Test + void findRequiresNumber() { + assertThrows(IllegalArgumentException.class, + () -> adapter(RecordingTransport.create()).getDestruction(CTX, " ")); + } + + // ================================================================ 能力位 + + @Test + void declaresDestructionCapability() { + assertTrue(adapter(RecordingTransport.create()).capabilities() + .contains(WarehouseCapability.DESTRUCTION)); + } + + /** + * 路径未经真机确认:这条测试把文档路径固定下来, + * 若联调时发现不同,改常量后这里会一起失败——提醒同步文档。 + */ + @Test + void documentedPathsArePinned() { + assertEquals("/v2/destroyPlanOrder/create", HengjianConstants.PATH_DESTRUCTION_CREATE); + assertEquals("/v2/destroyPlanOrder/find", HengjianConstants.PATH_DESTRUCTION_FIND); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java index 5468725..c2b72bc 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java @@ -237,9 +237,10 @@ class HengjianDirectoryTest { assertTrue(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY)); assertTrue(adapter.capabilities().contains(WarehouseCapability.INBOUND)); assertTrue(adapter.capabilities().contains(WarehouseCapability.RETURN)); - // 销毁 / 回调还没接:声明了就必须有实现 - assertTrue(!adapter.capabilities().contains(WarehouseCapability.DESTRUCTION)); + assertTrue(adapter.capabilities().contains(WarehouseCapability.DESTRUCTION)); + // 回调 / 轨迹还没接:声明了就必须有实现 assertTrue(!adapter.capabilities().contains(WarehouseCapability.WEBHOOK)); + assertTrue(!adapter.capabilities().contains(WarehouseCapability.TRACKING)); } @Test