diff --git a/README.md b/README.md index b7b2b92..0b57429 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ sequenceDiagram | `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 | | `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) | | `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) | -| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单) | +| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单 / 订单详情与列表) | 依赖方向: ``` @@ -376,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 # 单模块 mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试 mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 商品 / 下单 / 转运 -mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 渠道 / 商品保存 / 出库下单 +mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 渠道 / 商品 / 下单 / 订单查询 ``` --- diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 3bae611..007d0f2 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -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 @@ | 接口 | 路径 | 状态 | |---|---|---| | 创建销售发货单(中文页「带附件」/ 英文页 "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/ ├── 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/ ├── 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 \ ``` - 默认跳过;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 \ | 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。 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java index 2dfba69..1bac0e7 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java @@ -52,6 +52,13 @@ public enum OutboundStatus { OUT_OF_STOCK(160, "缺货", 15), /** 已删除(信仓订单 {@code state=10})。 */ DELETED(170, "已删除", 16), + /** + * 已退款(恒健 {@code orderStatusEnum=refunded})。 + * + *
与「已取消」不是一回事:取消是订单作废,退款是订单已履约后的资金退回, + * 不能合并——合并后就分不出「这单有没有发出去」。
+ */ + REFUNDED(180, "已退款", 17), /** 无法识别;原值见 {@code rawStatus},不参与 rank 比较。 */ UNKNOWN(0, "未知", -1); diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java index c76af70..3887f0b 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java @@ -67,6 +67,42 @@ public final class HengjianConstants { */ public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create"; + /** + * 订单详情。 + * + *只按{@code orderNo}(来源单号)查,响应不回 {@code orderId}。
+ */ + public static final String PATH_ORDER_FIND_ONE = "/v1/saleOrder/findOne"; + + /** + * 订单列表(分页)。 + * + *{@code GET},时间、订单号、订单 id 三者必填其一;时间跨度不超过 30 天。 + * 是唯一会回 {@code orderId} 的查询接口。
+ */ + public static final String PATH_ORDER_FIND_BY_PAGE = "/v1/saleOrder/findByPage"; + + /** + * 列表接口的排序字段。 + * + *文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc}; + * 两个都是必填。
+ */ + public static final String ORDER_LIST_SIDX = "id"; + /** 列表接口的排序方向。 */ + public static final String ORDER_LIST_SORT = "desc"; + + /** + * 列表接口的时间跨度上限(天)。 + * + *文档:{@code beginDateTime} 与 {@code endDateTime} 的跨度不要超过 30 天。 + * 超过时适配器在本地拒绝,不把必然被拒的请求发出去。
+ */ + 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; diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java index 9cebeae..9228e1e 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java @@ -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; 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 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 resp.message); } - /** 恒健出库查询尚未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */ + /** + * 查订单详情({@code POST /v1/saleOrder/findOne})。 + * + *恒健只按来源单号查。统一引用里的 {@code outboundRequestNo} 就是来源单号; + * {@code providerOrderId} 是仓内部数字 id,这个接口查不了,所以拿来当兜底 + * (调用方只给了 id 时照样发出去,仓方会查不到,由仓方报错而不是我们静默返回 null)。
+ * + *查不到({@code data} 为空)返回 null——与其它仓一致,调用方据此判断「没有这单」。
+ */ @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})。 + * + *恒健要求「时间、订单号、订单 id 三者必填其一」,所以:
+ *时间跨度上限 30 天,超过也在本地拒绝。
+ * + *{@code orderRef}(平台单号)恒健没有对应查询参数,不参与查询; + * {@code statuses} 恒健列表也没有状态过滤参数,传了就拒绝——静默忽略会让调用方 + * 以为过滤生效了。
+ */ @Override public Page恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款不再接受取消, + * 判为 {@link CancelEligibility#BLOCKED};其余交给取消时仓方判定。
+ * + *查不到单时返回 BLOCKED,不猜 FREE——猜错会下发出一个注定被拒的取消。
+ */ @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 throw unsupportedOutbound("warehouse.outbound.cancel", ctx); } + /** + * 包裹列表:从详情的 {@code shipmentPackages} 提取。 + * + *恒健没有独立的包裹接口,发货信息就在详情报文里。按 {@code trackingNo} 去重 + * (同一包裹可能同时以「实际包裹」和「面单信息」两行出现),实际包裹 + * ({@code packageFlag=0})优先。
+ */ @Override public List恒健收的是 UTC 日期({@code yyyy-MM-dd}),不是时间戳;跨度不超过 + * {@link HengjianConstants#ORDER_LIST_MAX_DAYS} 天。用「起止都含当天」的口径, + * 所以计算跨度时把 end 当天算进去。
+ */ + private void addDateRange(WarehouseContext ctx, Map两个接口回的字段高度重合,行模型也一致;差异只在 + * {@code orderId} / {@code channelFlag} / {@code amount} / {@code taxPrice} + * (列表独有)与 {@code estimatedShippingFeeItems}(详情独有)。
+ * + *恒健声明时间字段是 utc 的 {@code yyyy-MM-dd HH:mm:ss},这里按 UTC 解析, + * 不用 {@code WarehouseContext.zone()}——那个时区是给「仓方回传的无时区本地时间」用的, + * 而恒健已经明确是 UTC。
+ * + *详情只回 {@code orderNo}(我们的来源单号),列表才回 {@code orderId}。 + * 所以:
+ *列表比详情多出 {@code orderId},所以这里的 {@code providerOrderId} 有值; + * 但列表没有预估费用明细,需要完整信息时还是要按单号再查一次详情。
+ */ + 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(); + } + + // ================================================================ 行 + + /** + * 产品行(详情)。 + * + *{@code skuAmount} 在恒健是行总额(不是单价),落 + * {@link OutboundLine#totalAmount()};恒健不回申报单价,所以 + * {@code declareValue} 留空,避免把总额当单价再乘一次。
+ * + *数量缺失或非正的行直接跳过:{@link OutboundLine} 要求数量为正, + * 保留会在构造期抛异常,把「一条坏数据」放大成「整单查不出来」。
+ */ + static List恒健没有邮箱字段;电话在文档示例里带多余空格与分机,文档没说格式, + * 原样保留,不猜着清洗。整组都为空时返回 null, + * 避免把「空地址」当成真实地址回传给业务。
+ */ + 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{@link OutboundOrder} 要求 {@code outboundRequestNo} 非空,恒健的回包理论上 + * 一定带 {@code orderNo};不带说明报文结构变了,直接抛而不是造一个空单。
+ */ + 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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderDetailDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderDetailDtos.java new file mode 100644 index 0000000..8abe7be --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderDetailDtos.java @@ -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})。 + * + *请求只有 {@code orderNo}。响应没有 {@code orderId}——那是列表接口才回的字段, + * 所以按详情查回来的单拿不到仓内部 id,取消时要用的话得靠列表接口补。
+ */ +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; + } + + /** + * 订单详情。 + * + *字段名照抄文档。注意 {@code estimatedShippingFeeItems} 是预估费用明细 + * (Basic Rate / Residential / Fuel Surcharge 等),与 {@code estimatedShippingFee} + * 是同一份钱的不同粒度,不要累加。
+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderDetail { + + /** 订单号(来源单号)。 */ + @JsonProperty("orderNo") + public String orderNo; + + /** + * 支付时间,{@code yyyy-MM-dd HH:mm:ss}。 + * + *文档没写时区;创建接口的 {@code paidAt} 注明是 utc,这里**按 UTC 解析**, + * 待真机核对。
+ */ + @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详情页标 STRING、列表页标 INTEGER,示例给的是 {@code "Shippinglabel"}; + * 按 String 读,两种形态都能接住。
+ */ + @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; + } + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderListDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderListDtos.java new file mode 100644 index 0000000..84bbdfe --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderListDtos.java @@ -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})。 + * + *与详情接口的差异(真机 / 文档双确认):
+ *{@code number} 是0 基页码(示例里请求第 1 页返回 {@code number: 0}), + * 翻页要用它 + 1 反过来推。
+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class PageData { + + @JsonProperty("content") + public List码表来自《获取订单的详细信息》与《订单--查询列表》两页文档: + * {@code pending} 未支付 / {@code unshipped} 未发货 / {@code approved} 已审核 / + * {@code assigned} 已分配 / {@code picked} 已配货 / {@code shipped} 已发货 / + * {@code canceled} 已取消 / {@code refunded} 已退款。
+ * + *与运去哪同名不是巧合也不是同源:两家都是美国仓、同一套英文词, + * 但码值集合与后续扩展各自独立,必须各建一套枚举,不能互相引用。
+ * + *按完整值精确匹配。历史教训:用 {@code contains("SHIP")} 会把 + * {@code UNSHIPPED}(未发货)判成 {@code SHIPPED}(已交运),下游据此认为货已发出、 + * 取消被直接锁死。认不出的归 {@link #UNKNOWN},不猜;原值同时写进 + * {@code OutboundOrder.rawStatus}。
+ */ +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; + } + + /** + * 恒健原始值 → 平台枚举。精确匹配(只忽略大小写与首尾空白)。 + * + *空值、未收录的取值都返回 {@link #UNKNOWN}。
+ */ + 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(); + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java index 8c11ebe..31e0819 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java @@ -1,7 +1,10 @@ /** - * 恒健平台枚举(本期尚未建立)。 + * 恒健平台枚举:仓方原始码 + {@code toCore()} 映射到底层枚举。 * - *只读基础资料阶段没有状态码。接入出库 / 库存 / 退货时按 + *
已建:{@link common.ecommerce.hengjian.enums.HengjianOrderStatus} + * (订单 {@code orderStatusEnum})。
+ * + *后续接入库存 / 退货 / 转运时按 * {@code docs-warehouse/onboarding-checklist.md} 阶段 2.6 建:
* *恒健已知的状态字段:{@code /v1/saleOrder/findByPage} 的 {@code orderStatusEnum} - * 取值为 {@code pending / unshipped / approved / assigned / picked / shipped / - * canceled / refunded}——注意与运去哪同名,但那是巧合,两套码表各建各的。
+ *恒健的 {@code orderStatusEnum} 与运去哪同名(都是英文词),但那是巧合, + * 两套码表各建各的,不能互相引用。
*/ package common.ecommerce.hengjian.enums; diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java index a0921e6..c2ceae5 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java @@ -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())); } /** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */ diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java new file mode 100644 index 0000000..af9a3fb --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java @@ -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需要 {@code -Dhengjian.probe.begin=yyyy-MM-dd} 与 {@code -Dhengjian.probe.end=yyyy-MM-dd}, + * 跨度不超过 30 天。
+ */ + @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