From 586d9c5eb847be21e54e794a5c6360d8054754c3 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Thu, 12 Nov 2026 17:57:35 +0800 Subject: [PATCH] =?UTF-8?q?feat(hengjian):=20=E5=AF=B9=E6=8E=A5=E5=88=9B?= =?UTF-8?q?=E5=BB=BA=E9=94=80=E5=94=AE=E5=8F=91=E8=B4=A7=E5=8D=95=20/v1/sa?= =?UTF-8?q?leOrder/create?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 HengjianCreateOrderDtos + HengjianOutboundMapper,实现 OutboundCapable.create, 声明 OUTBOUND 与 PLATFORM_LABEL_DELIVERY 能力位 - 时间按 UTC 的 yyyy-MM-dd HH:mm:ss 输出(文档明确 utc),不用仓时区—— 那个时区是给仓方回传的无时区本地时间用的,方向相反 - skuAmount 取「行总额」:有 totalAmount 直接用,否则申报单价 × 数量 - isSignature 挂在行上且必填:取命令的布尔值套到每一行,成人 / 间接签收 统一映射成直接签收(1),比静默降成 0 安全 - attachInfoItems 必填:无附件发空数组;平台面单剥掉 data: 前缀后进 file - 必填字段(地址六项 / 城市 / createdAt / 产品行)本地拒绝,不发无效请求 - 响应只回 data.orderId,拿不到即报错——取消接口同时要 orderId 与 orderNo - 查询 / 取消 / 包裹仍显式拒绝,不返回 null;写探针增加建单用例 - 文档补建单口径与两页文档不一致处 验证:mvn test 全量通过,恒健 74 个用例 + 2 个探针跳过。 Co-Authored-By: Claude Code --- README.md | 10 +- docs-warehouse/hengjian/README.md | 105 +++-- .../ecommerce/hengjian/HengjianConstants.java | 8 + .../hengjian/adapter/HengjianAdapter.java | 117 +++++- .../hengjian/adapter/HengjianOutboundMapper.java | 243 ++++++++++++ .../hengjian/dto/HengjianCreateOrderDtos.java | 200 ++++++++++ .../hengjian/adapter/HengjianAdapterTest.java | 18 +- .../hengjian/adapter/HengjianCreateOrderTest.java | 440 +++++++++++++++++++++ .../hengjian/adapter/HengjianDirectoryTest.java | 6 +- .../hengjian/probe/HengjianWriteProbeTest.java | 65 +++ 10 files changed, 1168 insertions(+), 44 deletions(-) create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java create mode 100644 warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java diff --git a/README.md b/README.md index d5af3c0..b7b2b92 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,11 +376,11 @@ common.ecommerce │ └── hengjian 恒健三方仓(warehouse-sdk-hengjian) ├── HengjianConstants 测试基址、当前接入路径、双授权头名、成功码 / 未授权码、限流 - ├── adapter HengjianAdapter(仓库目录 + 承运商 + 按仓渠道 + 商品保存)/ + ├── adapter HengjianAdapter(目录 + 渠道 + 商品保存 + 出库下单)/ │ HengjianAdapterFactory / HengjianDirectoryMapper / - │ HengjianProductMapper + │ HengjianProductMapper / HengjianOutboundMapper ├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos / - │ HengjianProductSaveDtos + │ HengjianProductSaveDtos / HengjianCreateOrderDtos ├── enums (package-info:调拨 / 出库状态枚举约定,待建) ├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter └── webhook (package-info:文档无回调页,未实现) @@ -1076,7 +1076,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 696ed37..3bae611 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -49,6 +49,9 @@ | 7 | 《创建/编辑 产品》`length` vs 《查询 sku》`itemLength` | 同一概念两个字段名;接入商品前要真机确认哪个是「产品长」 | | 8 | 试算 / 地址属性文档的路径写的是 `open-api.ehenglin.com`、`thebizark.com` | 与 `ehengjian.com` 不同域,疑似旧域名或从别家文档复制;接入前必须真机核对 | | 9 | 几乎所有接口页**没有验签 / 请求头说明** | 真机返回早于业务码的 Spring 错误页,说明鉴权在网关层,文档没覆盖 | +| 10 | 《创建销售发货单》与 "Create Sale Order With Label" 是同一路径的两页 | 中文页把 `createdAt` 标必填、也没有 `isPrime`;英文页有 `isPrime`、没有 `customerRemark` / `warehouseRemark`。字段表按两页并集实现 | +| 11 | 建单页 `isPrime` 类型写 STRING | 请求示例给的是数字 `0`;按示例发 Integer | +| 12 | 建单页行级 `isSignature` 是 0~3 | 统一模型只有布尔,2 / 3(成人 / 间接签收)暂不可表达 | > 运去哪的教训:只按文档写代码,有 4 处接口一个都跑不通。恒健的文档完整度更差 > (路径缺失、类型不一致、域名不一致),**接入任何写接口前必须先跑只读探针**。 @@ -61,10 +64,12 @@ | 2 | 获取物流渠道(全量) | `POST /v2/carrierGroup/getCarrierGroup` | `DIRECTORY` / `LOGISTICS_PRODUCT` | ✅ | | 3 | 获取仓库支持的物流渠道 | `POST /v2/carrierGroup/getWarehouseCarrierGroupServices` | 同上(适配器方法,非 capability) | ✅ | | 4 | 创建 / 编辑产品 | `POST /v1/product/save` | `PRODUCT` | ✅ | -| 5 | 回调 | — | — | ❌ 文档无回调页 | +| 5 | 创建销售发货单 | `POST /v1/saleOrder/create` | `OUTBOUND` / `PLATFORM_LABEL_DELIVERY` | ✅ | +| 6 | 回调 | — | — | ❌ 文档无回调页 | 前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, -但只写主数据、不产生履约单据,所以放在第二阶段。 +但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, +门面强制经幂等守卫(`warehouseCode + outboundRequestNo + create`)。 ### 返回形状差异 @@ -130,34 +135,61 @@ - `cost` 与 `currency` 成对发送;`cost` 缺失则两个都不发。 - 单位与统一模型一致(cm / g),**不做换算**。 +### 创建销售发货单(`/v1/saleOrder/create`) + +中英文两页文档是**同一个接口**(中文页「创建销售发货单(带附件的)」、英文页 +「Create Sale Order With Label」),按两页并集实现。 + +**必填字段**:`orderNo`、`shipToCountry`、`shipToState`、`shipToCity`、`shipToPostal`、 +`shipToAddress1`、`shipToContact`、`shipToTelephone`、`createdAt`、`productItems`、 +`attachInfoItems`。适配器在本地逐项校验,缺任何一项直接抛 `IllegalArgumentException`, +**一个请求都不发**。 + +**几个关键口径**: + +| 项 | 处理 | +|---|---| +| `createdAt` | 统一模型没有该字段,用调用方注入的 `Clock` 生成下单时刻(请求侧时间戳,不是编造数据)。恒健不拿它去重 | +| 时间格式 | 恒健是 **UTC** 的 `yyyy-MM-dd HH:mm:ss`,固定按 UTC 格式化,**不用** `WarehouseContext.zone()`——那个时区是给「仓方回传的无时区本地时间」用的,方向相反 | +| `skuAmount` | 是「当前 SKU **总**金额」,不是单价:有 `totalAmount` 直接用,没有就用申报单价 × 数量 | +| `isSign` / `isSignature` | 恒健挂在**行**上且必填;统一模型挂在**命令**上(布尔)。取命令值套到每一行 | +| 签收类型 | 统一模型只有布尔,表达不了成人签收(2) / 间接签收(3),统一映射成**直接签收(1)**——比静默降成「不签收(0)」安全 | +| `isInsure` / `insureAmount` | 由「行是否有保价金额」推导;有金额即视为保价并带上金额 | +| `attachInfoItems` | **必填**。没有附件时发**空数组**而不是省略字段;平台面单(base64)会剥掉 `data:` 前缀后放进 `file`,`type=0`,名称优先用跟踪号 | +| `salesPlatform` | 恒健没有平台维度(店铺路由走 `channelAccount`),**不发**,也**不**拿它推 `isDFOrder`——VC 订单里只有一部分是 DF | +| `splitOrder` / `packages` | 恒健没有拆单与包裹入参,忽略 | +| `estimatedDeliveryTime` | 恒健只有 `expectedShipDate`(要求发货时间),没有送达时间 | + +**响应**:只回 `data.orderId`(仓内部**数字** id,不是字符串单号)。取消接口要 +`orderId` + `orderNo` 两个都传,所以这个 id 必须随 `OutboundReceipt.providerOrderId()` +落库;拿不到就报错,**不当创建成功**。 + +**未接入**:查询 / 取消 / 包裹。调用这些方法会显式抛 `WarehouseException`,不返回 null—— +静默返回空会让调用方以为「仓说没有这单」。 + ## 3. 未接入(文档已有,按需排期) 按能力位分组,路径取自文档(**标注 ⚠ 的表示文档没写路径或路径可疑,需真机核对**): ### 出库(`OUTBOUND`) -| 接口 | 路径 | -|---|---| -| 创建销售发货单(带附件) | `POST /v1/saleOrder/create` → 返回 `data.orderId` | -| Create Sale Order With Label(英文版,同路径) | `POST /v1/saleOrder/create` | -| 订单详情 | `POST /v1/saleOrder/findOne` | -| 订单列表 | `GET /v1/saleOrder/findByPage` | -| 订单取消 | `POST /v1/saleOrder/cancel`(`orderId` + `orderNo` 都必填) | -| 订单上传附件 | `POST /v1/saleOrder/createAttachment` | -| 物流异动单 创建 / 查询 / 取消 | `POST /v1/trackingChange/create`、`POST /v1/saleOrder/findOrder`、`POST /v1/trackingChange/cancel` | - -要点: - -- 创建接口的必填字段:`orderNo`、`shipToCountry`、`shipToState`、`shipToCity`、`shipToPostal`、 - `shipToAddress1`、`shipToContact`、`shipToTelephone`、`createdAt`(英文版页标注 `Y`;中文版页标 `否`, - **两页矛盾**)、`productItems`(每行的 `sku/quantity/isInsure/isSignature`)、`attachInfoItems`。 -- `attachInfoItems.type`:`0` ShippingLabel / `1` PackingList / `2` BOL / `3` Other / `4` CartonLabel / - `5` PalletLabel / `6` itemlabel。`url` 与 `file`(base64) 二选一。 +| 接口 | 路径 | 状态 | +|---|---|---| +| 创建销售发货单(中文页「带附件」/ 英文页 "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/createAttachment` | ⬜ | +| 物流异动单 创建 / 查询 / 取消 | `POST /v1/trackingChange/create`、`POST /v1/saleOrder/findOrder`、`POST /v1/trackingChange/cancel` | ⬜ | + +接查询 / 取消时要注意: + - `orderStatusEnum` 取值:`pending / unshipped / approved / assigned / picked / shipped / canceled / refunded` - ——与运去哪**同名但不同源**,必须各建一套平台枚举。 -- `isSignature`:`0` 否 / `1` 直接签收 / `2` 成人签收 / `3` 间接签收(仅 FedEx)。 + ——与运去哪**同名但不同源**,必须各建一套平台枚举,精确匹配、未知归 UNKNOWN。 - 取消接口需要**创建时由仓方返回的 `orderId`**(`findByPage` 也回 `orderId`), - 只给单号不行——所以 `OutboundReceipt.providerOrderId` 必须落库。 + 只给单号不行。 +- `attachInfoItems.type`:`0` ShippingLabel / `1` PackingList / `2` BOL / `3` Other / `4` CartonLabel / + `5` PalletLabel / `6` itemlabel。`url` 与 `file`(base64) 二选一。 ### 库存(`INVENTORY_QUERY`) @@ -213,14 +245,16 @@ warehouse-sdk-hengjian/ ├── main/java/common/ecommerce/hengjian/ │ ├── HengjianConstants.java 端点 / 路径 / 两个授权头 / 成功码 / 未授权码 / 限流 │ ├── adapter/ - │ │ ├── HengjianAdapter.java 仓库目录 + 承运商 + 按仓渠道 + 商品保存 + │ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品保存 + 出库下单 │ │ ├── HengjianAdapterFactory.java │ │ ├── HengjianDirectoryMapper.java 仓库 / 渠道字段搬运 - │ │ └── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验 + │ │ ├── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验 + │ │ └── HengjianOutboundMapper.java 出库下单报文(UTC 时间 / 行总额 / 面单附件) │ ├── dto/ │ │ ├── HengjianWarehouseDtos.java │ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型 - │ │ └── HengjianProductSaveDtos.java /v1/product/save + │ │ ├── HengjianProductSaveDtos.java /v1/product/save + │ │ └── HengjianCreateOrderDtos.java /v1/saleOrder/create │ ├── enums/package-info.java 状态枚举约定(待建) │ ├── http/ │ │ ├── HengjianRequestFactory.java 双授权头 + 链路 ID @@ -230,13 +264,14 @@ warehouse-sdk-hengjian/ └── test/java/common/ecommerce/hengjian/ ├── adapter/HengjianDirectoryTest.java 13 个:请求形状 / 鉴权头 / 映射 / 能力位 ├── adapter/HengjianProductSaveTest.java 20 个:必填拒绝 / 三组尺寸 / 不编造字段 - ├── adapter/HengjianAdapterTest.java 4 个:注册 / 能力拒绝 / 枚举 + ├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝 + ├── 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` 全部通过(48 个 + 2 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(74 个 + 2 个跳过)。 ## 5. 探针用法 @@ -254,19 +289,22 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ - 4 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重。异常只打印不中断。 - 只读,不建单。 -写探针(会留下真实商品数据): +写探针(会留下真实数据): ```bash mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ -Dhengjian.probe=true -Dhengjian.probe.write=true \ -Dhengjian.probe.token=<组织token> \ -Dhengjian.probe.sku=PROBE-SKU-001 \ + -Dhengjian.probe.postcode=90001 \ -Dtest=HengjianWriteProbeTest test ``` - 两个开关同时打开才跑;SKU 默认带时间戳,重跑不撞唯一约束。 -- 2 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)。 -- **恒健没有删除产品的接口**,跑完需要人工在 Efulfill 后台清理。 +- 3 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)、建销售发货单 + (需额外给 `-Dhengjian.probe.postcode`;可选 `carrierCode` / `shopName` / `state` / `city`)。 +- **恒健没有删除产品的接口**,跑完需要人工在 Efulfill 后台清理; + 建单探针也不自动取消——取消接口尚未接入。 ## 6. 待确认(交给业务方 / 恒健) @@ -282,13 +320,16 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ | 8 | 商品「产品长」到底是 `length` 还是 `itemLength` | 《创建/编辑产品》写 `length`、《查询 sku》写 `itemLength`;接查询接口前必须确认,否则尺寸错位 | | 9 | 是否有沙箱测试 SKU | 建单需要仓方系统里真实存在的 SKU(运去哪的 `lineCode` 就踩过这个坑) | | 10 | 时区口径 | 文档多处写 UTC,但仓在美国;需真机确认返回的时间到底是不是 UTC | +| 11 | 建单的 `channelAccount` 是否必填 | 两页文档都标「否」,但写的是「必须在 Efulfill 店铺管理中维护」;未给时仓方按什么路由需真机确认 | +| 12 | `isPrime` 的真实类型 | 文档类型列写 STRING,请求示例却是数字 `0`;适配器按示例发 Integer,真机报类型错就问仓方 | +| 13 | 签收类型能否区分成人 / 间接签收 | 统一模型只有布尔,目前全部映射成「直接签收(1)」;业务若需要 2 / 3,要在 `OutboundCommand` 上加行级签收类型 | ## 7. 下一步 1. 拿到 token 后跑 `HengjianReadOnlyProbeTest` 与 `HengjianWriteProbeTest`,把结论补进本文档 - 「文档与实际不一致」表;重点验商品保存的必填组合与保存语义。 + 「文档与实际不一致」表;重点验商品保存的必填组合、保存语义、建单的必填组合与 `orderId` 回传。 2. 按 [onboarding-checklist.md](../onboarding-checklist.md) 阶段 2 逐接口接入,建议顺序: - **出库(创建 / 详情 / 列表 / 取消)→ 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2**。 + **出库详情 / 列表 / 取消 → 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2**。 3. 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。 4. 出库状态枚举按 `orderStatusEnum` 全量建(8 个值),未知归 `UNKNOWN`,原值进 `rawStatus`; 注意 `unshipped` / `shipped` 必须精确匹配,不能用 `contains("SHIP")`。 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 5a90283..c76af70 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 @@ -59,6 +59,14 @@ public final class HengjianConstants { */ public static final String PATH_PRODUCT_SAVE = "/v1/product/save"; + /** + * 创建销售发货单。 + * + *

