Browse Source
两个接口都在 /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
15 changed files with 944 additions and 15 deletions
@ -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); |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
} |
||||
@ -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)); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue