From 73892d60522a643240352793374a295d64b118a6 Mon Sep 17 00:00:00 2001
From: lml <1297555865@qq.com>
Date: Mon, 16 Nov 2026 13:53:59 +0800
Subject: [PATCH] =?UTF-8?q?feat(hengjian):=20=E5=AF=B9=E6=8E=A5=E8=BF=90?=
=?UTF-8?q?=E8=B4=B9=E6=B5=8B=E7=AE=97=E4=B8=8E=E5=9C=B0=E5=9D=80=E5=B1=9E?=
=?UTF-8?q?=E6=80=A7=E8=AF=86=E5=88=AB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
两个接口都在 /v2/api/shipping 下,真机均确认可用(无 token 时的
参数校验响应与 404 对照组可区分)。
运费测算 /v2/api/shipping/calculate
- 真机确认必填项是包裹四项 + 两个单位 + 收货方五项;文档标必填的
shipper* 系列实际可不传
- 单位 cm/g 与统一模型一致,不换算
- 包裹尺寸在恒健是 INTEGER,厘米值四舍五入(截断会让报价偏低)
- totalRate 取 conversionTotalRate(折算价 / 客户实付),
不取 originalTotalRate(承运商牌价)
- 恒健不按仓返回,统一结果只有一个实例,仓编码用账户仓填充
地址属性 /v2/api/shipping/addressClassification
- 新增能力位 ADDRESS_CLASSIFICATION + AddressClassificationCapable
+ core 枚举 AddressType(BUSINESS/RESIDENTIAL/MIXED/UNKNOWN)
- 真机确认 street1/zip/city/state/country 五项必填,本地先挡
- 认不出归 UNKNOWN 不猜;MIXED 在 residential() 里按住宅计
- 文档域名写的是 open-api.thebizark.com(别家),真机确认本仓域名可用
顺带修 core 缺陷:FeeEstimateQuery.logisticsServiceCode 原为构造期必填,
而恒健允许不传(由仓报全部渠道)。改为选填,并新增 hasLogisticsServiceCode();
运去哪要求必填,改为在它的 mapper 里校验,不影响既有行为。
验证:mvn test 全量通过,恒健 180 个用例(+14)通过。
Co-Authored-By: Claude Code
---
README.md | 7 +-
docs-warehouse/architecture.md | 3 +-
docs-warehouse/hengjian/README.md | 40 +++-
.../capability/AddressClassificationCapable.java | 34 +++
.../ecommerce/warehouse/enums/AddressType.java | 56 +++++
.../warehouse/enums/WarehouseCapability.java | 4 +-
.../warehouse/model/FeeEstimateQuery.java | 26 +-
.../warehouse/sdk/WarehouseOperations.java | 20 ++
.../ecommerce/hengjian/HengjianConstants.java | 17 ++
.../hengjian/adapter/HengjianAdapter.java | 79 +++++-
.../hengjian/adapter/HengjianEstimateMapper.java | 175 ++++++++++++++
.../dto/HengjianAddressClassificationDtos.java | 58 +++++
.../hengjian/dto/HengjianFeeEstimateDtos.java | 167 +++++++++++++
.../hengjian/adapter/HengjianEstimateTest.java | 266 +++++++++++++++++++++
.../yqn/adapter/YqnFeeEstimateMapper.java | 7 +
15 files changed, 944 insertions(+), 15 deletions(-)
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/AddressClassificationCapable.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AddressType.java
create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java
create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianAddressClassificationDtos.java
create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java
create mode 100644 warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianEstimateTest.java
diff --git a/README.md b/README.md
index 6b6b558..427d6f8 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;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性) |
依赖方向:
```
@@ -380,13 +380,14 @@ common.ecommerce
│ HengjianAdapterFactory / HengjianDirectoryMapper /
│ HengjianProductMapper / HengjianOutboundMapper /
│ HengjianOrderMapper / HengjianTrackingChangeMapper /
- │ HengjianFeeMapper
+ │ HengjianFeeMapper / HengjianEstimateMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos /
│ HengjianOrderDetailDtos / HengjianOrderListDtos /
│ HengjianCancelOrderDtos / HengjianTrackingChangeDtos /
│ HengjianTrackingChangeQueryDtos / HengjianStorageFeeDtos /
- │ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos
+ │ HengjianTailDeliveryFeeDtos / HengjianOperationFeeDtos /
+ │ HengjianFeeEstimateDtos / HengjianAddressClassificationDtos
├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus);
│ 其余状态枚举约定见 package-info,待建
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter
diff --git a/docs-warehouse/architecture.md b/docs-warehouse/architecture.md
index 911e228..7e12139 100644
--- a/docs-warehouse/architecture.md
+++ b/docs-warehouse/architecture.md
@@ -85,7 +85,7 @@ public enum YqnOutboundStatus {
`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略,
调用方不应假定排序一定生效。
-`WarehouseCapability`(25 个):
+`WarehouseCapability`(26 个):
| 能力 | 说明 | 运去哪 | 信仓 |
|---|---|:---:|:---:|
@@ -106,6 +106,7 @@ public enum YqnOutboundStatus {
| `RETURN_DISPOSITION` | 退货条目处理 | ✅ | — |
| `TRACKING` | 物流轨迹 | ✅ | — |
| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
+| `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — |
| `DESTRUCTION` | 销毁 / 报废 | ✅ | — |
| `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — |
| `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — |
diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md
index 939023a..b06f3d8 100644
--- a/docs-warehouse/hengjian/README.md
+++ b/docs-warehouse/hengjian/README.md
@@ -73,7 +73,9 @@
| 11 | 仓储费明细 | `POST /v1/chargingSettlement/getChargingStorageSettlement` | `FEE_SETTLEMENT` | ✅ |
| 12 | 尾程配送费明细 | `POST /v1/chargingSettlement/getChargingTailDeliverySettlement` | `FEE_SETTLEMENT` | ✅ |
| 13 | 作业费明细 | `POST /v1/chargingSettlement/getChargingOperationSettlement` | `FEE_SETTLEMENT` | ✅ |
-| 14 | 回调 | — | — | ❌ 文档无回调页 |
+| 14 | 运费测算 | `POST /v2/api/shipping/calculate` | `FEE_ESTIMATE` | ✅ |
+| 15 | 地址属性识别 | `POST /v2/api/shipping/addressClassification` | `ADDRESS_CLASSIFICATION` | ✅ |
+| 16 | 回调 | — | — | ❌ 文档无回调页 |
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作,
@@ -370,6 +372,36 @@
入库计划创建 / 列表 / 查询 / 取消 / 加附件 / 上传附件 / 发运 / 更新到仓日期 / 生成箱标,
预约单创建 / 修改 / 取消 / 信息查询 / 日期查询。路径以 `/v1/inbound/...`、`/v3/booking_order/...` 为主。
+### 运费测算与地址属性 —— 已接入
+
+#### 运费测算(`/v2/api/shipping/calculate`)
+
+**真机确认的必填项**(文档把 `shipper*` 系列也标必填,但真机校验信息里没有它们):
+
+`parcelLength / parcelWidth / parcelHeight / parcelWeight /
+parcelLengthUnit / parcelWeightUnit /
+receiverCountryCode / receiverState / receiverCity / receiverZipcode / receiverAddressLine1`
+
+即**发货方信息可不传**。缺任一项时仓方回「参数校验异常」并列出所有缺的字段。
+
+| 项 | 处理 |
+|---|---|
+| 单位 | 统一模型 cm / g,恒健也接受 `cm` / `g`,**不换算** |
+| 包裹尺寸 | 恒健字段是 **INTEGER**,厘米值**四舍五入**取整(截断会让报价偏低) |
+| 价格口径 | `conversionTotalRate` 是**折算价**(客户实付)→ `totalRate`;`originalTotalRate` 是承运商牌价,统一模型无对应字段 |
+| 物流服务码 | **选填**:不给由仓报全部渠道。`FeeEstimateQuery.logisticsServiceCode` 已从必填改为选填,运去哪那种要求必填的仓在适配器里拒绝 |
+| 返回维度 | 恒健**不按仓返回**,统一结果只有一个实例,`shipOrgWarehouseCode` 用账户仓填充 |
+
+#### 地址属性识别(`/v2/api/shipping/addressClassification`)
+
+**文档域名写错了**:页面链接是 `open-api.thebizark.com`(别家域名)。真机确认本仓域名下可正常调用。
+
+- 五项必填(真机):`street1 / zip / city / state / country`;`street2` 选填。
+- 响应 `data` 是**字符串**:`BUSINESS / RESIDENTIAL / MIXED / UNKNOWN`。
+- 映射到 core 的 `AddressType`;**认不出归 UNKNOWN,不猜**——猜错会多收或少收住宅附加费。
+- `AddressType.residential()` 把 `MIXED` 也算住宅(附加费按住宅计)。
+- 该能力单独一个能力位 `ADDRESS_CLASSIFICATION`,与试算分开:只判地址、不拉价格时用它。
+
### 计费明细(`FEE_SETTLEMENT`)—— 已接入
恒健把三类费用拆成三个独立接口,行字段完全不同:
@@ -445,7 +477,8 @@ warehouse-sdk-hengjian/
│ │ ├── HengjianOutboundMapper.java 出库下单报文(UTC 时间 / 行总额 / 面单附件)
│ │ ├── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型
│ │ ├── HengjianTrackingChangeMapper.java 异动单 → 统一模型
- │ │ └── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射
+ │ │ ├── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射
+ │ │ └── HengjianEstimateMapper.java 运费测算 + 地址属性映射
│ ├── dto/
│ │ ├── HengjianWarehouseDtos.java
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
@@ -475,13 +508,14 @@ warehouse-sdk-hengjian/
├── adapter/HengjianCancelOrderTest.java 10 个:双键补齐 / 精确匹配 / 拒绝路径 / 预判
├── adapter/HengjianTrackingChangeTest.java 19 个:必填拒绝 / 换址三项 / 路径 / 双状态
├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过
+ ├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射
├── 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` 全部通过(166 个 + 4 个跳过)。
+已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(180 个 + 4 个跳过)。
## 5. 探针用法
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/AddressClassificationCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/AddressClassificationCapable.java
new file mode 100644
index 0000000..2fe89ce
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/AddressClassificationCapable.java
@@ -0,0 +1,34 @@
+package common.ecommerce.warehouse.capability;
+
+import common.ecommerce.warehouse.enums.AddressType;
+import common.ecommerce.warehouse.sdk.WarehouseAdapter;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+
+/**
+ * 地址属性识别:判定收件地址是商业还是住宅。
+ *
+ * 与 {@link WarehouseFeeEstimateCapable} 分开:试算给价格,这个只给地址分类。
+ * 分类结果影响住宅附加费与分区计价,试算前先判一次能让报价更准;
+ * 也用于下单前校验地址是否可投递。
+ *
+ * 只读、无幂等。恒健的试算响应里也带 {@code isResidential},
+ * 但只要分类、不要把试算的价格一起拉时用本能力。
+ */
+public interface AddressClassificationCapable extends WarehouseAdapter {
+
+ /**
+ * 判定地址属性。
+ *
+ * @param street1 街道地址 1;必填
+ * @param street2 街道地址 2;可空
+ * @param city 城市;必填
+ * @param state 州 / 省;必填
+ * @param postal 邮编;必填
+ * @param country 国家(ISO 3166-1 alpha-2);必填
+ * @return 地址属性;仓方给未知值时返回 {@link AddressType#UNKNOWN},不返回 null
+ * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
+ * 该仓不声明 {@code ADDRESS_CLASSIFICATION}
+ */
+ AddressType classifyAddress(WarehouseContext ctx, String street1, String street2,
+ String city, String state, String postal, String country);
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AddressType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AddressType.java
new file mode 100644
index 0000000..61f3489
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AddressType.java
@@ -0,0 +1,56 @@
+package common.ecommerce.warehouse.enums;
+
+/**
+ * 地址属性:判定收件地址是商业还是住宅。
+ *
+ * 直接影响住宅附加费(Residential Surcharge)与承运商分区计价,
+ * 所以单独一个能力位而不是藏在试算里。
+ *
+ * 仓方码值由适配器映射:恒健回 {@code BUSINESS / RESIDENTIAL / MIXED / UNKNOWN}
+ * 四个英文词,其它仓可能是数字码。认不出归 {@link #UNKNOWN},不猜——
+ * 猜成住宅会多收客户钱,猜成商业会漏收。
+ */
+public enum AddressType {
+
+ /** 商业地址。 */
+ BUSINESS(10, "商业地址"),
+ /** 住宅地址。 */
+ RESIDENTIAL(20, "住宅地址"),
+ /** 混合(同一地址既有商业也有住宅单元)。 */
+ MIXED(30, "混合"),
+ /** 无法识别;仓方未给或给了未知值。 */
+ UNKNOWN(0, "未知");
+
+ private final int code;
+ private final String label;
+
+ AddressType(int code, String label) {
+ this.code = code;
+ this.label = label;
+ }
+
+ /** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
+ public int code() {
+ return code;
+ }
+
+ /** 中文显示名。 */
+ public String label() {
+ return label;
+ }
+
+ /** 是否住宅类(住宅附加费按它收)。{@link #MIXED} 按住宅计。 */
+ public boolean residential() {
+ return this == RESIDENTIAL || this == MIXED;
+ }
+
+ /** 按落库码反查;未知返回 {@link #UNKNOWN}。 */
+ public static AddressType ofCode(int code) {
+ for (AddressType t : values()) {
+ if (t.code == code) {
+ return t;
+ }
+ }
+ return UNKNOWN;
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
index 21fdec7..9b99da3 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
@@ -57,7 +57,9 @@ public enum WarehouseCapability {
/** 最优渠道推荐(按 SKU + 邮编由仓择优) */
CHANNEL_RECOMMEND(240, "最优渠道推荐"),
/** 物流异动单:召回 / 换址 / 在途异常(对已交运的运单发起处理) */
- TRACKING_CHANGE(250, "物流异动单");
+ TRACKING_CHANGE(250, "物流异动单"),
+ /** 地址属性识别:判定收件地址是商业 / 住宅(影响附加费) */
+ ADDRESS_CLASSIFICATION(260, "地址属性识别");
private final int code;
private final String label;
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java
index 4a2d638..bbb1aae 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java
@@ -53,7 +53,9 @@ public final class FeeEstimateQuery {
this.receivePostal = require(b.receivePostal, "receivePostal");
this.receiveAddress = b.receiveAddress;
this.residential = b.residential;
- this.logisticsServiceCode = require(b.logisticsServiceCode, "logisticsServiceCode");
+ // 选填:恒健允许「只给包裹 + 地址」由仓报全部渠道;运去哪等仓要求显式指定,
+ // 由各适配器在拼报文时校验
+ this.logisticsServiceCode = trimToNull(b.logisticsServiceCode);
this.logisticsProductCode = b.logisticsProductCode;
this.signService = b.signService;
}
@@ -114,11 +116,22 @@ public final class FeeEstimateQuery {
return residential;
}
- /** 物流产品服务码;取值由仓定义。 */
+ /**
+ * 物流产品服务码;取值由仓定义。
+ *
+ * 选填:不给时由仓报出全部可用渠道(恒健的行为);要求必填的仓
+ * (运去哪等)会在适配器里拒绝,而不是在这里构造期卡死。
+ * 用 {@link #hasLogisticsServiceCode()} 判断是否给了。
+ */
public String logisticsServiceCode() {
return logisticsServiceCode;
}
+ /** 是否指定了物流服务码。 */
+ public boolean hasLogisticsServiceCode() {
+ return logisticsServiceCode != null;
+ }
+
public String logisticsProductCode() {
return logisticsProductCode;
}
@@ -135,6 +148,14 @@ public final class FeeEstimateQuery {
return v;
}
+ private static String trimToNull(String v) {
+ if (v == null) {
+ return null;
+ }
+ String t = v.trim();
+ return t.isEmpty() ? null : t;
+ }
+
private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
@@ -222,6 +243,7 @@ public final class FeeEstimateQuery {
return this;
}
+ /** 物流服务码;选填,不给则由仓报全部渠道(要求必填的仓在适配器里拒绝)。 */
public Builder logisticsServiceCode(String v) {
this.logisticsServiceCode = v;
return this;
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
index 22bf510..146fecc 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
@@ -11,6 +11,7 @@ import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
+import common.ecommerce.warehouse.capability.AddressClassificationCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.TrackingChangeCapable;
import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
@@ -645,6 +646,25 @@ public final class WarehouseOperations {
}
/**
+ * 地址属性识别:判定收件地址是商业 / 住宅(影响住宅附加费)。
+ *
+ * 只读,不走幂等。仓方给未知值或无法识别时返回
+ * {@code AddressType.UNKNOWN},不返回 null——调用方据此判断
+ * 「仓说不知道」而不是「调用失败」。
+ */
+ public common.ecommerce.warehouse.enums.AddressType classifyAddress(
+ final String street1, final String street2, final String city,
+ final String state, final String postal, final String country) {
+ require(WarehouseCapability.ADDRESS_CLASSIFICATION, AddressClassificationCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.address.classify",
+ CallSupport.params("country", country, "state", state,
+ "postal", postal, "city", city),
+ r -> CallSupport.NO_COUNT,
+ () -> ((AddressClassificationCapable) adapter).classifyAddress(
+ ctx, street1, street2, city, state, postal, country));
+ }
+
+ /**
* 最优渠道推荐:给定 SKU 与邮编,由仓择优并给出全部报价。
*
* 只读,不走幂等。与 {@link #estimate(FeeEstimateQuery)} 的区别见
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 9b8082f..5d5a91a 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
@@ -138,6 +138,23 @@ public final class HengjianConstants {
public static final int FEE_PAGE_SIZE_MAX = 200;
/**
+ * 运费测算。
+ *
+ *
真机确认存在;包裹四项 + 两个单位 + 收货方五项必填
+ * ({@code shipper*} 系列可省)。
+ */
+ public static final String PATH_FEE_ESTIMATE = "/v2/api/shipping/calculate";
+
+ /**
+ * 地址属性识别。
+ *
+ * 文档写的域名是 {@code open-api.thebizark.com}(别家),是本仓的笔误。
+ * 真机确认本仓域名下正常返回 {@code data: "BUSINESS"} 等值。
+ */
+ public static final String PATH_ADDRESS_CLASSIFICATION =
+ "/v2/api/shipping/addressClassification";
+
+ /**
* {@code btChargeAt} 的日期区间分隔符。
*
* 文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。
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 8353a89..5d5d129 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
@@ -1,19 +1,21 @@
package common.ecommerce.hengjian.adapter;
import com.fasterxml.jackson.databind.JsonNode;
-import common.ecommerce.hengjian.HengjianConstants;
+import common.ecommerce.hengjian.dto.HengjianAddressClassificationDtos;
import common.ecommerce.hengjian.dto.HengjianCancelOrderDtos;
import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos;
import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos;
+import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos;
+import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos;
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos;
import common.ecommerce.hengjian.dto.HengjianOrderListDtos;
-import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos;
+import common.ecommerce.hengjian.dto.HengjianProductSaveDtos;
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;
import common.ecommerce.hengjian.dto.HengjianWarehouseDtos;
+import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.http.HengjianEnvelope;
import common.ecommerce.hengjian.http.HengjianRateLimiter;
import common.ecommerce.hengjian.http.HengjianRequestFactory;
@@ -23,13 +25,16 @@ import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.support.Page;
+import common.ecommerce.warehouse.capability.AddressClassificationCapable;
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.WarehouseFeeCapable;
+import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
+import common.ecommerce.warehouse.enums.AddressType;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.TrackingChangeHandleType;
@@ -42,6 +47,8 @@ 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.FeeEstimateQuery;
+import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundCommand;
@@ -76,7 +83,8 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。
*/
public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable,
- WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable {
+ WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable,
+ WarehouseFeeEstimateCapable, AddressClassificationCapable {
private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses";
private static final String OP_CARRIERS = "warehouse.directory.carriers";
@@ -91,6 +99,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
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";
+ private static final String OP_FEE_ESTIMATE = "warehouse.fee.estimate";
+ private static final String OP_ADDRESS_CLASSIFY = "warehouse.address.classify";
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
@@ -124,10 +134,69 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
WarehouseCapability.PLATFORM_LABEL_DELIVERY,
WarehouseCapability.TRACKING_CHANGE,
WarehouseCapability.FEE_SETTLEMENT,
+ WarehouseCapability.FEE_ESTIMATE,
+ WarehouseCapability.ADDRESS_CLASSIFICATION,
WarehouseCapability.DIRECTORY,
WarehouseCapability.LOGISTICS_PRODUCT);
}
+ // ------------------------------------------------------------------ 试算与地址属性
+
+ /**
+ * 运费测算({@code POST /v2/api/shipping/calculate})。
+ *
+ * 统一模型是 cm / g,恒健也接受 {@code cm} / {@code g},不换算;
+ * 但它的包裹尺寸字段是 INTEGER,所以厘米值四舍五入取整(截断会让报价偏低)。
+ *
+ * 恒健不按仓维度返回报价,结果只有一个实例,
+ * {@code shipOrgWarehouseCode} 用账户仓填充。
+ */
+ @Override
+ public List estimate(WarehouseContext ctx, FeeEstimateQuery query) {
+ HengjianFeeEstimateDtos.CalculateRequest body = HengjianEstimateMapper.toRequest(query);
+ String raw = execute(ctx, HengjianConstants.PATH_FEE_ESTIMATE, body, OP_FEE_ESTIMATE);
+ HengjianFeeEstimateDtos.CalculateResponse resp =
+ json.fromJson(raw, HengjianFeeEstimateDtos.CalculateResponse.class);
+ String warehouseCode = trimToNull(ctx.providerWarehouseId()) == null
+ ? ctx.warehouseCode() : ctx.providerWarehouseId();
+ List out = new ArrayList(1);
+ out.add(HengjianEstimateMapper.toResult(resp == null ? null : resp.data, warehouseCode));
+ return out;
+ }
+
+ /**
+ * 地址属性识别({@code POST /v2/api/shipping/addressClassification})。
+ *
+ * 真机确认五项必填({@code street1 / zip / city / state / country}),
+ * 缺任何一项仓方都回参数校验异常,所以本地先挡。
+ */
+ @Override
+ public AddressType classifyAddress(WarehouseContext ctx, String street1, String street2,
+ String city, String state, String postal, String country) {
+ String s1 = requireAddressPart(street1, "street1");
+ String c = requireAddressPart(city, "city");
+ String st = requireAddressPart(state, "state");
+ String zip = requireAddressPart(postal, "postal");
+ String cy = requireAddressPart(country, "country");
+
+ HengjianAddressClassificationDtos.ClassifyRequest body =
+ HengjianEstimateMapper.toClassifyRequest(s1, street2, c, st, zip, cy);
+ String raw = execute(ctx, HengjianConstants.PATH_ADDRESS_CLASSIFICATION, body,
+ OP_ADDRESS_CLASSIFY);
+ HengjianAddressClassificationDtos.ClassifyResponse resp =
+ json.fromJson(raw, HengjianAddressClassificationDtos.ClassifyResponse.class);
+ return HengjianEstimateMapper.addressTypeOf(resp == null ? null : resp.data);
+ }
+
+ private static String requireAddressPart(String value, String field) {
+ String v = trimToNull(value);
+ if (v == null) {
+ throw new IllegalArgumentException(
+ "hengjian address classification requires " + field);
+ }
+ return v;
+ }
+
// ------------------------------------------------------------------ 计费明细
/**
diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java
new file mode 100644
index 0000000..2be0a86
--- /dev/null
+++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java
@@ -0,0 +1,175 @@
+package common.ecommerce.hengjian.adapter;
+
+import common.ecommerce.hengjian.dto.HengjianAddressClassificationDtos;
+import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos;
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.enums.AddressType;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.FeeEstimateQuery;
+import common.ecommerce.warehouse.model.FeeEstimateResult;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+
+/**
+ * 恒健运费测算与地址属性映射。
+ *
+ * 测算
+ * 统一模型是 cm / g;恒健的 {@code parcelLength} 等字段是 INTEGER,
+ * 所以厘米值要取整(四舍五入)——截断会让包裹尺寸偏小,报价偏低。
+ *
+ * 价格口径:{@code original*} 是承运商牌价、{@code conversion*} 是折算价
+ * (客户实付)。统一模型的 {@code totalRate} 取折算价——那才是客户要付的钱。
+ * 牌价没有对应字段,只进费用明细的名称里(如果仓方给了的话)。
+ *
+ * 地址属性
+ * 恒健回四个英文词,映射到 {@link AddressType};认不出归 UNKNOWN,不猜——
+ * 猜错会多收或少收住宅附加费。
+ */
+public final class HengjianEstimateMapper {
+
+ /** 长度单位:统一模型是 cm,恒健也接受 cm,直接下发不换算。 */
+ static final String UNIT_LENGTH_CM = "cm";
+ /** 重量单位:统一模型是 g,恒健也接受 g,直接下发不换算。 */
+ static final String UNIT_WEIGHT_G = "g";
+
+ /** 币种缺失时的默认值。 */
+ private static final String DEFAULT_CURRENCY = "USD";
+
+ private HengjianEstimateMapper() {
+ }
+
+ /**
+ * 统一试算条件 → 恒健请求。
+ *
+ * 文档把 {@code shipper*} 系列标为必填,但真机校验信息里没有它们,
+ * 所以不传。若真机后续要求,补上即可(模型里没有发货方信息,需调用方提供)。
+ */
+ public static HengjianFeeEstimateDtos.CalculateRequest toRequest(FeeEstimateQuery query) {
+ HengjianFeeEstimateDtos.CalculateRequest req = new HengjianFeeEstimateDtos.CalculateRequest();
+ // 恒健这几个字段是 INTEGER:四舍五入而不是截断,截断会让包裹偏小、报价偏低
+ req.parcelLength = roundedCm(query.lengthCm());
+ req.parcelWidth = roundedCm(query.widthCm());
+ req.parcelHeight = roundedCm(query.heightCm());
+ req.parcelWeight = query.weightGrams().doubleValue();
+ req.parcelLengthUnit = UNIT_LENGTH_CM;
+ req.parcelWeightUnit = UNIT_WEIGHT_G;
+
+ req.receiverCountryCode = query.receiveCountry();
+ req.receiverState = query.receiveState();
+ req.receiverCity = query.receiveCity();
+ req.receiverZipcode = query.receivePostal();
+ req.receiverAddressLine1 = query.receiveAddress();
+
+ // 承运商 / 服务码是选填:给了就下发,由仓按指定渠道报价
+ req.carrier = trimToNull(query.logisticsProductCode());
+ req.serviceCode = trimToNull(query.logisticsServiceCode());
+ return req;
+ }
+
+ /** 厘米取整(四舍五入);恒健字段是 INTEGER。 */
+ static Integer roundedCm(BigDecimal cm) {
+ return cm == null ? null : Integer.valueOf(cm.setScale(0, java.math.RoundingMode.HALF_UP).intValue());
+ }
+
+ /**
+ * 报价数组 → 统一结果。
+ *
+ * 恒健不按仓维度返回(请求也没带仓),所以统一结果只有一个实例,
+ * {@code shipOrgWarehouseCode} 用账户仓填充——这是「这些报价适用于这个仓」的意思,
+ * 不是从响应里读出来的。
+ */
+ public static FeeEstimateResult toResult(List rows,
+ String warehouseCode) {
+ FeeEstimateResult.Builder builder = FeeEstimateResult.builder()
+ .sourceProvider(WarehouseProvider.HENGJIAN)
+ .shipOrgWarehouseCode(warehouseCode);
+ if (rows != null) {
+ for (HengjianFeeEstimateDtos.QuoteRow row : rows) {
+ if (row == null) {
+ continue;
+ }
+ builder.carrier(toQuote(row));
+ }
+ }
+ return builder.build();
+ }
+
+ private static FeeEstimateResult.CarrierQuote toQuote(HengjianFeeEstimateDtos.QuoteRow row) {
+ String currency = trimToNull(row.currency) == null ? DEFAULT_CURRENCY : row.currency.trim();
+ // 服务码优先用物流产品服务码(响应示例里 logisticServiceCode 才是下单用的那个)
+ String serviceCode = firstNonBlank(row.logisticServiceCode, row.serviceCode);
+ FeeEstimateResult.CarrierQuote.Builder quote = FeeEstimateResult.CarrierQuote.builder()
+ .carrier(trimToNull(row.carrier))
+ .logisticsServiceCode(serviceCode)
+ // 折算价:客户实付口径;牌价(original*)统一模型没有对应字段
+ .totalRate(moneyOf(row.conversionTotalRate, currency));
+ if (row.costItems != null) {
+ for (HengjianFeeEstimateDtos.QuoteRow.CostItem cost : row.costItems) {
+ if (cost == null) {
+ continue;
+ }
+ quote.costItem(FeeEstimateResult.CarrierQuote.CostItem.builder()
+ .costName(trimToNull(cost.costName))
+ .estimatedCost(moneyOf(cost.estimatedCost,
+ trimToNull(cost.currency) == null ? currency : cost.currency.trim()))
+ .build());
+ }
+ }
+ return quote.build();
+ }
+
+ /** 地址属性原值 → 枚举;认不出归 UNKNOWN。 */
+ public static AddressType addressTypeOf(String raw) {
+ String v = trimToNull(raw);
+ if (v == null) {
+ return AddressType.UNKNOWN;
+ }
+ switch (v.toUpperCase(Locale.ROOT)) {
+ case "BUSINESS":
+ return AddressType.BUSINESS;
+ case "RESIDENTIAL":
+ return AddressType.RESIDENTIAL;
+ case "MIXED":
+ return AddressType.MIXED;
+ case "UNKNOWN":
+ return AddressType.UNKNOWN;
+ default:
+ // 仓方将来可能加新值:不猜
+ return AddressType.UNKNOWN;
+ }
+ }
+
+ /** 地址属性请求;五项必填由调用方(适配器)先校验。 */
+ public static HengjianAddressClassificationDtos.ClassifyRequest toClassifyRequest(
+ String street1, String street2, String city, String state, String postal, String country) {
+ HengjianAddressClassificationDtos.ClassifyRequest req =
+ new HengjianAddressClassificationDtos.ClassifyRequest();
+ req.street1 = street1;
+ req.street2 = trimToNull(street2);
+ req.city = city;
+ req.state = state;
+ req.zip = postal;
+ req.country = country;
+ return req;
+ }
+
+ private static Money moneyOf(Double amount, String currency) {
+ return amount == null ? null : Money.of(BigDecimal.valueOf(amount), currency);
+ }
+
+ private static String firstNonBlank(String a, String b) {
+ String x = trimToNull(a);
+ return x != null ? x : trimToNull(b);
+ }
+
+ private static String trimToNull(String v) {
+ if (v == null) {
+ return null;
+ }
+ String t = v.trim();
+ return t.isEmpty() ? null : t;
+ }
+}
diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianAddressClassificationDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianAddressClassificationDtos.java
new file mode 100644
index 0000000..037098f
--- /dev/null
+++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianAddressClassificationDtos.java
@@ -0,0 +1,58 @@
+package common.ecommerce.hengjian.dto;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * 恒健报文结构:地址属性识别
+ * ({@code POST /v2/api/shipping/addressClassification})。
+ *
+ * 路径域名的坑:文档页写的链接是 {@code open-api.thebizark.com}
+ * (别家域名,疑似复制)。真机确认在本仓域名
+ * {@code pr-open-api.ehengjian.com} 上可以正常调用,见
+ * {@code HengjianConstants.PATH_ADDRESS_CLASSIFICATION}。
+ *
+ * 真机确认:{@code street1 / zip / city / state / country} 五项必填
+ * (缺任一项回「参数校验异常」);{@code street2} 选填。
+ *
+ * 响应 {@code data} 是字符串而不是对象:
+ * {@code BUSINESS / RESIDENTIAL / MIXED / UNKNOWN}。
+ */
+public final class HengjianAddressClassificationDtos {
+
+ private HengjianAddressClassificationDtos() {
+ }
+
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class ClassifyRequest {
+
+ /** 地址 1;必填。 */
+ public String street1;
+ /** 地址 2;选填。 */
+ public String street2;
+ /** 邮编;必填。 */
+ public String zip;
+ /** 城市;必填。 */
+ public String city;
+ /** 州;必填。 */
+ public String state;
+ /** 国家;必填。 */
+ public String country;
+ }
+
+ /** 响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class ClassifyResponse {
+
+ @JsonProperty("code")
+ public Integer code;
+
+ @JsonProperty("message")
+ public String message;
+
+ /** 地址属性原值:{@code BUSINESS} / {@code RESIDENTIAL} / {@code MIXED} / {@code UNKNOWN}。 */
+ @JsonProperty("data")
+ public String data;
+ }
+}
diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java
new file mode 100644
index 0000000..37bda65
--- /dev/null
+++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java
@@ -0,0 +1,167 @@
+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 /v2/api/shipping/calculate})。
+ *
+ * 真机确认的必填项(文档标「否」的 {@code shipper*} 系列不在必填列表里):
+ *
+ * parcelLength / parcelWidth / parcelHeight / parcelWeight /
+ * parcelLengthUnit / parcelWeightUnit /
+ * receiverCountryCode / receiverState / receiverCity / receiverZipcode /
+ * receiverAddressLine1
+ *
+ * 即发货方信息可不传(真机校验信息里没有 {@code shipper*}),收货方五项必填。
+ *
+ * 单位可选值:长度 {@code inch} / {@code cm},重量 {@code oz} / {@code lbs} / {@code g}。
+ * 统一模型是 cm / g,适配器下发改成仓方接受的单位。
+ */
+public final class HengjianFeeEstimateDtos {
+
+ private HengjianFeeEstimateDtos() {
+ }
+
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class CalculateRequest {
+
+ /** 包裹长;必填。 */
+ public Integer parcelLength;
+ /** 包裹宽;必填。 */
+ public Integer parcelWidth;
+ /** 包裹高;必填。 */
+ public Integer parcelHeight;
+ /** 包裹重量;必填。 */
+ public Double parcelWeight;
+ /** 长度单位:{@code inch} / {@code cm};必填。 */
+ public String parcelLengthUnit;
+ /** 重量单位:{@code oz} / {@code lbs} / {@code g};必填。 */
+ public String parcelWeightUnit;
+
+ /** 发货方国家(文档写只能 US);选填。 */
+ public String shipperCountryCode;
+ public String shipperState;
+ public String shipperCity;
+ public String shipperAddressLine1;
+ public String shipperAddressLine2;
+ public String shipperZipcode;
+
+ /** 收货方国家;必填。 */
+ public String receiverCountryCode;
+ /** 收货方州;必填。 */
+ public String receiverState;
+ /** 收货方城市;必填。 */
+ public String receiverCity;
+ /** 收货方地址 1;必填。 */
+ public String receiverAddressLine1;
+ /** 收货方地址 2;选填。 */
+ public String receiverAddressLine2;
+ /** 收货方邮编;必填。 */
+ public String receiverZipcode;
+
+ /** 承运商(如 {@code FedEx});选填,不给则报全部渠道。 */
+ public String carrier;
+ /** 承运商服务代码(如 {@code FEDHD});选填。 */
+ public String serviceCode;
+ }
+
+ /** 响应外层:{@code data} 是报价数组。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class CalculateResponse {
+
+ @JsonProperty("code")
+ public Integer code;
+
+ @JsonProperty("message")
+ public String message;
+
+ @JsonProperty("data")
+ public List data;
+ }
+
+ /**
+ * 一条渠道报价。
+ *
+ * 注意两个价格口径:{@code original*} 是官方价(承运商牌价),
+ * {@code conversion*} 是折算价(客户实际计价);两者可能差别很大
+ * (示例里官方 36.76、折算 18.38)。统一模型的 {@code totalRate} 用折算价——
+ * 那才是客户要付的钱。
+ */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class QuoteRow {
+
+ /** 承运商。 */
+ @JsonProperty("carrier")
+ public String carrier;
+
+ /**
+ * 物流产品服务码(响应示例里的 {@code logisticServiceCode})。
+ *
+ * 字段表没列,示例里有;与请求时的 {@code serviceCode} 不是同一个值
+ * (示例请求 {@code FEDHD}、响应 {@code FEDHD_HL})。
+ */
+ @JsonProperty("logisticServiceCode")
+ public String logisticServiceCode;
+
+ /** 承运商服务代码。 */
+ @JsonProperty("serviceCode")
+ public String serviceCode;
+
+ /** 折算总价(客户实付口径)。 */
+ @JsonProperty("conversionTotalRate")
+ public Double conversionTotalRate;
+ /** 折算基础价。 */
+ @JsonProperty("conversionBaseRate")
+ public Double conversionBaseRate;
+ /** 折算附加费之和。 */
+ @JsonProperty("conversionAdditionalTotalRate")
+ public Double conversionAdditionalTotalRate;
+
+ /** 官方总价(承运商牌价)。 */
+ @JsonProperty("originalTotalRate")
+ public Double originalTotalRate;
+ /** 官方基础价。 */
+ @JsonProperty("originalBaseRate")
+ public Double originalBaseRate;
+ /** 官方附加费之和。 */
+ @JsonProperty("originalAdditionalTotalRate")
+ public Double originalAdditionalTotalRate;
+
+ /** 币种。 */
+ @JsonProperty("currency")
+ public String currency;
+
+ /** 是否住宅地址:1 是 / 0 否。 */
+ @JsonProperty("isResidential")
+ public Integer isResidential;
+
+ /** 费用明细。 */
+ @JsonProperty("costItems")
+ public List costItems;
+
+ /** 一条费用明细。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class CostItem {
+
+ /** 费用名称,如 {@code Basic Rate} / {@code Fuel Surcharge}。 */
+ @JsonProperty("costName")
+ public String costName;
+
+ /** 费用金额。 */
+ @JsonProperty("estimatedCost")
+ public Double estimatedCost;
+
+ /** 币种。 */
+ @JsonProperty("currency")
+ public String currency;
+
+ /** 该项异常说明;正常为 null 或空串。 */
+ @JsonProperty("errorMsg")
+ public String errorMsg;
+ }
+ }
+}
diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianEstimateTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianEstimateTest.java
new file mode 100644
index 0000000..93206d6
--- /dev/null
+++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianEstimateTest.java
@@ -0,0 +1,266 @@
+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.AddressType;
+import common.ecommerce.warehouse.enums.WarehouseCapability;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.FeeEstimateQuery;
+import common.ecommerce.warehouse.model.FeeEstimateResult;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import org.junit.jupiter.api.Test;
+
+import java.math.BigDecimal;
+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.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 运费测算({@code /v2/api/shipping/calculate})与地址属性
+ * ({@code /v2/api/shipping/addressClassification})契约测试。
+ */
+class HengjianEstimateTest {
+
+ 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(java.time.Instant.parse("2026-11-16T00:00:00Z"),
+ java.time.ZoneOffset.UTC));
+
+ private static HengjianAdapter adapter(RecordingTransport transport) {
+ return new HengjianAdapter(transport, new JacksonJsonCodec());
+ }
+
+ private static FeeEstimateQuery.Builder query() {
+ return FeeEstimateQuery.builder()
+ .lengthCm(new BigDecimal("10.4"))
+ .widthCm(new BigDecimal("10.6"))
+ .heightCm(new BigDecimal("9.4"))
+ .weightGrams(new BigDecimal("500"))
+ .receiveCountry("US")
+ .receiveState("CA")
+ .receiveCity("Los Angeles")
+ .receivePostal("90001")
+ .receiveAddress("1 Main St");
+ }
+
+ // ================================================================ 测算请求
+
+ private static final String ESTIMATE_BODY =
+ "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"success\",\"data\":["
+ + "{\"carrier\":\"FedEx\",\"logisticServiceCode\":\"FEDHD_HL\","
+ + "\"serviceCode\":\"FEDHD\",\"conversionTotalRate\":18.38,"
+ + "\"originalTotalRate\":36.76,\"currency\":\"USD\",\"isResidential\":1,"
+ + "\"costItems\":[{\"costName\":\"Basic Rate\",\"estimatedCost\":9.38,"
+ + "\"currency\":\"USD\",\"errorMsg\":null},"
+ + "{\"costName\":\"Fuel Surcharge\",\"estimatedCost\":3.06,"
+ + "\"currency\":\"USD\",\"errorMsg\":\"\"}]}]}";
+
+ private static RecordingTransport estimating() {
+ return RecordingTransport.create()
+ .route(HengjianConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(ESTIMATE_BODY));
+ }
+
+ @Test
+ void estimatePostsToCalculate() {
+ RecordingTransport transport = estimating();
+ adapter(transport).estimate(CTX, query().build());
+
+ assertEquals("POST", transport.lastDataRequest().method());
+ assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/api/shipping/calculate",
+ transport.lastDataRequest().url());
+ }
+
+ /** 真机确认的必填项都要出现;shipper* 不必传。 */
+ @Test
+ void estimateSendsMandatoryFields() {
+ RecordingTransport transport = estimating();
+ adapter(transport).estimate(CTX, query().build());
+ String body = transport.lastDataRequest().body();
+
+ String[] mandatory = {"parcelLength", "parcelWidth", "parcelHeight", "parcelWeight",
+ "parcelLengthUnit", "parcelWeightUnit", "receiverCountryCode", "receiverState",
+ "receiverCity", "receiverZipcode", "receiverAddressLine1"};
+ for (String field : mandatory) {
+ assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body);
+ }
+ // 真机校验信息里没有 shipper*,不发
+ assertFalse(body.contains("shipper"), body);
+ }
+
+ /** 单位直接用 cm / g,不做换算。 */
+ @Test
+ void estimateUsesCmAndGramsWithoutConversion() {
+ RecordingTransport transport = estimating();
+ adapter(transport).estimate(CTX, query().build());
+ String body = transport.lastDataRequest().body();
+
+ assertTrue(body.contains("\"parcelLengthUnit\":\"cm\""), body);
+ assertTrue(body.contains("\"parcelWeightUnit\":\"g\""), body);
+ assertTrue(body.contains("\"parcelWeight\":500.0"), body);
+ }
+
+ /** 恒健的包裹尺寸是 INTEGER:四舍五入,不截断(截断会让报价偏低)。 */
+ @Test
+ void estimateRoundsDimensionsHalfUp() {
+ RecordingTransport transport = estimating();
+ adapter(transport).estimate(CTX, query().build());
+ String body = transport.lastDataRequest().body();
+
+ // 10.4 -> 10, 10.6 -> 11, 9.4 -> 9
+ assertTrue(body.contains("\"parcelLength\":10"), body);
+ assertTrue(body.contains("\"parcelWidth\":11"), body);
+ assertTrue(body.contains("\"parcelHeight\":9"), body);
+ }
+
+ /** 物流服务码是选填:不给也能调(由仓报全部渠道)。 */
+ @Test
+ void estimateWorksWithoutServiceCode() {
+ RecordingTransport transport = estimating();
+ adapter(transport).estimate(CTX, query().build());
+ String body = transport.lastDataRequest().body();
+
+ assertFalse(body.contains("serviceCode\""), body);
+ assertFalse(body.contains("\"carrier\""), body);
+ }
+
+ @Test
+ void estimateSendsServiceCodeWhenGiven() {
+ RecordingTransport transport = estimating();
+ adapter(transport).estimate(CTX, query()
+ .logisticsServiceCode("FEDHD").logisticsProductCode("FedEx").build());
+ String body = transport.lastDataRequest().body();
+
+ assertTrue(body.contains("\"serviceCode\":\"FEDHD\""), body);
+ assertTrue(body.contains("\"carrier\":\"FedEx\""), body);
+ }
+
+ // ================================================================ 测算结果
+
+ @Test
+ void estimateMapsQuote() {
+ List results = adapter(estimating()).estimate(CTX, query().build());
+
+ assertEquals(1, results.size(), "恒健不按仓维度返回,只有一个结果");
+ FeeEstimateResult result = results.get(0);
+ assertEquals(WarehouseProvider.HENGJIAN, result.sourceProvider());
+ assertEquals("EFCA", result.shipOrgWarehouseCode());
+ assertEquals(1, result.carriers().size());
+
+ FeeEstimateResult.CarrierQuote quote = result.carriers().get(0);
+ assertEquals("FedEx", quote.carrier());
+ // 优先用 logisticServiceCode(响应示例里那才是下单用的服务码)
+ assertEquals("FEDHD_HL", quote.logisticsServiceCode());
+ // 折算价(客户实付),不是官方牌价 36.76
+ assertEquals(18.38, quote.totalRate().amount().doubleValue(), 0.0001);
+ assertEquals("USD", quote.totalRate().currency().getCurrencyCode());
+ assertEquals(2, quote.costItems().size());
+ assertEquals("Fuel Surcharge", quote.costItems().get(1).costName());
+ assertEquals(3.06, quote.costItems().get(1).estimatedCost().amount().doubleValue(), 0.0001);
+ }
+
+ /** 没有报价时不抛,返回一个渠道为空的仓级结果。 */
+ @Test
+ void estimateEmptyQuotesIsNotAnError() {
+ RecordingTransport transport = RecordingTransport.create()
+ .route(HengjianConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(
+ "{\"code\":200,\"message\":\"success\",\"data\":[]}"));
+
+ List results = adapter(transport).estimate(CTX, query().build());
+
+ assertEquals(1, results.size());
+ assertTrue(results.get(0).carriers().isEmpty());
+ }
+
+ // ================================================================ 地址属性
+
+ private static RecordingTransport classifying(String data) {
+ return RecordingTransport.create()
+ .route(HengjianConstants.PATH_ADDRESS_CLASSIFICATION, req -> Responses.ok(
+ "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"success\","
+ + "\"data\":\"" + data + "\"}"));
+ }
+
+ @Test
+ void classifyPostsToAddressClassification() {
+ RecordingTransport transport = classifying("BUSINESS");
+ adapter(transport).classifyAddress(CTX, "1 Main St", null, "LA", "CA", "90001", "US");
+
+ assertEquals("POST", transport.lastDataRequest().method());
+ assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/api/shipping/addressClassification",
+ transport.lastDataRequest().url());
+ String body = transport.lastDataRequest().body();
+ assertTrue(body.contains("\"street1\":\"1 Main St\""), body);
+ assertTrue(body.contains("\"zip\":\"90001\""), body);
+ assertTrue(body.contains("\"country\":\"US\""), body);
+ // street2 没给就不发
+ assertFalse(body.contains("street2"), body);
+ }
+
+ /** 文档里的四个值都要映射对;认不出归 UNKNOWN。 */
+ @Test
+ void classifiesAllDocumentedValues() {
+ assertEquals(AddressType.BUSINESS, classifyAs("BUSINESS"));
+ assertEquals(AddressType.RESIDENTIAL, classifyAs("RESIDENTIAL"));
+ assertEquals(AddressType.MIXED, classifyAs("MIXED"));
+ assertEquals(AddressType.UNKNOWN, classifyAs("UNKNOWN"));
+ }
+
+ /** 仓方将来加新值:不猜,归 UNKNOWN。 */
+ @Test
+ void unknownValueIsNotGuessed() {
+ assertEquals(AddressType.UNKNOWN, classifyAs("SOMETHING_NEW"));
+ // 大小写不敏感,但只认文档里那四个
+ assertEquals(AddressType.BUSINESS, classifyAs("business"));
+ }
+
+ /** 住宅附加费按 RESIDENTIAL 与 MIXED 计。 */
+ @Test
+ void mixedCountsAsResidential() {
+ assertTrue(AddressType.RESIDENTIAL.residential());
+ assertTrue(AddressType.MIXED.residential());
+ assertFalse(AddressType.BUSINESS.residential());
+ assertFalse(AddressType.UNKNOWN.residential());
+ }
+
+ /** 真机确认五项必填:缺哪个报哪个,不发出去被仓方挡回来。 */
+ @Test
+ void classifyRejectsMissingRequiredParts() {
+ RecordingTransport transport = classifying("BUSINESS");
+ HengjianAdapter adapter = adapter(transport);
+
+ assertThrows(IllegalArgumentException.class,
+ () -> adapter.classifyAddress(CTX, null, null, "LA", "CA", "90001", "US"));
+ assertThrows(IllegalArgumentException.class,
+ () -> adapter.classifyAddress(CTX, "1 St", null, null, "CA", "90001", "US"));
+ assertThrows(IllegalArgumentException.class,
+ () -> adapter.classifyAddress(CTX, "1 St", null, "LA", null, "90001", "US"));
+ assertThrows(IllegalArgumentException.class,
+ () -> adapter.classifyAddress(CTX, "1 St", null, "LA", "CA", null, "US"));
+ assertThrows(IllegalArgumentException.class,
+ () -> adapter.classifyAddress(CTX, "1 St", null, "LA", "CA", "90001", null));
+ assertTrue(transport.dataRequests().isEmpty(), "本地校验失败不应发请求");
+ }
+
+ private static AddressType classifyAs(String raw) {
+ return adapter(classifying(raw)).classifyAddress(CTX, "1 St", null, "LA", "CA", "90001", "US");
+ }
+
+ // ================================================================ 能力位
+
+ @Test
+ void declaresEstimateAndAddressCapabilities() {
+ HengjianAdapter adapter = adapter(RecordingTransport.create());
+
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.FEE_ESTIMATE));
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.ADDRESS_CLASSIFICATION));
+ }
+}
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java
index 505c475..941f05b 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java
@@ -33,6 +33,13 @@ public final class YqnFeeEstimateMapper {
* @param defaultWarehouseCode 调用方未指定仓时的回退仓 code
*/
public static YqnFeeEstimateDtos.CalculateRequest toRequest(FeeEstimateQuery query, String defaultWarehouseCode) {
+ // 运去哪要求显式指定物流服务码;标准模型里它是选填(恒健允许不传),
+ // 所以在这里按运去哪的协议校验。
+ if (!query.hasLogisticsServiceCode()) {
+ throw new IllegalArgumentException(
+ "yqn fee estimate requires logisticsServiceCode; "
+ + "call logisticsProducts() first to pick an available service");
+ }
YqnFeeEstimateDtos.CalculateRequest req = new YqnFeeEstimateDtos.CalculateRequest();
req.sizeUnit = SIZE_UNIT_CM;
req.length = toDouble(query.lengthCm());