You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

188 lines
8.1 KiB

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>
5 days ago
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) {
test(hengjian): 只读探针补全全部查询接口,并用真机结果修 5 处映射 探针从 7 个用例扩到 21 个,覆盖全部已接入的查询接口(商品 / 库存 / 入库 / 调拨 / 退货 / 销毁 / 试算 / 地址 / 计费 / 目录)。 真机跑通 14 个接口,暴露并修掉这些问题: - 运费试算必须给「发运仓库」或「发运邮编」其一,否则 400。发运仓的 字段名是 warehouseCode,shipWarehouseCode / orgWarehouseCode / shipFromWarehouseCode 都不认(逐个试过)。core 的 FeeEstimateQuery 补 shipFromWarehouseCode,适配器用账户仓兜底 - 试算的 shipper* 给了不完整会报「发货人信息不完整」,所以要么只给 warehouseCode,要么给全五项 - 商品查询 length 真机确实有(文档响应表漏了),之前的兜底没触发 - 商品 nameEn 空值返回字符串 "null" 而不是 JSON null,trimToNull 一并当空 - 商品 cost 可为 0.0,是合法成本,原先当「没给」丢掉;且误塞进了 declaredValue(语义是申报价值),改为 cost - isInsuranceRate 是费率不是金额,不再塞进 insuranceFee(Money 是金额语义) - 响应有文档没写的 productStatus,保留原值到 rawStatus 另记录一条仓方故障:chargingSettlement 的 STORAGE 类型在测试环境返回 code=999999 + Elasticsearch scroll 异常,是恒健侧 ES 故障,我方报文正确。 销毁查询路径仍 404,探针标注未覆盖。token 只从 -Dhengjian.probe.token 读, 不入库。 mvn test 全量通过。
4 days ago
return toRequest(query, null);
}
/**
* 统一试算条件 → 恒健请求。
*
* @param fallbackWarehouseCode 调用方没给发运仓时的兜底(账户仓);恒健要求
* 「发运仓库」与「发运邮编」至少给一个
*/
public static HengjianFeeEstimateDtos.CalculateRequest toRequest(FeeEstimateQuery query,
String fallbackWarehouseCode) {
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>
5 days ago
HengjianFeeEstimateDtos.CalculateRequest req = new HengjianFeeEstimateDtos.CalculateRequest();
test(hengjian): 只读探针补全全部查询接口,并用真机结果修 5 处映射 探针从 7 个用例扩到 21 个,覆盖全部已接入的查询接口(商品 / 库存 / 入库 / 调拨 / 退货 / 销毁 / 试算 / 地址 / 计费 / 目录)。 真机跑通 14 个接口,暴露并修掉这些问题: - 运费试算必须给「发运仓库」或「发运邮编」其一,否则 400。发运仓的 字段名是 warehouseCode,shipWarehouseCode / orgWarehouseCode / shipFromWarehouseCode 都不认(逐个试过)。core 的 FeeEstimateQuery 补 shipFromWarehouseCode,适配器用账户仓兜底 - 试算的 shipper* 给了不完整会报「发货人信息不完整」,所以要么只给 warehouseCode,要么给全五项 - 商品查询 length 真机确实有(文档响应表漏了),之前的兜底没触发 - 商品 nameEn 空值返回字符串 "null" 而不是 JSON null,trimToNull 一并当空 - 商品 cost 可为 0.0,是合法成本,原先当「没给」丢掉;且误塞进了 declaredValue(语义是申报价值),改为 cost - isInsuranceRate 是费率不是金额,不再塞进 insuranceFee(Money 是金额语义) - 响应有文档没写的 productStatus,保留原值到 rawStatus 另记录一条仓方故障:chargingSettlement 的 STORAGE 类型在测试环境返回 code=999999 + Elasticsearch scroll 异常,是恒健侧 ES 故障,我方报文正确。 销毁查询路径仍 404,探针标注未覆盖。token 只从 -Dhengjian.probe.token 读, 不入库。 mvn test 全量通过。
4 days ago
req.warehouseCode = firstNonBlank(query.shipFromWarehouseCode(), fallbackWarehouseCode);
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>
5 days ago
// 恒健这几个字段是 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;
}
}