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());
+ }
+ }
+ });
+ }
}