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 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 params = new LinkedHashMap(); + 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 orders = new ArrayList(); + 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)); } + /** + * 取消资格预判:查详情按状态推断。 + * + *

恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款不再接受取消, + * 判为 {@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 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(); + } + HengjianOrderDetailDtos.OrderDetail detail = + json.fromJson(data.toString(), HengjianOrderDetailDtos.OrderDetail.class); + return toPackages(detail, orderNo); + } + + /** 实际包裹优先、按 trackingNo 去重;没有 trackingNo 时用 SKU 作键。 */ + private static List toPackages(HengjianOrderDetailDtos.OrderDetail detail, String orderNo) { + List out = new ArrayList(); + if (detail.shipmentPackages == null || detail.shipmentPackages.isEmpty()) { + return out; + } + java.util.Set seen = new java.util.LinkedHashSet(); + // 两遍:先实际包裹,再面单信息行 + 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()); + } + + /** + * 时间窗转恒健的日期参数。 + * + *

恒健收的是 UTC 日期({@code yyyy-MM-dd}),不是时间戳;跨度不超过 + * {@link HengjianConstants#ORDER_LIST_MAX_DAYS} 天。用「起止都含当天」的口径, + * 所以计算跨度时把 end 当天算进去。

+ */ + private void addDateRange(WarehouseContext ctx, Map 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; } /** diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOrderMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOrderMapper.java new file mode 100644 index 0000000..8cfa077 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOrderMapper.java @@ -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; + +/** + * 恒健订单报文 → 统一模型(详情 / 列表共用)。 + * + *

两个接口回的字段高度重合,行模型也一致;差异只在 + * {@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 outboundRequestNo} = {@code orderNo};
  • + *
  • {@code providerOrderId} = {@code orderId}(详情查不到时为 null,不编);
  • + *
  • {@code orderRef} 恒为 null——恒健不回传平台单号。
  • + *
+ */ +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(); + } + + // ================================================================ 列表 + + /** + * 列表行 → 统一出库单。 + * + *

列表比详情多出 {@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 toDetailLines(List items) { + List out = new ArrayList(); + 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 toListLines(List items) { + List out = new ArrayList(); + 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 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 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(); + } + + // ================================================================ 其它 + + /** + * 收件地址。 + * + *

恒健没有邮箱字段;电话在文档示例里带多余空格与分机,文档没说格式, + * 原样保留,不猜着清洗。整组都为空时返回 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 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 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 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 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; + } + + /** + * 订单号。 + * + *

{@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 estimatedShippingFeeItems; + + /** + * 异常码:{@code unexception} 表示无异常,其余见文档 + * ({@code pickingException} / {@code addressException} / {@code trackingException} 等)。 + */ + @JsonProperty("errorCode") + public String errorCode; + + /** 产品行。 */ + @JsonProperty("productItems") + public List productItems; + + /** 附件。 */ + @JsonProperty("enclosure") + public List enclosure; + + /** 发货信息。 */ + @JsonProperty("shipmentPackages") + public List 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; + /** 销售金额;是行总额(与下单接口的 skuAmount 同语义)。 */ + @JsonProperty("skuAmount") + public Double skuAmount; + /** 投保金额;不保价为 0。 */ + @JsonProperty("insureAmount") + public Double insureAmount; + } + + /** 附件。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Enclosure { + /** + * 附件类型。 + * + *

详情页标 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 orderId}——取消接口需要它,所以「按单号查列表」是补 + * {@code orderId} 的正规途径;
  • + *
  • 列表多回 {@code channelFlag} / {@code amount},产品行多回 {@code taxPrice};
  • + *
  • 列表的 {@code enclosure[].type} 文档标 INTEGER,详情页标 STRING(示例是 + * {@code "Shippinglabel"});这里按 String 读,Jackson 会把数字也转成文本。
  • + *
+ */ +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; + } + + /** + * 分页数据。 + * + *

{@code number} 是0 基页码(示例里请求第 1 页返回 {@code number: 0}), + * 翻页要用它 + 1 反过来推。

+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class PageData { + + @JsonProperty("content") + public List content; + + /** 总记录数。 */ + @JsonProperty("totalElements") + public Integer totalElements; + + /** 总页数。 */ + @JsonProperty("totalPages") + public Integer totalPages; + + /** 当前页记录数。 */ + @JsonProperty("numberOfElements") + public Integer numberOfElements; + + /** 当前页码,0 基。 */ + @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 productItems; + + @JsonProperty("enclosure") + public List enclosure; + + @JsonProperty("shipmentPackages") + public List 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; + } + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianOrderStatus.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianOrderStatus.java new file mode 100644 index 0000000..6aa50a0 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/HengjianOrderStatus.java @@ -0,0 +1,86 @@ +package common.ecommerce.hengjian.enums; + +import common.ecommerce.warehouse.enums.OutboundStatus; + +/** + * 恒健出库订单状态({@code orderStatusEnum},详情与列表接口共用)。 + * + *

码表来自《获取订单的详细信息》与《订单--查询列表》两页文档: + * {@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 建:

* *
    @@ -11,8 +14,7 @@ *
  • 用完的原值同时写进模型的 {@code rawStatus}。
  • *
* - *

恒健已知的状态字段:{@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 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:这是取消接口需要的内��� 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 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 page = adapter(transport).query(ctx(), + OutboundQuery.builder().outboundRequestNo("OB-1").build()); + + assertTrue(page.items().isEmpty()); + } + + // ================================================================ 包裹 + + @Test + void packagesComeFromDetail() { + List 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 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("")); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java index 9c95189..053ecc5 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java @@ -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 { } }); } + + /** 订单详情:只按来源单号查,需要 {@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} 是否真回。 + * + *

需要 {@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 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()); + } + } + }); + } }