Browse Source

feat(hengjian): 对接运费测算与地址属性识别

两个接口都在 /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 <noreply@anthropic.com>
master
lml 5 days ago
parent
commit
73892d6052
  1. 7
      README.md
  2. 3
      docs-warehouse/architecture.md
  3. 40
      docs-warehouse/hengjian/README.md
  4. 34
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/AddressClassificationCapable.java
  5. 56
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AddressType.java
  6. 4
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
  7. 26
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java
  8. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  9. 17
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  10. 79
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  11. 175
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java
  12. 58
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianAddressClassificationDtos.java
  13. 167
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java
  14. 266
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianEstimateTest.java
  15. 7
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java

7
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;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性) |
依赖方向:
```
@ -380,13 +380,14 @@ common.ecommerce @@ -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

3
docs-warehouse/architecture.md

@ -85,7 +85,7 @@ public enum YqnOutboundStatus { @@ -85,7 +85,7 @@ public enum YqnOutboundStatus {
`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略,
调用方不应假定排序一定生效。
`WarehouseCapability`(25 个):
`WarehouseCapability`(26 个):
| 能力 | 说明 | 运去哪 | 信仓 |
|---|---|:---:|:---:|
@ -106,6 +106,7 @@ public enum YqnOutboundStatus { @@ -106,6 +106,7 @@ public enum YqnOutboundStatus {
| `RETURN_DISPOSITION` | 退货条目处理 | ✅ | — |
| `TRACKING` | 物流轨迹 | ✅ | — |
| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
| `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — |
| `DESTRUCTION` | 销毁 / 报废 | ✅ | — |
| `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — |
| `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — |

40
docs-warehouse/hengjian/README.md

@ -73,7 +73,9 @@ @@ -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 @@ @@ -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`)—— 已接入
恒健把三类费用拆成<b>三个独立接口</b>,行字段完全不同:
@ -445,7 +477,8 @@ warehouse-sdk-hengjian/ @@ -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/ @@ -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. 探针用法

34
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/AddressClassificationCapable.java

@ -0,0 +1,34 @@ @@ -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;
/**
* 地址属性识别:判定收件地址是商业还是住宅。
*
* <p>与 {@link WarehouseFeeEstimateCapable} 分开:试算给价格,这个只给地址分类。
* 分类结果影响住宅附加费与分区计价,试算前先判一次能让报价更准;
* 也用于下单前校验地址是否可投递。</p>
*
* <p>只读、无幂等。恒健的试算响应里也带 {@code isResidential},
* 但只要分类、不要把试算的价格一起拉时用本能力。</p>
*/
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);
}

56
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AddressType.java

@ -0,0 +1,56 @@ @@ -0,0 +1,56 @@
package common.ecommerce.warehouse.enums;
/**
* 地址属性:判定收件地址是商业还是住宅。
*
* <p>直接影响<b>住宅附加费</b>(Residential Surcharge)与承运商分区计价,
* 所以单独一个能力位而不是藏在试算里。</p>
*
* <p>仓方码值由适配器映射:恒健回 {@code BUSINESS / RESIDENTIAL / MIXED / UNKNOWN}
* 四个英文词,其它仓可能是数字码。<b>认不出归 {@link #UNKNOWN},不猜</b>——
* 猜成住宅会多收客户钱,猜成商业会漏收。</p>
*/
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;
}
}

4
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java

