Browse Source

feat(hengjian): 对接订单详情 /v1/saleOrder/findOne 与订单列表 /v1/saleOrder/findByPage

- 新增 HengjianOrderDetailDtos / HengjianOrderListDtos / HengjianOrderMapper,
  实现 OutboundCapable.get / query / checkCancel / packages
- 新增 HengjianOrderStatus:8 个 orderStatusEnum 值精确匹配,未识别归 UNKNOWN;
  core OutboundStatus 追加 REFUNDED(180)——退款与取消语义不同,合并会分不清是否已发货
- 详情不回 orderId:providerOrderId 保持 null,不编造;列表是唯一回 orderId 的接口
- skuAmount 是行总额落 totalAmount;恒健不回申报单价,declareValue 留空
- 列表:时间/单号二者必填其一(否则本地拒绝)、跨度上限 30 天、rows 截断 100、
  状态过滤显式拒绝;游标是页码,末页以仓方 last 为准
- 时间按 UTC 解析(文档声明 utc),不用仓时区
- 包裹从详情 shipmentPackages 提取,按 trackingNo 去重且实际包裹优先
- 取消预判按状态推断,查不到单判 BLOCKED 而不是猜 FREE;cancel 仍未接入
- 只读探针补订单详情 / 订单列表用例

验证:mvn test 全量通过,恒健 99 个用例 + 2 个探针跳过。

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 1 week ago
parent
commit
a6226a37cc
  1. 14
      README.md
  2. 113
      docs-warehouse/hengjian/README.md
  3. 7
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java
  4. 36
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  5. 242
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  6. 411
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOrderMapper.java
  7. 228
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderDetailDtos.java
  8. 219
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderListDtos.java
  9. 86
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianOrderStatus.java
  10. 12
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java
  11. 10
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java
  12. 440
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java
  13. 76
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java

14
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,12 +376,14 @@ common.ecommerce @@ -376,12 +376,14 @@ common.ecommerce
│
└── hengjian 恒健三方仓(warehouse-sdk-hengjian)
├── HengjianConstants 测试基址、当前接入路径、双授权头名、成功码 / 未授权码、限流
├── adapter HengjianAdapter(目录 + 渠道 + 商品保存 + 出库下单)/
├── adapter HengjianAdapter(目录 + 渠道 + 商品保存 + 出库下单 / 详情 / 列表 / 包裹)/
│ HengjianAdapterFactory / HengjianDirectoryMapper /
│ HengjianProductMapper / HengjianOutboundMapper
│ HengjianProductMapper / HengjianOutboundMapper / HengjianOrderMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos
├── enums (package-info:调拨 / 出库状态枚举约定,待建)
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter
└── webhook (package-info:文档无回调页,未实现)
```
@ -1076,7 +1078,7 @@ mvn -pl lingxing test # 单模块 @@ -1076,7 +1078,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 # 恒健目录 / 渠道 / 商品 / 下单 / 订单查询
```
---

113
docs-warehouse/hengjian/README.md

@ -65,7 +65,9 @@ @@ -65,7 +65,9 @@
| 3 | 获取仓库支持的物流渠道 | `POST /v2/carrierGroup/getWarehouseCarrierGroupServices` | 同上(适配器方法,非 capability) | ✅ |
| 4 | 创建 / 编辑产品 | `POST /v1/product/save` | `PRODUCT` | ✅ |
| 5 | 创建销售发货单 | `POST /v1/saleOrder/create` | `OUTBOUND` / `PLATFORM_LABEL_DELIVERY` | ✅ |
| 6 | 回调 | — | — | ❌ 文档无回调页 |
| 6 | 订单详情 | `POST /v1/saleOrder/findOne` | `OUTBOUND` | ✅ |
| 7 | 订单列表 | `GET /v1/saleOrder/findByPage` | `OUTBOUND` | ✅ |
| 8 | 回调 | — | — | ❌ 文档无回调页 |
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作,
@ -176,20 +178,78 @@ @@ -176,20 +178,78 @@
| 接口 | 路径 | 状态 |
|---|---|---|
| 创建销售发货单(中文页「带附件」/ 英文页 "With Label",同路径) | `POST /v1/saleOrder/create` → `data.orderId` | ✅ 已接入 |
| 订单详情 | `POST /v1/saleOrder/findOne` | ⬜ |
| 订单列表 | `GET /v1/saleOrder/findByPage` | ⬜ |
| 订单详情 | `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` | ⬜ |
接查询 / 取消时要注意:
#### 订单详情(`/v1/saleOrder/findOne`)
- 请求只有 `orderNo`(来源单号)。
- **响应不回 `orderId`**:详情查回来的单拿不到仓内部 id。要取消的话,
得走列表接口按 `orderNos` 查一次补 `orderId`。
- 统一模型映射:`outboundRequestNo = orderNo`、`providerOrderId = null`、`orderRef = null`。
- `skuAmount` 是**行总额**,落 `OutboundLine.totalAmount`;恒健不回申报单价,
`declareValue` 保持 null,**不把总额当单价再乘一次**。
- 时间按 **UTC** 解析(`yyyy-MM-dd HH:mm:ss`),不用 `WarehouseContext.zone()`。
- `errorCode = "unexception"` 归一成 `exceptionCode = null`。
- 发货信息里 `packageFlag=1` 是面单信息行,取运单号 / 发货时间时只认 `0`(实际包裹)。
- `data` 为空 → 返回 `null`(「查不到」),不造空单。
#### 订单列表(`/v1/saleOrder/findByPage`)
- `GET`;分页四件套 `page / rows / sidx / sort` 都必填,适配器固定
`sidx=id&sort=desc`,`rows` 超过 100 截断到 100。
- **时间、订单号、订单 id 三者必填其一**:给 `outboundRequestNo` 就按 `orderNos` 查;
给时间窗就按 `beginDateTime / endDateTime`(UTC 日期)查;都没有 →
**本地拒绝**,不发必然被仓方拒的请求。
- 时间跨度上限 **30 天**,超过也本地拒绝。
- 不支持状态过滤:`OutboundQuery.statuses()` 非空时**拒绝**而不是静默忽略
(静默忽略会让调用方以为过滤生效了)。
- `OutboundQuery.orderRef` 恒健没有对应参数,不参与查询。
- **列表是唯一回 `orderId` 的接口**,映射进 `providerOrderId` 与 `providerId`。
- 翻页游标是字符串页码(恒健入参 1 基,响应 `number` 是 0 基);
是否末页以仓方 `last` 为准。
- 列表独有 `amount`(整单销售金额)落 `totalAmount`;`taxPrice` 统一模型无对应字段,不落。
#### 取消预判(`checkCancel`)
恒健没有独立的预判接口,按详情状态推断:`shipped` / `canceled` / `refunded` / `deleted`
判 `BLOCKED`,其余 `FREE`。**查不到单时也判 BLOCKED**——猜成 FREE 会发出注定被拒的取消。
#### 包裹(`packages`)
恒健没有独立包裹接口,从详情 `shipmentPackages` 提取。按 `trackingNo` 去重
(同一包裹可能同时以「实际包裹」和「面单信息」两行出现),实际包裹优先。
#### 状态枚举
`HengjianOrderStatus` 全量 8 个值:
| 恒健 | 含义 | core `OutboundStatus` |
|---|---|---|
| `pending` | 未支付 | `CREATED` |
| `unshipped` | 未发货 | `SUBMITTED` |
| `approved` | 已审核 | `ACCEPTED` |
| `assigned` | 已分配 | `ACCEPTED` |
| `picked` | 已配货 | `PICKING` |
| `shipped` | 已发货 | `SHIPPED` |
| `canceled` | 已取消 | `CANCELLED` |
| `refunded` | 已退款 | `REFUNDED`(core 新增,码 180) |
> `refunded` 为此新增了 core 枚举值:退款是履约后的资金退回,与取消语义不同,
> 合并就分不出「这单有没有发出去」。core 枚举**只追加**,不动已有码值。
**精确匹配**,不用 `contains`;`unshipped` 与 `shipped` 是前缀关系,
用子串判断会把未发货判成交运。
#### 待接:取消
`POST /v1/saleOrder/cancel` 要 `orderId` + `orderNo` 两个都传,目前 `cancel()`
显式抛不支持异常。接入时注意:`orderId` 只有**创建响应**与**列表接口**给,
详情接口不给。
- `orderStatusEnum` 取值:`pending / unshipped / approved / assigned / picked / shipped / canceled / refunded`
——与运去哪**同名但不同源**,必须各建一套平台枚举,精确匹配、未知归 UNKNOWN。
- 取消接口需要**创建时由仓方返回的 `orderId`**(`findByPage` 也回 `orderId`),
只给单号不行。
- `attachInfoItems.type`:`0` ShippingLabel / `1` PackingList / `2` BOL / `3` Other / `4` CartonLabel /
`5` PalletLabel / `6` itemlabel。`url` 与 `file`(base64) 二选一。
### 库存(`INVENTORY_QUERY`)
@ -245,17 +305,22 @@ warehouse-sdk-hengjian/ @@ -245,17 +305,22 @@ warehouse-sdk-hengjian/
├── main/java/common/ecommerce/hengjian/
│ ├── HengjianConstants.java 端点 / 路径 / 两个授权头 / 成功码 / 未授权码 / 限流
│ ├── adapter/
│ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品保存 + 出库下单
│ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品保存 + 出库下单 / 详情 / 列表 / 包裹
│ │ ├── HengjianAdapterFactory.java
│ │ ├── HengjianDirectoryMapper.java 仓库 / 渠道字段搬运
│ │ ├── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验
│ │ └── HengjianOutboundMapper.java 出库下单报文(UTC 时间 / 行总额 / 面单附件)
│ │ ├── HengjianOutboundMapper.java 出库下单报文(UTC 时间 / 行总额 / 面单附件)
│ │ └── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型
│ ├── dto/
│ │ ├── HengjianWarehouseDtos.java
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
│ │ ├── HengjianProductSaveDtos.java /v1/product/save
│ │ └── HengjianCreateOrderDtos.java /v1/saleOrder/create
│ ├── enums/package-info.java 状态枚举约定(待建)
│ │ ├── HengjianCreateOrderDtos.java /v1/saleOrder/create
│ │ ├── HengjianOrderDetailDtos.java /v1/saleOrder/findOne
│ │ └── HengjianOrderListDtos.java /v1/saleOrder/findByPage
│ ├── enums
│ │ ├── HengjianOrderStatus.java orderStatusEnum → OutboundStatus
│ │ └── package-info.java 其余状态枚举约定(待建)
│ ├── http/
│ │ ├── HengjianRequestFactory.java 双授权头 + 链路 ID
│ │ ├── HengjianEnvelope.java 三种形态信封校验
@ -265,13 +330,14 @@ warehouse-sdk-hengjian/ @@ -265,13 +330,14 @@ warehouse-sdk-hengjian/
├── adapter/HengjianDirectoryTest.java 13 个:请求形状 / 鉴权头 / 映射 / 能力位
├── adapter/HengjianProductSaveTest.java 20 个:必填拒绝 / 三组尺寸 / 不编造字段
├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝
├── adapter/HengjianOrderQueryTest.java 25 个:详情映射 / 列表分页 / 时间窗 / 包裹去重 / 枚举
├── 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` 全部通过(74 个 + 2 个跳过)。
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(99 个 + 2 个跳过)。
## 5. 探针用法
@ -286,7 +352,10 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ @@ -286,7 +352,10 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
```
- 默认跳过;token 不入库、只走系统属性。
- 4 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重。异常只打印不中断。
- 6 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重 / 订单详情 / 订单列表。
异常只打印不中断。
- 订单详情需 `-Dhengjian.probe.orderNo=`;订单列表需 `-Dhengjian.probe.begin=` 与 `-Dhengjian.probe.end=`
(`yyyy-MM-dd`,跨度 ≤30 天)。没给就跳过对应用例。
- 只读,不建单。
写探针(会留下真实数据):
@ -323,13 +392,17 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ @@ -323,13 +392,17 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
| 11 | 建单的 `channelAccount` 是否必填 | 两页文档都标「否」,但写的是「必须在 Efulfill 店铺管理中维护」;未给时仓方按什么路由需真机确认 |
| 12 | `isPrime` 的真实类型 | 文档类型列写 STRING,请求示例却是数字 `0`;适配器按示例发 Integer,真机报类型错就问仓方 |
| 13 | 签收类型能否区分成人 / 间接签收 | 统一模型只有布尔,目前全部映射成「直接签收(1)」;业务若需要 2 / 3,要在 `OutboundCommand` 上加行级签收类型 |
| 14 | 列表分页是 1 基入参还是 0 基 | 文档参数示例 `page: 1`,响应 `number: 0`;适配器按「入参 1 基、响应 0 基」处理,真机若错位只改 `pageNumberOf` |
| 15 | 详情 / 列表的 `paidAt` 是否真是 UTC | 两页都没写时区,只有创建接口注明 utc;适配器按 UTC 解析,若仓方回的是本地时间,时间会整体平移 |
| 16 | 列表 `enclosure[].type` 到底回字符串还是数字 | 列表页标 INTEGER、详情页标 STRING 且示例是 `"Shippinglabel"`;适配器按文本读,两种都能接住 |
## 7. 下一步
1. 拿到 token 后跑 `HengjianReadOnlyProbeTest` 与 `HengjianWriteProbeTest`,把结论补进本文档
「文档与实际不一致」表;重点验商品保存的必填组合、保存语义、建单的必填组合与 `orderId` 回传。
「文档与实际不一致」表;重点验商品保存的必填组合、保存语义、建单的必填组合与 `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")`。
4. 接取消(`/v1/saleOrder/cancel`)时注意:`orderId` 只有**创建响应**与**列表接口**给,
详情不给;只拿到单号时要先查一次列表补 id。

