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