Browse Source

feat(hengjian): 对接创建销售发货单 /v1/saleOrder/create

- 新增 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 <noreply@anthropic.com>
master
lml 1 week ago
parent
commit
586d9c5eb8
  1. 10
      README.md
  2. 105
      docs-warehouse/hengjian/README.md
  3. 8
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  4. 117
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  5. 243
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java
  6. 200
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java
  7. 18
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java
  8. 440
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java
  9. 6
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java
  10. 65
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java

10
README.md

@ -141,7 +141,7 @@ sequenceDiagram @@ -141,7 +141,7 @@ sequenceDiagram
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单) |
依赖方向:
```
@ -376,11 +376,11 @@ common.ecommerce @@ -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 # 单模块 @@ -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 # 恒健目录 / 渠道 / 商品保存 / 出库下单
```
---

105
docs-warehouse/hengjian/README.md

@ -49,6 +49,9 @@ @@ -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 @@ @@ -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 @@ @@ -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/ @@ -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/ @@ -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 \ @@ -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 \ @@ -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")`。

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

@ -59,6 +59,14 @@ public final class HengjianConstants { @@ -59,6 +59,14 @@ public final class HengjianConstants {
*/
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/**
* 创建销售发货单。
*
* <p>响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与
* {@code orderNo} 都要,所以调用方必须落库这个 id。</p>
*/
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/** 业务成功码;文档各接口一致写 {@code 200}。 */
public static final int SUCCESS_CODE = 200;

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

@ -3,6 +3,7 @@ package common.ecommerce.hengjian.adapter; @@ -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; @@ -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; @@ -43,12 +56,13 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。</p>
*/
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 @@ -78,10 +92,111 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(
WarehouseCapability.PRODUCT,
WarehouseCapability.OUTBOUND,
WarehouseCapability.PLATFORM_LABEL_DELIVERY,
WarehouseCapability.DIRECTORY,
WarehouseCapability.LOGISTICS_PRODUCT);
}
// ------------------------------------------------------------------ 出库
/**
* 创建销售发货单({@code POST /v1/saleOrder/create})。
*
* <p>承接 {@code WarehouseOutbounds.create} 的幂等守卫:同一
* {@code outboundRequestNo} 重复下发由门面拦住,这里只负责拼报文与解析。</p>
*
* <p>响应只回 {@code data.orderId}(<b>仓内部数字 id</b>,不是字符串单号)。
* 恒健的取消接口同时要 {@code orderId} 与 {@code orderNo},所以这个 id
* 必须随 {@link OutboundReceipt#providerOrderId()} 落库;缺了它后续取消做不了,
* 因此拿不到就报错,<b>不静默当成创建成功</b>。</p>
*/
@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<OutboundOrder> 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<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) {
throw unsupportedOutbound("warehouse.outbound.packages", ctx);
}
/**
* 平台面单必须真的带文件。
*
* <p>恒健的面单就是 {@code attachInfoItems} 里的一条附件;声明了
* {@code PLATFORM_LABEL_DELIVERY} 却不给文件,仓没有面单可打,等于静默失败。</p>
*/
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) + "...";
}
// ------------------------------------------------------------------ 商品
/**

243
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java

@ -0,0 +1,243 @@ @@ -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})。
*
* <p>平台字段名只出现在本类与 {@link HengjianCreateOrderDtos}。</p>
*
* <h2>时间</h2>
* <p>恒健的时间字段是 <b>UTC</b> 的 {@code yyyy-MM-dd HH:mm:ss}(文档明确写了 utc 时间),
* 所以格式化固定按 {@link ZoneOffset#UTC},<b>不用</b> {@code WarehouseContext.zone()}——
* 那个时区是给「仓方回传的无时区本地时间」用的,方向相反。</p>
*
* <h2>必填项</h2>
* <p>{@code createdAt} 在统一模型里没有对应字段,用调用方注入的 {@link Clock} 生成
* 「下单时刻」。这是请求侧的时间戳,不是把仓方没给的数据编出来;
* 幂等重放时它会变,但恒健不拿它做去重。</p>
*
* <h2>统一模型里恒健没有对应概念的字段</h2>
* <table border="1">
* <tr><th>字段</th><th>处理</th></tr>
* <tr><td>{@code salesPlatform}</td>
* <td>恒健没有平台维度,店铺路由走 {@code channelAccount}。<b>不发</b>,
* 也不拿它去推断 {@code isDFOrder}——VC 订单里只有一部分是 DF。</td></tr>
* <tr><td>{@code splitOrder} / {@code packages}</td>
* <td>恒健没有拆单入参与包裹入参,忽略。</td></tr>
* <tr><td>{@code estimatedDeliveryTime}</td>
* <td>恒健只有 {@code expectedShipDate}(要求发货时间),没有送达时间。</td></tr>
* <tr><td>{@code declaredTotal}</td>
* <td>恒健按行收金额,没有整单申报额。</td></tr>
* </table>
*/
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<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem> toProductItems(
List<OutboundLine> lines, Boolean signatureRequired, String orderNo) {
boolean signature = Boolean.TRUE.equals(signatureRequired);
List<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem> items =
new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem>(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;
}
/**
* 行总金额。
*
* <p>恒健 {@code skuAmount} 是「当前 SKU 总金额」,<b>不是单价</b>:
* 有 {@code totalAmount} 直接用;没有就用申报单价 × 数量,
* 否则整单金额会少算 quantity 倍(运去哪踩过同样的坑)。</p>
*/
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();
}
/**
* 附件:平台面单随单下发。
*
* <p>恒健把 {@code attachInfoItems} 标为<b>必填</b>,所以没有附件时返回空数组,
* 不省略该字段——省略会被当成缺必填项。</p>
*
* <p>仓自有面单({@link LabelMode#WAREHOUSE_LABEL})时不给附件;
* 给了面单内容却不是平台面单模式,直接拒绝,不静默丢弃。</p>
*/
private static List<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> 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<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>();
}
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<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> out =
new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>(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;
}
}