7
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java

@ -52,6 +52,13 @@ public enum OutboundStatus { @@ -52,6 +52,13 @@ public enum OutboundStatus {
OUT_OF_STOCK(160, "缺货", 15),
/** 已删除(信仓订单 {@code state=10})。 */
DELETED(170, "已删除", 16),
/**
* 已退款(恒健 {@code orderStatusEnum=refunded})。
*
* <p>与「已取消」不是一回事:取消是订单作废,退款是订单已履约后的资金退回,
* 不能合并——合并后就分不出「这单有没有发出去」。</p>
*/
REFUNDED(180, "已退款", 17),
/** 无法识别;原值见 {@code rawStatus},不参与 rank 比较。 */
UNKNOWN(0, "未知", -1);

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

@ -67,6 +67,42 @@ public final class HengjianConstants { @@ -67,6 +67,42 @@ public final class HengjianConstants {
*/
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/**
* 订单详情。
*
* <p>只按{@code orderNo}(来源单号)查,响应<b>不回 {@code orderId}</b>。</p>
*/
public static final String PATH_ORDER_FIND_ONE = "/v1/saleOrder/findOne";
/**
* 订单列表(分页)。
*
* <p>{@code GET},<b>时间、订单号、订单 id 三者必填其一</b>;时间跨度不超过 30 天。
* 是唯一会回 {@code orderId} 的查询接口。</p>
*/
public static final String PATH_ORDER_FIND_BY_PAGE = "/v1/saleOrder/findByPage";
/**
* 列表接口的排序字段。
*
* <p>文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc};
* 两个都是必填。</p>
*/
public static final String ORDER_LIST_SIDX = "id";
/** 列表接口的排序方向。 */
public static final String ORDER_LIST_SORT = "desc";
/**
* 列表接口的时间跨度上限(天)。
*
* <p>文档:{@code beginDateTime} 与 {@code endDateTime} 的跨度不要超过 30 天。
* 超过时适配器在本地拒绝,不把必然被拒的请求发出去。</p>
*/
public static final int ORDER_LIST_MAX_DAYS = 30;
/** 列表接口单页最大行数(文档:默认最高 100)。 */
public static final int ORDER_LIST_MAX_ROWS = 100;
/** 业务成功码;文档各接口一致写 {@code 200}。 */
public static final int SUCCESS_CODE = 200;

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

@ -4,6 +4,8 @@ import com.fasterxml.jackson.databind.JsonNode; @@ -4,6 +4,8 @@ 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.HengjianOrderDetailDtos;
import common.ecommerce.hengjian.dto.HengjianOrderListDtos;
import common.ecommerce.hengjian.dto.HengjianProductSaveDtos;
import common.ecommerce.hengjian.dto.HengjianWarehouseDtos;
import common.ecommerce.hengjian.http.HengjianEnvelope;
@ -36,6 +38,7 @@ import common.ecommerce.warehouse.model.PackageResult; @@ -36,6 +38,7 @@ import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import java.time.ZoneOffset;
import java.util.ArrayList;
import java.util.EnumSet;
import java.util.Iterator;
@ -63,6 +66,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -63,6 +66,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
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";
private static final String OP_ORDER_GET = "warehouse.outbound.get";
private static final String OP_ORDER_QUERY = "warehouse.outbound.query";
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
@ -137,20 +142,123 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -137,20 +142,123 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
resp.message);
}
/** 恒健出库查询尚未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */
/**
* 查订单详情({@code POST /v1/saleOrder/findOne})。
*
* <p>恒健只按<b>来源单号</b>查。统一引用里的 {@code outboundRequestNo} 就是来源单号;
* {@code providerOrderId} 是仓内部数字 id,<b>这个接口查不了</b>,所以拿来当兜底
* (调用方只给了 id 时照样发出去,仓方会查不到,由仓方报错而不是我们静默返回 null)。</p>
*
* <p>查不到({@code data} 为空)返回 null——与其它仓一致,调用方据此判断「没有这单」。</p>
*/
@Override
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
throw unsupportedOutbound("warehouse.outbound.get", ctx);
String orderNo = orderNoOf(ref);
HengjianOrderDetailDtos.FindOneRequest body = new HengjianOrderDetailDtos.FindOneRequest();
body.orderNo = orderNo;
String raw = execute(ctx, HengjianConstants.PATH_ORDER_FIND_ONE, body, OP_ORDER_GET);
JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
return null;
}
HengjianOrderDetailDtos.OrderDetail detail =
json.fromJson(data.toString(), HengjianOrderDetailDtos.OrderDetail.class);
return HengjianOrderMapper.toOrder(detail, ctx.providerWarehouseId());
}
/**
* 查订单列表({@code GET /v1/saleOrder/findByPage})。
*
* <p>恒健要求「<b>时间、订单号、订单 id</b> 三者必填其一」,所以:</p>
* <ul>
* <li>给了 {@code outboundRequestNo} → 按 {@code orderNos} 查;</li>
* <li>给了时间窗 → 按 {@code beginDateTime / endDateTime} 查(UTC 日期);</li>
* <li>都没有 → <b>本地拒绝</b>,不发一个必然被仓方拒的请求。</li>
* </ul>
*
* <p>时间跨度上限 30 天,超过也在本地拒绝。</p>
*
* <p>{@code orderRef}(平台单号)恒健没有对应查询参数,<b>不参与查询</b>;
* {@code statuses} 恒健列表也没有状态过滤参数,传了就拒绝——静默忽略会让调用方
* 以为过滤生效了。</p>
*/
@Override
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) {
throw unsupportedOutbound("warehouse.outbound.query", ctx);
if (!query.statuses().isEmpty()) {
throw validation(ctx, OP_ORDER_QUERY,
"hengjian order list has no status filter; refusing to silently ignore "
+ query.statuses());
}
Map<String, Object> params = new LinkedHashMap<String, Object>();
int pageSize = clampRows(query.pageSize());
params.put("rows", pageSize);
params.put("sidx", HengjianConstants.ORDER_LIST_SIDX);
params.put("sort", HengjianConstants.ORDER_LIST_SORT);
params.put("page", pageNumberOf(query.cursor()));
String orderNo = trimToNull(query.outboundRequestNo());
if (orderNo != null) {
params.put("orderNos", orderNo);
} else if (query.after() != null && query.before() != null) {
addDateRange(ctx, params, query);
} else {
throw validation(ctx, OP_ORDER_QUERY,
"hengjian order list requires outboundRequestNo or both after/before "
+ "(time, order number or order id - at least one)");
}
rateLimiter.acquire(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, HengjianConstants.PERMITS_PER_SECOND);
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(),
HengjianConstants.PATH_ORDER_FIND_BY_PAGE, params, ctx.secret(), ctx, OP_ORDER_QUERY);
String raw = HengjianEnvelope.of(transport.execute(req), json, OP_ORDER_QUERY,
ctx.warehouseCode(), ctx.requestId()).body();
HengjianOrderListDtos.ListResponse resp =
json.fromJson(raw, HengjianOrderListDtos.ListResponse.class);
if (resp == null || resp.data == null) {
throw validation(ctx, OP_ORDER_QUERY, "hengjian order list returned no data");
}
List<OutboundOrder> orders = new ArrayList<OutboundOrder>();
if (resp.data.content != null) {
for (HengjianOrderListDtos.OrderRow row : resp.data.content) {
if (row == null) {
continue;
}
orders.add(HengjianOrderMapper.toOrder(row, ctx.providerWarehouseId()));
}
}
// 是否最后一页以仓方的 last 为准;缺省时用「本页是否满页」推断,
// 不能只看 content 是否为空——空页在两种判断下含义不同
boolean last = resp.data.last != null
? resp.data.last
: (resp.data.numberOfElements != null && resp.data.numberOfElements < pageSize);
return last ? Page.last(orders) : Page.of(orders, String.valueOf(pageNumberOf(query.cursor()) + 1));
}
/**
* 取消资格预判:查详情按状态推断。
*
* <p>恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款不再接受取消,
* 判为 {@link CancelEligibility#BLOCKED};其余交给取消时仓方判定。</p>
*
* <p>查不到单时返回 BLOCKED,不猜 FREE——猜错会下发出一个注定被拒的取消。</p>
*/
@Override
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) {
throw unsupportedOutbound("warehouse.outbound.checkCancel", ctx);
OutboundOrder order = get(ctx, ref);
if (order == null) {
return CancelEligibility.BLOCKED;
}
switch (order.status()) {
case SHIPPED:
case CANCELLED:
case REFUNDED:
case DELETED:
return CancelEligibility.BLOCKED;
default:
return CancelEligibility.FREE;
}
}
@Override
@ -158,9 +266,133 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -158,9 +266,133 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
throw unsupportedOutbound("warehouse.outbound.cancel", ctx);
}
/**
* 包裹列表:从详情的 {@code shipmentPackages} 提取。
*
* <p>恒健没有独立的包裹接口,发货信息就在详情报文里。按 {@code trackingNo} 去重
* (同一包裹可能同时以「实际包裹」和「面单信息」两行出现),实际包裹
* ({@code packageFlag=0})优先。</p>
*/
@Override
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) {
throw unsupportedOutbound("warehouse.outbound.packages", ctx);
String orderNo = orderNoOf(ref);
HengjianOrderDetailDtos.FindOneRequest body = new HengjianOrderDetailDtos.FindOneRequest();
body.orderNo = orderNo;
String raw = execute(ctx, HengjianConstants.PATH_ORDER_FIND_ONE, body,
"warehouse.outbound.packages");
JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
return new ArrayList<PackageResult>();
}
HengjianOrderDetailDtos.OrderDetail detail =
json.fromJson(data.toString(), HengjianOrderDetailDtos.OrderDetail.class);
return toPackages(detail, orderNo);
}
/** 实际包裹优先、按 trackingNo 去重;没有 trackingNo 时用 SKU 作键。 */
private static List<PackageResult> toPackages(HengjianOrderDetailDtos.OrderDetail detail, String orderNo) {
List<PackageResult> out = new ArrayList<PackageResult>();
if (detail.shipmentPackages == null || detail.shipmentPackages.isEmpty()) {
return out;
}
java.util.Set<String> seen = new java.util.LinkedHashSet<String>();
// 两遍:先实际包裹,再面单信息行
for (int pass = 0; pass < 2; pass++) {
for (HengjianOrderDetailDtos.OrderDetail.ShipmentPackage p : detail.shipmentPackages) {
if (p == null) {
continue;
}
boolean actual = p.packageFlag == null || p.packageFlag == 0;
if (actual != (pass == 0)) {
continue;
}
String tracking = trimToNull(p.trackingNo);
String key = tracking != null ? tracking : "SKU-" + trimToNull(p.erpSku);
if (!seen.add(key)) {
continue;
}
PackageResult.Builder builder = PackageResult.builder()
.packageId(key)
.outboundRequestNo(orderNo)
.trackingNumber(tracking)
.carrier(trimToNull(p.carrier))
.erpSku(trimToNull(p.erpSku))
.shippedQuantity(p.shipedQuantity)
.shippedAt(HengjianOrderMapper.parseTime(p.shipmentDate));
if (p.cost != null && p.cost > 0) {
builder.cost(HengjianOrderMapper.moneyOf(p.cost, detail.currency));
}
out.add(builder.build());
}
}
return out;
}
/** 统一引用 → 来源单号;两者都空时拒绝。 */
private static String orderNoOf(OutboundRef ref) {
String orderNo = trimToNull(ref.outboundRequestNo());
return orderNo != null ? orderNo : trimToNull(ref.providerOrderId());
}
/**
* 时间窗转恒健的日期参数。
*
* <p>恒健收的是 UTC <b>日期</b>({@code yyyy-MM-dd}),不是时间戳;跨度不超过
* {@link HengjianConstants#ORDER_LIST_MAX_DAYS} 天。用「起止都含当天」的口径,
* 所以计算跨度时把 end 当天算进去。</p>
*/
private void addDateRange(WarehouseContext ctx, Map<String, Object> params, OutboundQuery query) {
java.time.LocalDate begin = query.after().atZone(ZoneOffset.UTC).toLocalDate();
java.time.LocalDate end = query.before().atZone(ZoneOffset.UTC).toLocalDate();
long days = java.time.temporal.ChronoUnit.DAYS.between(begin, end);
if (days > HengjianConstants.ORDER_LIST_MAX_DAYS) {
throw validation(ctx, OP_ORDER_QUERY,
"hengjian order list window must not exceed "
+ HengjianConstants.ORDER_LIST_MAX_DAYS + " days, got " + days);
}
params.put("beginDateTime", begin.toString());
params.put("endDateTime", end.toString());
}
/** 单页行数;恒健上限 100,超出截断而不是让仓方报错。 */
private static int clampRows(int pageSize) {
if (pageSize <= 0) {
return HengjianConstants.ORDER_LIST_MAX_ROWS;
}
return Math.min(pageSize, HengjianConstants.ORDER_LIST_MAX_ROWS);
}
/** 游标是字符串化的页码;空游标表示第 1 页(恒健是 1 基入参)。 */
private static int pageNumberOf(String cursor) {
String v = trimToNull(cursor);
if (v == null) {
return 1;
}
try {
int page = Integer.parseInt(v);
return page < 1 ? 1 : page;
} catch (NumberFormatException e) {
throw new IllegalArgumentException("hengjian order list cursor must be a page number, got " + v);
}
}
private common.ecommerce.shared.error.ValidationException validation(WarehouseContext ctx,
String operation, String message) {
return new common.ecommerce.shared.error.ValidationException(WarehouseException.builder()
.message(message)
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false));
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String t = v.trim();
return t.isEmpty() ? null : t;
}
/**

411
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOrderMapper.java

@ -0,0 +1,411 @@ @@ -0,0 +1,411 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos;
import common.ecommerce.hengjian.dto.HengjianOrderListDtos;
import common.ecommerce.hengjian.enums.HengjianOrderStatus;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.model.WarehouseAttachment;
import java.math.BigDecimal;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.List;
/**
* 恒健订单报文 → 统一模型(详情 / 列表共用)。
*
* <p>两个接口回的字段高度重合,行模型也一致;差异只在
* {@code orderId} / {@code channelFlag} / {@code amount} / {@code taxPrice}
* (列表独有)与 {@code estimatedShippingFeeItems}(详情独有)。</p>
*
* <h2>时间</h2>
* <p>恒健声明时间字段是 utc 的 {@code yyyy-MM-dd HH:mm:ss},这里<b>按 UTC 解析</b>,
* 不用 {@code WarehouseContext.zone()}——那个时区是给「仓方回传的无时区本地时间」用的,
* 而恒健已经明确是 UTC。</p>
*
* <h2>双号</h2>
* <p>详情<b>只回 {@code orderNo}</b>(我们的来源单号),列表才回 {@code orderId}。
* 所以:</p>
* <ul>
* <li>{@code outboundRequestNo} = {@code orderNo};</li>
* <li>{@code providerOrderId} = {@code orderId}(详情查不到时为 null,<b>不编</b>);</li>
* <li>{@code orderRef} 恒为 null——恒健不回传平台单号。</li>
* </ul>
*/
public final class HengjianOrderMapper {
/** 恒健时间格式(UTC)。 */
private static final DateTimeFormatter TIME_FORMAT =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
/** 无异常时恒健回的哨兵值。 */
private static final String NO_EXCEPTION = "unexception";
/** 未指定币种时的默认值(与下单接口一致)。 */
private static final String DEFAULT_CURRENCY = "USD";
/** 发货类型:0 实际包裹 / 1 面单信息。 */
private static final int PACKAGE_FLAG_ACTUAL = 0;
private HengjianOrderMapper() {
}
// ================================================================ 详情
/** 订单详情 → 统一出库单。 */
public static OutboundOrder toOrder(HengjianOrderDetailDtos.OrderDetail detail, String warehouseCode) {
String orderNo = requireOrderNo(detail.orderNo);
OutboundOrder.Builder builder = OutboundOrder.builder()
.warehouseCode(warehouseOf(detail.warehouseCode, warehouseCode))
.outboundRequestNo(orderNo)
// 详情接口不回 orderId —— 不给假值,保持 null
.providerOrderId(null)
.orderRef(null)
.status(HengjianOrderStatus.toCore(detail.orderStatusEnum))
.rawStatus(trimToNull(detail.orderStatusEnum))
.carrier(trimToNull(detail.carrierCode))
.carrierCode(trimToNull(detail.carrierCode))
.trackingNumber(firstTrackingOfDetail(detail.shipmentPackages))
.currency(trimToNull(detail.currency))
.thirdPartyAccount(trimToNull(detail.thirdPartyAccount))
.paidAt(parseTime(detail.paidAt))
.shippedAt(firstShippedAtOfDetail(detail.shipmentPackages))
.signatureRequired(flagOf(detail.isSignature))
.insured(flagOf(detail.isInsure))
.shipTo(toShipTo(detail.shipToCountry, detail.shipToContact, detail.shipToAddress1,
detail.shipToAddress2, detail.shipToAddress3, detail.shipToCity,
detail.shipToState, detail.shipToPostal, detail.shipToTelephone))
.exceptionCode(exceptionOf(detail.errorCode))
.lines(toDetailLines(detail.productItems))
.estimatedShippingFee(moneyOf(detail.estimatedShippingFee, detail.currency))
.sourceProvider(WarehouseProvider.HENGJIAN);
addDetailAttachments(builder, detail.enclosure);
return builder.build();
}
// ================================================================ 列表
/**
* 列表行 → 统一出库单。
*
* <p>列表比详情多出 {@code orderId},所以这里的 {@code providerOrderId} 有值;
* 但列表<b>没有</b>预估费用明细,需要完整信息时还是要按单号再查一次详情。</p>
*/
public static OutboundOrder toOrder(HengjianOrderListDtos.OrderRow row, String warehouseCode) {
String orderNo = requireOrderNo(row.orderNo);
OutboundOrder.Builder builder = OutboundOrder.builder()
.warehouseCode(warehouseOf(row.warehouseCode, warehouseCode))
.outboundRequestNo(orderNo)
.providerOrderId(row.orderId == null ? null : String.valueOf(row.orderId))
.providerId(row.orderId == null ? null : String.valueOf(row.orderId))
.orderRef(null)
.status(HengjianOrderStatus.toCore(row.orderStatusEnum))
.rawStatus(trimToNull(row.orderStatusEnum))
.carrier(trimToNull(row.carrierCode))
.carrierCode(trimToNull(row.carrierCode))
.trackingNumber(firstTrackingOfList(row.shipmentPackages))
.currency(trimToNull(row.currency))
.thirdPartyAccount(trimToNull(row.thirdPartyAccount))
.paidAt(parseTime(row.paidAt))
.shippedAt(firstShippedAtOfList(row.shipmentPackages))
.signatureRequired(flagOf(row.isSignature))
.insured(flagOf(row.isInsure))
.shipTo(toShipTo(row.shipToCountry, row.shipToContact, row.shipToAddress1,
row.shipToAddress2, row.shipToAddress3, row.shipToCity,
row.shipToState, row.shipToPostal, row.shipToTelephone))
.exceptionCode(exceptionOf(row.errorCode))
.lines(toListLines(row.productItems))
.estimatedShippingFee(moneyOf(row.estimatedShippingFee, row.currency))
.sourceProvider(WarehouseProvider.HENGJIAN);
// 列表独有:整单销售金额。统一模型没有专门字段,落 totalAmount 并注明口径,
// 币种用整单 currency,缺失时才按 USD 兜底。
if (row.amount != null) {
builder.totalAmount(moneyOf(row.amount, row.currency));
}
addListAttachments(builder, row.enclosure);
return builder.build();
}
// ================================================================ 行
/**
* 产品行(详情)。
*
* <p>{@code skuAmount} 在恒健是<b>行总额</b>(不是单价),落
* {@link OutboundLine#totalAmount()};恒健不回申报单价,所以
* {@code declareValue} 留空,避免把总额当单价再乘一次。</p>
*
* <p>数量缺失或非正的行直接跳过:{@link OutboundLine} 要求数量为正,
* 保留会在构造期抛异常,把「一条坏数据」放大成「整单查不出来」。</p>
*/
static List<OutboundLine> toDetailLines(List<HengjianOrderDetailDtos.OrderDetail.ProductItem> items) {
List<OutboundLine> out = new ArrayList<OutboundLine>();
if (items == null) {
return out;
}
for (HengjianOrderDetailDtos.OrderDetail.ProductItem item : items) {
if (item == null) {
continue;
}
OutboundLine line = lineOf(item.sku, item.quantity, item.skuAmount, item.insureAmount);
if (line != null) {
out.add(line);
}
}
return out;
}
/** 产品行(列表);列表多一个 {@code taxPrice},统一模型没有对应字段,不落。 */
static List<OutboundLine> toListLines(List<HengjianOrderListDtos.OrderRow.ProductItem> items) {
List<OutboundLine> out = new ArrayList<OutboundLine>();
if (items == null) {
return out;
}
for (HengjianOrderListDtos.OrderRow.ProductItem item : items) {
if (item == null) {
continue;
}
OutboundLine line = lineOf(item.sku, item.quantity, item.skuAmount, item.insureAmount);
if (line != null) {
out.add(line);
}
}
return out;
}
private static OutboundLine lineOf(String sku, Integer quantity, Double skuAmount, Double insureAmount) {
String providerSku = trimToNull(sku);
if (providerSku == null || quantity == null || quantity <= 0) {
return null;
}
OutboundLine.Builder line = OutboundLine.builder()
.lineNo(providerSku)
.omsSku(providerSku)
.providerSku(providerSku)
.quantity(quantity);
if (skuAmount != null) {
line.totalAmount(moneyOf(skuAmount, null));
}
if (insureAmount != null && insureAmount > 0) {
line.insuredAmount(moneyOf(insureAmount, null));
}
return line.build();
}
// ================================================================ 附件
private static void addDetailAttachments(OutboundOrder.Builder builder,
List<HengjianOrderDetailDtos.OrderDetail.Enclosure> enclosures) {
if (enclosures == null) {
return;
}
for (HengjianOrderDetailDtos.OrderDetail.Enclosure e : enclosures) {
if (e == null) {
continue;
}
builder.attachment(attachmentOf(e.name, e.type, e.url));
}
}
private static void addListAttachments(OutboundOrder.Builder builder,
List<HengjianOrderListDtos.OrderRow.Enclosure> enclosures) {
if (enclosures == null) {
return;
}
for (HengjianOrderListDtos.OrderRow.Enclosure e : enclosures) {
if (e == null) {
continue;
}
builder.attachment(attachmentOf(e.name, e.type, e.url));
}
}
/** 附件;{@code type} 是仓方原值,不做归一。 */
private static WarehouseAttachment attachmentOf(String name, String type, String url) {
return WarehouseAttachment.builder()
.name(trimToNull(name))
.type(trimToNull(type))
.url(trimToNull(url))
.build();
}
// ================================================================ 其它
/**
* 收件地址。
*
* <p>恒健没有邮箱字段;电话在文档示例里带多余空格与分机,文档没说格式,
* <b>原样保留</b>,不猜着清洗。整组都为空时返回 null,
* 避免把「空地址」当成真实地址回传给业务。</p>
*/
private static ShipTo toShipTo(String country, String contact, String address1, String address2,
String address3, String city, String state, String postal,
String phone) {
if (blank(country) && blank(address1) && blank(city) && blank(contact)) {
return null;
}
return ShipTo.builder()
.name(trimToNull(contact))
.phone(trimToNull(phone))
.countryCode(trimToNull(country))
.stateOrProvince(trimToNull(state))
.city(trimToNull(city))
.addressLine1(trimToNull(address1))
.addressLine2(trimToNull(address2))
.addressLine3(trimToNull(address3))
.postalCode(trimToNull(postal))
.build();
}
/** 首个实际包裹的发货时间;面单信息行({@code packageFlag=1})不参与。 */
private static Instant firstShippedAtOfDetail(
List<HengjianOrderDetailDtos.OrderDetail.ShipmentPackage> packages) {
if (packages == null) {
return null;
}
for (HengjianOrderDetailDtos.OrderDetail.ShipmentPackage p : packages) {
if (p == null || !isActualPackage(p.packageFlag)) {
continue;
}
Instant at = parseTime(p.shipmentDate);
if (at != null) {
return at;
}
}
return null;
}
private static Instant firstShippedAtOfList(List<HengjianOrderListDtos.OrderRow.ShipmentPackage> packages) {
if (packages == null) {
return null;
}
for (HengjianOrderListDtos.OrderRow.ShipmentPackage p : packages) {
if (p == null || !isActualPackage(p.packageFlag)) {
continue;
}
Instant at = parseTime(p.shipmentDate);
if (at != null) {
return at;
}
}
return null;
}
private static boolean isActualPackage(Integer packageFlag) {
return packageFlag == null || packageFlag == PACKAGE_FLAG_ACTUAL;
}
/** 首个实际包裹的跟踪号;面单信息行不参与,避免把「面单信息」当成真实运单。 */
private static String firstTrackingOfDetail(
List<HengjianOrderDetailDtos.OrderDetail.ShipmentPackage> packages) {
if (packages == null) {
return null;
}
for (HengjianOrderDetailDtos.OrderDetail.ShipmentPackage p : packages) {
if (p == null || !isActualPackage(p.packageFlag)) {
continue;
}
String tracking = trimToNull(p.trackingNo);
if (tracking != null) {
return tracking;
}
}
return null;
}
private static String firstTrackingOfList(List<HengjianOrderListDtos.OrderRow.ShipmentPackage> packages) {
if (packages == null) {
return null;
}
for (HengjianOrderListDtos.OrderRow.ShipmentPackage p : packages) {
if (p == null || !isActualPackage(p.packageFlag)) {
continue;
}
String tracking = trimToNull(p.trackingNo);
if (tracking != null) {
return tracking;
}
}
return null;
}
/** 0/1 标记 → Boolean;缺省为 null(表示仓方未给,不是「否」)。 */
static Boolean flagOf(Integer flag) {
return flag == null ? null : flag != 0;
}
/** {@code unexception} 或空视为无异常。 */
static String exceptionOf(String errorCode) {
String code = trimToNull(errorCode);
if (code == null || NO_EXCEPTION.equalsIgnoreCase(code)) {
return null;
}
return code;
}
/** 金额;币种缺失时按 USD(恒健默认币种)。 */
static Money moneyOf(Double amount, String currency) {
if (amount == null) {
return null;
}
String code = trimToNull(currency);
return Money.of(BigDecimal.valueOf(amount), code == null ? DEFAULT_CURRENCY : code);
}
/** 解析恒健的 UTC 时间;格式不符返回 null,不因时间格式阻断整单。 */
static Instant parseTime(String value) {
String v = trimToNull(value);
if (v == null) {
return null;
}
try {
return LocalDateTime.parse(v, TIME_FORMAT).toInstant(ZoneOffset.UTC);
} catch (DateTimeParseException e) {
try {
return Instant.parse(v);
} catch (DateTimeParseException ignored) {
return null;
}
}
}
/** 仓编码:报文里的优先,没有才用账户配置。 */
private static String warehouseOf(String fromPayload, String fallback) {
String fromBody = trimToNull(fromPayload);
return fromBody != null ? fromBody : fallback;
}
/**
* 订单号。
*
* <p>{@link OutboundOrder} 要求 {@code outboundRequestNo} 非空,恒健的回包理论上
* 一定带 {@code orderNo};不带说明报文结构变了,直接抛而不是造一个空单。</p>
*/
private static String requireOrderNo(String orderNo) {
String v = trimToNull(orderNo);
if (v == null) {
throw new IllegalArgumentException("hengjian order payload has no orderNo");
}
return v;
}
private static boolean blank(String v) {
return v == null || v.trim().isEmpty();
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String t = v.trim();
return t.isEmpty() ? null : t;
}
}

