From 1c3a99a8c60605a28c043c2299f3c0367f805d2e Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Mon, 16 Nov 2026 10:30:30 +0800 Subject: [PATCH] =?UTF-8?q?feat(hengjian):=20=E5=AF=B9=E6=8E=A5=E4=BB=93?= =?UTF-8?q?=E5=82=A8=E8=B4=B9=20/=20=E5=B0=BE=E7=A8=8B=E8=B4=B9=20/=20?= =?UTF-8?q?=E4=BD=9C=E4=B8=9A=E8=B4=B9=E4=B8=89=E4=B8=AA=E8=AE=A1=E8=B4=B9?= =?UTF-8?q?=E6=98=8E=E7=BB=86=E6=8E=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增三个 DTO + HengjianFeeMapper,实现 WarehouseFeeCapable.settlements, 声明 FEE_SETTLEMENT - 三个接口行结构不同、统一方法只有一个返回类型,因此必须由 FeeQuery.costType 指定查哪一类;不指定即拒绝,不「三个都查再合并」—— 合并会让调用方误以为拿到完整账单 - VALUE_ADDED(增值服务费)恒健无对应接口,显式拒绝 - 过滤条件全空时本地拒绝(等于拉全量账单);金额缺失的行跳过而非记 0 元 - 费用类型由接口决定,不靠 settlementName 猜(作业费名形如「退货入库->入库费->…」) - FeeQuery 补分页(pageCursor / pageSize)与 toBuilder:三个接口都是分页的, 原来返回 List 不带游标,调用方无法翻页 - 只读探针补计费用例(-Dhengjian.probe.feeType=STORAGE|LAST_MILE|OPERATION) 真机确认三个路径均存在(无 token 时返回对应的 Unauthorized 文案)。 验证:mvn test 全量通过,恒健 149 个用例 + 4 个探针跳过。 Co-Authored-By: Claude Code --- README.md | 12 +- docs-warehouse/hengjian/README.md | 66 +++- .../common/ecommerce/warehouse/model/FeeQuery.java | 57 ++++ .../ecommerce/hengjian/HengjianConstants.java | 29 ++ .../hengjian/adapter/HengjianAdapter.java | 140 ++++++++- .../hengjian/adapter/HengjianFeeMapper.java | 279 +++++++++++++++++ .../hengjian/dto/HengjianOperationFeeDtos.java | 214 +++++++++++++ .../hengjian/dto/HengjianStorageFeeDtos.java | 202 ++++++++++++ .../hengjian/dto/HengjianTailDeliveryFeeDtos.java | 225 ++++++++++++++ .../hengjian/adapter/HengjianFeeTest.java | 346 +++++++++++++++++++++ .../hengjian/probe/HengjianReadOnlyProbeTest.java | 57 ++++ 11 files changed, 1615 insertions(+), 12 deletions(-) create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOperationFeeDtos.java create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianStorageFeeDtos.java create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTailDeliveryFeeDtos.java create mode 100644 warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java diff --git a/README.md b/README.md index ae770b1..6b6b558 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,15 +376,17 @@ common.ecommerce │ └── hengjian 恒健三方仓(warehouse-sdk-hengjian) ├── HengjianConstants 测试基址、当前接入路径、双授权头名、成功码 / 未授权码、限流 - ├── adapter HengjianAdapter(目录 + 渠道 + 商品 + 出库全链路 + 物流异动单)/ + ├── adapter HengjianAdapter(目录 + 渠道 + 商品 + 出库全链路 + 异动单 + 计费明细)/ │ HengjianAdapterFactory / HengjianDirectoryMapper / │ HengjianProductMapper / HengjianOutboundMapper / - │ HengjianOrderMapper / HengjianTrackingChangeMapper + │ HengjianOrderMapper / HengjianTrackingChangeMapper / + │ HengjianFeeMapper ├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos / │ HengjianProductSaveDtos / HengjianCreateOrderDtos / │ HengjianOrderDetailDtos / HengjianOrderListDtos / │ HengjianCancelOrderDtos / HengjianTrackingChangeDtos / - │ HengjianTrackingChangeQueryDtos + │ HengjianTrackingChangeQueryDtos / HengjianStorageFeeDtos / + │ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos ├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus); │ 其余状态枚举约定见 package-info,待建 ├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter @@ -1081,7 +1083,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 6c9bf31..0e0b89e 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -70,7 +70,10 @@ | 8 | 订单取消 | `POST /v1/saleOrder/cancel` | `OUTBOUND` | ✅ | | 9 | 物流异动单创建 | `POST /v1/trackingChange/create` | `TRACKING_CHANGE` | ✅ | | 10 | 物流异动单查询 | `POST /v1/trackingChange/findOrder` | `TRACKING_CHANGE` | ✅ | -| 11 | 回调 | — | — | ❌ 文档无回调页 | +| 11 | 仓储费明细 | `POST /v1/chargingSettlement/getChargingStorageSettlement` | `FEE_SETTLEMENT` | ✅ | +| 12 | 尾程配送费明细 | `POST /v1/chargingSettlement/getChargingTailDeliverySettlement` | `FEE_SETTLEMENT` | ✅ | +| 13 | 作业费明细 | `POST /v1/chargingSettlement/getChargingOperationSettlement` | `FEE_SETTLEMENT` | ✅ | +| 14 | 回调 | — | — | ❌ 文档无回调页 | 前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, @@ -345,14 +348,57 @@ 入库计划创建 / 列表 / 查询 / 取消 / 加附件 / 上传附件 / 发运 / 更新到仓日期 / 生成箱标, 预约单创建 / 修改 / 取消 / 信息查询 / 日期查询。路径以 `/v1/inbound/...`、`/v3/booking_order/...` 为主。 -### 调拨 / 退货 / 销毁 / 计费 / 测算 +### 计费明细(`FEE_SETTLEMENT`)—— 已接入 + +恒健把三类费用拆成三个独立接口,行字段完全不同: + +| `FeeQuery.costType` | 接口 | 行特征 | +|---|---|---| +| `STORAGE` | `getChargingStorageSettlement` | 批次 / 库存类型 / 存储天数 / 计费量(CBM) | +| `LAST_MILE` | `getChargingTailDeliverySettlement` | 承运商 / 物流产品 / 计费重 / 分区 / 跟踪号 | +| `OPERATION` | `getChargingOperationSettlement` | 五级费用分类 / 计费阈值 / 箱数 | + +**必须用 `costType` 指定查哪一类**:统一模型只有一个 `settlements()`,而三类接口的 +返回结构不同。不指定就**拒绝**,而不是「三个都查再合并」——合并会让调用方以为 +拿到完整账单,实际只覆盖了一部分。`VALUE_ADDED`(增值服务费)恒健没有独立接口,显式拒绝。 + +**请求**(三个接口一致):`orgWarehouseCodes` / `relOrderNos` / `sourceNos` / +`btChargeAt` 可选,`page` / `size` 必填。 + +| 统一模型 | 恒健 | +|---|---| +| `billingTransNo` | `relOrderNos`(计费单号) | +| `saleOrderNo` / `externalOrderNo` | `sourceNos`(来源单号,两者都当来源单号,重复只发一个) | +| `settledAfter/Before` 或 `snapshotDateRange` | `btChargeAt`,格式 `yyyy-MM-dd ~ yyyy-MM-dd` | +| 账户仓代码 | 自动带上 `orgWarehouseCodes`,避免跨仓混账 | + +- **一条过滤条件都没有时本地拒绝**:等于拉全量账单。 +- **分页**:统一方法返回 `List`、不带游标,翻页靠 + `query.toBuilder().pageCursor("2").build()`。判末页的约定是 + **返回条数 < 本次请求的 `pageSize`**。`size` 未给时默认 100,超过 200 截断 + (文档没写上限,取保守值)。 +- **状态口径**:三项都是账单明细(带 `billNo`),是已发生账目, + 不是预估 → `estimated(false)`。 +- **金额**:`cost` 是该行总费用,不是单价。`cost` 缺失的行**跳过**, + 不用 0 兜底——0 会让对账金额偏小且查不出是哪行缺的。 +- **费用类型由接口决定**,不靠猜 `settlementName`(作业费的名字形如 + 「退货入库->入库费->…」,靠字符串归类型迟早错)。 +- **单号口径**:仓储费取 `sourceNo`;尾程费按 发货单号 → 来源单号 → 订单号 → 平台单号 + 依次兜底;作业费取 `relOrderNo` → `sourceNo`。`transactionNo` → `serialNumber`, + `billNo` → `documentNo`。 + +**文档问题**:作业费页的标题和链接都写成了「测算费用(接口)」和 +`open-api.ehenglin.com/v2/api/shipping/calculate`(从测算页复制),只有路径与示例是对的。 +另有两处类型不一致:仓储页 `btChargeAt` 是字符串、作业页字段表标 List;尾程页的 +`sourceOrderNo` 中文名也写成「售后单号」。均按示例实现,待真机确认。 + +### 调拨 / 退货 / 销毁 / 测算 | 领域 | 规模 | |---|---| | 调拨 | 创建 / 查询 / 取消 / 上传附件(`/v1/transferPlan/...`) | | 退货 | 旧版 3 个(标「废弃」)+ v2 10 个(`/v1/saleReturn/...`、`/v3/hj_wms/receiptReturn`) | | 销毁 | 创建 / 取消 / 批量查询(`/v2/destroyPlanOrder/...`) | -| 计费 | 尾程配送费 / 仓储费明细 / 作业费账单明细 | | 测算 | 测算费用 `/v2/api/shipping/calculate`、地址属性 `/v2/api/shipping/addressClassification`(⚠ 域名可疑) | ## 4. 代码结构 @@ -370,7 +416,8 @@ warehouse-sdk-hengjian/ │ │ ├── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验 │ │ ├── HengjianOutboundMapper.java 出库下单报文(UTC 时间 / 行总额 / 面单附件) │ │ ├── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型 - │ │ └── HengjianTrackingChangeMapper.java 异动单 → 统一模型 + │ │ ├── HengjianTrackingChangeMapper.java 异动单 → 统一模型 + │ │ └── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射 │ ├── dto/ │ │ ├── HengjianWarehouseDtos.java │ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型 @@ -380,7 +427,10 @@ warehouse-sdk-hengjian/ │ │ ├── HengjianOrderListDtos.java /v1/saleOrder/findByPage │ │ ├── HengjianCancelOrderDtos.java /v1/saleOrder/cancel │ │ ├── HengjianTrackingChangeDtos.java /v1/trackingChange/create - │ │ └── HengjianTrackingChangeQueryDtos.java /v1/trackingChange/findOrder + │ │ ├── HengjianTrackingChangeQueryDtos.java /v1/trackingChange/findOrder + │ │ ├── HengjianStorageFeeDtos.java 仓储费明细 + │ │ ├── HengjianTailDeliveryFeeDtos.java 尾程配送费明细 + │ │ └── HengjianOperationFeeDtos.java 作业费明细 │ ├── enums │ │ ├── HengjianOrderStatus.java orderStatusEnum → OutboundStatus │ │ └── package-info.java 其余状态枚举约定(待建) @@ -396,13 +446,14 @@ warehouse-sdk-hengjian/ ├── adapter/HengjianOrderQueryTest.java 25 个:详情映射 / 列表分页 / 时间窗 / 包裹去重 / 枚举 ├── adapter/HengjianCancelOrderTest.java 10 个:双键补齐 / 精确匹配 / 拒绝路径 / 预判 ├── adapter/HengjianTrackingChangeTest.java 19 个:必填拒绝 / 换址三项 / 路径 / 双状态 + ├── adapter/HengjianFeeTest.java 18 个:三接口路由 / 分页 / 过滤 / 行映射 / 缺金额跳过 ├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举 ├── http/HengjianEnvelopeTest.java 12 个:三种信封形态 + 通用失败码 + 错误路径 ├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性 └── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true ``` -已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(129 个 + 2 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(149 个 + 4 个跳过)。 ## 5. 探针用法 @@ -419,6 +470,9 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ - 默认跳过;token 不入库、只走系统属性。 - 6 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重 / 订单详情 / 订单列表。 异常只打印不中断。 +- 计费明细的只读探针在 `HengjianReadOnlyProbeTest` 之外, + 用 `-Dhengjian.probe.begin=` / `-Dhengjian.probe.end=` 加 `-Dhengjian.probe.feeType=` + (STORAGE / LAST_MILE / OPERATION)指定查哪一类。 - 订单详情需 `-Dhengjian.probe.orderNo=`;订单列表需 `-Dhengjian.probe.begin=` 与 `-Dhengjian.probe.end=` (`yyyy-MM-dd`,跨度 ≤30 天)。没给就跳过对应用例。 - 只读,不建单。 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java index 9a5884a..3be894d 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java @@ -38,6 +38,16 @@ public final class FeeQuery { * 适配器不支持的类型要显式拒绝。