响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与 + * {@code orderNo} 都要,所以调用方必须落库这个 id。

+ */ + public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create"; + /** 业务成功码;文档各接口一致写 {@code 200}。 */ public static final int SUCCESS_CODE = 200; 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 8fe404e..9cebeae 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 @@ -3,6 +3,7 @@ package common.ecommerce.hengjian.adapter; import com.fasterxml.jackson.databind.JsonNode; import common.ecommerce.hengjian.HengjianConstants; import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos; +import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; import common.ecommerce.hengjian.dto.HengjianProductSaveDtos; import common.ecommerce.hengjian.dto.HengjianWarehouseDtos; import common.ecommerce.hengjian.http.HengjianEnvelope; @@ -12,14 +13,26 @@ import common.ecommerce.http.HttpRequest; import common.ecommerce.http.HttpResponse; import common.ecommerce.http.HttpTransport; import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.LogisticsProductCapable; +import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; +import common.ecommerce.warehouse.enums.CancelEligibility; +import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.enums.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.WarehouseException; +import common.ecommerce.warehouse.model.CancelCommand; +import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.LogisticsProduct; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundOrder; +import common.ecommerce.warehouse.model.OutboundQuery; +import common.ecommerce.warehouse.model.OutboundReceipt; +import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.PackageResult; import common.ecommerce.warehouse.model.WarehouseFacility; import common.ecommerce.warehouse.sdk.WarehouseContext; @@ -43,12 +56,13 @@ import java.util.Map; * {@code WarehouseConnection} 传入。