228
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderDetailDtos.java

@ -0,0 +1,228 @@ @@ -0,0 +1,228 @@
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/findOne})。
*
* <p>请求只有 {@code orderNo}。<b>响应没有 {@code orderId}</b>——那是列表接口才回的字段,
* 所以按详情查回来的单拿不到仓内部 id,取消时要用的话得靠列表接口补。</p>
*/
public final class HengjianOrderDetailDtos {
private HengjianOrderDetailDtos() {
}
/** 请求:{@code {"orderNo": "..."}}。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class FindOneRequest {
/** 订单号,是我们下单时下发的来源单号。 */
public String orderNo;
}
/** 响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class FindOneResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public OrderDetail data;
}
/**
* 订单详情。
*
* <p>字段名照抄文档。注意 {@code estimatedShippingFeeItems} 是<b>预估费用明细</b>
* (Basic Rate / Residential / Fuel Surcharge 等),与 {@code estimatedShippingFee}
* 是同一份钱的不同粒度,不要累加。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderDetail {
/** 订单号(来源单号)。 */
@JsonProperty("orderNo")
public String orderNo;
/**
* 支付时间,{@code yyyy-MM-dd HH:mm:ss}。
*
* <p>文档没写时区;创建接口的 {@code paidAt} 注明是 utc,这里**按 UTC 解析**,
* 待真机核对。</p>
*/
@JsonProperty("paidAt")
public String paidAt;
/** 店铺标识(文档字段表未列,响应示例里有)。 */
@JsonProperty("channelAccount")
public String channelAccount;
@JsonProperty("shipToContact")
public String shipToContact;
@JsonProperty("shipToAddress1")
public String shipToAddress1;
@JsonProperty("shipToAddress2")
public String shipToAddress2;
@JsonProperty("shipToAddress3")
public String shipToAddress3;
@JsonProperty("shipToCity")
public String shipToCity;
@JsonProperty("shipToState")
public String shipToState;
@JsonProperty("shipToCountry")
public String shipToCountry;
@JsonProperty("shipToPostal")
public String shipToPostal;
@JsonProperty("shipToTelephone")
public String shipToTelephone;
/** 仓库 code。 */
@JsonProperty("warehouseCode")
public String warehouseCode;
/** 物流商服务 code。 */
@JsonProperty("carrierCode")
public String carrierCode;
/** 发货时效等级(响应示例里有)。 */
@JsonProperty("shipServiceLevel")
public String shipServiceLevel;
/** third party 账号。 */
@JsonProperty("thirdPartyAccount")
public String thirdPartyAccount;
/** 币种。 */
@JsonProperty("currency")
public String currency;
/** 是否签收:0 否 / 1 是。 */
@JsonProperty("isSignature")
public Integer isSignature;
/** 是否保价:0 否 / 1 是。 */
@JsonProperty("isInsure")
public Integer isInsure;
/**
* 订单状态:{@code pending / unshipped / approved / assigned / picked /
* shipped / canceled / refunded}。
*/
@JsonProperty("orderStatusEnum")
public String orderStatusEnum;
/** 预估运费;实际以快递账单为准。 */
@JsonProperty("estimatedShippingFee")
public Double estimatedShippingFee;
/** 预估费用明细;与 {@link #estimatedShippingFee} 是同一份钱的拆分。 */
@JsonProperty("estimatedShippingFeeItems")
public List<EstimatedFeeItem> estimatedShippingFeeItems;
/**
* 异常码:{@code unexception} 表示无异常,其余见文档
* ({@code pickingException} / {@code addressException} / {@code trackingException} 等)。
*/
@JsonProperty("errorCode")
public String errorCode;
/** 产品行。 */
@JsonProperty("productItems")
public List<ProductItem> productItems;
/** 附件。 */
@JsonProperty("enclosure")
public List<Enclosure> enclosure;
/** 发货信息。 */
@JsonProperty("shipmentPackages")
public List<ShipmentPackage> shipmentPackages;
/** 一条预估费用。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class EstimatedFeeItem {
/** 费用项名称,如 {@code Fuel Surcharge}。 */
@JsonProperty("costName")
public String costName;
@JsonProperty("estimatedCost")
public Double estimatedCost;
@JsonProperty("currency")
public String currency;
}
/** 产品行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductItem {
@JsonProperty("sku")
public String sku;
@JsonProperty("quantity")
public Integer quantity;
/** 销售金额;<b>是行总额</b>(与下单接口的 skuAmount 同语义)。 */
@JsonProperty("skuAmount")
public Double skuAmount;
/** 投保金额;不保价为 0。 */
@JsonProperty("insureAmount")
public Double insureAmount;
}
/** 附件。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Enclosure {
/**
* 附件类型。
*
* <p>详情页标 STRING、列表页标 INTEGER,示例给的是 {@code "Shippinglabel"};
* 按 String 读,两种形态都能接住。</p>
*/
@JsonProperty("type")
public String type;
@JsonProperty("name")
public String name;
@JsonProperty("url")
public String url;
}
/** 发货信息。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ShipmentPackage {
/** 跟踪号。 */
@JsonProperty("trackingNo")
public String trackingNo;
/** 发货方式(承运商)。 */
@JsonProperty("carrier")
public String carrier;
/** 发货产品 SKU。 */
@JsonProperty("erpSku")
public String erpSku;
/** 成本。 */
@JsonProperty("cost")
public Double cost;
/** 发货数量。 */
@JsonProperty("shipedQuantity")
public Integer shipedQuantity;
/** 发货时间(utc),{@code yyyy-MM-dd HH:mm:ss}。 */
@JsonProperty("shipmentDate")
public String shipmentDate;
/** 装车交接时间(utc)。 */
@JsonProperty("departureDate")
public String departureDate;
/** 发货类型:0 实际包裹 / 1 面单信息。 */
@JsonProperty("packageFlag")
public Integer packageFlag;
/** 产品二维码-组织。 */
@JsonProperty("qrOrg")
public String qrOrg;
/** 产品二维码-PO。 */
@JsonProperty("qrPo")
public String qrPo;
}
}
}