@ -57,7 +57,9 @@ public enum WarehouseCapability { @@ -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;

26
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java

@ -53,7 +53,9 @@ public final class FeeEstimateQuery { @@ -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 { @@ -114,11 +116,22 @@ public final class FeeEstimateQuery {
return residential;
}
/** 物流产品服务码;取值由仓定义。 */
/**
* 物流产品服务码;取值由仓定义。
*
* <p><b>选填</b>:不给时由仓报出全部可用渠道(恒健的行为);要求必填的仓
* (运去哪等)会在适配器里拒绝,而不是在这里构造期卡死。
* 用 {@link #hasLogisticsServiceCode()} 判断是否给了。</p>
*/
public String logisticsServiceCode() {
return logisticsServiceCode;
}
/** 是否指定了物流服务码。 */
public boolean hasLogisticsServiceCode() {
return logisticsServiceCode != null;
}
public String logisticsProductCode() {
return logisticsProductCode;
}
@ -135,6 +148,14 @@ public final class FeeEstimateQuery { @@ -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 { @@ -222,6 +243,7 @@ public final class FeeEstimateQuery {
return this;
}
/** 物流服务码;选填,不给则由仓报全部渠道(要求必填的仓在适配器里拒绝)。 */
public Builder logisticsServiceCode(String v) {
this.logisticsServiceCode = v;
return this;

20
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -11,6 +11,7 @@ import common.ecommerce.warehouse.capability.InboundCapable; @@ -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 { @@ -645,6 +646,25 @@ public final class WarehouseOperations {
}
/**
* 地址属性识别:判定收件地址是商业 / 住宅(影响住宅附加费)。
*
* <p>只读,不走幂等。仓方给未知值或无法识别时返回
* {@code AddressType.UNKNOWN},<b>不返回 null</b>——调用方据此判断
* 「仓说不知道」而不是「调用失败」。</p>
*/
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 与邮编,由仓择优并给出全部报价。
*
* <p>只读,不走幂等。与 {@link #estimate(FeeEstimateQuery)} 的区别见

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

@ -138,6 +138,23 @@ public final class HengjianConstants { @@ -138,6 +138,23 @@ public final class HengjianConstants {
public static final int FEE_PAGE_SIZE_MAX = 200;
/**
* 运费测算。
*
* <p>真机确认存在;包裹四项 + 两个单位 + 收货方五项必填
* ({@code shipper*} 系列可省)。</p>
*/
public static final String PATH_FEE_ESTIMATE = "/v2/api/shipping/calculate";
/**
* 地址属性识别。
*
* <p><b>文档写的域名是 {@code open-api.thebizark.com}(别家),是本仓的笔误。</b>
* 真机确认本仓域名下正常返回 {@code data: "BUSINESS"} 等值。</p>
*/
public static final String PATH_ADDRESS_CLASSIFICATION =
"/v2/api/shipping/addressClassification";
/**
* {@code btChargeAt} 的日期区间分隔符。
*
* <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p>

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

@ -1,19 +1,21 @@ @@ -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; @@ -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; @@ -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; @@ -76,7 +83,8 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。</p>
*/
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 @@ -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 @@ -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})。
*
* <p>统一模型是 cm / g,恒健也接受 {@code cm} / {@code g},<b>不换算</b>;
* 但它的包裹尺寸字段是 INTEGER,所以厘米值四舍五入取整(截断会让报价偏低)。</p>
*
* <p>恒健不按仓维度返回报价,结果只有一个实例,
* {@code shipOrgWarehouseCode} 用账户仓填充。</p>
*/
@Override
public List<FeeEstimateResult> 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<FeeEstimateResult> out = new ArrayList<FeeEstimateResult>(1);
out.add(HengjianEstimateMapper.toResult(resp == null ? null : resp.data, warehouseCode));
return out;
}
/**
* 地址属性识别({@code POST /v2/api/shipping/addressClassification})。
*
* <p>真机确认五项必填({@code street1 / zip / city / state / country}),
* 缺任何一项仓方都回参数校验异常,所以本地先挡。</p>
*/
@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;
}
// ------------------------------------------------------------------ 计费明细
/**

175
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java

@ -0,0 +1,175 @@ @@ -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;
/**
* 恒健运费测算与地址属性映射。
*
* <h2>测算</h2>
* <p>统一模型是 cm / g;恒健的 {@code parcelLength} 等字段是 <b>INTEGER</b>,
* 所以厘米值要取整(四舍五入)——截断会让包裹尺寸偏小,报价偏低。</p>
*
* <p>价格口径:{@code original*} 是承运商牌价、{@code conversion*} 是折算价
* (客户实付)。统一模型的 {@code totalRate} 取<b>折算价</b>——那才是客户要付的钱。
* 牌价没有对应字段,只进费用明细的名称里(如果仓方给了的话)。</p>
*
* <h2>地址属性</h2>
* <p>恒健回四个英文词,映射到 {@link AddressType};<b>认不出归 UNKNOWN,不猜</b>——
* 猜错会多收或少收住宅附加费。</p>
*/
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() {
}
/**
* 统一试算条件 → 恒健请求。
*
* <p>文档把 {@code shipper*} 系列标为必填,但<b>真机校验信息里没有它们</b>,
* 所以不传。若真机后续要求,补上即可(模型里没有发货方信息,需调用方提供)。</p>
*/
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());
}
/**
* 报价数组 → 统一结果。
*
* <p>恒健<b>不按仓维度返回</b>(请求也没带仓),所以统一结果只有一个实例,
* {@code shipOrgWarehouseCode} 用账户仓填充——这是「这些报价适用于这个仓」的意思,
* 不是从响应里读出来的。</p>
*/
public static FeeEstimateResult toResult(List<HengjianFeeEstimateDtos.QuoteRow> 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;
}
}

58
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianAddressClassificationDtos.java

@ -0,0 +1,58 @@ @@ -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})。
*
* <p><b>路径域名的坑</b>:文档页写的链接是 {@code open-api.thebizark.com}
* (别家域名,疑似复制)。<b>真机确认</b>在本仓域名
* {@code pr-open-api.ehengjian.com} 上可以正常调用,见
* {@code HengjianConstants.PATH_ADDRESS_CLASSIFICATION}。</p>
*
* <p><b>真机确认</b>:{@code street1 / zip / city / state / country} 五项必填
* (缺任一项回「参数校验异常」);{@code street2} 选填。</p>
*
* <p>响应 {@code data} 是<b>字符串</b>而不是对象:
* {@code BUSINESS / RESIDENTIAL / MIXED / UNKNOWN}。</p>
*/
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;
}
}

