Browse Source

feat(hengjian): 对接仓储费 / 尾程费 / 作业费三个计费明细接口

- 新增三个 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 <noreply@anthropic.com>
master
lml 6 days ago
parent
commit
1c3a99a8c6
  1. 12
      README.md
  2. 66
      docs-warehouse/hengjian/README.md
  3. 57
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java
  4. 29
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  5. 140
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  6. 279
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java
  7. 214
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOperationFeeDtos.java
  8. 202
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianStorageFeeDtos.java
  9. 225
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTailDeliveryFeeDtos.java
  10. 346
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java
  11. 57
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java

12
README.md

@ -141,7 +141,7 @@ sequenceDiagram @@ -141,7 +141,7 @@ sequenceDiagram
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费、尾程费、作业费明细) |
依赖方向:
```
@ -376,15 +376,17 @@ common.ecommerce @@ -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 # 单模块 @@ -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 # 恒健目录 / 渠道 / 商品 / 出库 / 异动单 / 计费
```
---

66
docs-warehouse/hengjian/README.md

@ -70,7 +70,10 @@ @@ -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 @@ @@ -345,14 +348,57 @@
入库计划创建 / 列表 / 查询 / 取消 / 加附件 / 上传附件 / 发运 / 更新到仓日期 / 生成箱标,
预约单创建 / 修改 / 取消 / 信息查询 / 日期查询。路径以 `/v1/inbound/...`、`/v3/booking_order/...` 为主。
### 调拨 / 退货 / 销毁 / 计费 / 测算
### 计费明细(`FEE_SETTLEMENT`)—— 已接入
恒健把三类费用拆成<b>三个独立接口</b>,行字段完全不同:
| `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`),是<b>已发生账目</b>,
不是预估 → `estimated(false)`。
- **金额**:`cost` 是<b>该行总费用</b>,不是单价。`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/ @@ -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/ @@ -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/ @@ -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 \ @@ -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 天)。没给就跳过对应用例。
- 只读,不建单。

57
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java

@ -38,6 +38,16 @@ public final class FeeQuery { @@ -38,6 +38,16 @@ public final class FeeQuery {
* 适配器不支持的类型要显式拒绝。</p>
*/
private final common.ecommerce.warehouse.enums.FeeQueryNoType noType;
/**
* 目录分页页码;null 表示适配器按自己的默认值(通常第 1 页)。
*
* <p>恒健、易达云这类「账单明细」接口是<b>分页的</b>,一次最多几百条;
* 不分页就会把「只拿到第一页」当成「一共这么多钱」。分页语义与
* {@code OutboundQuery.cursor} 一样是字符串游标,具体含义由适配器解释。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

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

@ -110,6 +110,35 @@ public final class HengjianConstants { @@ -110,6 +110,35 @@ public final class HengjianConstants {
public static final String PATH_TRACKING_CHANGE_FIND = "/v1/trackingChange/findOrder";
/**
* 仓储费明细({@code POST},分页)。
*
* <p>三个计费接口的请求结构一致:{@code orgWarehouseCodes} / {@code relOrderNos} /
* {@code sourceNos} / {@code btChargeAt} 都可选,{@code page} / {@code size} 必填。</p>
*/
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} 的日期区间分隔符。
*
* <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p>
*/
public static final String FEE_DATE_RANGE_SEPARATOR = " ~ ";
/**
* 列表接口的排序字段。
*
* <p>文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc};

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

@ -7,6 +7,9 @@ import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos; @@ -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; @@ -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; @@ -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; @@ -68,7 +75,7 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。</p>
*/
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 @@ -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 @@ -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);
}
// ------------------------------------------------------------------ 计费明细
/**
* 拉取计费明细(仓储费 / 尾程费 / 作业费)。
*
* <p>恒健把三类费用拆成<b>三个独立接口</b>,行字段各不相同,统一模型只有一个
* {@code settlements()}。因此<b>必须由调用方用 {@link FeeQuery#costType()} 指定查哪一类</b>:</p>
*
* <table border="1">
* <tr><th>costType</th><th>接口</th></tr>
* <tr><td>{@code STORAGE}</td><td>{@code getChargingStorageSettlement}</td></tr>
* <tr><td>{@code LAST_MILE}</td><td>{@code getChargingTailDeliverySettlement}</td></tr>
* <tr><td>{@code OPERATION}</td><td>{@code getChargingOperationSettlement}</td></tr>
* </table>
*
* <p>不指定就<b>拒绝</b>而不是「三个都查再合并」:三类费用的行结构不同、金额口径也不同,
* 合并会让调用方以为拿到了一份完整账单,实际少了另外两类。</p>
*
* <p>{@code VALUE_ADDED}(增值服务费)恒健没有对应接口,显式拒绝。</p>
*
* <h3>分页</h3>
* <p>三个接口都是分页的,统一方法返回 {@code List}、不带游标,所以分页由调用方驱动:
* 用 {@link FeeQuery#toBuilder()}{@code .pageCursor("2")} 翻页。
* <b>判末页的约定</b>:返回条数小于本次请求的 {@code pageSize} 即末页
* (少于请求量说明后面没有了)。</p>
*/
@Override
public List<BillingDocument> 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<BillingDocument> 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<String>();
body.relOrderNos = new ArrayList<String>();
body.sourceNos = new ArrayList<String>();
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<BillingDocument>();
}
final String warehouseCode = ctx.warehouseCode();
return HengjianFeeMapper.mapAll(resp.data.content,
new HengjianFeeMapper.RowMapper<HengjianStorageFeeDtos.StorageFeeRow>() {
@Override
public BillingDocument map(HengjianStorageFeeDtos.StorageFeeRow row) {
return HengjianFeeMapper.toDocument(row, warehouseCode);
}
});
}
private List<BillingDocument> 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<String>();
body.relOrderNos = new ArrayList<String>();
body.sourceNos = new ArrayList<String>();
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<BillingDocument>();
}
final String warehouseCode = ctx.warehouseCode();
return HengjianFeeMapper.mapAll(resp.data.content,
new HengjianFeeMapper.RowMapper<HengjianTailDeliveryFeeDtos.TailDeliveryFeeRow>() {
@Override
public BillingDocument map(HengjianTailDeliveryFeeDtos.TailDeliveryFeeRow row) {
return HengjianFeeMapper.toDocument(row, warehouseCode);
}
});
}
private List<BillingDocument> 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<String>();
body.relOrderNos = new ArrayList<String>();
body.sourceNos = new ArrayList<String>();
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<BillingDocument>();
}
final String warehouseCode = ctx.warehouseCode();
return HengjianFeeMapper.mapAll(resp.data.content,
new HengjianFeeMapper.RowMapper<HengjianOperationFeeDtos.OperationFeeRow>() {
@Override
public BillingDocument map(HengjianOperationFeeDtos.OperationFeeRow row) {
return HengjianFeeMapper.toDocument(row, warehouseCode);
}
});
}
// ------------------------------------------------------------------ 物流异动单
/**

279
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java

@ -0,0 +1,279 @@ @@ -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;
/**
* 恒健计费明细映射(仓储费 / 尾程费 / 作业费)。
*
* <p>三个接口的<b>请求结构一致</b>、<b>行字段完全不同</b>,所以请求构造共用一份,
* 行映射各写一个方法。</p>
*
* <h2>口径</h2>
* <ul>
* <li><b>都是已发生的账单明细</b>,不是预估 → {@code estimated(false)}。
* 恒健的计费明细来自账单({@code billNo}),不存在「先给预估、后出实际」的两段式。</li>
* <li><b>金额单位</b>:{@code cost} 是<b>该行总费用</b>,不是单价。</li>
* <li><b>交易号</b>:{@code transactionNo} 是同一计费项多条记录的唯一区分,
* 落 {@link BillingDocument#serialNumber()};{@code billNo} 落
* {@link BillingDocument#documentNo()}。</li>
* <li><b>费用类型</b>由<i>接口</i>决定(仓储 / 尾程 / 作业),不靠猜费用名——
* 作业费的 {@code settlementName} 形如「退货入库->入库费->…」,靠字符串归类迟早错。</li>
* </ul>
*/
public final class HengjianFeeMapper {
/** 币种缺失时的默认值(恒健默认 USD)。 */
private static final String DEFAULT_CURRENCY = "USD";
private HengjianFeeMapper() {
}
// ================================================================ 请求
/**
* 把统一查询条件填进三个计费接口共用的过滤字段。
*
* <p><b>必须有过滤条件</b>:全空等于拉全量账单,这里直接拒绝,
* 不发这种请求。</p>
*
* <p>字段对应关系:</p>
* <table border="1">
* <tr><th>{@link FeeQuery}</th><th>恒健</th><th>说明</th></tr>
* <tr><td>{@code billingTransNo}</td><td>{@code relOrderNos}</td>
* <td>计费单号(账单侧的业务单号)</td></tr>
* <tr><td>{@code saleOrderNo} / {@code externalOrderNo}</td><td>{@code sourceNos}</td>
* <td>来源单号(我们下发的出库单号);两个字段都当来源单号,去重后下发</td></tr>
* <tr><td>{@code settledAfter/Before} 或 {@code snapshotDateRange}</td>
* <td>{@code btChargeAt}</td><td>{@code yyyy-MM-dd ~ yyyy-MM-dd}</td></tr>
* </table>
*
* @param defaultWarehouseCode 调用方没在 {@code orgWarehouseCodes} 里指定仓时用的兜底仓
* @return {@code btChargeAt};没有日期条件时为 null
* @throws IllegalArgumentException 一条过滤条件都没有
*/
public static String applyFilters(FeeQuery query, String defaultWarehouseCode,
List<String> orgWarehouseCodes,
List<String> relOrderNos,
List<String> 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 <T> List<BillingDocument> mapAll(List<T> rows, RowMapper<T> mapper) {
if (rows == null || rows.isEmpty()) {
return new ArrayList<BillingDocument>();
}
List<BillingDocument> out = new ArrayList<BillingDocument>(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<T> {
BillingDocument map(T row);
}
// ================================================================ 工具
/**
* 金额。
*
* <p>恒健三项计费接口的 {@code cost} 都是<b>该行总费用</b>;缺失时返回
* {@code null}(调用方会跳过该行),<b>不用 0 兜底</b>——0 会让对账金额偏小,
* 而且看不出是哪一行缺了。</p>
*/
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;
}
}

214
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOperationFeeDtos.java

@ -0,0 +1,214 @@ @@ -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})。
*
* <p><b>文档问题</b>:这一页的标题与链接都写成了「测算费用(接口)」和
* {@code open-api.ehenglin.com/v2/api/shipping/calculate}(明显是从测算页复制的),
* 只有路径与返回示例是本接口的。以路径与示例为准。</p>
*
* <p>行结构比另两个接口多出<b>五级费用分类</b>(一~五级分类名 + 计费单位 + 计费标识 +
* 计费阈值),是三个接口里分类最细的。</p>
*/
public final class HengjianOperationFeeDtos {
private HengjianOperationFeeDtos() {
}
/** 请求;三个计费接口结构一致,各自声明一份。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListRequest {
/** 仓库 code 列表。 */
public List<String> orgWarehouseCodes;
/** 计费单号列表。 */
public List<String> relOrderNos;
/** 来源单号列表。 */
public List<String> sourceNos;
/**
* 业务发生日期区间,格式 {@code yyyy-MM-dd ~ yyyy-MM-dd}。
*
* <p>本页字段表把类型标成 List、示例给的却是字符串;按字符串实现。</p>
*/
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<OperationFeeRow> content;
@JsonProperty("totalElements")
public Integer totalElements;
@JsonProperty("totalPages")
public Integer totalPages;
@JsonProperty("numberOfElements")
public Integer numberOfElements;
/** 当前页码,<b>0 基</b>。 */
@JsonProperty("number")
public Integer number;
@JsonProperty("size")
public Integer size;
@JsonProperty("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;
/**
* 计费阈值。
*
* <p>字段表标 STRING、示例给数字 {@code 0};按 String 读,Jackson 会把数字转文本。</p>
*/
@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;
}
}

202
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianStorageFeeDtos.java

@ -0,0 +1,202 @@ @@ -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})。
*
* <p>三个计费接口(仓储 / 尾程 / 作业)的<b>请求结构与分页信封完全一致</b>,
* 只有行字段不同。按仓库约定「一个接口一个文件」,这里各自声明一份——
* 分页信封只有几个协议字段,复制比抽象成泛型更省事、也不会有跨接口耦合。</p>
*/
public final class HengjianStorageFeeDtos {
private HengjianStorageFeeDtos() {
}
/**
* 请求。
*
* <p>{@code page} / {@code size} 文档标「必填」;其余过滤条件全可选,
* 但<b>全都不给等于拉全量账单</b>,适配器会拒绝。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListRequest {
/** 仓库 code 列表,如 {@code ["EFCA"]}。 */
public List<String> orgWarehouseCodes;
/** 计费单号(单据号)列表。 */
public List<String> relOrderNos;
/** 来源单号列表(我们下发的出库单号)。 */
public List<String> sourceNos;
/**
* 交易时间区间,格式 {@code yyyy-MM-dd ~ yyyy-MM-dd}。
*
* <p><b>类型不一致</b>:仓储页示例里是单个字符串;作业页的字段表标成 List。
* 按字符串实现——真机只验证过三个路径存在,参数形态待联调确认。</p>
*/
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<StorageFeeRow> content;
/** 总记录数。 */
@JsonProperty("totalElements")
public Integer totalElements;
@JsonProperty("totalPages")
public Integer totalPages;
/** 当前页记录数。 */
@JsonProperty("numberOfElements")
public Integer numberOfElements;
/** 当前页码,<b>0 基</b>(示例请求第 1 页返回 {@code number: 0})。 */
@JsonProperty("number")
public Integer number;
@JsonProperty("size")
public Integer size;
@JsonProperty("last")
public Boolean last;
}
/**
* 一行仓储费。
*
* <p>仓储费按<b>批次 × 库存类型 × 存储天数区间</b>拆行,一个 SKU 一天可能出多行;
* 对账时按 {@code transactionNo} 区分。</p>
*/
@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<X<9999」。 */
@JsonProperty("settlementName")
public String settlementName;
/** 项目 code / 名称。 */
@JsonProperty("lineCode")
public String lineCode;
@JsonProperty("lineName")
public String lineName;
/** SKU。 */
@JsonProperty("sku")
public String sku;
/** 产品尺寸与重量(字段表没写单位;示例里是整数)。 */
@JsonProperty("height")
public Integer height;
@JsonProperty("length")
public Integer length;
@JsonProperty("width")
public Integer width;
@JsonProperty("weight")
public Integer weight;
/** 库存类型,原文如「不可售库存」。 */
@JsonProperty("inventoryType")
public String inventoryType;
/** 批次号。 */
@JsonProperty("batchNo")
public String batchNo;
/** 来源单号;可能为 null。 */
@JsonProperty("sourceNo")
public String sourceNo;
/** 存储天数。 */
@JsonProperty("storageDays")
public Integer storageDays;
/** 库存数量。 */
@JsonProperty("inventoryQty")
public Integer inventoryQty;
/** 计费量(配合 {@link #unit})。 */
@JsonProperty("count")
public Double count;
/** 计费单位,原文如「立方米(CBM)」。 */
@JsonProperty("unit")
public String unit;
/** 总费用。 */
@JsonProperty("cost")
public Double cost;
/** 币种。 */
@JsonProperty("currency")
public String currency;
/** 结算备注。 */
@JsonProperty("settleRemark")
public String settleRemark;
/** 其他备注。 */
@JsonProperty("remark")
public String remark;
/**
* 结算时间。
*
* <p>字段表里有、<b>示例里没有</b>;按字符串接,缺失即 null。</p>
*/
@JsonProperty("settlementAt")
public String settlementAt;
/** 异常信息。 */
@JsonProperty("errorMessage")
public String errorMessage;
}
}

225
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianTailDeliveryFeeDtos.java

@ -0,0 +1,225 @@ @@ -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})。
*
* <p>行字段与仓储费差异很大:带承运商、物流产品、计费重、分区、跟踪号,
* 以及三个时间(业务计费 / 结算 / 入账)。</p>
*/
public final class HengjianTailDeliveryFeeDtos {
private HengjianTailDeliveryFeeDtos() {
}
/**
* 请求。
*
* <p>三个计费接口的请求结构一致;按「一个接口一个文件」各自声明一份,
* 免得改一家时误伤另两家。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListRequest {
/** 仓库 code 列表。 */
public List<String> orgWarehouseCodes;
/** 计费单号列表。 */
public List<String> relOrderNos;
/** 来源单号列表。 */
public List<String> 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<TailDeliveryFeeRow> content;
@JsonProperty("totalElements")
public Integer totalElements;
@JsonProperty("totalPages")
public Integer totalPages;
@JsonProperty("numberOfElements")
public Integer numberOfElements;
/** 当前页码,<b>0 基</b>。 */
@JsonProperty("number")
public Integer number;
@JsonProperty("size")
public Integer size;
@JsonProperty("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;
}
}

346
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianFeeTest.java

@ -0,0 +1,346 @@ @@ -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<BillingDocument> 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<X<9999", doc.feeName());
assertEquals(1.078272, doc.amount().amount().doubleValue(), 0.000001);
assertEquals("USD", doc.amount().currency().getCurrencyCode());
assertEquals("TEST001", doc.providerSku());
assertFalse(doc.estimated(), "账单明细是已发生账目,不是预估");
}
@Test
void mapsTailDeliveryRow() {
RecordingTransport t = transport(HengjianConstants.PATH_FEE_TAIL_DELIVERY, tailBody("6.95"));
List<BillingDocument> 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<BillingDocument> 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<BillingDocument> 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<X<9999\","
+ "\"lineCode\":\"CS\",\"lineName\":\"CS\",\"sku\":\"TEST001\","
+ "\"inventoryType\":\"不可售库存\",\"batchNo\":\"B2022060900001\","
+ "\"storageDays\":1,\"inventoryQty\":1,\"count\":0.269568,"
+ "\"unit\":\"立方米(CBM)\","
+ (cost == null ? "" : "\"cost\":" + cost + ",")
+ (currency == null ? "" : "\"currency\":\"" + currency + "\",")
+ "\"settlementAt\":\"2026-11-01 00:00:00\",\"errorMessage\":\"\"}]}}";
}
private static String tailBody(String cost) {
return "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"获取账单尾程费明细数据\","
+ "\"data\":{\"last\":true,\"numberOfElements\":1,\"number\":0,\"size\":100,"
+ "\"content\":[{"
+ "\"orgWarehouseCode\":\"EFCA\",\"billNo\":\"TEST001\",\"transactionNo\":\"TXN-2\","
+ "\"settlementName\":\"Basic Rate\",\"carrierCode\":\"FedEx\","
+ "\"carrierServiceCode\":\"FEDXG\",\"trackingNo\":\"1Z999\","
+ "\"parcelWeight\":8.6,\"ratedWeight\":9,\"zoneCode\":\"5\","
+ "\"count\":1,\"cost\":" + cost + ",\"currency\":\"USD\","
+ "\"deliveryOrderNo\":\"P123456\",\"orderNo\":\"12345\","
+ "\"platformOrderNo\":\"TEST001\",\"sourceOrderNo\":\"TEST001\","
+ "\"erpSku\":\"SKU001\",\"chargeAt\":\"2025-08-12 00:00:00\","
+ "\"settlementAt\":\"2025-08-14 03:41:28\",\"bookAt\":\"2025-08-12 00:00:00\"}]}}";
}
private static String operationBody(String cost) {
return "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"获取账单作业费明细数据\","
+ "\"data\":{\"last\":true,\"numberOfElements\":1,\"number\":0,\"size\":100,"
+ "\"content\":[{"
+ "\"orgWarehouseCode\":\"EFCA\",\"billNo\":\"CB20230901001000-408100\","
+ "\"transactionNo\":\"CO20230926163817-615191\","
+ "\"settlementName\":\"退货入库->入库费->销售退货入库费\","
+ "\"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\"}]}}";
}
}

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

@ -6,7 +6,9 @@ import common.ecommerce.http.JacksonJsonCodec; @@ -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 { @@ -221,4 +223,59 @@ class HengjianReadOnlyProbeTest {
}
});
}
/**
* 计费明细(仓储费 / 尾程费 / 作业费):只读,验证三个路径与分页信封。
*
* <p>用 {@code -Dhengjian.probe.feeType=STORAGE|LAST_MILE|OPERATION} 指定查哪一类;
* 必须同时给 {@code -Dhengjian.probe.begin} / {@code end}(yyyy-MM-dd),
* 因为恒健要求至少一条过滤条件。</p>
*/
@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<common.ecommerce.warehouse.model.BillingDocument> 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());
}
}
});
}
}

Loading…
Cancel
Save