219
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderListDtos.java

@ -0,0 +1,219 @@ @@ -0,0 +1,219 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 恒健报文结构:订单列表({@code GET /v1/saleOrder/findByPage})。
*
* <p>与详情接口的差异(真机 / 文档双确认):</p>
* <ul>
* <li>列表<b>多回 {@code orderId}</b>——取消接口需要它,所以「按单号查列表」是补
* {@code orderId} 的正规途径;</li>
* <li>列表多回 {@code channelFlag} / {@code amount},产品行多回 {@code taxPrice};</li>
* <li>列表的 {@code enclosure[].type} 文档标 INTEGER,详情页标 STRING(示例是
* {@code "Shippinglabel"});这里按 String 读,Jackson 会把数字也转成文本。</li>
* </ul>
*/
public final class HengjianOrderListDtos {
private HengjianOrderListDtos() {
}
/** 响应外层(分页信封)。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ListResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public PageData data;
}
/**
* 分页数据。
*
* <p>{@code number} 是<b>0 基</b>页码(示例里请求第 1 页返回 {@code number: 0}),
* 翻页要用它 + 1 反过来推。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class PageData {
@JsonProperty("content")
public List<OrderRow> content;
/** 总记录数。 */
@JsonProperty("totalElements")
public Integer totalElements;
/** 总页数。 */
@JsonProperty("totalPages")
public Integer totalPages;
/** 当前页记录数。 */
@JsonProperty("numberOfElements")
public Integer numberOfElements;
/** 当前页码,<b>0 基</b>。 */
@JsonProperty("number")
public Integer number;
/** 每页条数。 */
@JsonProperty("size")
public Integer size;
/** 是否第一页。 */
@JsonProperty("first")
public Boolean first;
/** 是否最后一页。 */
@JsonProperty("last")
public Boolean last;
/** 是否为空页。 */
@JsonProperty("empty")
public Boolean empty;
}
/** 一行订单。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderRow {
/** 仓内部订单 id;取消接口要它。 */
@JsonProperty("orderId")
public Long orderId;
/** 订单号(来源单号)。 */
@JsonProperty("orderNo")
public String orderNo;
@JsonProperty("paidAt")
public String paidAt;
/** 店铺标识(文档字段表未列,示例里有)。 */
@JsonProperty("channelAccount")
public String channelAccount;
@JsonProperty("shipToContact")
public String shipToContact;
@JsonProperty("shipToAddress1")
public String shipToAddress1;
@JsonProperty("shipToAddress2")
public String shipToAddress2;
@JsonProperty("shipToAddress3")
public String shipToAddress3;
@JsonProperty("shipToCity")
public String shipToCity;
@JsonProperty("shipToState")
public String shipToState;
@JsonProperty("shipToCountry")
public String shipToCountry;
@JsonProperty("shipToPostal")
public String shipToPostal;
@JsonProperty("shipToTelephone")
public String shipToTelephone;
@JsonProperty("warehouseCode")
public String warehouseCode;
@JsonProperty("carrierCode")
public String carrierCode;
@JsonProperty("shipServiceLevel")
public String shipServiceLevel;
@JsonProperty("thirdPartyAccount")
public String thirdPartyAccount;
@JsonProperty("currency")
public String currency;
@JsonProperty("isSignature")
public Integer isSignature;
@JsonProperty("isInsure")
public Integer isInsure;
/** 订单状态,码值与详情一致。 */
@JsonProperty("orderStatusEnum")
public String orderStatusEnum;
/** 渠道标识。 */
@JsonProperty("channelFlag")
public String channelFlag;
/** 销售金额(整单)。 */
@JsonProperty("amount")
public Double amount;
/** 预估运费。 */
@JsonProperty("estimatedShippingFee")
public Double estimatedShippingFee;
@JsonProperty("errorCode")
public String errorCode;
@JsonProperty("productItems")
public List<ProductItem> productItems;
@JsonProperty("enclosure")
public List<Enclosure> enclosure;
@JsonProperty("shipmentPackages")
public List<ShipmentPackage> shipmentPackages;
/** 产品行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductItem {
@JsonProperty("sku")
public String sku;
@JsonProperty("quantity")
public Integer quantity;
@JsonProperty("skuAmount")
public Double skuAmount;
@JsonProperty("insureAmount")
public Double insureAmount;
/** 税费;详情接口没有这个字段。 */
@JsonProperty("taxPrice")
public Double taxPrice;
}
/** 附件。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Enclosure {
/** 附件类型;列表页文档标 INTEGER,详情页是字符串,这里统一按文本读。 */
@JsonProperty("type")
public String type;
@JsonProperty("name")
public String name;
@JsonProperty("url")
public String url;
}
/** 发货信息。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ShipmentPackage {
@JsonProperty("trackingNo")
public String trackingNo;
@JsonProperty("carrier")
public String carrier;
/** 文档列表页没有 erpSku,示例也没给;接住但不依赖。 */
@JsonProperty("erpSku")
public String erpSku;
@JsonProperty("cost")
public Double cost;
@JsonProperty("shipedQuantity")
public Integer shipedQuantity;
@JsonProperty("shipmentDate")
public String shipmentDate;
@JsonProperty("departureDate")
public String departureDate;
@JsonProperty("packageFlag")
public Integer packageFlag;
@JsonProperty("qrOrg")
public String qrOrg;
@JsonProperty("qrPo")
public String qrPo;
}
}
}