167
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java

@ -0,0 +1,167 @@ @@ -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})。
*
* <p><b>真机确认的必填项</b>(文档标「否」的 {@code shipper*} 系列不在必填列表里):</p>
* <pre>
* parcelLength / parcelWidth / parcelHeight / parcelWeight /
* parcelLengthUnit / parcelWeightUnit /
* receiverCountryCode / receiverState / receiverCity / receiverZipcode /
* receiverAddressLine1
* </pre>
* <p>即<b>发货方信息可不传</b>(真机校验信息里没有 {@code shipper*}),收货方五项必填。</p>
*
* <p>单位可选值:长度 {@code inch} / {@code cm},重量 {@code oz} / {@code lbs} / {@code g}。
* 统一模型是 cm / g,适配器下发改成仓方接受的单位。</p>
*/
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<QuoteRow> data;
}
/**
* 一条渠道报价。
*
* <p>注意两个价格口径:{@code original*} 是<b>官方价</b>(承运商牌价),
* {@code conversion*} 是<b>折算价</b>(客户实际计价);两者可能差别很大
* (示例里官方 36.76、折算 18.38)。统一模型的 {@code totalRate} 用折算价——
* 那才是客户要付的钱。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class QuoteRow {
/** 承运商。 */
@JsonProperty("carrier")
public String carrier;
/**
* 物流产品服务码(响应示例里的 {@code logisticServiceCode})。
*
* <p>字段表没列,示例里有;与请求时的 {@code serviceCode} 不是同一个值
* (示例请求 {@code FEDHD}、响应 {@code FEDHD_HL})。</p>
*/
@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<CostItem> 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;
}
}
}

266
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianEstimateTest.java

@ -0,0 +1,266 @@ @@ -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<FeeEstimateResult> 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<FeeEstimateResult> 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));
}
}

7
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java

@ -33,6 +33,13 @@ public final class YqnFeeEstimateMapper { @@ -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());

Loading…
Cancel
Save