*/ public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, - WarehouseProductCapable { + WarehouseProductCapable, OutboundCapable { private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; private static final String OP_CARRIERS = "warehouse.directory.carriers"; private static final String OP_LOGISTICS_PRODUCTS = "warehouse.logistics.products"; private static final String OP_PRODUCT_SAVE = "warehouse.product.create"; + private static final String OP_ORDER_CREATE = "warehouse.outbound.create"; /** 保存语义没有 create / update 之分,仓方也不回是哪种。 */ private static final String SAVED = "SAVED"; @@ -78,10 +92,111 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti public EnumSet capabilities() { return EnumSet.of( WarehouseCapability.PRODUCT, + WarehouseCapability.OUTBOUND, + WarehouseCapability.PLATFORM_LABEL_DELIVERY, WarehouseCapability.DIRECTORY, WarehouseCapability.LOGISTICS_PRODUCT); } + // ------------------------------------------------------------------ 出库 + + /** + * 创建销售发货单({@code POST /v1/saleOrder/create})。 + * + *

承接 {@code WarehouseOutbounds.create} 的幂等守卫:同一 + * {@code outboundRequestNo} 重复下发由门面拦住,这里只负责拼报文与解析。

+ * + *

响应只回 {@code data.orderId}(仓内部数字 id,不是字符串单号)。 + * 恒健的取消接口同时要 {@code orderId} 与 {@code orderNo},所以这个 id + * 必须随 {@link OutboundReceipt#providerOrderId()} 落库;缺了它后续取消做不了, + * 因此拿不到就报错,不静默当成创建成功。

+ */ + @Override + public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { + requirePlatformLabelSupported(cmd); + String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( + cmd.warehouseId(), ctx.providerWarehouseId()); + HengjianCreateOrderDtos.CreateOrderRequest body = + HengjianOutboundMapper.toRequest(cmd, warehouseCode, ctx.clock()); + + String raw = execute(ctx, HengjianConstants.PATH_ORDER_CREATE, body, OP_ORDER_CREATE); + HengjianCreateOrderDtos.CreateOrderResponse resp = + json.fromJson(raw, HengjianCreateOrderDtos.CreateOrderResponse.class); + if (resp == null || resp.data == null || resp.data.orderId == null) { + throw WarehouseException.builder() + .message("hengjian create order returned no data.orderId: " + safeRelay(raw)) + .operation(OP_ORDER_CREATE) + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false) + .rawResponse(safeRelay(raw)) + .build(); + } + return OutboundReceipt.of(cmd.outboundRequestNo(), String.valueOf(resp.data.orderId), + resp.message); + } + + /** 恒健出库查询尚未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */ + @Override + public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { + throw unsupportedOutbound("warehouse.outbound.get", ctx); + } + + @Override + public Page query(WarehouseContext ctx, OutboundQuery query) { + throw unsupportedOutbound("warehouse.outbound.query", ctx); + } + + @Override + public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) { + throw unsupportedOutbound("warehouse.outbound.checkCancel", ctx); + } + + @Override + public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { + throw unsupportedOutbound("warehouse.outbound.cancel", ctx); + } + + @Override + public List packages(WarehouseContext ctx, OutboundRef ref) { + throw unsupportedOutbound("warehouse.outbound.packages", ctx); + } + + /** + * 平台面单必须真的带文件。 + * + *

恒健的面单就是 {@code attachInfoItems} 里的一条附件;声明了 + * {@code PLATFORM_LABEL_DELIVERY} 却不给文件,仓没有面单可打,等于静默失败。

+ */ + private static void requirePlatformLabelSupported(OutboundCommand cmd) { + if (cmd.labelMode() == LabelMode.PLATFORM_LABEL + && (cmd.labelContentBase64() == null || cmd.labelContentBase64().trim().isEmpty())) { + throw new IllegalArgumentException( + "labelContentBase64 is required when labelMode=PLATFORM_LABEL for " + + cmd.outboundRequestNo()); + } + } + + 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) { + if (raw == null) { + return null; + } + return raw.length() <= 300 ? raw : raw.substring(0, 300) + "..."; + } + // ------------------------------------------------------------------ 商品 /** diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java new file mode 100644 index 0000000..f8de14d --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java @@ -0,0 +1,243 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.enums.LabelMode; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.ShipTo; + +import java.math.BigDecimal; +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 恒健出库报文映射({@code POST /v1/saleOrder/create})。 + * + *