86
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianOrderStatus.java

@ -0,0 +1,86 @@ @@ -0,0 +1,86 @@
package common.ecommerce.hengjian.enums;
import common.ecommerce.warehouse.enums.OutboundStatus;
/**
* 恒健出库订单状态({@code orderStatusEnum},详情与列表接口共用)。
*
* <p>码表来自《获取订单的详细信息》与《订单--查询列表》两页文档:
* {@code pending} 未支付 / {@code unshipped} 未发货 / {@code approved} 已审核 /
* {@code assigned} 已分配 / {@code picked} 已配货 / {@code shipped} 已发货 /
* {@code canceled} 已取消 / {@code refunded} 已退款。</p>
*
* <p><b>与运去哪同名不是巧合也不是同源</b>:两家都是美国仓、同一套英文词,
* 但码值集合与后续扩展各自独立,必须各建一套枚举,不能互相引用。</p>
*
* <p><b>按完整值精确匹配</b>。历史教训:用 {@code contains("SHIP")} 会把
* {@code UNSHIPPED}(未发货)判成 {@code SHIPPED}(已交运),下游据此认为货已发出、
* 取消被直接锁死。认不出的归 {@link #UNKNOWN},不猜;原值同时写进
* {@code OutboundOrder.rawStatus}。</p>
*/
public enum HengjianOrderStatus {
/** 未支付。 */
PENDING("pending", OutboundStatus.CREATED),
/** 未发货(仓已接单但未作业)。 */
UNSHIPPED("unshipped", OutboundStatus.SUBMITTED),
/** 已审核。 */
APPROVED("approved", OutboundStatus.ACCEPTED),
/** 已分配(仓已接单)。 */
ASSIGNED("assigned", OutboundStatus.ACCEPTED),
/** 已配货。 */
PICKED("picked", OutboundStatus.PICKING),
/** 已发货。 */
SHIPPED("shipped", OutboundStatus.SHIPPED),
/** 已取消。 */
CANCELLED("canceled", OutboundStatus.CANCELLED),
/** 已退款。 */
REFUNDED("refunded", OutboundStatus.REFUNDED),
/** 无法识别。 */
UNKNOWN(null, OutboundStatus.UNKNOWN);
/** 恒健原始值(小写);null 表示「无关键字 / 认不出」。 */
private final String rawValue;
private final OutboundStatus core;
HengjianOrderStatus(String rawValue, OutboundStatus core) {
this.rawValue = rawValue;
this.core = core;
}
/** 恒健原始值;null 表示无法识别。 */
public String rawValue() {
return rawValue;
}
/** 对应的底层状态。 */
public OutboundStatus toCore() {
return core;
}
/**
* 恒健原始值 → 平台枚举。<b>精确匹配</b>(只忽略大小写与首尾空白)。
*
* <p>空值、未收录的取值都返回 {@link #UNKNOWN}。</p>
*/
public static HengjianOrderStatus of(String rawStatus) {
if (rawStatus == null) {
return UNKNOWN;
}
String s = rawStatus.trim();
if (s.isEmpty()) {
return UNKNOWN;
}
for (HengjianOrderStatus v : values()) {
if (v.rawValue != null && s.equalsIgnoreCase(v.rawValue)) {
return v;
}
}
return UNKNOWN;
}
/** 恒健原始值 → 底层状态。 */
public static OutboundStatus toCore(String rawStatus) {
return of(rawStatus).toCore();
}
}