200
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java

@ -0,0 +1,200 @@ @@ -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})。
*
* <p>中英文两页文档描述的是同一个接口,中文页叫「创建销售发货单(带附件的)」,
* 英文页叫「Create Sale Order With Label」;两页字段表基本一致,差异见各字段注释。</p>
*
* <p><b>两页的必填口径不完全一致</b>:中文页把 {@code createdAt} 标为必填、英文页也标 Y;
* 但中文页没有 {@code isPrime}(只有英文页有),英文页没有 {@code customerRemark} /
* {@code warehouseRemark}(只有中文页有)。按两页并集实现,必填取两页都要求的字段。</p>
*/
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};不填由仓方取当前时间。
*
* <p>统一模型没有「支付时间」字段,这里通常不传。</p>
*/
public String paidAt;
/** Amazon VC Direct Fulfillment 订单:0 否 / 1 是;不填默认为否。 */
public Integer isDFOrder;
/**
* 是否 SFP 订单:0 否 / 1 是;不填默认为否。
*
* <p><b>文档类型写的是 String,但请求示例给的是数字 {@code "isPrime": 0}</b>。
* 这里按示例用 Integer——两页示例一致,且 Spring 后端按数字绑定的可能性更高。
* 真机若报类型错,改成 String 即可。</p>
*/
public Integer isPrime;
/**
* 平台要求发货时间,UTC,{@code yyyy-MM-dd HH:mm:ss}。
*
* <p>文档:{@code isDFOrder=1} 时必填。</p>
*/
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<ProductItem> productItems;
/**
* 附件信息;<b>两页文档都标必填</b>。
*
* <p>没有附件时发空数组而不是省略该字段——省略会被仓方当成缺必填项。</p>
*/
public List<AttachInfoItem> 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);必填。
*
* <p>统一模型只有布尔型的 {@code signatureRequired},表达不了 2 / 3。</p>
*/
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;
}
}

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

@ -62,15 +62,27 @@ class HengjianAdapterTest { @@ -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() {

440
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java

@ -0,0 +1,440 @@ @@ -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));
}
}

6
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java

@ -227,14 +227,14 @@ class HengjianDirectoryTest { @@ -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));

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

@ -4,11 +4,16 @@ import common.ecommerce.hengjian.HengjianConstants; @@ -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 { @@ -123,4 +128,64 @@ class HengjianWriteProbeTest {
+ " ← 若非幂等保存,这里会报 SKU 已存在");
}
}
// ================================================================ 出库
/**
* 建销售发货单:验证必填组合、时间格式与 {@code data.orderId} 是否真回。
*
* <p>需要 {@code -Dhengjian.probe.postcode};SKU 用 {@link #SKU},
* 所以要先把商品建出来({@link #probeProductSave})。</p>
*
* <p><b>会在仓方测试环境留一张真实订单</b>。探针不自动取消——取消接口尚未接入。</p>
*/
@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();
}
}

Loading…
Cancel
Save