diff --git a/README.md b/README.md index a55f9d8..5ead682 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;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨创建查询取消) | 依赖方向: ``` @@ -382,7 +382,7 @@ common.ecommerce │ HengjianOrderMapper / HengjianTrackingChangeMapper / │ HengjianFeeMapper / HengjianEstimateMapper / │ HengjianInventoryMapper / HengjianInboundMapper / - │ HengjianInboundQueryMapper + │ HengjianInboundQueryMapper / HengjianTransferMapper ├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos / │ HengjianProductSaveDtos / HengjianCreateOrderDtos / │ HengjianOrderDetailDtos / HengjianOrderListDtos / @@ -391,7 +391,8 @@ common.ecommerce │ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos / │ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos / │ HengjianInventoryDtos / HengjianInventoryMovementDtos / - │ HengjianInboundCreateDtos / HengjianInboundQueryDtos + │ HengjianInboundCreateDtos / HengjianInboundQueryDtos / + │ HengjianTransferDtos ├── 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 7692c45..035e4aa 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -81,7 +81,10 @@ | 19 | 入库计划创建 | `POST /v1/inbound/createInboundPlan` | `INBOUND` | ✅ | | 20 | 入库计划详情 | `POST /v1/inbound/getInboundPlanInfo` | `INBOUND` | ✅ | | 21 | 入库计划列表 | `POST /v1/inbound/getInboundPlanPage` | `INBOUND` | ✅ | -| 22 | 回调 | — | — | ❌ 文档无回调页 | +| 22 | 调拨计划创建 | `POST /v1/transferPlan/create` | `TRANSFER` | ✅ | +| 23 | 调拨计划查询 | `GET /v1/transferPlan/findByPage` | `TRANSFER` | ✅ | +| 24 | 调拨计划取消 | `GET /v1/transferPlan/cancel` | `TRANSFER` | ✅ | +| 25 | 回调 | — | — | ❌ 文档无回调页 | 前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, @@ -421,6 +424,63 @@ productItems(入库产品明细必须填写) **未接入**:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。 +### 调拨(`TRANSFER`)—— 已接入 + +#### 创建(`POST /v1/transferPlan/create`) + +**真机确认的必填项**(按校验顺序):`outOrgWarehouseCode` → `inOrgWarehouseCode` → +`estimateOutboundTime` → `estimateInboundTime`。 + +文档另标了 `projectUnicode` / `transportationType` / `inventoryType` / `isLabel` / +`receiveStore` / 六个 `shipTo*` 为必填,但**真机校验里没有它们**——不传也能过(只停在鉴权)。 +按选填实现,与入库创建的 `currency` 是同一类情况。 + +| 项 | 处理 | +|---|---| +| `details[].qty` | 文档标 **STRING**(不是 INTEGER),按字符串下发;查询响应里是数字,两个 DTO 各声明 | +| 日期 | 统一模型是 `LocalDate`,恒健要 `yyyy-MM-dd HH:mm:ss`:补当天 `00:00:00`,**不编造具体时刻** | +| `refferenceId` | 文档里就是**三个 f**,照抄 | +| `inOrgWarehouseCode=Other` | 外部仓库的固定代号;此时统一模型的 `type` 映射为 `OUTBOUND` | +| `transportationType` | 1 客户安排 / 2 仓库安排;未指定(0)按「仓库安排」兜底并在文档注明;其它值拒绝 | +| 响应 | `data` 是**字符串单号**(不是对象);拿不到单号即报错,不当创建成功 | + +创建接口**不回状态**:`TransferOrder.status` 保持 `UNKNOWN`,不拿请求侧的值冒充。 + +#### 查询(`GET /v1/transferPlan/findByPage`) + +- `page` / `rows` / `sidx` / `sort` 必填(`sidx=id`、`sort=desc`);`rows` 默认最高 **100**,超限拒绝。 +- 过滤参数都是**单值**(`sourceNo` / `transferOutboundPlanNo` / `projectUnicode` / + `outOrgWarehouseCode` / `inOrgWarehouseCode`)——与其它接口不同,这里给多个单号时 + 只下发第一个(语义是「按这个单号查」,多给没有意义),文档已注明。 +- 响应 `data` 是标准分页信封;游标换算同订单 / 库存列表(`number + 2`)。 + +#### 取消(`GET /v1/transferPlan/cancel`) + +- **参数在 query,不是 body**;真机确认 `sourceNo` 必填 + (缺了回 `Required String parameter 'sourceNo' is not present`)。 +- 统一模型里落在 `TransferCapable.deleteTransfer`——恒健叫「取消」,语义等价于撤销。 +- 恒健**没有取消费概念**;仓方拒绝时原样抛业务异常(如「未查询到对应调拨计划数据」), + 不伪装成成功。 + +#### 状态枚举(`HengjianTransferStatus`) + +13 个值:0 草稿 / 3 已驳回 / 5 待审核 / 7 审核通过 / 8 待确认 / 10 待出库 / +15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 / 90 已关闭 / 100 取消中 / 110 已取消。 + +**精确匹配**,未知归 `UNKNOWN` 不猜。`100`(取消中)与 `110`(已取消)**不合并**—— +合并就分不出「取消请求已发出」和「仓方已确认取消」。 + +#### 只为这些接口给 core 加的字段 + +`TransferCommand`:`projectCode` / `relabelProducts` / `referenceId` / `deliveryDate` / +`externalDestination` +`TransferOrder`:`projectCode` / `attachments` +`TransferQuery`(新增模型)+ `TransferCapable.queryTransfers()` + 门面 `queryTransfers()` + +#### 未接入 + +`approve`(审核)与 `getTransfer`(按单号查详情)恒健没有对应接口,保持默认拒绝。 + ### 入库计划详情 / 列表(`INBOUND`)—— 已接入 两个接口回的对象**字段完全一致**,只有外层形状不同(`data` 对象 vs `data.content[]` 分页信封), @@ -624,7 +684,8 @@ warehouse-sdk-hengjian/ │ │ ├── HengjianEstimateMapper.java 运费测算 + 地址属性映射 │ │ ├── HengjianInventoryMapper.java 库存两个接口 + 变动流水 │ │ ├── HengjianInboundMapper.java 入库计划创建 - │ │ └── HengjianInboundQueryMapper.java 入库详情 / 列表 + │ │ ├── HengjianInboundQueryMapper.java 入库详情 / 列表 + │ │ └── HengjianTransferMapper.java 调拨创建 / 查询 / 取消 │ ├── dto/ │ │ ├── HengjianWarehouseDtos.java │ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型 @@ -658,13 +719,14 @@ warehouse-sdk-hengjian/ ├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射 ├── adapter/HengjianInboundCreateTest.java 17 个:必填 / 柜型 / 装箱 / 无仓单号 ├── adapter/HengjianInboundQueryTest.java 18 个:详情映射 / 状态码表 / 列表过滤 / 分页 + ├── adapter/HengjianTransferTest.java 21 个:必填 / 字符串数量 / 外部仓 / 13 状态 / 取消 ├── 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` 全部通过(238 个 + 4 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(259 个 + 4 个跳过)。 ## 5. 探针用法 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java index f6c0a60..936af37 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java @@ -55,6 +55,20 @@ public interface TransferCapable extends WarehouseAdapter { } /** + * 多条件分页查调拨单。 + * + *
与 {@link #getTransfer} 的区别:那个按单号查单条,这个支持仓 / 单号 / 项目 + * 等条件分页。不支持的维度由适配器显式拒绝。
+ * + *默认不支持——只有提供列表接口的仓才覆盖。
+ */ + default common.ecommerce.shared.support.Page恒健 {@code projectUnicode},文档标必填;用于仓方按项目分账 / 路由。
+ */ + private final String projectCode; + /** + * 是否更换产品标;null 表示不传(由仓方按默认否处理)。 + * + *恒健 {@code isLabel}(1 是 / 0 否)。与 {@link #labelRequirements()} 不同: + * 那个是「需要哪些标签」的清单,这个是「是否换标」的布尔开关。
+ */ + private final Boolean relabelProducts; + /** Amazon referenceId;恒健 {@code refferenceId}(文档里就是三个 f,照抄)。 */ + private final String referenceId; + /** 提货日期;恒健 {@code deliveryDate}({@code yyyy-MM-dd})。 */ + private final java.time.LocalDate deliveryDate; + /** + * 该调拨是否为「发往外部地址」。 + * + *恒健要求仓外调拨时 {@code inOrgWarehouseCode} 固定填 {@code Other}; + * 统一模型用 {@code toWarehouseCode} 表达,值为 {@code Other} 时即外部。 + * 该标志只用于适配器判断是否走外部地址分支,不单独下发。
+ */ + private final boolean externalDestination; + private TransferCommand(Builder b) { if (b.transferRequestNo == null || b.transferRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("transferRequestNo must not be blank"); @@ -158,6 +186,11 @@ public final class TransferCommand { this.bolAttachments = java.util.Collections.unmodifiableList( new java.util.ArrayList恒健字段:{@code attachesEntityList}(findByPage)。其它仓未提供时为空列表。
+ */ + private final List恒健 {@code projectUnicode}(findByPage)。其它仓未提供时为 null。
+ */ + private final String projectCode; /** 商品明细;查询详情时回填,创建返回时通常为空。 */ private final List各仓支持的维度不同:不支持的维度由适配器显式拒绝, + * 不静默忽略——忽略一个过滤条件会让调用方以为「这段时间就这么多调拨单」。
+ */ +public final class TransferQuery { + + private final List与 {@link #getTransfer(String)} 的区别:那个按单号查单条,这个支持条件分页。
+ */ + public common.ecommerce.shared.support.Page真机确认必填:{@code outOrgWarehouseCode} / {@code inOrgWarehouseCode} / + * {@code estimateOutboundTime} / {@code estimateInboundTime}。响应 {@code data} + * 是字符串单号。
+ */ + public static final String PATH_TRANSFER_CREATE = "/v1/transferPlan/create"; + + /** 调拨计划查询({@code GET},分页;rows 默认最高 100)。 */ + public static final String PATH_TRANSFER_PAGE = "/v1/transferPlan/findByPage"; + + /** + * 调拨计划取消({@code GET},参数在 query)。 + * + *真机确认 {@code sourceNo} 必填(缺了回 + * {@code Required String parameter 'sourceNo' is not present})。
+ */ + public static final String PATH_TRANSFER_CANCEL = "/v1/transferPlan/cancel"; + + /** * {@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 1c82d8d..b3a8db7 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 @@ -10,6 +10,7 @@ import common.ecommerce.hengjian.dto.HengjianInventoryDtos; import common.ecommerce.hengjian.dto.HengjianInboundCreateDtos; import common.ecommerce.hengjian.dto.HengjianInboundQueryDtos; import common.ecommerce.hengjian.dto.HengjianInventoryMovementDtos; +import common.ecommerce.hengjian.dto.HengjianTransferDtos; import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; import common.ecommerce.hengjian.dto.HengjianOrderListDtos; @@ -32,6 +33,7 @@ import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.AddressClassificationCapable; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; +import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.TrackingChangeCapable; @@ -65,6 +67,9 @@ import common.ecommerce.warehouse.model.InventoryMovement; import common.ecommerce.warehouse.model.InventoryMovementQuery; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; +import common.ecommerce.warehouse.model.TransferCommand; +import common.ecommerce.warehouse.model.TransferOrder; +import common.ecommerce.warehouse.model.TransferQuery; import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundOrder; @@ -100,7 +105,7 @@ import java.util.Map; public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable, - InboundCapable { + InboundCapable, TransferCapable { private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; private static final String OP_CARRIERS = "warehouse.directory.carriers"; @@ -122,6 +127,9 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti private static final String OP_INBOUND_CREATE = "warehouse.inbound.create"; private static final String OP_INBOUND_GET = "warehouse.inbound.get"; private static final String OP_INBOUND_QUERY = "warehouse.inbound.query"; + private static final String OP_TRANSFER_CREATE = "warehouse.transfer.create"; + private static final String OP_TRANSFER_QUERY = "warehouse.transfer.query"; + private static final String OP_TRANSFER_CANCEL = "warehouse.transfer.cancel"; /** 保存语义没有 create / update 之分,仓方也不回是哪种。 */ private static final String SAVED = "SAVED"; @@ -156,6 +164,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.TRACKING_CHANGE, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND, + WarehouseCapability.TRANSFER, WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE, WarehouseCapability.ADDRESS_CLASSIFICATION, @@ -163,6 +172,85 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.LOGISTICS_PRODUCT); } + // ------------------------------------------------------------------ 调拨 + + /** + * 创建调拨计划({@code POST /v1/transferPlan/create})。 + * + *真机确认必填:调出 / 调入仓、期望出库 / 入库时间。 + * 响应 {@code data} 是字符串单号(不是对象)。
+ * + *外部仓库用仓代码 {@code Other} 表达——恒健的约定,适配器不猜。
+ */ + @Override + public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) { + HengjianTransferDtos.CreateRequest body = HengjianTransferMapper.toRequest(cmd); + String raw = execute(ctx, HengjianConstants.PATH_TRANSFER_CREATE, body, OP_TRANSFER_CREATE); + String planNo = json.stringAt(raw, "data"); + if (trimToNull(planNo) == null) { + // 拿不到单号不能当成功:后续查询 / 取消都要它 + throw WarehouseException.builder() + .message("hengjian transfer returned no data (plan no): " + safeRelay(raw)) + .operation(OP_TRANSFER_CREATE) + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false) + .rawResponse(safeRelay(raw)) + .build(); + } + return HengjianTransferMapper.toCreated(cmd, planNo.trim()); + } + + /** + * 多条件分页查调拨计划({@code GET /v1/transferPlan/findByPage})。 + * + *恒健的过滤参数都是单值(不是数组),所以统一模型里给了多个单号时 + * 只下发第一个——这与其它接口「拒绝多值」的做法不同,因为这里的语义是 + * 「按这个单号查」,多给没有意义。文档已注明。
+ */ + @Override + public Page这是统一模型里 {@link TransferCapable#deleteTransfer} 的落点:恒健叫「取消」, + * 语义等价于「撤销这张调拨单」。取消要收费是运去哪的概念,恒健没有。
+ * + *参数在 query(不是 body);真机确认 {@code sourceNo} 必填。
+ */ + @Override + public void deleteTransfer(WarehouseContext ctx, String providerTransferNo) { + String sourceNo = trimToNull(providerTransferNo); + if (sourceNo == null) { + throw new IllegalArgumentException("hengjian transfer cancel requires sourceNo"); + } + Map{@code outOrgWarehouseCode} / {@code inOrgWarehouseCode} / + * {@code estimateOutboundTime} / {@code estimateInboundTime}。文档另标了 + * {@code projectUnicode} / {@code transportationType} / {@code inventoryType} / + * {@code isLabel} / {@code receiveStore} / 六个 {@code shipTo*}, + * 但真机校验里没有——按选填实现。
+ * + *创建的 {@code details[].qty} 是 STRING(不是 INTEGER), + * 查询响应里是 INTEGER。两个 DTO 各自声明,互不干扰。
+ */ +public final class HengjianTransferMapper { + + /** 恒健日期时间格式(文档写 {@code yyyy-mm-dd h24:mi:ss})。 */ + private static final DateTimeFormatter DATE_TIME = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + + /** 外部仓库的固定代号。 */ + static final String OTHER_WAREHOUSE = "Other"; + + /** 运输方式:1 客户安排。 */ + static final int TRANSPORT_CUSTOMER = 1; + /** 运输方式:2 仓库安排。 */ + static final int TRANSPORT_WAREHOUSE = 2; + + /** 恒健列表单页上限(文档:默认最高 100)。 */ + static final int MAX_ROWS = 100; + + private HengjianTransferMapper() { + } + + // ================================================================ 创建 + + /** + * 统一命令 → 恒健创建请求。 + * + * @param ctx 用于取期望出库 / 入库时间(统一模型只有日期) + * @throws IllegalArgumentException 缺必填项 + */ + public static HengjianTransferDtos.CreateRequest toRequest(TransferCommand cmd) { + String from = requireText(cmd.fromWarehouseCode(), "fromWarehouseCode"); + String to = requireText(cmd.toWarehouseCode(), "toWarehouseCode"); + LocalDate outDate = cmd.estimateOutboundDate(); + LocalDate inDate = cmd.estimateInboundDate(); + if (outDate == null || inDate == null) { + // 恒健只要「期望出库 / 入库时间」,统一模型里是日期;缺一个都发不出去 + throw new IllegalArgumentException( + "hengjian transfer requires estimateOutboundDate and estimateInboundDate"); + } + + HengjianTransferDtos.CreateRequest req = new HengjianTransferDtos.CreateRequest(); + req.projectUnicode = trimToNull(cmd.projectCode()); + req.outOrgWarehouseCode = from; + req.inOrgWarehouseCode = to; + req.transportationType = transportationTypeOf(cmd.transportationType()); + req.inventoryType = cmd.inventoryType(); + req.isLabel = flagOf(cmd.relabelProducts()); + req.sourceNo = cmd.transferRequestNo(); + // 统一模型只有日期,恒健要日期时间:按当天 00:00:00 补全(不编造具体时刻) + req.estimateOutboundTime = dateTimeOf(outDate); + req.estimateInboundTime = dateTimeOf(inDate); + req.shipmentId = trimToNull(cmd.shipmentId()); + req.refferenceId = trimToNull(cmd.referenceId()); + req.receiveStore = trimToNull(cmd.receiveStore()); + req.remark = trimToNull(cmd.remark()); + req.deliveryDate = cmd.deliveryDate() == null ? null : cmd.deliveryDate().toString(); + + if (cmd.shipTo() != null) { + req.shipToCountry = trimToNull(cmd.shipTo().countryCode()); + req.shipToState = trimToNull(cmd.shipTo().stateOrProvince()); + req.shipToCity = trimToNull(cmd.shipTo().city()); + req.shipToPostal = trimToNull(cmd.shipTo().postalCode()); + req.shipToAddress1 = trimToNull(cmd.shipTo().addressLine1()); + req.shipToAddress2 = trimToNull(cmd.shipTo().addressLine2()); + req.shipToContact = trimToNull(cmd.shipTo().name()); + req.shipToTelephone = trimToNull(cmd.shipTo().phone()); + } + + req.details = toDetails(cmd.lines()); + return req; + } + + /** 产品明细:数量按字符串下发(恒健该字段标 STRING)。 */ + private static List恒健 1 客户安排 / 2 仓库安排。统一模型的 {@code transportationType} 是 + * 仓方口径的裸数字,所以直接透传 1 / 2;其它值拒绝而不是猜—— + * 猜错会让客户被误收运费。
+ */ + static Integer transportationTypeOf(int raw) { + if (raw == TRANSPORT_CUSTOMER || raw == TRANSPORT_WAREHOUSE) { + return raw; + } + // 0 表示未指定:按「仓库安排」下发(恒健的常用默认),并在文档里注明 + if (raw == 0) { + return TRANSPORT_WAREHOUSE; + } + throw new IllegalArgumentException( + "hengjian transfer transportationType must be 1 (customer) or 2 (warehouse), got " + raw); + } + + /** 日期 → {@code yyyy-MM-dd HH:mm:ss}(当天 00:00:00,不编造时刻)。 */ + static String dateTimeOf(LocalDate date) { + return date.atStartOfDay().format(DATE_TIME); + } + + private static Integer flagOf(Boolean flag) { + return flag == null ? null : (flag ? 1 : 0); + } + + private static String requireText(String value, String field) { + String v = trimToNull(value); + if (v == null) { + throw new IllegalArgumentException("hengjian transfer requires " + field); + } + return v; + } + + // ================================================================ 查询 + + /** 查询参数(GET)。 */ + public static Map创建接口真机确认的必填项(按校验顺序):
+ *+ * outOrgWarehouseCode(调出仓库不能为空) + * inOrgWarehouseCode(调入仓库不能为空) + * estimateOutboundTime(期望出库日期不能为空) + * estimateInboundTime(期望入库日期不能为空) + *+ *
文档还标了 {@code projectUnicode} / {@code transportationType} / {@code inventoryType} / + * {@code isLabel} / {@code receiveStore} / 六个 {@code shipTo*} 为必填,但真机校验里没有它们 + * ——不传都能过参数校验(只停在鉴权处)。按选填实现,与 {@code currency}(入库创建) + * 是同一类情况。
+ * + *响应 {@code data} 是字符串(调拨计划单号),不是对象。
+ */ +public final class HengjianTransferDtos { + + private HengjianTransferDtos() { + } + + // ================================================================ 创建 + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateRequest { + + /** 项目编号;文档标必填,真机不校验。 */ + public String projectUnicode; + + /** 调出仓库;必填。外部仓库填 {@code Other}。 */ + public String outOrgWarehouseCode; + + /** 调入仓库;必填。外部仓库填 {@code Other}。 */ + public String inOrgWarehouseCode; + + /** 运输方式:1 客户安排 / 2 仓库安排。 */ + public Integer transportationType; + + /** 库存类型:0 可售 / 1 不可售。 */ + public Integer inventoryType; + + /** 是否更换产品标:1 是 / 0 否。 */ + public Integer isLabel; + + /** 来源单号(参考字段);我们下发时用 transferRequestNo。 */ + public String sourceNo; + + /** 期望出库日期 {@code yyyy-MM-dd HH:mm:ss};必填。 */ + public String estimateOutboundTime; + + /** 期望入库日期 {@code yyyy-MM-dd HH:mm:ss};必填。 */ + public String estimateInboundTime; + + /** Amazon ShipmentId(参考字段)。 */ + public String shipmentId; + + /** Amazon referenceId(参考字段);文档里就是三个 f,照抄。 */ + public String refferenceId; + + /** 目的地址 CODE,默认等于调入仓库。 */ + public String receiveStore; + + public String shipToCountry; + public String shipToState; + public String shipToCity; + public String shipToPostal; + public String shipToAddress1; + public String shipToAddress2; + public String shipToContact; + public String shipToTelephone; + + /** 提货日期 {@code yyyy-MM-dd}。 */ + public String deliveryDate; + + public String remark; + + /** 产品明细;必填。 */ + public List用 String 接住——文档标 INTEGER,但同站的其它接口出现过数字串, + * 两种都能解析。
+ */ + @JsonProperty("transferOutboundPlanStatus") + public String transferOutboundPlanStatus; + + @JsonProperty("outOrgWarehouseCode") + public String outOrgWarehouseCode; + @JsonProperty("inOrgWarehouseCode") + public String inOrgWarehouseCode; + + /** 运输方式:1 客户安排 / 2 仓库安排。 */ + @JsonProperty("transportationType") + public Integer transportationType; + /** 库存类型:0 可售 / 1 不可售。 */ + @JsonProperty("inventoryType") + public Integer inventoryType; + /** 是否更换产品标:1 是 / 0 否。 */ + @JsonProperty("isLabel") + public Integer isLabel; + + @JsonProperty("sourceNo") + public String sourceNo; + + /** 期望出库 / 入库时间 {@code yyyy-MM-dd HH:mm:ss}。 */ + @JsonProperty("estimateOutboundTime") + public String estimateOutboundTime; + @JsonProperty("estimateInboundTime") + public String estimateInboundTime; + + /** 实际出库时间(示例里有,字段表没列)。 */ + @JsonProperty("actualOutboundTime") + public String actualOutboundTime; + + @JsonProperty("shipmentId") + public String shipmentId; + /** referenceId;文档拼成 {@code refferenceId},照抄。 */ + @JsonProperty("refferenceId") + public String refferenceId; + + @JsonProperty("receiveStore") + public String receiveStore; + + @JsonProperty("shipToCountry") + public String shipToCountry; + @JsonProperty("shipToState") + public String shipToState; + @JsonProperty("shipToCity") + public String shipToCity; + @JsonProperty("shipToPostal") + public String shipToPostal; + @JsonProperty("shipToAddress1") + public String shipToAddress1; + @JsonProperty("shipToAddress2") + public String shipToAddress2; + @JsonProperty("shipToContact") + public String shipToContact; + @JsonProperty("shipToTelephone") + public String shipToTelephone; + + @JsonProperty("remark") + public String remark; + + /** 产品明细。 */ + @JsonProperty("details") + public List码表来自《调拨计划单查询接口》:0 草稿 / 3 已驳回 / 5 待审核 / 7 审核通过 / + * 8 待确认 / 10 待出库 / 15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 / + * 90 已关闭 / 100 取消中 / 110 已取消。
+ * + *精确匹配,未知归 {@link #UNKNOWN} 不猜;原值同时写进 + * {@code TransferOrder.rawStatus}。
+ * + *注意 {@code 100}(取消中)与 {@code 110}(已取消)是两个状态—— + * 合并就分不出「取消请求已发出」和「仓方已确认取消」。
+ */ +public enum HengjianTransferStatus { + + /** 0 草稿。 */ + DRAFT("0", TransferStatus.DRAFT), + /** 3 已驳回。 */ + REJECTED("3", TransferStatus.REJECTED), + /** 5 待审核。 */ + PENDING_REVIEW("5", TransferStatus.PENDING_REVIEW), + /** 7 审核通过。 */ + APPROVED("7", TransferStatus.APPROVED), + /** 8 待确认。 */ + PENDING_CONFIRM("8", TransferStatus.PENDING_CONFIRM), + /** 10 待出库。 */ + PENDING_OUTBOUND("10", TransferStatus.PENDING_OUTBOUND), + /** 15 出库中。 */ + OUTBOUNDING("15", TransferStatus.OUTBOUNDING), + /** 20 待入库。 */ + PENDING_INBOUND("20", TransferStatus.PENDING_INBOUND), + /** 25 入库中。 */ + INBOUNDING("25", TransferStatus.INBOUNDING), + /** 70 已完成。 */ + COMPLETED("70", TransferStatus.COMPLETED), + /** 90 已关闭。 */ + CLOSED("90", TransferStatus.CLOSED), + /** 100 取消中。 */ + CANCELLING("100", TransferStatus.CANCELLING), + /** 110 已取消。 */ + CANCELLED("110", TransferStatus.CANCELLED), + /** 无法识别。 */ + UNKNOWN(null, TransferStatus.UNKNOWN); + + private final String rawCode; + private final TransferStatus core; + + HengjianTransferStatus(String rawCode, TransferStatus core) { + this.rawCode = rawCode; + this.core = core; + } + + /** 恒健原始码;null 表示无法识别。 */ + public String rawCode() { + return rawCode; + } + + public TransferStatus toCore() { + return core; + } + + /** 精确匹配(忽略首尾空白);空值 / 未收录归 {@link #UNKNOWN}。 */ + public static HengjianTransferStatus of(String raw) { + if (raw == null) { + return UNKNOWN; + } + String s = raw.trim(); + if (s.isEmpty()) { + return UNKNOWN; + } + for (HengjianTransferStatus v : values()) { + if (v.rawCode != null && s.equals(v.rawCode)) { + return v; + } + } + return UNKNOWN; + } + + public static TransferStatus toCore(String raw) { + return of(raw).toCore(); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTransferTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTransferTest.java new file mode 100644 index 0000000..ae4bb79 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianTransferTest.java @@ -0,0 +1,371 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.hengjian.enums.HengjianTransferStatus; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.support.Page; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.TransferStatus; +import common.ecommerce.warehouse.enums.TransferType; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.model.TransferCommand; +import common.ecommerce.warehouse.model.TransferOrder; +import common.ecommerce.warehouse.model.TransferQuery; +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 java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 调拨计划创建 / 查询 / 取消契约测试。 + */ +class HengjianTransferTest { + + private static final WarehouseContext CTX = WarehouseContext.of( + "HJ-EFGA", WarehouseProvider.HENGJIAN, "EFGA", + WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("token-1").build()), + "req-1", Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC)); + + private static HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + private static TransferCommand.Builder command() { + return TransferCommand.builder() + .transferRequestNo("TF-2026-0001") + .type(TransferType.WAREHOUSE_TO_WAREHOUSE) + .fromWarehouseCode("EFGA") + .toWarehouseCode("EFCA") + .inventoryType(0) + .transportationType(2) + .estimateOutboundDate(LocalDate.parse("2026-12-01")) + .estimateInboundDate(LocalDate.parse("2026-12-10")) + .projectCode("P-1") + .relabelProducts(false) + .line("SKU-A", 3); + } + + // ================================================================ 创建 + + private static RecordingTransport creating() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200," + + "\"message\":\"创建调拨计划单成功\",\"data\":\"HI-TF2212089091\"}")); + } + + @Test + void createPostsToTransferPlan() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/transferPlan/create", + transport.lastDataRequest().url()); + } + + /** 真机确认的四个必填项都要有。 */ + @Test + void createSendsMandatoryFields() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + String body = transport.lastDataRequest().body(); + + String[] mandatory = {"outOrgWarehouseCode", "inOrgWarehouseCode", + "estimateOutboundTime", "estimateInboundTime", "details"}; + for (String field : mandatory) { + assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body); + } + } + + /** 日期补成 yyyy-MM-dd HH:mm:ss(当天 00:00:00,不编造时刻)。 */ + @Test + void createFormatsDatesWithMidnight() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"estimateOutboundTime\":\"2026-12-01 00:00:00\""), body); + assertTrue(body.contains("\"estimateInboundTime\":\"2026-12-10 00:00:00\""), body); + } + + /** 数量按字符串下发(恒健该字段标 STRING)。 */ + @Test + void detailsQuantityIsString() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"qty\":\"3\""), "数量必须是字符串,body=" + body); + assertFalse(body.contains("\"qty\":3"), "不能发成数字"); + } + + /** 外部仓库用 Other;收货地址整组下发。 */ + @Test + void createSendsExternalDestination() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command() + .toWarehouseCode("Other") + .externalDestination(true) + .shipTo(ShipTo.builder() + .name("Recv").phone("555").countryCode("US").stateOrProvince("GA") + .city("Atlanta").addressLine1("1 St").addressLine2("Suite 2") + .postalCode("30349").build()) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"inOrgWarehouseCode\":\"Other\""), body); + assertTrue(body.contains("\"shipToCity\":\"Atlanta\""), body); + assertTrue(body.contains("\"shipToContact\":\"Recv\""), body); + assertTrue(body.contains("\"shipToPostal\":\"30349\""), body); + } + + /** 未指定运输方式(0)按「仓库安排」兜底并说明;其它值拒绝。 */ + @Test + void transportationTypeMapping() { + RecordingTransport transport = creating(); + adapter(transport).create(CTX, command().transportationType(0).build()); + assertTrue(transport.lastDataRequest().body().contains("\"transportationType\":2")); + + RecordingTransport customer = creating(); + adapter(customer).create(CTX, command().transportationType(1).build()); + assertTrue(customer.lastDataRequest().body().contains("\"transportationType\":1")); + + RecordingTransport bad = creating(); + assertThrows(IllegalArgumentException.class, + () -> adapter(bad).create(CTX, command().transportationType(9).build())); + } + + /** 缺出库 / 入库日期时本地拒绝:恒健必填,发出去也会被抓。 */ + @Test + void createRequiresBothDates() { + RecordingTransport transport = creating(); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(CTX, TransferCommand.builder() + .transferRequestNo("TF-X").type(TransferType.WAREHOUSE_TO_WAREHOUSE) + .fromWarehouseCode("EFGA").toWarehouseCode("EFCA") + .line("SKU-A", 1) + .build())); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 拿不到单号不能当成功。 */ + @Test + void createRejectsResponseWithoutPlanNo() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"code\":200,\"message\":\"OK\"}")); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).create(CTX, command().build())); + assertTrue(ex.getMessage().contains("plan no"), ex.getMessage()); + } + + @Test + void createdOrderCarriesProviderNo() { + TransferOrder order = adapter(creating()).create(CTX, command().build()); + + assertEquals("TF-2026-0001", order.transferRequestNo()); + assertEquals("HI-TF2212089091", order.providerTransferNo()); + assertEquals("EFGA", order.fromWarehouseCode()); + assertEquals("EFCA", order.toWarehouseCode()); + assertEquals(3, order.totalQuantity()); + // 创建接口不回状态:保持 UNKNOWN,不拿请求侧的值冒充 + assertEquals(TransferStatus.UNKNOWN, order.status()); + assertEquals(WarehouseProvider.HENGJIAN, order.sourceProvider()); + } + + // ================================================================ 查询 + + private static final String PAGE_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询调拨计划单成功\",\"data\":{" + + "\"totalElements\":1,\"totalPages\":1,\"numberOfElements\":1," + + "\"number\":0,\"size\":10,\"last\":true,\"content\":[{" + + "\"id\":45595,\"transferOutboundPlanNo\":\"XH-TF2604100004\"," + + "\"projectUnicode\":\"德姆勒-分销\",\"transferOutboundPlanStatus\":70," + + "\"outOrgWarehouseCode\":\"EFGA\",\"inOrgWarehouseCode\":\"Other\"," + + "\"transportationType\":2,\"inventoryType\":0,\"isLabel\":0," + + "\"sourceNo\":\"TF-2026-0001\"," + + "\"estimateOutboundTime\":\"2026-12-01 00:00:00\"," + + "\"estimateInboundTime\":\"2026-12-10 00:00:00\"," + + "\"details\":[{\"sku\":\"SKU-A\",\"qty\":3,\"qtyOutbound\":3,\"qtyInbound\":0}]," + + "\"attachesEntityList\":[{\"attachmentId\":1,\"type\":\"Other\"," + + "\"name\":\"test.jpg\",\"url\":\"https://cdn/x.jpg\"}]}]}}"; + + private static RecordingTransport paging() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_TRANSFER_PAGE, req -> Responses.ok(PAGE_BODY)); + } + + @Test + void querySendsPagingAndFilters() { + RecordingTransport transport = paging(); + adapter(transport).queryTransfers(CTX, TransferQuery.builder() + .sourceNo("TF-2026-0001") + .providerTransferNo("XH-TF2604100004") + .projectCode("P-1") + .fromWarehouseCode("EFGA") + .toWarehouseCode("Other") + .pageSize(10) + .build()); + + String url = transport.lastDataRequest().url(); + assertEquals("GET", transport.lastDataRequest().method()); + assertTrue(url.contains("page=1"), url); + assertTrue(url.contains("rows=10"), url); + assertTrue(url.contains("sidx=id"), url); + assertTrue(url.contains("sort=desc"), url); + assertTrue(url.contains("sourceNo=TF-2026-0001"), url); + assertTrue(url.contains("transferOutboundPlanNo=XH-TF2604100004"), url); + assertTrue(url.contains("outOrgWarehouseCode=EFGA"), url); + assertTrue(url.contains("inOrgWarehouseCode=Other"), url); + } + + @Test + void queryMapsOrder() { + Page