12
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java

@ -1,7 +1,10 @@ @@ -1,7 +1,10 @@
/**
* 恒健平台枚举(<b>本期尚未建立</b>)。
* 恒健平台枚举:仓方原始码 + {@code toCore()} 映射到底层枚举。
*
* <p>只读基础资料阶段没有状态码。接入出库 / 库存 / 退货时按
* <p>已建:{@link common.ecommerce.hengjian.enums.HengjianOrderStatus}
* (订单 {@code orderStatusEnum})。</p>
*
* <p>后续接入库存 / 退货 / 转运时按
* {@code docs-warehouse/onboarding-checklist.md} 阶段 2.6 建:</p>
*
* <ul>
@ -11,8 +14,7 @@ @@ -11,8 +14,7 @@
* <li>用完的原值同时写进模型的 {@code rawStatus}。</li>
* </ul>
*
* <p>恒健已知的状态字段:{@code /v1/saleOrder/findByPage} 的 {@code orderStatusEnum}
* 取值为 {@code pending / unshipped / approved / assigned / picked / shipped /
* canceled / refunded}——注意与运去哪<b>同名</b>,但那是巧合,两套码表各建各的。</p>
* <p>恒健的 {@code orderStatusEnum} 与运去哪<b>同名</b>(都是英文词),但那是巧合,
* 两套码表各建各的,不能互相引用。</p>
*/
package common.ecommerce.hengjian.enums;

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