*/ private final common.ecommerce.warehouse.enums.FeeQueryNoType noType; + /** + * 目录分页页码;null 表示适配器按自己的默认值(通常第 1 页)。 + * + *

恒健、易达云这类「账单明细」接口是分页的,一次最多几百条; + * 不分页就会把「只拿到第一页」当成「一共这么多钱」。分页语义与 + * {@code OutboundQuery.cursor} 一样是字符串游标,具体含义由适配器解释。

+ */ + private final String pageCursor; + /** 每页条数;0 表示用适配器默认值。 */ + private final int pageSize; private FeeQuery(Builder b) { if (b.snapshotStartDate != null && b.snapshotEndDate != null @@ -65,6 +75,11 @@ public final class FeeQuery { this.settledAfter = b.settledAfter; this.settledBefore = b.settledBefore; this.noType = b.noType; + this.pageCursor = b.pageCursor; + if (b.pageSize < 0) { + throw new IllegalArgumentException("pageSize must not be negative"); + } + this.pageSize = b.pageSize; } public static Builder builder() { @@ -136,6 +151,34 @@ public final class FeeQuery { return snapshotStartDate != null; } + /** 分页游标;null 表示适配器用自己的默认首页。 */ + public String pageCursor() { + return pageCursor; + } + + /** 每页条数;0 表示用适配器默认值。 */ + public int pageSize() { + return pageSize; + } + + /** 翻页时只改游标。 */ + public Builder toBuilder() { + Builder b = builder() + .saleOrderNo(saleOrderNo) + .billingTransNo(billingTransNo) + .costType(costType) + .providerSku(providerSku) + .externalOrderNo(externalOrderNo) + .noType(noType) + .settledAfter(settledAfter) + .settledBefore(settledBefore) + .pageSize(pageSize); + if (hasDateRange()) { + b.snapshotDateRange(snapshotStartDate, snapshotEndDate); + } + return b.pageCursor(pageCursor); + } + /** 是否给了任何查询条件;全空时适配器应拒绝,避免拉全量。 */ public boolean isEmpty() { return saleOrderNo == null && billingTransNo == null && costType == null @@ -155,6 +198,8 @@ public final class FeeQuery { private java.time.Instant settledAfter; private java.time.Instant settledBefore; private common.ecommerce.warehouse.enums.FeeQueryNoType noType; + private String pageCursor; + private int pageSize; /** 销售订单号;运去哪要求数字单号({@code providerOrderId}),非来源单号。 */ public Builder saleOrderNo(String v) { @@ -206,6 +251,18 @@ public final class FeeQuery { return this; } + /** 分页游标;null 表示第 1 页(适配器解释)。 */ + public Builder pageCursor(String v) { + this.pageCursor = v; + return this; + } + + /** 每页条数;0 表示用适配器默认值。 */ + public Builder pageSize(int v) { + this.pageSize = v; + return this; + } + public FeeQuery build() { return new FeeQuery(this); } 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 938f7f0..b406cca 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 @@ -110,6 +110,35 @@ public final class HengjianConstants { public static final String PATH_TRACKING_CHANGE_FIND = "/v1/trackingChange/findOrder"; /** + * 仓储费明细({@code POST},分页)。 + * + *

三个计费接口的请求结构一致:{@code orgWarehouseCodes} / {@code relOrderNos} / + * {@code sourceNos} / {@code btChargeAt} 都可选,{@code page} / {@code size} 必填。

+ */ + public static final String PATH_FEE_STORAGE = "/v1/chargingSettlement/getChargingStorageSettlement"; + + /** 尾程配送费明细({@code POST},分页)。 */ + public static final String PATH_FEE_TAIL_DELIVERY = + "/v1/chargingSettlement/getChargingTailDeliverySettlement"; + + /** 作业费明细({@code POST},分页)。 */ + public static final String PATH_FEE_OPERATION = + "/v1/chargingSettlement/getChargingOperationSettlement"; + + /** 计费明细默认每页条数;调用方未指定时使用。 */ + public static final int FEE_PAGE_SIZE_DEFAULT = 100; + + /** 计费明细单页上限:文档没写,取常见的 200,超过时截断。 */ + public static final int FEE_PAGE_SIZE_MAX = 200; + + /** + * {@code btChargeAt} 的日期区间分隔符。 + * + *

文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。

+ */ + public static final String FEE_DATE_RANGE_SEPARATOR = " ~ "; + + /** * 列表接口的排序字段。 * *

文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc}; 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 95ad2a4..0f424eb 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 @@ -7,6 +7,9 @@ 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.HengjianOperationFeeDtos; +import common.ecommerce.hengjian.dto.HengjianStorageFeeDtos; +import common.ecommerce.hengjian.dto.HengjianTailDeliveryFeeDtos; import common.ecommerce.hengjian.dto.HengjianProductSaveDtos; import common.ecommerce.hengjian.dto.HengjianTrackingChangeDtos; import common.ecommerce.hengjian.dto.HengjianTrackingChangeQueryDtos; @@ -23,6 +26,7 @@ import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.TrackingChangeCapable; +import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; @@ -30,11 +34,14 @@ import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.enums.TrackingChangeHandleType; import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseFeeType; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; +import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.CancelCommand; import common.ecommerce.warehouse.model.CancelResult; +import common.ecommerce.warehouse.model.FeeQuery; import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundOrder; @@ -68,7 +75,7 @@ import java.util.Map; * {@code WarehouseConnection} 传入。

*/ public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, - WarehouseProductCapable, OutboundCapable, TrackingChangeCapable { + WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable { private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; private static final String OP_CARRIERS = "warehouse.directory.carriers"; @@ -80,6 +87,9 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti private static final String OP_ORDER_CANCEL = "warehouse.outbound.cancel"; private static final String OP_TRACKING_CHANGE_CREATE = "warehouse.tracking.change.create"; private static final String OP_TRACKING_CHANGE_GET = "warehouse.tracking.change.get"; + private static final String OP_FEE_STORAGE = "warehouse.fee.storage"; + private static final String OP_FEE_TAIL_DELIVERY = "warehouse.fee.tailDelivery"; + private static final String OP_FEE_OPERATION = "warehouse.fee.operation"; /** 保存语义没有 create / update 之分,仓方也不回是哪种。 */ private static final String SAVED = "SAVED"; @@ -112,10 +122,138 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti WarehouseCapability.OUTBOUND, WarehouseCapability.PLATFORM_LABEL_DELIVERY, WarehouseCapability.TRACKING_CHANGE, + WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.DIRECTORY, WarehouseCapability.LOGISTICS_PRODUCT); } + // ------------------------------------------------------------------ 计费明细 + + /** + * 拉取计费明细(仓储费 / 尾程费 / 作业费)。 + * + *

恒健把三类费用拆成三个独立接口,行字段各不相同,统一模型只有一个 + * {@code settlements()}。因此必须由调用方用 {@link FeeQuery#costType()} 指定查哪一类:

+ * + * + * + * + * + * + *
costType接口
{@code STORAGE}{@code getChargingStorageSettlement}
{@code LAST_MILE}{@code getChargingTailDeliverySettlement}
{@code OPERATION}{@code getChargingOperationSettlement}
+ * + *

不指定就拒绝而不是「三个都查再合并」:三类费用的行结构不同、金额口径也不同, + * 合并会让调用方以为拿到了一份完整账单,实际少了另外两类。

+ * + *

{@code VALUE_ADDED}(增值服务费)恒健没有对应接口,显式拒绝。

+ * + *

分页

+ *

三个接口都是分页的,统一方法返回 {@code List}、不带游标,所以分页由调用方驱动: + * 用 {@link FeeQuery#toBuilder()}{@code .pageCursor("2")} 翻页。 + * 判末页的约定:返回条数小于本次请求的 {@code pageSize} 即末页 + * (少于请求量说明后面没有了)。

+ */ + @Override + public List settlements(WarehouseContext ctx, FeeQuery query) { + WarehouseFeeType type = query.costType(); + if (type == null) { + throw validation(ctx, OP_FEE_STORAGE, + "hengjian exposes three separate billing APIs; set FeeQuery.costType " + + "(STORAGE / LAST_MILE / OPERATION) to pick one"); + } + switch (type) { + case STORAGE: + return fetchStorageFees(ctx, query); + case LAST_MILE: + return fetchTailDeliveryFees(ctx, query); + case OPERATION: + return fetchOperationFees(ctx, query); + default: + // VALUE_ADDED:恒健没有增值服务费的独立接口 + throw validation(ctx, OP_FEE_STORAGE, + "hengjian has no billing API for fee type " + type); + } + } + + private List fetchStorageFees(WarehouseContext ctx, FeeQuery query) { + HengjianStorageFeeDtos.ListRequest body = new HengjianStorageFeeDtos.ListRequest(); + body.page = HengjianFeeMapper.pageOf(query.pageCursor()); + body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); + body.orgWarehouseCodes = new ArrayList(); + body.relOrderNos = new ArrayList(); + body.sourceNos = new ArrayList(); + body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), + body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); + + String raw = execute(ctx, HengjianConstants.PATH_FEE_STORAGE, body, OP_FEE_STORAGE); + HengjianStorageFeeDtos.ListResponse resp = + json.fromJson(raw, HengjianStorageFeeDtos.ListResponse.class); + if (resp == null || resp.data == null) { + return new ArrayList(); + } + final String warehouseCode = ctx.warehouseCode(); + return HengjianFeeMapper.mapAll(resp.data.content, + new HengjianFeeMapper.RowMapper() { + @Override + public BillingDocument map(HengjianStorageFeeDtos.StorageFeeRow row) { + return HengjianFeeMapper.toDocument(row, warehouseCode); + } + }); + } + + private List fetchTailDeliveryFees(WarehouseContext ctx, FeeQuery query) { + HengjianTailDeliveryFeeDtos.ListRequest body = new HengjianTailDeliveryFeeDtos.ListRequest(); + body.page = HengjianFeeMapper.pageOf(query.pageCursor()); + body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); + body.orgWarehouseCodes = new ArrayList(); + body.relOrderNos = new ArrayList(); + body.sourceNos = new ArrayList(); + body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), + body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); + + String raw = execute(ctx, HengjianConstants.PATH_FEE_TAIL_DELIVERY, body, + OP_FEE_TAIL_DELIVERY); + HengjianTailDeliveryFeeDtos.ListResponse resp = + json.fromJson(raw, HengjianTailDeliveryFeeDtos.ListResponse.class); + if (resp == null || resp.data == null) { + return new ArrayList(); + } + final String warehouseCode = ctx.warehouseCode(); + return HengjianFeeMapper.mapAll(resp.data.content, + new HengjianFeeMapper.RowMapper() { + @Override + public BillingDocument map(HengjianTailDeliveryFeeDtos.TailDeliveryFeeRow row) { + return HengjianFeeMapper.toDocument(row, warehouseCode); + } + }); + } + + private List fetchOperationFees(WarehouseContext ctx, FeeQuery query) { + HengjianOperationFeeDtos.ListRequest body = new HengjianOperationFeeDtos.ListRequest(); + body.page = HengjianFeeMapper.pageOf(query.pageCursor()); + body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); + body.orgWarehouseCodes = new ArrayList(); + body.relOrderNos = new ArrayList(); + body.sourceNos = new ArrayList(); + body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), + body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); + + String raw = execute(ctx, HengjianConstants.PATH_FEE_OPERATION, body, OP_FEE_OPERATION); + HengjianOperationFeeDtos.ListResponse resp = + json.fromJson(raw, HengjianOperationFeeDtos.ListResponse.class); + if (resp == null || resp.data == null) { + return new ArrayList(); + } + final String warehouseCode = ctx.warehouseCode(); + return HengjianFeeMapper.mapAll(resp.data.content, + new HengjianFeeMapper.RowMapper() { + @Override + public BillingDocument map(HengjianOperationFeeDtos.OperationFeeRow row) { + return HengjianFeeMapper.toDocument(row, warehouseCode); + } + }); + } + // ------------------------------------------------------------------ 物流异动单 /** diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java new file mode 100644 index 0000000..237123b --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java @@ -0,0 +1,279 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; +import common.ecommerce.hengjian.dto.HengjianStorageFeeDtos; +import common.ecommerce.hengjian.dto.HengjianTailDeliveryFeeDtos; +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.enums.WarehouseFeeType; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.FeeQuery; + +import java.math.BigDecimal; +import java.time.LocalDate; +import java.time.ZoneOffset; +import java.util.ArrayList; +import java.util.List; + +/** + * 恒健计费明细映射(仓储费 / 尾程费 / 作业费)。 + * + *

三个接口的请求结构一致、行字段完全不同,所以请求构造共用一份, + * 行映射各写一个方法。

+ * + *

口径

+ *
    + *
  • 都是已发生的账单明细,不是预估 → {@code estimated(false)}。 + * 恒健的计费明细来自账单({@code billNo}),不存在「先给预估、后出实际」的两段式。
  • + *
  • 金额单位:{@code cost} 是该行总费用,不是单价。
  • + *
  • 交易号:{@code transactionNo} 是同一计费项多条记录的唯一区分, + * 落 {@link BillingDocument#serialNumber()};{@code billNo} 落 + * {@link BillingDocument#documentNo()}。
  • + *
  • 费用类型由接口决定(仓储 / 尾程 / 作业),不靠猜费用名—— + * 作业费的 {@code settlementName} 形如「退货入库->入库费->…」,靠字符串归类迟早错。
  • + *
+ */ +public final class HengjianFeeMapper { + + /** 币种缺失时的默认值(恒健默认 USD)。 */ + private static final String DEFAULT_CURRENCY = "USD"; + + private HengjianFeeMapper() { + } + + // ================================================================ 请求 + + /** + * 把统一查询条件填进三个计费接口共用的过滤字段。 + * + *

必须有过滤条件:全空等于拉全量账单,这里直接拒绝, + * 不发这种请求。

+ * + *

字段对应关系:

+ * + * + * + * + * + * + * + * + *
{@link FeeQuery}恒健说明
{@code billingTransNo}{@code relOrderNos}计费单号(账单侧的业务单号)
{@code saleOrderNo} / {@code externalOrderNo}{@code sourceNos}来源单号(我们下发的出库单号);两个字段都当来源单号,去重后下发
{@code settledAfter/Before} 或 {@code snapshotDateRange}{@code btChargeAt}{@code yyyy-MM-dd ~ yyyy-MM-dd}
+ * + * @param defaultWarehouseCode 调用方没在 {@code orgWarehouseCodes} 里指定仓时用的兜底仓 + * @return {@code btChargeAt};没有日期条件时为 null + * @throws IllegalArgumentException 一条过滤条件都没有 + */ + public static String applyFilters(FeeQuery query, String defaultWarehouseCode, + List orgWarehouseCodes, + List relOrderNos, + List sourceNos) { + boolean filtered = false; + + String billingNo = trimToNull(query.billingTransNo()); + if (billingNo != null) { + relOrderNos.add(billingNo); + filtered = true; + } + // 两个字段语义都是「业务侧的单号」,都映射到来源单号;重复时只发一个 + String orderNo = trimToNull(firstNonBlank(query.externalOrderNo(), query.saleOrderNo())); + if (orderNo != null) { + sourceNos.add(orderNo); + filtered = true; + } + + String dateRange = null; + if (query.hasSettledRange()) { + dateRange = formatDateRange(query.settledAfter(), query.settledBefore()); + filtered = true; + } else if (query.hasDateRange()) { + dateRange = formatDateRange(query.snapshotStartDate(), query.snapshotEndDate()); + filtered = true; + } + + if (!filtered) { + throw new IllegalArgumentException( + "hengjian billing detail query requires at least one filter " + + "(billingTransNo / saleOrderNo / externalOrderNo / date range); " + + "refusing to pull the whole bill"); + } + + // 仓过滤:没显式给就用账户仓,避免跨仓混账 + String warehouse = trimToNull(defaultWarehouseCode); + if (warehouse != null) { + orgWarehouseCodes.add(warehouse); + } + return dateRange; + } + + /** 日期区间 → {@code "yyyy-MM-dd ~ yyyy-MM-dd"}(UTC 日期)。 */ + static String formatDateRange(java.time.Instant after, java.time.Instant before) { + LocalDate start = after.atZone(ZoneOffset.UTC).toLocalDate(); + LocalDate end = before.atZone(ZoneOffset.UTC).toLocalDate(); + return start + HengjianConstants.FEE_DATE_RANGE_SEPARATOR + end; + } + + /** 日期区间(仅日期版本)。 */ + static String formatDateRange(LocalDate start, LocalDate end) { + return start + HengjianConstants.FEE_DATE_RANGE_SEPARATOR + end; + } + + /** 页码:游标是字符串化的页码,空游标表示第 1 页(恒健入参 1 基)。 */ + static int pageOf(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 billing page cursor must be a page number, got " + v); + } + } + + /** 每页条数:0 用默认值,超过上限截断(文档没写上限,按 200 保守处理)。 */ + static int pageSizeOf(int requested) { + if (requested <= 0) { + return HengjianConstants.FEE_PAGE_SIZE_DEFAULT; + } + return Math.min(requested, HengjianConstants.FEE_PAGE_SIZE_MAX); + } + + // ================================================================ 仓储费 + + /** 仓储费行 → 统一费用单据。 */ + public static BillingDocument toDocument(HengjianStorageFeeDtos.StorageFeeRow row, + String warehouseCode) { + Money amount = moneyOf(row.cost, row.currency); + if (amount == null) { + // 金额缺失的行无法入账:返回 null,由 mapAll 跳过,不用 0 兜底 + return null; + } + return BillingDocument.builder() + .warehouseCode(firstNonBlank(row.orgWarehouseCode, warehouseCode)) + .sourceProvider(WarehouseProvider.HENGJIAN) + .documentNo(trimToNull(row.billNo)) + .serialNumber(trimToNull(row.transactionNo)) + .feeName(trimToNull(row.settlementName)) + .feeType(WarehouseFeeType.STORAGE) + // 账单明细是已发生账目,不是预估 + .estimated(false) + .settledAt(HengjianOrderMapper.parseTime( + firstNonBlank(row.settlementAt, null))) + .amount(amount) + .providerSku(trimToNull(row.sku)) + .saleOrderNo(trimToNull(row.sourceNo)) + .build(); + } + + // ================================================================ 尾程费 + + /** 尾程费行 → 统一费用单据。 */ + public static BillingDocument toDocument(HengjianTailDeliveryFeeDtos.TailDeliveryFeeRow row, + String warehouseCode) { + Money amount = moneyOf(row.cost, row.currency); + if (amount == null) { + return null; + } + return BillingDocument.builder() + .warehouseCode(firstNonBlank(row.orgWarehouseCode, warehouseCode)) + .sourceProvider(WarehouseProvider.HENGJIAN) + .documentNo(trimToNull(row.billNo)) + .serialNumber(trimToNull(row.transactionNo)) + .feeName(trimToNull(row.settlementName)) + .feeType(WarehouseFeeType.LAST_MILE) + .estimated(false) + .settledAt(HengjianOrderMapper.parseTime( + firstNonBlank(row.settlementAt, row.chargeAt))) + .amount(amount) + .providerSku(trimToNull(row.erpSku)) + // 订单号口径:站内单号优先,其次是来源单号,最后平台单号 + .saleOrderNo(firstNonBlank(row.deliveryOrderNo, + firstNonBlank(row.sourceOrderNo, + firstNonBlank(row.orderNo, row.platformOrderNo)))) + .build(); + } + + // ================================================================ 作业费 + + /** 作业费行 → 统一费用单据。 */ + public static BillingDocument toDocument(HengjianOperationFeeDtos.OperationFeeRow row, + String warehouseCode) { + Money amount = moneyOf(row.cost, row.currency); + if (amount == null) { + return null; + } + return BillingDocument.builder() + .warehouseCode(firstNonBlank(row.orgWarehouseCode, warehouseCode)) + .sourceProvider(WarehouseProvider.HENGJIAN) + .documentNo(trimToNull(row.billNo)) + .serialNumber(trimToNull(row.transactionNo)) + .feeName(trimToNull(row.settlementName)) + .feeType(WarehouseFeeType.OPERATION) + .estimated(false) + .settledAt(HengjianOrderMapper.parseTime( + firstNonBlank(row.settlementAt, row.chargeAt))) + .amount(amount) + .providerSku(trimToNull(row.relSku)) + .saleOrderNo(firstNonBlank(row.relOrderNo, row.sourceNo)) + .build(); + } + + // ================================================================ 列表 + + static List mapAll(List rows, RowMapper mapper) { + if (rows == null || rows.isEmpty()) { + return new ArrayList(); + } + List out = new ArrayList(rows.size()); + for (T row : rows) { + if (row == null) { + continue; + } + BillingDocument doc = mapper.map(row); + // 金额缺失的行直接跳过:BillingDocument 要求 amount 非空, + // 用 0 兜底会让对账金额偏小且查不出原因 + if (doc != null && doc.amount() != null) { + out.add(doc); + } + } + return out; + } + + /** 行 → 单据。 */ + interface RowMapper { + BillingDocument map(T row); + } + + // ================================================================ 工具 + + /** + * 金额。 + * + *

恒健三项计费接口的 {@code cost} 都是该行总费用;缺失时返回 + * {@code null}(调用方会跳过该行),不用 0 兜底——0 会让对账金额偏小, + * 而且看不出是哪一行缺了。

+ */ + static Money moneyOf(Double cost, String currency) { + if (cost == null) { + return null; + } + String code = trimToNull(currency); + return Money.of(BigDecimal.valueOf(cost), code == null ? DEFAULT_CURRENCY : code); + } + + static String firstNonBlank(String a, String b) { + String x = trimToNull(a); + return x != null ? x : trimToNull(b); + } + + 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/HengjianOperationFeeDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOperationFeeDtos.java new file mode 100644 index 0000000..aed5862 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOperationFeeDtos.java @@ -0,0 +1,214 @@ +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/chargingSettlement/getChargingOperationSettlement})。 + * + *

文档问题:这一页的标题与链接都写成了「测算费用(接口)」和 + * {@code open-api.ehenglin.com/v2/api/shipping/calculate}(明显是从测算页复制的), + * 只有路径与返回示例是本接口的。以路径与示例为准。

+ * + *

行结构比另两个接口多出五级费用分类(一~五级分类名 + 计费单位 + 计费标识 + + * 计费阈值),是三个接口里分类最细的。

+ */ +public final class HengjianOperationFeeDtos { + + private HengjianOperationFeeDtos() { + } + + /** 请求;三个计费接口结构一致,各自声明一份。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ListRequest { + + /** 仓库 code 列表。 */ + public List orgWarehouseCodes; + /** 计费单号列表。 */ + public List relOrderNos; + /** 来源单号列表。 */ + public List sourceNos; + /** + * 业务发生日期区间,格式 {@code yyyy-MM-dd ~ yyyy-MM-dd}。 + * + *

本页字段表把类型标成 List、示例给的却是字符串;按字符串实现。

+ */ + public String btChargeAt; + /** 页码;必填。 */ + public Integer page; + /** 每页条数;必填。 */ + public Integer size; + } + + /** 响应外层(分页信封)。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ListResponse { + + @JsonProperty("code") + public Integer code; + + @JsonProperty("message") + public String message; + + @JsonProperty("data") + public PageData data; + } + + /** 分页数据。 */ + @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("last") + public Boolean last; + } + + /** 一行作业费。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OperationFeeRow { + + @JsonProperty("orgName") + public String orgName; + @JsonProperty("orgWarehouseCode") + public String orgWarehouseCode; + + @JsonProperty("billNo") + public String billNo; + @JsonProperty("transactionNo") + public String transactionNo; + /** 费用名称,如「退货入库->入库费->销售退货入库费」。 */ + @JsonProperty("settlementName") + public String settlementName; + + /** 一~五级分类名称。 */ + @JsonProperty("firstCategoryName") + public String firstCategoryName; + @JsonProperty("secondCategoryName") + public String secondCategoryName; + @JsonProperty("thirdCategoryName") + public String thirdCategoryName; + @JsonProperty("fourthCategoryName") + public String fourthCategoryName; + @JsonProperty("chargingCategoryName") + public String chargingCategoryName; + + /** 计费单位。 */ + @JsonProperty("categoryUnit") + public String categoryUnit; + /** 计费标识,如「SKU件数」。 */ + @JsonProperty("categoryValueLabel") + public String categoryValueLabel; + /** 计费条件,如「SKU重量(LBS)」;字段表没列,示例里有。 */ + @JsonProperty("categoryLabelCondition") + public String categoryLabelCondition; + /** 计费单据类型,如「退货入库」。 */ + @JsonProperty("categoryOrderType") + public String categoryOrderType; + /** + * 计费阈值。 + * + *

字段表标 STRING、示例给数字 {@code 0};按 String 读,Jackson 会把数字转文本。

+ */ + @JsonProperty("categoryStandardValue") + public String categoryStandardValue; + + @JsonProperty("lineCode") + public String lineCode; + @JsonProperty("lineName") + public String lineName; + + /** 来源单号。 */ + @JsonProperty("sourceNo") + public String sourceNo; + /** 业务单号。 */ + @JsonProperty("relOrderNo") + public String relOrderNo; + /** 平台单号。 */ + @JsonProperty("platformOrderNo") + public String platformOrderNo; + /** 物流追踪号。 */ + @JsonProperty("trackingNo") + public String trackingNo; + /** 箱数。 */ + @JsonProperty("cartonQty") + public Integer cartonQty; + /** 集装箱号。 */ + @JsonProperty("containerNo") + public String containerNo; + /** 来源 SKU。 */ + @JsonProperty("relSku") + public String relSku; + + /** 产品尺寸与重量(字段表没写单位)。 */ + @JsonProperty("height") + public Double height; + @JsonProperty("length") + public Double length; + @JsonProperty("width") + public Double width; + @JsonProperty("weight") + public Double weight; + + /** 数量;字段表没列,示例里有。 */ + @JsonProperty("qty") + public Integer qty; + /** 分类数量;字段表没列,示例里有。 */ + @JsonProperty("categoryQty") + public String categoryQty; + + /** 计费量。 */ + @JsonProperty("count") + public Double count; + /** 计费金额。 */ + @JsonProperty("cost") + public Double cost; + /** 计费币种。 */ + @JsonProperty("currency") + public String currency; + + /** 其他费率;字段表没列,示例里有。 */ + @JsonProperty("otherRate") + public String otherRate; + + @JsonProperty("settleRemark") + public String settleRemark; + @JsonProperty("remark") + public String remark; + + /** 业务计费时间。 */ + @JsonProperty("chargeAt") + public String chargeAt; + /** 明细结算时间。 */ + @JsonProperty("settlementAt") + public String settlementAt; + /** 入账时间。 */ + @JsonProperty("bookAt") + public String bookAt; + + /** 异常信息。 */ + @JsonProperty("errorMessage") + public String errorMessage; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianStorageFeeDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianStorageFeeDtos.java new file mode 100644 index 0000000..d86f2ca --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianStorageFeeDtos.java @@ -0,0 +1,202 @@ +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/chargingSettlement/getChargingStorageSettlement})。 + * + *

三个计费接口(仓储 / 尾程 / 作业)的请求结构与分页信封完全一致, + * 只有行字段不同。按仓库约定「一个接口一个文件」,这里各自声明一份—— + * 分页信封只有几个协议字段,复制比抽象成泛型更省事、也不会有跨接口耦合。

+ */ +public final class HengjianStorageFeeDtos { + + private HengjianStorageFeeDtos() { + } + + /** + * 请求。 + * + *

{@code page} / {@code size} 文档标「必填」;其余过滤条件全可选, + * 但全都不给等于拉全量账单,适配器会拒绝。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ListRequest { + + /** 仓库 code 列表,如 {@code ["EFCA"]}。 */ + public List orgWarehouseCodes; + + /** 计费单号(单据号)列表。 */ + public List relOrderNos; + + /** 来源单号列表(我们下发的出库单号)。 */ + public List sourceNos; + + /** + * 交易时间区间,格式 {@code yyyy-MM-dd ~ yyyy-MM-dd}。 + * + *

类型不一致:仓储页示例里是单个字符串;作业页的字段表标成 List。 + * 按字符串实现——真机只验证过三个路径存在,参数形态待联调确认。

+ */ + public String btChargeAt; + + /** 页码;必填,从 1 开始。 */ + public Integer page; + + /** 每页条数;必填。 */ + public Integer size; + } + + /** 响应外层(分页信封)。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ListResponse { + + @JsonProperty("code") + public Integer code; + + @JsonProperty("message") + public String message; + + @JsonProperty("data") + public PageData data; + } + + /** 分页数据。 */ + @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 基(示例请求第 1 页返回 {@code number: 0})。 */ + @JsonProperty("number") + public Integer number; + + @JsonProperty("size") + public Integer size; + + @JsonProperty("last") + public Boolean last; + } + + /** + * 一行仓储费。 + * + *

仓储费按批次 × 库存类型 × 存储天数区间拆行,一个 SKU 一天可能出多行; + * 对账时按 {@code transactionNo} 区分。

+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class StorageFeeRow { + + /** 组织名称。 */ + @JsonProperty("orgName") + public String orgName; + + /** 仓库 code。 */ + @JsonProperty("orgWarehouseCode") + public String orgWarehouseCode; + + /** 账单编号。 */ + @JsonProperty("billNo") + public String billNo; + + /** 参考交易号;同一计费项的多条记录靠它区分。 */ + @JsonProperty("transactionNo") + public String transactionNo; + + /** 计费项名称,如「不可售库存->存储天数->361字段表里有、示例里没有;按字符串接,缺失即 null。

+ */ + @JsonProperty("settlementAt") + public String settlementAt; + + /** 异常信息。 */ + @JsonProperty("errorMessage") + public String errorMessage; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTailDeliveryFeeDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTailDeliveryFeeDtos.java new file mode 100644 index 0000000..eac6b08 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTailDeliveryFeeDtos.java @@ -0,0 +1,225 @@ +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/chargingSettlement/getChargingTailDeliverySettlement})。 + * + *

行字段与仓储费差异很大:带承运商、物流产品、计费重、分区、跟踪号, + * 以及三个时间(业务计费 / 结算 / 入账)。

+ */ +public final class HengjianTailDeliveryFeeDtos { + + private HengjianTailDeliveryFeeDtos() { + } + + /** + * 请求。 + * + *

三个计费接口的请求结构一致;按「一个接口一个文件」各自声明一份, + * 免得改一家时误伤另两家。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ListRequest { + + /** 仓库 code 列表。 */ + public List orgWarehouseCodes; + /** 计费单号列表。 */ + public List relOrderNos; + /** 来源单号列表。 */ + public List sourceNos; + /** 交易时间区间,格式 {@code yyyy-MM-dd ~ yyyy-MM-dd}。 */ + public String btChargeAt; + /** 页码;必填,从 1 开始。 */ + public Integer page; + /** 每页条数;必填。 */ + public Integer size; + } + + /** 响应外层(分页信封)。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ListResponse { + + @JsonProperty("code") + public Integer code; + + @JsonProperty("message") + public String message; + + @JsonProperty("data") + public PageData data; + } + + /** 分页数据。 */ + @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("last") + public Boolean last; + } + + /** 一行尾程配送费。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class TailDeliveryFeeRow { + + @JsonProperty("orgName") + public String orgName; + @JsonProperty("orgWarehouseCode") + public String orgWarehouseCode; + + /** 账单编号。 */ + @JsonProperty("billNo") + public String billNo; + /** 参考交易号。 */ + @JsonProperty("transactionNo") + public String transactionNo; + /** 计费项名称,如 {@code Basic Rate} / {@code Fuel Surcharge}。 */ + @JsonProperty("settlementName") + public String settlementName; + + @JsonProperty("lineCode") + public String lineCode; + @JsonProperty("lineName") + public String lineName; + + /** 国家 code。 */ + @JsonProperty("regionCode") + public String regionCode; + /** 承运商 code。 */ + @JsonProperty("carrierCode") + public String carrierCode; + /** 承运商服务 code。 */ + @JsonProperty("carrierServiceCode") + public String carrierServiceCode; + /** 物流产品 code。 */ + @JsonProperty("carrierGroupCode") + public String carrierGroupCode; + @JsonProperty("carrierGroupServiceCode") + public String carrierGroupServiceCode; + @JsonProperty("customerCarrierGroupServiceCode") + public String customerCarrierGroupServiceCode; + + /** express prefix。 */ + @JsonProperty("expressTrackingId") + public String expressTrackingId; + @JsonProperty("expressId") + public String expressId; + /** 物流跟踪号。 */ + @JsonProperty("trackingNo") + public String trackingNo; + + /** 包裹尺寸与重量;单位见 {@link #sizeUnit} / {@link #weightUnit}。 */ + @JsonProperty("parcelHeight") + public Integer parcelHeight; + @JsonProperty("parcelLength") + public Integer parcelLength; + @JsonProperty("parcelWidth") + public Integer parcelWidth; + @JsonProperty("parcelWeight") + public Double parcelWeight; + /** 计费重。 */ + @JsonProperty("ratedWeight") + public Integer ratedWeight; + /** 计费分区。 */ + @JsonProperty("zoneCode") + public String zoneCode; + @JsonProperty("sizeUnit") + public String sizeUnit; + @JsonProperty("weightUnit") + public String weightUnit; + + /** 计费量。 */ + @JsonProperty("count") + public Integer count; + /** 燃油费率;未给为 null。 */ + @JsonProperty("fuelRate") + public Double fuelRate; + /** 总费用。 */ + @JsonProperty("cost") + public Double cost; + @JsonProperty("currency") + public String currency; + + /** 渠道类型,如 {@code offline}。 */ + @JsonProperty("channelCategory") + public String channelCategory; + /** 店铺标识。 */ + @JsonProperty("channelFlag") + public String channelFlag; + + /** 发货单号。 */ + @JsonProperty("deliveryOrderNo") + public String deliveryOrderNo; + /** 订单号。 */ + @JsonProperty("orderNo") + public String orderNo; + /** 平台订单号。 */ + @JsonProperty("platformOrderNo") + public String platformOrderNo; + @JsonProperty("poNumber") + public String poNumber; + /** 售后单号。 */ + @JsonProperty("afterSaleOrderNo") + public String afterSaleOrderNo; + /** 来源单号(文档这里的中文名也写成「售后单号」,疑似笔误)。 */ + @JsonProperty("sourceOrderNo") + public String sourceOrderNo; + + @JsonProperty("erpSku") + public String erpSku; + @JsonProperty("sellerSku") + public String sellerSku; + @JsonProperty("thirdAccount") + public String thirdAccount; + + /** 订单发货时间。 */ + @JsonProperty("orderShipTime") + public String orderShipTime; + @JsonProperty("invoiceDate") + public String invoiceDate; + @JsonProperty("shipmentDate") + public String shipmentDate; + /** 发票号。 */ + @JsonProperty("invoiceNo") + public String invoiceNo; + + @JsonProperty("settleRemark") + public String settleRemark; + @JsonProperty("remark") + public String remark; + + /** 业务计费时间。 */ + @JsonProperty("chargeAt") + public String chargeAt; + /** 结算成功时间。 */ + @JsonProperty("settlementAt") + public String settlementAt; + /** 入账时间。 */ + @JsonProperty("bookAt") + public String bookAt; + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java new file mode 100644 index 0000000..fd78c54 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java @@ -0,0 +1,346 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseFeeType; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.FeeQuery; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import org.junit.jupiter.api.Test; + +import java.time.Instant; +import java.time.LocalDate; +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; + +/** + * 计费明细三接口(仓储费 / 尾程费 / 作业费)契约测试。 + */ +class HengjianFeeTest { + + private static final WarehouseContext CTX = WarehouseContext.of( + "HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA", + WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("token-1").build()), + "req-1", java.time.Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC)); + + private static HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + private static RecordingTransport transport(String path, String body) { + return RecordingTransport.create().route(path, req -> Responses.ok(body)); + } + + // ================================================================ 请求形状 + + /** 三个接口路径各不相同,且都用 POST + JSON。 */ + @Test + void eachFeeTypeHitsItsOwnPath() { + String storage = storageBody("1.078272"); + RecordingTransport t1 = transport(HengjianConstants.PATH_FEE_STORAGE, storage); + adapter(t1).settlements(CTX, storageQuery()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/chargingSettlement/getChargingStorageSettlement", + t1.lastDataRequest().url()); + assertEquals("POST", t1.lastDataRequest().method()); + + RecordingTransport t2 = transport(HengjianConstants.PATH_FEE_TAIL_DELIVERY, tailBody("6.95")); + adapter(t2).settlements(CTX, tailQuery()); + assertEquals(HengjianConstants.TEST_BASE_URL + + "/v1/chargingSettlement/getChargingTailDeliverySettlement", + t2.lastDataRequest().url()); + + RecordingTransport t3 = transport(HengjianConstants.PATH_FEE_OPERATION, operationBody("1.0")); + adapter(t3).settlements(CTX, operationQuery()); + assertEquals(HengjianConstants.TEST_BASE_URL + + "/v1/chargingSettlement/getChargingOperationSettlement", + t3.lastDataRequest().url()); + } + + /** 分页参数必填;未指定时用默认值。 */ + @Test + void sendsPagingFields() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0")); + adapter(t).settlements(CTX, storageQuery()); + String body = t.lastDataRequest().body(); + + assertTrue(body.contains("\"page\":1"), body); + assertTrue(body.contains("\"size\":" + HengjianConstants.FEE_PAGE_SIZE_DEFAULT), body); + } + + @Test + void honoursExplicitPaging() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0")); + adapter(t).settlements(CTX, storageQuery().toBuilder().pageCursor("3").pageSize(50).build()); + String body = t.lastDataRequest().body(); + + assertTrue(body.contains("\"page\":3"), body); + assertTrue(body.contains("\"size\":50"), body); + } + + @Test + void clampsPageSizeToMax() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0")); + adapter(t).settlements(CTX, storageQuery().toBuilder().pageSize(9999).build()); + + assertTrue(t.lastDataRequest().body() + .contains("\"size\":" + HengjianConstants.FEE_PAGE_SIZE_MAX)); + } + + /** 单号与日期区间都要映射到对应字段。 */ + @Test + void mapsFiltersToRequest() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0")); + adapter(t).settlements(CTX, FeeQuery.builder() + .costType(WarehouseFeeType.STORAGE) + .billingTransNo("BILL-1") + .saleOrderNo("OB-1") + .settledAfter(Instant.parse("2026-11-01T00:00:00Z")) + .settledBefore(Instant.parse("2026-11-10T00:00:00Z")) + .build()); + String body = t.lastDataRequest().body(); + + assertTrue(body.contains("\"relOrderNos\":[\"BILL-1\"]"), body); + assertTrue(body.contains("\"sourceNos\":[\"OB-1\"]"), body); + assertTrue(body.contains("\"btChargeAt\":\"2026-11-01 ~ 2026-11-10\""), body); + // 账户仓自动带上,避免跨仓混账 + assertTrue(body.contains("\"orgWarehouseCodes\":[\"EFCA\"]"), body); + } + + /** 日期区间只接受日期版式,按 UTC 取日期。 */ + @Test + void usesSnapshotDateRangeWhenSettledAbsent() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0")); + adapter(t).settlements(CTX, FeeQuery.builder() + .costType(WarehouseFeeType.STORAGE) + .snapshotDateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-31")) + .build()); + + assertTrue(t.lastDataRequest().body().contains("\"btChargeAt\":\"2026-10-01 ~ 2026-10-31\"")); + } + + /** 一条过滤条件都没有时本地拒绝:等于拉全量账单。 */ + @Test + void rejectsQueryWithoutAnyFilter() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0")); + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(t).settlements(CTX, + FeeQuery.builder().costType(WarehouseFeeType.STORAGE).build())); + + assertTrue(ex.getMessage().contains("at least one filter"), ex.getMessage()); + assertTrue(t.dataRequests().isEmpty(), "本地拒绝不应发请求"); + } + + /** 不指定费用类型无法决定查哪个接口,拒绝而不是三个都查。 */ + @Test + void rejectsQueryWithoutCostType() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0")); + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(t).settlements(CTX, + FeeQuery.builder().saleOrderNo("OB-1").build())); + + assertTrue(ex.getMessage().contains("costType"), ex.getMessage()); + assertTrue(t.dataRequests().isEmpty()); + } + + /** 增值服务费恒健没有对应接口,显式拒绝。 */ + @Test + void rejectsValueAddedFee() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.0")); + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(t).settlements(CTX, FeeQuery.builder() + .costType(WarehouseFeeType.VALUE_ADDED).saleOrderNo("OB-1").build())); + + assertTrue(ex.getMessage().contains("VALUE_ADDED"), ex.getMessage()); + } + + // ================================================================ 行映射 + + private static FeeQuery storageQuery() { + return FeeQuery.builder().costType(WarehouseFeeType.STORAGE).saleOrderNo("OB-1").build(); + } + + private static FeeQuery tailQuery() { + return FeeQuery.builder().costType(WarehouseFeeType.LAST_MILE).saleOrderNo("OB-1").build(); + } + + private static FeeQuery operationQuery() { + return FeeQuery.builder().costType(WarehouseFeeType.OPERATION).saleOrderNo("OB-1").build(); + } + + @Test + void mapsStorageFeeRow() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody("1.078272")); + List docs = adapter(t).settlements(CTX, storageQuery()); + + assertEquals(1, docs.size()); + BillingDocument doc = docs.get(0); + assertEquals(WarehouseFeeType.STORAGE, doc.feeType()); + assertEquals(WarehouseProvider.HENGJIAN, doc.sourceProvider()); + assertEquals("EFCA", doc.warehouseCode()); + assertEquals("123456", doc.documentNo(), "billNo → documentNo"); + assertEquals("TXN-1", doc.serialNumber(), "transactionNo → serialNumber"); + assertEquals("不可售库存->存储天数->361 docs = adapter(t).settlements(CTX, tailQuery()); + + assertEquals(1, docs.size()); + BillingDocument doc = docs.get(0); + assertEquals(WarehouseFeeType.LAST_MILE, doc.feeType()); + assertEquals("TEST001", doc.documentNo()); + assertEquals("TXN-2", doc.serialNumber()); + assertEquals("Basic Rate", doc.feeName()); + assertEquals(6.95, doc.amount().amount().doubleValue(), 0.000001); + assertEquals("SKU001", doc.providerSku(), "erpSku → providerSku"); + // 单号口径:发货单号优先 + assertEquals("P123456", doc.saleOrderNo()); + } + + @Test + void mapsOperationFeeRow() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_OPERATION, operationBody("1.0")); + List docs = adapter(t).settlements(CTX, operationQuery()); + + assertEquals(1, docs.size()); + BillingDocument doc = docs.get(0); + assertEquals(WarehouseFeeType.OPERATION, doc.feeType()); + assertEquals("CB20230901001000-408100", doc.documentNo()); + assertEquals("CO20230926163817-615191", doc.serialNumber()); + assertEquals("退货入库->入库费->销售退货入库费", doc.feeName()); + assertEquals(1.0, doc.amount().amount().doubleValue(), 0.000001); + assertEquals("TESTSKU001", doc.providerSku(), "relSku → providerSku"); + assertEquals("XXXTEST002", doc.saleOrderNo(), "relOrderNo 优先于 sourceNo"); + } + + /** 金额缺失的行跳过,不拿 0 兜底。 */ + @Test + void skipsRowsWithoutCost() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, storageBody(null)); + List docs = adapter(t).settlements(CTX, storageQuery()); + + assertTrue(docs.isEmpty(), "cost 为 null 的行应被跳过,而不是记成 0 元"); + } + + /** 空 content 不是错误。 */ + @Test + void emptyContentIsNotAnError() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, + "{\"code\":200,\"message\":\"OK\",\"data\":{\"content\":[],\"last\":true}}"); + + assertTrue(adapter(t).settlements(CTX, storageQuery()).isEmpty()); + } + + /** data 缺失返回空列表,不抛。 */ + @Test + void missingDataReturnsEmptyList() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, + "{\"code\":200,\"message\":\"OK\"}"); + + assertTrue(adapter(t).settlements(CTX, storageQuery()).isEmpty()); + } + + // ================================================================ 能力位 + + @Test + void declaresFeeSettlementCapability() { + assertTrue(adapter(RecordingTransport.create()).capabilities() + .contains(WarehouseCapability.FEE_SETTLEMENT)); + } + + /** 币种缺失按 USD;不编造其它币种。 */ + @Test + void defaultsCurrencyToUsd() { + RecordingTransport t = transport(HengjianConstants.PATH_FEE_STORAGE, + storageBodyWithCurrency("1.0", null)); + BillingDocument doc = adapter(t).settlements(CTX, storageQuery()).get(0); + + assertEquals("USD", doc.amount().currency().getCurrencyCode()); + } + + /** 结算时间取 settlementAt;缺失时保持 null,不拿当前时间兜底。 */ + @Test + void settledAtComesFromPayloadOnly() { + RecordingTransport withTime = transport(HengjianConstants.PATH_FEE_STORAGE, + storageBody("1.0")); + assertEquals(Instant.parse("2026-11-01T00:00:00Z"), + adapter(withTime).settlements(CTX, storageQuery()).get(0).settledAt()); + + RecordingTransport without = transport(HengjianConstants.PATH_FEE_STORAGE, + storageBodyWithCurrency("1.0", "USD").replace("\"settlementAt\":\"2026-11-01 00:00:00\",", "")); + assertNull(adapter(without).settlements(CTX, storageQuery()).get(0).settledAt(), + "仓方没给时间就不要编"); + } + + // ================================================================ 夹具 + + private static String storageBody(String cost) { + return storageBodyWithCurrency(cost, "USD"); + } + + private static String storageBodyWithCurrency(String cost, String currency) { + return "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"获取账单仓储费明细数据\"," + + "\"data\":{\"totalElements\":1,\"totalPages\":1,\"numberOfElements\":1," + + "\"number\":0,\"size\":100,\"last\":true,\"content\":[{" + + "\"orgName\":\"测试\",\"orgWarehouseCode\":\"EFCA\",\"billNo\":\"123456\"," + + "\"transactionNo\":\"TXN-1\"," + + "\"settlementName\":\"不可售库存->存储天数->361入库费->销售退货入库费\"," + + "\"firstCategoryName\":\"退货入库\",\"secondCategoryName\":\"入库费\"," + + "\"thirdCategoryName\":\"销售退货入库费\",\"categoryUnit\":\"SKU\"," + + "\"categoryStandardValue\":0,\"lineCode\":\"WEIMASI_default\"," + + "\"sourceNo\":\"XXXTEST001\",\"relOrderNo\":\"XXXTEST002\"," + + "\"relSku\":\"TESTSKU001\",\"count\":1.0,\"cost\":" + cost + "," + + "\"currency\":\"USD\",\"chargeAt\":\"2023-09-26 16:38:13\"," + + "\"settlementAt\":\"2023-09-26 16:38:18\",\"bookAt\":\"2023-09-27 00:11:48\"}]}}"; + } +} 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 053ecc5..9629b33 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 @@ -6,7 +6,9 @@ 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.WarehouseFeeType; import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.FeeQuery; import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundOrder; @@ -221,4 +223,59 @@ class HengjianReadOnlyProbeTest { } }); } + + /** + * 计费明细(仓储费 / 尾程费 / 作业费):只读,验证三个路径与分页信封。 + * + *

用 {@code -Dhengjian.probe.feeType=STORAGE|LAST_MILE|OPERATION} 指定查哪一类; + * 必须同时给 {@code -Dhengjian.probe.begin} / {@code end}(yyyy-MM-dd), + * 因为恒健要求至少一条过滤条件。

+ */ + @Test + void probeFeeDetails() { + assumeToken(); + final String feeType = opt("hengjian.probe.feeType", ""); + Assumptions.assumeTrue(!feeType.isEmpty(), + "未提供 -Dhengjian.probe.feeType,跳过计费明细探针"); + final String begin = opt("hengjian.probe.begin", ""); + final String end = opt("hengjian.probe.end", ""); + Assumptions.assumeTrue(!begin.isEmpty() && !end.isEmpty(), + "未提供 -Dhengjian.probe.begin / end,跳过计费明细探针"); + + final WarehouseFeeType type; + try { + type = WarehouseFeeType.valueOf(feeType.trim().toUpperCase()); + } catch (IllegalArgumentException e) { + System.out.println("[skip] 未知的 feeType=" + feeType); + return; + } + + run("POST /v1/chargingSettlement/* (" + type + ")", new Runnable() { + @Override + public void run() { + FeeQuery query = FeeQuery.builder() + .costType(type) + .settledAfter(java.time.LocalDate.parse(begin) + .atStartOfDay(java.time.ZoneOffset.UTC).toInstant()) + .settledBefore(java.time.LocalDate.parse(end) + .atTime(23, 59, 59).toInstant(java.time.ZoneOffset.UTC)) + .pageSize(10) + .build(); + List docs = + adapter().settlements(ctx(), query); + System.out.println(" 返回 " + docs.size() + " 条(<10 说明已是末页)"); + for (int i = 0; i < Math.min(docs.size(), 10); i++) { + common.ecommerce.warehouse.model.BillingDocument d = docs.get(i); + System.out.println(" [" + i + "] type=" + d.feeType() + + " billNo=" + d.documentNo() + + " txn=" + d.serialNumber() + + " name=" + d.feeName() + + " amount=" + d.amount() + + " sku=" + d.providerSku() + + " order=" + d.saleOrderNo() + + " settledAt=" + d.settledAt()); + } + } + }); + } }