平台字段名只出现在本类与 {@link HengjianCreateOrderDtos}。

+ * + *

时间

+ *

恒健的时间字段是 UTC 的 {@code yyyy-MM-dd HH:mm:ss}(文档明确写了 utc 时间), + * 所以格式化固定按 {@link ZoneOffset#UTC},不用 {@code WarehouseContext.zone()}—— + * 那个时区是给「仓方回传的无时区本地时间」用的,方向相反。

+ * + *

必填项

+ *

{@code createdAt} 在统一模型里没有对应字段,用调用方注入的 {@link Clock} 生成 + * 「下单时刻」。这是请求侧的时间戳,不是把仓方没给的数据编出来; + * 幂等重放时它会变,但恒健不拿它做去重。

+ * + *

统一模型里恒健没有对应概念的字段

+ * + * + * + * + * + * + * + * + * + * + *
字段处理
{@code salesPlatform}恒健没有平台维度,店铺路由走 {@code channelAccount}。不发, + * 也不拿它去推断 {@code isDFOrder}——VC 订单里只有一部分是 DF。
{@code splitOrder} / {@code packages}恒健没有拆单入参与包裹入参,忽略。
{@code estimatedDeliveryTime}恒健只有 {@code expectedShipDate}(要求发货时间),没有送达时间。
{@code declaredTotal}恒健按行收金额,没有整单申报额。
+ */ +public final class HengjianOutboundMapper { + + /** 恒健只接受 UTC 的 {@code yyyy-MM-dd HH:mm:ss}。 */ + private static final DateTimeFormatter TIME_FORMAT = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + + /** 附件类型:面单。 */ + private static final String ATTACH_TYPE_SHIPPING_LABEL = "0"; + + /** 保价 / 签收开关的取值。 */ + private static final int FLAG_NO = 0; + private static final int FLAG_YES = 1; + + /** 唯一支持的签收类型:直接签收(成人 / 间接签收统一模型表达不了)。 */ + private static final int SIGNATURE_DIRECT = 1; + + private HengjianOutboundMapper() { + } + + /** + * 统一命令 → 恒健创建订单请求。 + * + * @param warehouseCode 仓代码(命令显式指定优先,其次账户配置);null 时由仓方按默认仓处理 + * @param clock 用于生成必填的 {@code createdAt} + * @throws IllegalArgumentException 缺少恒健必填但统一模型可空的字段 + */ + public static HengjianCreateOrderDtos.CreateOrderRequest toRequest(OutboundCommand cmd, + String warehouseCode, + Clock clock) { + HengjianCreateOrderDtos.CreateOrderRequest req = new HengjianCreateOrderDtos.CreateOrderRequest(); + String orderNo = cmd.outboundRequestNo(); + req.orderNo = orderNo; + req.warehouseCode = trimToNull(warehouseCode); + req.carrier = trimToNull(cmd.carrier()); + req.carrierCode = trimToNull(cmd.carrierCode()); + // 店铺:仓方按店铺做路由 / 计费;标准模型对应 shopName + req.channelAccount = trimToNull(cmd.shopName()); + req.currency = trimToNull(cmd.currency()); + req.shipServiceLevel = trimToNull(cmd.shipServiceLevel()); + // 平台要求发货时间;恒健只在 isDFOrder=1 时强制,但有值就带上 + req.expectedShipDate = formatTime(cmd.latestShipDate()); + req.isPrime = flagOf(cmd.sfp()); + req.createdAt = formatTime(Instant.now(clock)); + req.customerRemark = trimToNull(cmd.remark()); + + ShipTo shipTo = cmd.shipTo(); + req.shipToCountry = require(shipTo.countryCode(), "shipTo.countryCode", orderNo); + req.shipToState = require(shipTo.stateOrProvince(), "shipTo.stateOrProvince", orderNo); + req.shipToPostal = require(shipTo.postalCode(), "shipTo.postalCode", orderNo); + req.shipToAddress1 = require(shipTo.addressLine1(), "shipTo.addressLine1", orderNo); + req.shipToContact = require(shipTo.name(), "shipTo.name", orderNo); + req.shipToTelephone = require(shipTo.phone(), "shipTo.phone", orderNo); + // 城市:中文页标必填、英文页未标,按必填处理 + req.shipToCity = require(shipTo.city(), "shipTo.city", orderNo); + req.shipToAddress2 = trimToNull(shipTo.addressLine2()); + req.customerEmail = trimToNull(shipTo.email()); + + req.productItems = toProductItems(cmd.lines(), cmd.signatureRequired(), orderNo); + req.attachInfoItems = toAttachInfoItems(cmd, orderNo); + return req; + } + + /** 仓方仓编码:命令显式指定优先,否则用账户配置。 */ + public static String resolveWarehouseCode(String fromCommand, String fromAccount) { + return trimToNull(fromCommand) != null ? trimToNull(fromCommand) : trimToNull(fromAccount); + } + + private static List toProductItems( + List lines, Boolean signatureRequired, String orderNo) { + boolean signature = Boolean.TRUE.equals(signatureRequired); + List items = + new ArrayList(lines.size()); + for (OutboundLine line : lines) { + HengjianCreateOrderDtos.CreateOrderRequest.ProductItem item = + new HengjianCreateOrderDtos.CreateOrderRequest.ProductItem(); + item.sku = line.providerSku() != null && !line.providerSku().trim().isEmpty() + ? line.providerSku().trim() : line.omsSku(); + item.quantity = line.quantity(); + + // 保价:统一模型只有「保价金额」,有金额即视为保价 + boolean insured = line.insuredAmount() != null; + item.isInsure = insured ? FLAG_YES : FLAG_NO; + if (insured) { + item.insureAmount = line.insuredAmount().amount().doubleValue(); + } + + // 签收:恒健的 isSignature 挂在行上,统一模型挂在命令上。 + // 语义是整单都要 / 都不要,所以取命令上的值套到每一行。 + // 统一模型只有布尔值,表达不了成人签收(2) / 间接签收(3), + // 统一映射成「直接签收(1)」——比静默降成「不签收(0)」安全 + item.isSignature = signature ? SIGNATURE_DIRECT : FLAG_NO; + + item.skuAmount = skuTotalAmount(line); + items.add(item); + } + return items; + } + + /** + * 行总金额。 + * + *

恒健 {@code skuAmount} 是「当前 SKU 总金额」,不是单价: + * 有 {@code totalAmount} 直接用;没有就用申报单价 × 数量, + * 否则整单金额会少算 quantity 倍(运去哪踩过同样的坑)。

+ */ + static Double skuTotalAmount(OutboundLine line) { + Money total = line.totalAmount(); + if (total != null) { + return total.amount().doubleValue(); + } + Money unit = line.declareValue(); + if (unit == null) { + return null; + } + return unit.amount().multiply(BigDecimal.valueOf(line.quantity())).doubleValue(); + } + + /** + * 附件:平台面单随单下发。 + * + *

恒健把 {@code attachInfoItems} 标为必填,所以没有附件时返回空数组, + * 不省略该字段——省略会被当成缺必填项。

+ * + *

仓自有面单({@link LabelMode#WAREHOUSE_LABEL})时不给附件; + * 给了面单内容却不是平台面单模式,直接拒绝,不静默丢弃。

+ */ + private static List toAttachInfoItems( + OutboundCommand cmd, String orderNo) { + String content = cmd.labelContentBase64(); + if (content == null || content.trim().isEmpty()) { + if (cmd.labelMode() == LabelMode.PLATFORM_LABEL) { + throw new IllegalArgumentException( + "hengjian order " + orderNo + + ": labelContentBase64 is required when labelMode=PLATFORM_LABEL"); + } + return new ArrayList(); + } + if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) { + throw new IllegalArgumentException( + "hengjian order " + orderNo + + ": labelContentBase64 requires labelMode=PLATFORM_LABEL"); + } + HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem item = + new HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem(); + // 文档建议附件名填跟踪号且不带后缀;没有运单号时退回出库单号 + String tracking = trimToNull(cmd.trackingNumber()); + item.name = tracking != null ? tracking : orderNo; + // 恒健同一个字段 url / file 二选一,file 优先;文档没说 file 支持 data URI 头, + // 这里统一剥掉,避免把 "data:application/pdf;base64," 当成文件内容解出来 + item.file = stripDataUri(content); + item.type = ATTACH_TYPE_SHIPPING_LABEL; + List out = + new ArrayList(1); + out.add(item); + return Collections.unmodifiableList(out); + } + + /** 去掉 {@code data:xxx/base64,} 头;没有头时原样返回。 */ + static String stripDataUri(String content) { + if (content == null) { + return null; + } + int comma = content.indexOf(','); + if (content.startsWith("data:") && comma > 0) { + return content.substring(comma + 1); + } + return content; + } + + /** 时间 → 恒健的 UTC {@code yyyy-MM-dd HH:mm:ss};null 透传。 */ + static String formatTime(Instant instant) { + return instant == null ? null : TIME_FORMAT.format(instant.atZone(ZoneOffset.UTC)); + } + + /** 布尔开关 → 0 / 1;null 不发(由仓方按默认否处理)。 */ + private static Integer flagOf(Boolean flag) { + return flag == null ? null : (flag ? FLAG_YES : FLAG_NO); + } + + private static String require(String value, String field, String orderNo) { + String v = trimToNull(value); + if (v == null) { + throw new IllegalArgumentException( + "hengjian order " + orderNo + " requires " + field + " (恒健下单必填)"); + } + return v; + } + + private static String trimToNull(String v) { + if (v == null) { + return null; + } + String trimmed = v.trim(); + return trimmed.isEmpty() ? null : trimmed; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java new file mode 100644 index 0000000..ebfdb49 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java @@ -0,0 +1,200 @@ +package common.ecommerce.hengjian.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonInclude; +import com.fasterxml.jackson.annotation.JsonProperty; + +import java.util.List; + +/** + * 恒健报文结构:创建销售发货单({@code POST /v1/saleOrder/create})。 + * + *

中英文两页文档描述的是同一个接口,中文页叫「创建销售发货单(带附件的)」, + * 英文页叫「Create Sale Order With Label」;两页字段表基本一致,差异见各字段注释。

+ * + *

两页的必填口径不完全一致:中文页把 {@code createdAt} 标为必填、英文页也标 Y; + * 但中文页没有 {@code isPrime}(只有英文页有),英文页没有 {@code customerRemark} / + * {@code warehouseRemark}(只有中文页有)。按两页并集实现,必填取两页都要求的字段。

+ */ +public final class HengjianCreateOrderDtos { + + private HengjianCreateOrderDtos() { + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateOrderRequest { + + /** 来源单号;必填。用 OMS 的出库单号,也是后续按单号查询 / 取消的锚点。 */ + public String orderNo; + + /** 承运商名称,如 {@code FedEx} / {@code UPS}。 */ + public String carrier; + + /** 承运商服务代码,如 {@code FEDEX_GROUND} / {@code UPS_2DAY}。 */ + public String carrierCode; + + /** 仓库 code;必须已在 Efulfill 系统维护。 */ + public String warehouseCode; + + /** 店铺标识;必须已在 Efulfill 店铺管理中维护。 */ + public String channelAccount; + + /** 币种;不填默认 USD。 */ + public String currency; + + /** + * 支付时间,UTC,{@code yyyy-MM-dd HH:mm:ss};不填由仓方取当前时间。 + * + *

统一模型没有「支付时间」字段,这里通常不传。

+ */ + public String paidAt; + + /** Amazon VC Direct Fulfillment 订单:0 否 / 1 是;不填默认为否。 */ + public Integer isDFOrder; + + /** + * 是否 SFP 订单:0 否 / 1 是;不填默认为否。 + * + *

文档类型写的是 String,但请求示例给的是数字 {@code "isPrime": 0}。 + * 这里按示例用 Integer——两页示例一致,且 Spring 后端按数字绑定的可能性更高。 + * 真机若报类型错,改成 String 即可。

+ */ + public Integer isPrime; + + /** + * 平台要求发货时间,UTC,{@code yyyy-MM-dd HH:mm:ss}。 + * + *

文档:{@code isDFOrder=1} 时必填。

+ */ + public String expectedShipDate; + + /** 目的国家,2 位字符;必填。 */ + public String shipToCountry; + + /** 目的州(美国:2 位编码);必填。 */ + public String shipToState; + + /** 目的城市;中文页标必填,英文页未标。 */ + public String shipToCity; + + /** 发运邮编;必填。 */ + public String shipToPostal; + + /** 发运地址 1;必填。 */ + public String shipToAddress1; + + /** 发运地址 2。 */ + public String shipToAddress2; + + /** 发运联系人;必填。 */ + public String shipToContact; + + /** 客户邮箱。 */ + public String customerEmail; + + /** 发运联系电话;必填。 */ + public String shipToTelephone; + + /** third party 账号。 */ + public String thirdPartyAccount; + + /** 发货时效:{@code Standard-48Hours}(标准)/ {@code SameDay ShipOut}(加急);不填为标准。 */ + public String shipServiceLevel; + + /** 创建时间,UTC,{@code yyyy-MM-dd HH:mm:ss};必填。 */ + public String createdAt; + + /** 买家备注。 */ + public String customerRemark; + + /** 仓库备注;传了仓方会参考此信息发货。 */ + public String warehouseRemark; + + /** 产品行;必填。 */ + public List productItems; + + /** + * 附件信息;两页文档都标必填。 + * + *

没有附件时发空数组而不是省略该字段——省略会被仓方当成缺必填项。

+ */ + public List attachInfoItems; + + /** 产品行。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ProductItem { + + /** 发货产品 SKU;必填。 */ + public String sku; + + /** 发货数量;必填。 */ + public Integer quantity; + + /** 是否保价:0 否 / 1 是;必填。 */ + public Integer isInsure; + + /** + * 签收类型:0 否 / 1 直接签收 / 2 成人签收 / 3 间接签收(仅 FedEx);必填。 + * + *

统一模型只有布尔型的 {@code signatureRequired},表达不了 2 / 3。

+ */ + public Integer isSignature; + + /** 当前 SKU 总金额(不是单价)。 */ + public Double skuAmount; + + /** 投保金额;{@code isInsure=1} 时必填。 */ + public Double insureAmount; + } + + /** 附件。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class AttachInfoItem { + + /** 附件名称;必填。文档建议填跟踪号且不带后缀。 */ + public String name; + + /** 附件 URL;与 {@link #file} 至少给一个。 */ + public String url; + + /** base64 内容;给了就忽略 {@link #url}。 */ + public String file; + + /** + * 附件类型;必填。文档类型写 STRING: + * 0 Shippinglabel / 1 Packinglist / 2 BOL / 3 Other / + * 4 CartonLabel / 5 PalletLabel / 6 itemlabel。 + */ + public String type; + + /** 备注。 */ + public String remark; + } + } + + /** 创建响应:{@code {statusCode, status, code, message, data:{orderId}}}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class CreateOrderResponse { + + @JsonProperty("statusCode") + public Integer statusCode; + + @JsonProperty("code") + public Integer code; + + @JsonProperty("message") + public String message; + + @JsonProperty("data") + public CreateOrderData data; + } + + /** 响应 {@code data}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class CreateOrderData { + + /** 仓方订单 id;列表查询的条件,取消时也要带上。 */ + @JsonProperty("orderId") + public Long orderId; + } +} 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 581d1ec..a0921e6 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 @@ -62,15 +62,27 @@ class HengjianAdapterTest { common.ecommerce.warehouse.enums.WarehouseCapability.LOGISTICS_PRODUCT)); } - /** 出库未接入:门面显式拒绝,不返回空列表。 */ + /** + * 下单已接、查询未接:门面能力检查放行 {@code OUTBOUND}, + * 适配器对未实现的 {@code get} 显式抛异常,不返回 null。 + */ @Test - void unimplementedOutboundIsRejected() { + void unimplementedOutboundQueryIsRejected() { WarehouseSdk sdk = sdk(); - assertThrows(WarehouseUnsupportedCapabilityException.class, + assertThrows(common.ecommerce.warehouse.error.WarehouseException.class, () -> sdk.warehouses(WH, conn()).outbound().get(OutboundRef.ofRequestNo("OB-1"))); } + /** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */ + @Test + void undeclaredCapabilityIsRejected() { + WarehouseSdk sdk = sdk(); + + assertThrows(WarehouseUnsupportedCapabilityException.class, + () -> sdk.warehouses(WH, conn()).inventory().query(null)); + } + /** 能力矩阵查询本身可用(不触发真实 API)。 */ @Test void capabilityQueryIsOffline() { 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 new file mode 100644 index 0000000..c5becfc --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java @@ -0,0 +1,440 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.model.Platform; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.support.Money; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.LabelMode; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; +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; +import common.ecommerce.warehouse.sdk.WarehouseSdk; +import common.ecommerce.warehouse.spi.WarehouseAccount; +import common.ecommerce.warehouse.testkit.InMemoryWarehouses; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneId; +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.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 创建销售发货单({@code POST /v1/saleOrder/create})契约测试。 + */ +class HengjianCreateOrderTest { + + private static final Instant NOW = Instant.parse("2026-11-12T03:04:05Z"); + private static final Clock CLOCK = Clock.fixed(NOW, ZoneOffset.UTC); + + private static final String CREATE_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"创建订单成功\"," + + "\"data\":{\"orderId\":193252852}}"; + + private static WarehouseContext ctx() { + return ctx(ZoneOffset.UTC); + } + + private static WarehouseContext ctx(ZoneId zone) { + return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA", + WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("token-1").build(), zone), + "req-1", CLOCK); + } + + private static HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + private static RecordingTransport creating() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok(CREATE_BODY)); + } + + private static ShipTo shipTo() { + return ShipTo.builder() + .name("Test Receiver") + .phone("555-0100") + .email("buyer@example.com") + .countryCode("US") + .stateOrProvince("CA") + .city("Los Angeles") + .addressLine1("1 Test St") + .addressLine2("Suite 2") + .postalCode("90001") + .build(); + } + + private static OutboundCommand.Builder order() { + return OutboundCommand.builder() + .outboundRequestNo("OB-2026-0001") + .orderRef("SO-1") + .salesPlatform(Platform.AMAZON_SC) + .carrier("UPS") + .carrierCode("UPSG_HL") + .shopName("EFCA-STORE") + .shipTo(shipTo()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku("DM00001") + .quantity(2) + .declareValue(Money.of("9.99", "USD")) + .build()); + } + + // ---------------------------------------------------------------- 请求形状 + + @Test + void sendsPostToSaleOrderCreate() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/saleOrder/create", + transport.lastDataRequest().url()); + } + + /** 文档必填的字段必须全部出现。 */ + @Test + void sendsAllMandatoryFields() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + String[] mandatory = {"orderNo", "shipToCountry", "shipToState", "shipToCity", + "shipToPostal", "shipToAddress1", "shipToContact", "shipToTelephone", + "createdAt", "productItems", "attachInfoItems"}; + for (String field : mandatory) { + assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body); + } + } + + /** 产品行里的四个必填子字段都要有。 */ + @Test + void productItemCarriesMandatoryFlags() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + String[] mandatory = {"sku", "quantity", "isInsure", "isSignature"}; + for (String field : mandatory) { + assertTrue(body.contains("\"" + field + "\""), "产品行缺少 " + field + ",body=" + body); + } + assertTrue(body.contains("\"sku\":\"DM00001\""), body); + assertTrue(body.contains("\"quantity\":2"), body); + } + + /** + * 恒健把 {@code attachInfoItems} 标为必填:没有附件时发空数组, + * 不能省略字段。 + */ + @Test + void sendsEmptyAttachmentArrayWhenNoLabel() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"attachInfoItems\":[]"), + "没有附件时应发空数组而不是省略,body=" + body); + } + + /** 平台面单:base64 内容进 file,类型 0,名称优先用跟踪号。 */ + @Test + void sendsPlatformLabelAsAttachment() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order() + .labelMode(LabelMode.PLATFORM_LABEL) + .trackingNumber("1ZXH1234567890") + .labelContentBase64("data:application/pdf;base64,JVBERi0xLjQK") + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"name\":\"1ZXH1234567890\""), body); + // data URI 头必须剥掉,否则仓方会把前缀当文件内容 + assertTrue(body.contains("\"file\":\"JVBERi0xLjQK\""), body); + assertFalse(body.contains("data:application/pdf"), body); + assertTrue(body.contains("\"type\":\"0\""), body); + } + + /** 声明平台面单却不给文件,本地就拒绝——仓没有面单可打等于静默失败。 */ + @Test + void rejectsPlatformLabelWithoutContent() { + RecordingTransport transport = creating(); + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(ctx(), + order().labelMode(LabelMode.PLATFORM_LABEL).build())); + assertTrue(ex.getMessage().contains("labelContentBase64"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty(), "本地校验失败不应发出请求"); + } + + /** 给了面单内容却不是平台面单模式,拒绝而不是静默丢弃。 */ + @Test + void rejectsLabelContentWithoutPlatformMode() { + RecordingTransport transport = creating(); + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(ctx(), + order().labelContentBase64("JVBERi0xLjQK").build())); + assertTrue(ex.getMessage().contains("PLATFORM_LABEL"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 时间按 UTC 输出,不受调用方传的时区影响。 */ + @Test + void formatsTimesInUtc() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(ZoneId.of("America/Los_Angeles")), + order().latestShipDate(Instant.parse("2026-11-15T23:30:00Z")).build()); + String body = transport.lastDataRequest().body(); + + // createdAt 用注入的固定时钟 + assertTrue(body.contains("\"createdAt\":\"2026-11-12 03:04:05\""), body); + assertTrue(body.contains("\"expectedShipDate\":\"2026-11-15 23:30:00\""), + "恒健要求 UTC,不能按仓所在时区输出,body=" + body); + } + + /** 行金额是「当前 SKU 总金额」,申报单价要乘数量。 */ + @Test + void skuAmountIsLineTotalNotUnitPrice() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + // 9.99 × 2 = 19.98 + assertTrue(body.contains("\"skuAmount\":19.98"), "skuAmount 必须是行总额,body=" + body); + } + + @Test + void usesExplicitTotalAmountWhenGiven() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), OutboundCommand.builder() + .outboundRequestNo("OB-2") + .salesPlatform(Platform.AMAZON_SC) + .shipTo(shipTo()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku("DM00001") + .quantity(3) + .declareValue(Money.of("10.00", "USD")) + .totalAmount(Money.of("28.00", "USD")) + .build()) + .build()); + + assertTrue(transport.lastDataRequest().body().contains("\"skuAmount\":28.0")); + } + + /** 保价由「是否有保价金额」推导;有金额就要带 insureAmount。 */ + @Test + void insuredLineSendsFlagAndAmount() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), OutboundCommand.builder() + .outboundRequestNo("OB-3") + .salesPlatform(Platform.AMAZON_SC) + .shipTo(shipTo()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku("DM00001") + .quantity(1) + .insuredAmount(Money.of("100.00", "USD")) + .build()) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"isInsure\":1"), body); + assertTrue(body.contains("\"insureAmount\":100.0"), body); + } + + @Test + void uninsuredLineSendsZero() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + + assertTrue(transport.lastDataRequest().body().contains("\"isInsure\":0")); + } + + /** 签收:布尔值映射成 1 / 0;null 视为不签收(恒健必填,不能省略)。 */ + @Test + void signatureFlagIsMandatoryAndMapped() { + RecordingTransport required = creating(); + adapter(required).create(ctx(), order().signatureRequired(true).build()); + assertTrue(required.lastDataRequest().body().contains("\"isSignature\":1")); + + RecordingTransport notRequired = creating(); + adapter(notRequired).create(ctx(), order().build()); + assertTrue(notRequired.lastDataRequest().body().contains("\"isSignature\":0")); + } + + @Test + void mapsShopCurrencyAndCarrier() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order() + .currency("CAD") + .sfp(true) + .remark("买家备注") + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"channelAccount\":\"EFCA-STORE\""), body); + assertTrue(body.contains("\"currency\":\"CAD\""), body); + assertTrue(body.contains("\"carrier\":\"UPS\""), body); + assertTrue(body.contains("\"carrierCode\":\"UPSG_HL\""), body); + assertTrue(body.contains("\"isPrime\":1"), body); + assertTrue(body.contains("\"customerRemark\":\"买家备注\""), body); + } + + /** 恒健没有平台维度:salesPlatform 不发,也不拿它推 isDFOrder。 */ + @Test + void doesNotSendSalesPlatformOrInferDfOrder() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + assertFalse(body.contains("salesPlatform"), body); + assertFalse(body.contains("isDFOrder"), body); + } + + /** 仓代码:命令显式指定优先,否则用账户配置。 */ + @Test + void warehouseCodeResolvesFromCommandThenAccount() { + RecordingTransport fromCommand = creating(); + adapter(fromCommand).create(ctx(), order().warehouseId("EFNJ").build()); + assertTrue(fromCommand.lastDataRequest().body().contains("\"warehouseCode\":\"EFNJ\"")); + + RecordingTransport fromAccount = creating(); + adapter(fromAccount).create(ctx(), order().build()); + assertTrue(fromAccount.lastDataRequest().body().contains("\"warehouseCode\":\"EFCA\"")); + } + + // ---------------------------------------------------------------- 本地必填校验 + + @Test + void rejectsMissingShipToFields() { + String[] fields = {"countryCode", "stateOrProvince", "postalCode", "addressLine1", + "name", "phone", "city"}; + for (String field : fields) { + ShipTo.Builder b = ShipTo.builder() + .name("N").phone("P").countryCode("US").stateOrProvince("CA") + .city("C").addressLine1("A").postalCode("Z"); + if ("countryCode".equals(field)) { + b.countryCode(null); + } else if ("stateOrProvince".equals(field)) { + b.stateOrProvince(null); + } else if ("postalCode".equals(field)) { + b.postalCode(null); + } else if ("addressLine1".equals(field)) { + b.addressLine1(null); + } else if ("name".equals(field)) { + b.name(null); + } else if ("phone".equals(field)) { + b.phone(null); + } else { + b.city(null); + } + OutboundCommand cmd = OutboundCommand.builder() + .outboundRequestNo("OB-X") + .salesPlatform(Platform.AMAZON_SC) + .shipTo(b.build()) + .line(OutboundLine.builder().lineNo("1").omsSku("S").quantity(1).build()) + .build(); + assertThrows(IllegalArgumentException.class, + () -> adapter(creating()).create(ctx(), cmd), field); + } + } + + // ---------------------------------------------------------------- 响应 + + @Test + void readsProviderOrderIdFromData() { + RecordingTransport transport = creating(); + OutboundReceipt receipt = adapter(transport).create(ctx(), order().build()); + + assertEquals("OB-2026-0001", receipt.outboundRequestNo()); + assertEquals("193252852", receipt.providerOrderId(), "仓内部数字 id 必须落库,取消时要用"); + assertEquals("创建订单成功", receipt.rawStatus()); + } + + /** 没有 orderId 不能当成功:后续取消需要它。 */ + @Test + void rejectsResponseWithoutOrderId() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\"}")); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).create(ctx(), order().build())); + assertTrue(ex.getMessage().contains("data.orderId"), ex.getMessage()); + } + + @Test + void businessErrorIsPropagated() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok( + "{\"code\":500,\"message\":\"仓库不存在\"}")); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).create(ctx(), order().build())); + assertTrue(ex.getMessage().contains("仓库不存在"), ex.getMessage()); + } + + // ---------------------------------------------------------------- 能力位与未接入接口 + + @Test + void declaresOutboundAndLabelCapabilities() { + HengjianAdapter adapter = adapter(RecordingTransport.create()); + + assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + assertTrue(adapter.capabilities().contains(WarehouseCapability.PLATFORM_LABEL_DELIVERY)); + } + + /** 查询 / 取消还没接:显式拒绝,不返回 null 或空集合。 */ + @Test + void unimplementedOutboundMethodsThrow() { + HengjianAdapter adapter = adapter(RecordingTransport.create()); + + assertThrows(RuntimeException.class, + () -> adapter.get(ctx(), OutboundRef.ofRequestNo("OB-1"))); + assertThrows(RuntimeException.class, + () -> adapter.packages(ctx(), OutboundRef.ofRequestNo("OB-1"))); + assertThrows(RuntimeException.class, + () -> adapter.checkCancel(ctx(), OutboundRef.ofRequestNo("OB-1"))); + assertThrows(RuntimeException.class, + () -> adapter.cancel(ctx(), common.ecommerce.warehouse.model.CancelCommand.builder() + .outboundRequestNo("OB-1").build())); + } + + /** 未声明的能力位仍然被门面挡住(INVENTORY_QUERY 还没接)。 */ + @Test + void undeclaredCapabilityIsRejectedByFacade() { + WarehouseSdk sdk = WarehouseSdk.builder() + .warehouseRepository(new InMemoryWarehouses().put(WarehouseAccount.builder() + .warehouseCode("HJ-EFCA") + .provider(WarehouseProvider.HENGJIAN.name()) + .providerWarehouseId("EFCA") + .credentialRef("kms://test") + .timeZone("America/Los_Angeles") + .build())) + .clock(CLOCK) + .register(new HengjianAdapterFactory()) + .build(); + + assertThrows(WarehouseUnsupportedCapabilityException.class, + () -> sdk.warehouses("HJ-EFCA", WarehouseConnection.of( + HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("t").build(), + ZoneOffset.UTC)) + .inventory().query(null)); + } +} 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 8854855..dde4c2d 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 @@ -227,14 +227,14 @@ class HengjianDirectoryTest { // ---------------------------------------------------------------- 能力位 @Test - void declaresDirectoryAndProductCapabilitiesOnly() { + void declaresExpectedCapabilities() { HengjianAdapter adapter = adapter(RecordingTransport.create()); assertTrue(adapter.capabilities().contains(WarehouseCapability.DIRECTORY)); assertTrue(adapter.capabilities().contains(WarehouseCapability.LOGISTICS_PRODUCT)); assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT)); - // 出库 / 库存 / 入库 / 退货都还没接:声明了就必须有实现 - assertTrue(!adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + // 库存 / 入库 / 退货 / 回调都还没接:声明了就必须有实现 assertTrue(!adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY)); assertTrue(!adapter.capabilities().contains(WarehouseCapability.INBOUND)); assertTrue(!adapter.capabilities().contains(WarehouseCapability.RETURN)); 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 a272dfb..7feaae8 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 @@ -4,11 +4,16 @@ import common.ecommerce.hengjian.HengjianConstants; import common.ecommerce.hengjian.adapter.HengjianAdapter; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.shared.model.Platform; 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.WarehouseProvider; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.OutboundReceipt; +import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseContext; import org.junit.jupiter.api.Assumptions; @@ -123,4 +128,64 @@ class HengjianWriteProbeTest { + " ← 若非幂等保存,这里会报 SKU 已存在"); } } + + // ================================================================ 出库 + + /** + * 建销售发货单:验证必填组合、时间格式与 {@code data.orderId} 是否真回。 + * + *