@ -63,15 +63,17 @@ class HengjianAdapterTest { @@ -63,15 +63,17 @@ class HengjianAdapterTest {
}
/**
* 下单已接、查询未接:门面能力检查放行 {@code OUTBOUND},
* 适配器对未实现的 {@code get} 显式抛异常,不返回 null。
* 下单 / 查询 / 包裹已接、取消未接:门面能力检查放行 {@code OUTBOUND},
* 适配器对未实现的 {@code cancel} 显式抛异常,不返回 null。
*/
@Test
void unimplementedOutboundQueryIsRejected() {
void unimplementedCancelIsRejected() {
WarehouseSdk sdk = sdk();
assertThrows(common.ecommerce.warehouse.error.WarehouseException.class,
() -> sdk.warehouses(WH, conn()).outbound().get(OutboundRef.ofRequestNo("OB-1")));
() -> sdk.warehouses(WH, conn()).outbound().cancel(
common.ecommerce.warehouse.model.CancelCommand.builder()
.outboundRequestNo("OB-1").build()));
}
/** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */

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

@ -0,0 +1,440 @@ @@ -0,0 +1,440 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.enums.HengjianOrderStatus;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.OutboundStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 订单详情({@code /v1/saleOrder/findOne})与订单列表({@code /v1/saleOrder/findByPage})契约测试。
*/
class HengjianOrderQueryTest {
private static final Instant NOW = Instant.parse("2026-11-13T00:00:00Z");
private static final Clock CLOCK = Clock.fixed(NOW, ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build()),
"req-1", CLOCK);
}
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
/** 文档示例的详情结构。 */
private static final String DETAIL_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"获取订单数据成功\",\"data\":{"
+ "\"orderNo\":\"OB-2026-0001\","
+ "\"paidAt\":\"2026-11-10 18:48:42\","
+ "\"channelAccount\":\"accessory2go\","
+ "\"shipToContact\":\"Gabriel Garner\","
+ "\"shipToAddress1\":\"9211 WINDWARD TRCE\","
+ "\"shipToAddress2\":\"\","
+ "\"shipToCity\":\"SAN ANTONIO\","
+ "\"shipToState\":\"TX\","
+ "\"shipToCountry\":\"US\","
+ "\"shipToPostal\":\"78254-6046\","
+ "\"shipToTelephone\":\"415-851-9136\","
+ "\"warehouseCode\":\"EFCA\","
+ "\"carrierCode\":\"FEDXG\","
+ "\"shipServiceLevel\":\"Std US D2D Dom\","
+ "\"currency\":\"USD\","
+ "\"isSignature\":1,"
+ "\"isInsure\":0,"
+ "\"errorCode\":\"unexception\","
+ "\"orderStatusEnum\":\"shipped\","
+ "\"estimatedShippingFee\":21.28,"
+ "\"estimatedShippingFeeItems\":[{\"costName\":\"Basic Rate\","
+ "\"estimatedCost\":15.0,\"currency\":\"USD\"}],"
+ "\"productItems\":[{\"sku\":\"P6121A51\",\"quantity\":2,"
+ "\"skuAmount\":19.98,\"insureAmount\":0.0}],"
+ "\"enclosure\":[{\"type\":\"Shippinglabel\",\"name\":\"label.pdf\","
+ "\"url\":\"https://example.com/l.pdf\"}],"
+ "\"shipmentPackages\":[{\"trackingNo\":\"788676678675\",\"carrier\":\"FEDXG\","
+ "\"erpSku\":\"P6121A51\",\"cost\":12.5,\"shipedQuantity\":2,"
+ "\"shipmentDate\":\"2026-11-11 03:00:05\",\"packageFlag\":0}]}}";
private static RecordingTransport detail() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(DETAIL_BODY));
}
// ================================================================ 详情
@Test
void getSendsPostWithOrderNo() {
RecordingTransport transport = detail();
adapter(transport).get(ctx(), OutboundRef.ofRequestNo("OB-2026-0001"));
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/saleOrder/findOne",
transport.lastDataRequest().url());
assertEquals("{\"orderNo\":\"OB-2026-0001\"}", transport.lastDataRequest().body());
}
@Test
void getMapsOrderFields() {
OutboundOrder order = adapter(detail()).get(ctx(), OutboundRef.ofRequestNo("OB-2026-0001"));
assertEquals(WarehouseProvider.HENGJIAN, order.sourceProvider());
assertEquals("OB-2026-0001", order.outboundRequestNo());
assertEquals("EFCA", order.warehouseCode());
assertEquals(OutboundStatus.SHIPPED, order.status());
assertEquals("shipped", order.rawStatus());
assertEquals("FEDXG", order.carrierCode());
assertEquals("FEDXG", order.carrier());
assertEquals("USD", order.currency());
assertEquals(Boolean.TRUE, order.signatureRequired());
assertEquals(Boolean.FALSE, order.insured());
// 2026-11-10 18:48:42 UTC
assertEquals(Instant.parse("2026-11-10T18:48:42Z"), order.paidAt());
assertEquals(Instant.parse("2026-11-11T03:00:05Z"), order.shippedAt());
assertEquals("788676678675", order.trackingNumber());
assertNull(order.exceptionCode(), "unexception 应归一成 null");
assertEquals(21.28, order.estimatedShippingFee().amount().doubleValue(), 0.0001);
assertEquals("USD", order.estimatedShippingFee().currency().getCurrencyCode());
}
/** 详情接口不回 orderId:不能编一个,也不能把单号塞进去当 id。 */
@Test
void detailHasNoProviderOrderId() {
OutboundOrder order = adapter(detail()).get(ctx(), OutboundRef.ofRequestNo("OB-2026-0001"));
assertNull(order.providerOrderId());
}
@Test
void detailMapsLinesAndAttachments() {
OutboundOrder order = adapter(detail()).get(ctx(), OutboundRef.ofRequestNo("OB-2026-0001"));
assertEquals(1, order.lines().size());
OutboundLine line = order.lines().get(0);
assertEquals("P6121A51", line.providerSku());
assertEquals(2, line.quantity());
// skuAmount 是行总额,落 totalAmount,不能当 declareValue(单价)
assertEquals(19.98, line.totalAmount().amount().doubleValue(), 0.0001);
assertNull(line.declareValue(), "恒健不回申报单价,不能拿行总额顶替");
assertEquals(1, order.attachments().size());
assertEquals("label.pdf", order.attachments().get(0).name());
assertEquals("Shippinglabel", order.attachments().get(0).type());
}
@Test
void detailMapsShipTo() {
OutboundOrder order = adapter(detail()).get(ctx(), OutboundRef.ofRequestNo("OB-2026-0001"));
assertEquals("Gabriel Garner", order.shipTo().name());
assertEquals("US", order.shipTo().countryCode());
assertEquals("TX", order.shipTo().stateOrProvince());
assertEquals("SAN ANTONIO", order.shipTo().city());
assertEquals("78254-6046", order.shipTo().postalCode());
}
/** data 为空表示查不到,返回 null 而不是造空单。 */
@Test
void getReturnsNullWhenDataMissing() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(
"{\"code\":200,\"message\":\"未找到\"}"));
assertNull(adapter(transport).get(ctx(), OutboundRef.ofRequestNo("OB-NONE")));
}
/** 只给 providerOrderId 时退化成来源单号发出去;仓方查不到会报错,不静默返回 null。 */
@Test
void getAcceptsProviderOrderIdAsFallback() {
RecordingTransport transport = detail();
adapter(transport).get(ctx(), OutboundRef.ofProviderOrderId("193252852"));
assertEquals("{\"orderNo\":\"193252852\"}", transport.lastDataRequest().body());
}
// ================================================================ 列表
private static final String LIST_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"获取订单数据成功\",\"data\":{"
+ "\"totalElements\":2,\"totalPages\":1,\"numberOfElements\":2,"
+ "\"number\":0,\"size\":10,\"first\":true,\"last\":true,\"empty\":false,"
+ "\"content\":["
+ "{\"orderId\":193252852,\"orderNo\":\"OB-1\",\"paidAt\":\"2026-11-10 03:09:59\","
+ "\"warehouseCode\":\"EFCA\",\"carrierCode\":\"UPSG_HL\",\"currency\":\"USD\","
+ "\"isSignature\":0,\"isInsure\":0,\"orderStatusEnum\":\"unshipped\","
+ "\"channelFlag\":\"amazon\",\"amount\":39.96,\"estimatedShippingFee\":8.5,"
+ "\"shipToCountry\":\"US\",\"shipToState\":\"CA\",\"shipToCity\":\"LA\","
+ "\"shipToPostal\":\"90001\",\"shipToContact\":\"A\",\"shipToAddress1\":\"1 St\","
+ "\"shipToTelephone\":\"555\","
+ "\"productItems\":[{\"sku\":\"S1\",\"quantity\":1,\"skuAmount\":19.98,"
+ "\"insureAmount\":0.0,\"taxPrice\":1.5}],"
+ "\"enclosure\":[],\"shipmentPackages\":[]},"
+ "{\"orderId\":193252853,\"orderNo\":\"OB-2\",\"orderStatusEnum\":\"shipped\","
+ "\"currency\":\"USD\","
+ "\"productItems\":[{\"sku\":\"S2\",\"quantity\":3,\"skuAmount\":30.0}],"
+ "\"shipmentPackages\":[{\"trackingNo\":\"TRK-1\",\"carrier\":\"UPS\","
+ "\"shipedQuantity\":3,\"shipmentDate\":\"2026-11-11 10:00:00\","
+ "\"packageFlag\":0}]}]}}";
private static RecordingTransport list() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, req -> Responses.ok(LIST_BODY));
}
@Test
void querySendsRequiredPagingParams() {
RecordingTransport transport = list();
adapter(transport).query(ctx(), OutboundQuery.builder()
.outboundRequestNo("OB-1").pageSize(10).build());
String url = transport.lastDataRequest().url();
assertEquals("GET", transport.lastDataRequest().method());
assertTrue(url.contains("/v1/saleOrder/findByPage?"), url);
assertTrue(url.contains("page=1"), url);
assertTrue(url.contains("rows=10"), url);
assertTrue(url.contains("sidx=id"), url);
assertTrue(url.contains("sort=desc"), url);
assertTrue(url.contains("orderNos=OB-1"), url);
}
@Test
void queryMapsListRows() {
Page<OutboundOrder> page = adapter(list()).query(ctx(),
OutboundQuery.builder().outboundRequestNo("OB-1").build());
assertEquals(2, page.size());
assertFalse(page.hasMore(), "仓方 last=true 应视为末页");
OutboundOrder first = page.items().get(0);
assertEquals("OB-1", first.outboundRequestNo());
// 列表回 orderId:这是取消接口需要的内<EFBFBD><EFBFBD><EFBFBD> id
assertEquals("193252852", first.providerOrderId());
assertEquals(OutboundStatus.SUBMITTED, first.status());
assertEquals("unshipped", first.rawStatus());
assertEquals(39.96, first.totalAmount().amount().doubleValue(), 0.0001);
OutboundOrder second = page.items().get(1);
assertEquals(OutboundStatus.SHIPPED, second.status());
assertEquals(Instant.parse("2026-11-11T10:00:00Z"), second.shippedAt());
}
/** 时间窗查询:转成 UTC 日期,起止都带上。 */
@Test
void queryConvertsTimeWindowToUtcDates() {
RecordingTransport transport = list();
adapter(transport).query(ctx(), OutboundQuery.builder()
.after(Instant.parse("2026-11-01T00:00:00Z"))
.before(Instant.parse("2026-11-10T23:59:59Z"))
.build());
String url = transport.lastDataRequest().url();
assertTrue(url.contains("beginDateTime=2026-11-01"), url);
assertTrue(url.contains("endDateTime=2026-11-10"), url);
}
/** 时间、单号都没有时本地拒绝,不发必然被拒的请求。 */
@Test
void queryRejectsWithoutAnySelector() {
RecordingTransport transport = list();
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).query(ctx(), OutboundQuery.builder().build()));
assertTrue(ex.getMessage().contains("outboundRequestNo"), ex.getMessage());
assertTrue(transport.dataRequests().isEmpty(), "本地拒绝不应发请求");
}
/** 超过 30 天跨度本地拒绝。 */
@Test
void queryRejectsWindowLongerThan30Days() {
RecordingTransport transport = list();
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).query(ctx(), OutboundQuery.builder()
.after(Instant.parse("2026-10-01T00:00:00Z"))
.before(Instant.parse("2026-11-10T00:00:00Z"))
.build()));
assertTrue(ex.getMessage().contains("30"), ex.getMessage());
assertTrue(transport.dataRequests().isEmpty());
}
/** 状态过滤恒健列表不支持:拒绝而不是静默忽略。 */
@Test
void queryRejectsStatusFilter() {
RecordingTransport transport = list();
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).query(ctx(), OutboundQuery.builder()
.outboundRequestNo("OB-1").status("shipped").build()));
assertTrue(ex.getMessage().contains("status filter"), ex.getMessage());
}
/** 单页行数超过仓方上限时截断。 */
@Test
void queryClampsPageSize() {
RecordingTransport transport = list();
adapter(transport).query(ctx(), OutboundQuery.builder()
.outboundRequestNo("OB-1").pageSize(500).build());
assertTrue(transport.lastDataRequest().url()
.contains("rows=" + HengjianConstants.ORDER_LIST_MAX_ROWS));
}
/** 翻页:游标是页码,回填下一页。 */
@Test
void queryAdvancesCursorWhenNotLastPage() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":false,"
+ "\"numberOfElements\":1,\"number\":0,\"content\":["
+ "{\"orderId\":1,\"orderNo\":\"OB-1\",\"orderStatusEnum\":\"picked\"}]}}"));
Page<OutboundOrder> page = adapter(transport).query(ctx(),
OutboundQuery.builder().outboundRequestNo("OB-1").pageSize(1).build());
assertTrue(page.hasMore());
assertEquals("2", page.nextCursor());
}
/** 空页不是错误。 */
@Test
void queryEmptyPageIsNotAnError() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":true,"
+ "\"numberOfElements\":0,\"content\":[]}}"));
Page<OutboundOrder> page = adapter(transport).query(ctx(),
OutboundQuery.builder().outboundRequestNo("OB-1").build());
assertTrue(page.items().isEmpty());
}
// ================================================================ 包裹
@Test
void packagesComeFromDetail() {
List<PackageResult> packages = adapter(detail())
.packages(ctx(), OutboundRef.ofRequestNo("OB-2026-0001"));
assertEquals(1, packages.size());
PackageResult pkg = packages.get(0);
assertEquals("788676678675", pkg.trackingNumber());
assertEquals("FEDXG", pkg.carrier());
assertEquals("P6121A51", pkg.erpSku());
assertEquals(2, pkg.shippedQuantity());
assertEquals(Instant.parse("2026-11-11T03:00:05Z"), pkg.shippedAt());
assertEquals(12.5, pkg.cost().amount().doubleValue(), 0.0001);
}
/** 同一个 trackingNo 同时以「实际包裹」和「面单信息」出现时只保留一条。 */
@Test
void packagesAreDeduplicatedByTrackingNo() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-1\","
+ "\"shipmentPackages\":["
+ "{\"trackingNo\":\"T1\",\"packageFlag\":0,\"shipedQuantity\":1},"
+ "{\"trackingNo\":\"T1\",\"packageFlag\":1}]}}"));
List<PackageResult> packages = adapter(transport).packages(ctx(),
OutboundRef.ofRequestNo("OB-1"));
assertEquals(1, packages.size());
assertEquals(1, packages.get(0).shippedQuantity(), "实际包裹优先,不能被面单行顶掉");
}
// ================================================================ 取消预判
@Test
void checkCancelIsBlockedForShippedOrder() {
assertEquals(CancelEligibility.BLOCKED,
adapter(detail()).checkCancel(ctx(), OutboundRef.ofRequestNo("OB-2026-0001")));
}
@Test
void checkCancelIsFreeForUnshippedOrder() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-1\","
+ "\"orderStatusEnum\":\"unshipped\"}}"));
assertEquals(CancelEligibility.FREE,
adapter(transport).checkCancel(ctx(), OutboundRef.ofRequestNo("OB-1")));
}
/** 查不到单时判 BLOCKED:猜成 FREE 会发出注定被拒的取消。 */
@Test
void checkCancelIsBlockedWhenOrderNotFound() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(
"{\"code\":200,\"message\":\"未找到\"}"));
assertEquals(CancelEligibility.BLOCKED,
adapter(transport).checkCancel(ctx(), OutboundRef.ofRequestNo("OB-NONE")));
}
@Test
void cancelledAndRefundedAreBlocked() {
for (String raw : new String[]{"canceled", "refunded"}) {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-1\","
+ "\"orderStatusEnum\":\"" + raw + "\"}}"));
assertEquals(CancelEligibility.BLOCKED,
adapter(transport).checkCancel(ctx(), OutboundRef.ofRequestNo("OB-1")), raw);
}
}
// ================================================================ 枚举
/** 文档里的每个值都要映射对;UNSHIPPED 不能被当成 SHIPPED。 */
@Test
void allDocumentedStatusesMap() {
assertEquals(OutboundStatus.CREATED, HengjianOrderStatus.toCore("pending"));
assertEquals(OutboundStatus.SUBMITTED, HengjianOrderStatus.toCore("unshipped"));
assertEquals(OutboundStatus.ACCEPTED, HengjianOrderStatus.toCore("approved"));
assertEquals(OutboundStatus.ACCEPTED, HengjianOrderStatus.toCore("assigned"));
assertEquals(OutboundStatus.PICKING, HengjianOrderStatus.toCore("picked"));
assertEquals(OutboundStatus.SHIPPED, HengjianOrderStatus.toCore("shipped"));
assertEquals(OutboundStatus.CANCELLED, HengjianOrderStatus.toCore("canceled"));
assertEquals(OutboundStatus.REFUNDED, HengjianOrderStatus.toCore("refunded"));
}
/** 精确匹配:UNSHIPPED 绝不能被判成已交运。 */
@Test
void unshippedIsNotShipped() {
assertEquals(OutboundStatus.SUBMITTED, HengjianOrderStatus.toCore("unshipped"));
assertEquals(OutboundStatus.SUBMITTED, HengjianOrderStatus.toCore("UNSHIPPED"));
}
@Test
void unknownStatusIsNotGuessed() {
assertEquals(OutboundStatus.UNKNOWN, HengjianOrderStatus.toCore("returned"));
assertEquals(OutboundStatus.UNKNOWN, HengjianOrderStatus.toCore(null));
assertEquals(HengjianOrderStatus.UNKNOWN, HengjianOrderStatus.of(""));
}
}