需要 {@code -Dhengjian.probe.postcode};SKU 用 {@link #SKU}, + * 所以要先把商品建出来({@link #probeProductSave})。

+ * + *

会在仓方测试环境留一张真实订单。探针不自动取消——取消接口尚未接入。

+ */ + @Test + void probeCreateSaleOrder() { + assumeToken(); + String postcode = opt("hengjian.probe.postcode", ""); + Assumptions.assumeTrue(!postcode.isEmpty(), + "未提供 -Dhengjian.probe.postcode,跳过建单探针"); + System.out.println("\n================ hengjian / v1/saleOrder/create ================"); + System.out.println(" orderNo=" + orderNo() + " warehouse=" + PROVIDER_WAREHOUSE + + " sku=" + SKU + " postcode=" + postcode); + try { + OutboundReceipt receipt = adapter().create(ctx(), command(postcode)); + System.out.println(" [OK] outboundRequestNo=" + receipt.outboundRequestNo() + + " providerOrderId=" + receipt.providerOrderId() + + " rawStatus=" + receipt.rawStatus()); + System.out.println(" ← providerOrderId 是仓内部数字 id,取消接口要同时用它和单号"); + } catch (RuntimeException e) { + System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage()); + } + } + + private static String orderNo() { + return "PROBE-OB-" + System.currentTimeMillis(); + } + + private static OutboundCommand command(String postcode) { + return OutboundCommand.builder() + .outboundRequestNo(orderNo()) + .salesPlatform(Platform.AMAZON_SC) + .carrier("UPS") + .carrierCode(opt("hengjian.probe.carrierCode", "UPSG_HL")) + .shopName(opt("hengjian.probe.shopName", "")) + .currency("USD") + .shipTo(ShipTo.builder() + .name("Probe Receiver") + .phone("5550000000") + .countryCode("US") + .stateOrProvince(opt("hengjian.probe.state", "CA")) + .city(opt("hengjian.probe.city", "Los Angeles")) + .addressLine1("1 Probe St") + .postalCode(postcode) + .build()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku(SKU) + .quantity(1) + .declareValue(Money.of("1.00", "USD")) + .build()) + .build(); + } }