76
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java

@ -5,8 +5,13 @@ import common.ecommerce.hengjian.adapter.HengjianAdapter; @@ -5,8 +5,13 @@ import common.ecommerce.hengjian.adapter.HengjianAdapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -145,4 +150,75 @@ class HengjianReadOnlyProbeTest { @@ -145,4 +150,75 @@ class HengjianReadOnlyProbeTest {
}
});
}
/** 订单详情:只按来源单号查,需要 {@code -Dhengjian.probe.orderNo}。 */
@Test
void probeOrderDetail() {
assumeToken();
final String orderNo = opt("hengjian.probe.orderNo", "");
Assumptions.assumeTrue(!orderNo.isEmpty(),
"未提供 -Dhengjian.probe.orderNo,跳过订单详情探针");
run("POST /v1/saleOrder/findOne", new Runnable() {
@Override
public void run() {
OutboundOrder order = adapter().get(ctx(), OutboundRef.ofRequestNo(orderNo));
if (order == null) {
System.out.println(" [空] 未找到该单");
return;
}
System.out.println(" status=" + order.status()
+ " rawStatus=" + order.rawStatus()
+ " providerOrderId=" + order.providerOrderId()
+ " tracking=" + order.trackingNumber()
+ " paidAt=" + order.paidAt()
+ " shippedAt=" + order.shippedAt()
+ " fee=" + order.estimatedShippingFee());
System.out.println(" 行数=" + order.lines().size()
+ " 附件数=" + order.attachments().size()
+ " exception=" + order.exceptionCode());
for (OutboundLine line : order.lines()) {
System.out.println(" line sku=" + line.providerSku()
+ " qty=" + line.quantity()
+ " total=" + line.totalAmount());
}
}
});
}
/**
* 订单列表:按时间窗查,核对分页结构与 {@code orderId} 是否真回。
*
* <p>需要 {@code -Dhengjian.probe.begin=yyyy-MM-dd} 与 {@code -Dhengjian.probe.end=yyyy-MM-dd},
* 跨度不超过 30 天。</p>
*/
@Test
void probeOrderList() {
assumeToken();
final String begin = opt("hengjian.probe.begin", "");
final String end = opt("hengjian.probe.end", "");
Assumptions.assumeTrue(!begin.isEmpty() && !end.isEmpty(),
"未提供 -Dhengjian.probe.begin / end,跳过订单列表探针");
run("GET /v1/saleOrder/findByPage", new Runnable() {
@Override
public void run() {
OutboundQuery query = OutboundQuery.builder()
.after(java.time.LocalDate.parse(begin)
.atStartOfDay(java.time.ZoneOffset.UTC).toInstant())
.before(java.time.LocalDate.parse(end)
.atTime(23, 59, 59).toInstant(java.time.ZoneOffset.UTC))
.pageSize(10)
.build();
Page<OutboundOrder> page = adapter().query(ctx(), query);
System.out.println(" 本页 " + page.size() + " 条, 有下一页=" + page.hasMore()
+ ", 游标=" + page.nextCursor());
for (OutboundOrder order : page.items()) {
System.out.println(" orderNo=" + order.outboundRequestNo()
+ " orderId=" + order.providerOrderId()
+ " status=" + order.rawStatus()
+ " carrier=" + order.carrierCode()
+ " shippedAt=" + order.shippedAt());
}
}
});
}
}

Loading…
Cancel
Save