Browse Source
新能力,与既有结算明细(API 133 / FEE_SETTLEMENT)是两条路径: 后者查已发生的账单,这个在发货前按包裹 + 地址 + 渠道询价。 - FeeEstimateQuery:cm / g 为单位,适配器负责换算成仓方单位, 调用方不用按仓猜单位;isResidential 用 Boolean 三态,null 表示不传 - FeeEstimateResult:按仓库维度返回,一个仓下多个渠道报价, 每个渠道一笔总价 + 若干细分成本项 - WarehouseFeeEstimateCapable.estimate(ctx, query),入口 sdk.warehouses(...).fees().estimate(query),校验 FEE_ESTIMATE 能力位 logisticsServiceCode 有 29 个固定取值,建 YqnLogisticsService 枚举放 yqn 模块 (不映射到 core——各仓渠道划分口径不同,强行归一会失真);查询类仍接受字符串, 文档未收录的新渠道可直接透传。 报价仅供参考,实际费用以 BillingDocument 结算为准,已在 Javadoc 标注。 Co-Authored-By: Claude <noreply@anthropic.com>feature/supplier-lingxing
10 changed files with 903 additions and 4 deletions
@ -0,0 +1,29 @@ |
|||||||
|
package common.ecommerce.warehouse.capability; |
||||||
|
|
||||||
|
import common.ecommerce.warehouse.model.FeeEstimateQuery; |
||||||
|
import common.ecommerce.warehouse.model.FeeEstimateResult; |
||||||
|
import common.ecommerce.warehouse.sdk.WarehouseAdapter; |
||||||
|
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||||
|
|
||||||
|
import java.util.List; |
||||||
|
|
||||||
|
/** |
||||||
|
* 运费试算能力:发货前按包裹 + 地址 + 渠道询价。 |
||||||
|
* |
||||||
|
* <p><b>与 {@link WarehouseFeeCapable} 不是一回事</b>:那个查已发生的结算明细, |
||||||
|
* 这个在发货前给报价。报价仅供参考,实际费用以结算账单为准。</p> |
||||||
|
* |
||||||
|
* <p>按仓库维度返回:一个仓下可能有多个可选渠道。只读操作,无幂等要求。</p> |
||||||
|
*/ |
||||||
|
public interface WarehouseFeeEstimateCapable extends WarehouseAdapter { |
||||||
|
|
||||||
|
/** |
||||||
|
* 试算运费。 |
||||||
|
* |
||||||
|
* @param query 包裹尺寸重量、收件地址与物流渠道;必填项在构造期已校验 |
||||||
|
* @return 每个发货仓一条结果;仓方无可承运渠道时该仓的 {@code carriers()} 为空 |
||||||
|
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException |
||||||
|
* 该仓不声明 {@code FEE_ESTIMATE} |
||||||
|
*/ |
||||||
|
List<FeeEstimateResult> estimate(WarehouseContext ctx, FeeEstimateQuery query); |
||||||
|
} |
||||||
@ -0,0 +1,244 @@ |
|||||||
|
package common.ecommerce.warehouse.model; |
||||||
|
|
||||||
|
import common.ecommerce.shared.support.Money; |
||||||
|
|
||||||
|
import java.math.BigDecimal; |
||||||
|
import java.util.ArrayList; |
||||||
|
import java.util.Collections; |
||||||
|
import java.util.List; |
||||||
|
|
||||||
|
/** |
||||||
|
* 运费试算条件(下单前的费用预估,<b>不是</b>已发生的账单)。 |
||||||
|
* |
||||||
|
* <p>与 {@link FeeQuery} 是两条不同的路径:{@code FeeQuery} 查已经产生的结算明细, |
||||||
|
* 本类用于<b>发货前</b>按包裹尺寸重量 + 收件地址 + 物流渠道询价。</p> |
||||||
|
* |
||||||
|
* <p>单位写进字段名(cm / g),由适配器换算成仓方要求的单位,避免调用方按仓猜单位。</p> |
||||||
|
* |
||||||
|
* <p>结果是「参考价」:实际费用以出库结算账单为准。</p> |
||||||
|
*/ |
||||||
|
public final class FeeEstimateQuery { |
||||||
|
|
||||||
|
/** 发货仓 code;空表示用账户配置的仓。 */ |
||||||
|
private final List<String> warehouseCodes; |
||||||
|
private final BigDecimal lengthCm; |
||||||
|
private final BigDecimal widthCm; |
||||||
|
private final BigDecimal heightCm; |
||||||
|
private final BigDecimal weightGrams; |
||||||
|
/** 保价货值;null 表示不保价。币种口径由仓方账户决定。 */ |
||||||
|
private final Money insuredValue; |
||||||
|
private final String receiveCountry; |
||||||
|
private final String receiveState; |
||||||
|
private final String receiveCity; |
||||||
|
private final String receivePostal; |
||||||
|
private final String receiveAddress; |
||||||
|
/** 是否住宅地址;null 表示不传(仓方按默认口径)。 */ |
||||||
|
private final Boolean residential; |
||||||
|
/** 物流产品服务码,如 {@code FedEx_FEDEX_GROUND}。取值由各仓定义,适配器不做跨仓归一。 */ |
||||||
|
private final String logisticsServiceCode; |
||||||
|
private final String logisticsProductCode; |
||||||
|
/** 签名服务,如 {@code SIGNATURE}。 */ |
||||||
|
private final String signService; |
||||||
|
|
||||||
|
private FeeEstimateQuery(Builder b) { |
||||||
|
this.warehouseCodes = Collections.unmodifiableList(new ArrayList<String>(b.warehouseCodes)); |
||||||
|
this.lengthCm = requirePositive(b.lengthCm, "lengthCm"); |
||||||
|
this.widthCm = requirePositive(b.widthCm, "widthCm"); |
||||||
|
this.heightCm = requirePositive(b.heightCm, "heightCm"); |
||||||
|
this.weightGrams = requirePositive(b.weightGrams, "weightGrams"); |
||||||
|
this.insuredValue = b.insuredValue; |
||||||
|
this.receiveCountry = require(b.receiveCountry, "receiveCountry"); |
||||||
|
this.receiveState = b.receiveState; |
||||||
|
this.receiveCity = b.receiveCity; |
||||||
|
this.receivePostal = require(b.receivePostal, "receivePostal"); |
||||||
|
this.receiveAddress = b.receiveAddress; |
||||||
|
this.residential = b.residential; |
||||||
|
this.logisticsServiceCode = require(b.logisticsServiceCode, "logisticsServiceCode"); |
||||||
|
this.logisticsProductCode = b.logisticsProductCode; |
||||||
|
this.signService = b.signService; |
||||||
|
} |
||||||
|
|
||||||
|
public static Builder builder() { |
||||||
|
return new Builder(); |
||||||
|
} |
||||||
|
|
||||||
|
/** 发货仓 code 列表;空表示用账户配置的仓。 */ |
||||||
|
public List<String> warehouseCodes() { |
||||||
|
return warehouseCodes; |
||||||
|
} |
||||||
|
|
||||||
|
public BigDecimal lengthCm() { |
||||||
|
return lengthCm; |
||||||
|
} |
||||||
|
|
||||||
|
public BigDecimal widthCm() { |
||||||
|
return widthCm; |
||||||
|
} |
||||||
|
|
||||||
|
public BigDecimal heightCm() { |
||||||
|
return heightCm; |
||||||
|
} |
||||||
|
|
||||||
|
public BigDecimal weightGrams() { |
||||||
|
return weightGrams; |
||||||
|
} |
||||||
|
|
||||||
|
/** 保价货值;null 表示不保价。 */ |
||||||
|
public Money insuredValue() { |
||||||
|
return insuredValue; |
||||||
|
} |
||||||
|
|
||||||
|
/** ISO 3166-1 alpha-2,如 US。 */ |
||||||
|
public String receiveCountry() { |
||||||
|
return receiveCountry; |
||||||
|
} |
||||||
|
|
||||||
|
public String receiveState() { |
||||||
|
return receiveState; |
||||||
|
} |
||||||
|
|
||||||
|
public String receiveCity() { |
||||||
|
return receiveCity; |
||||||
|
} |
||||||
|
|
||||||
|
public String receivePostal() { |
||||||
|
return receivePostal; |
||||||
|
} |
||||||
|
|
||||||
|
public String receiveAddress() { |
||||||
|
return receiveAddress; |
||||||
|
} |
||||||
|
|
||||||
|
/** 是否住宅地址;null 表示不传。 */ |
||||||
|
public Boolean residential() { |
||||||
|
return residential; |
||||||
|
} |
||||||
|
|
||||||
|
/** 物流产品服务码;取值由仓定义。 */ |
||||||
|
public String logisticsServiceCode() { |
||||||
|
return logisticsServiceCode; |
||||||
|
} |
||||||
|
|
||||||
|
public String logisticsProductCode() { |
||||||
|
return logisticsProductCode; |
||||||
|
} |
||||||
|
|
||||||
|
/** 签名服务码。 */ |
||||||
|
public String signService() { |
||||||
|
return signService; |
||||||
|
} |
||||||
|
|
||||||
|
private static BigDecimal requirePositive(BigDecimal v, String name) { |
||||||
|
if (v == null || v.signum() <= 0) { |
||||||
|
throw new IllegalArgumentException(name + " must be positive"); |
||||||
|
} |
||||||
|
return v; |
||||||
|
} |
||||||
|
|
||||||
|
private static String require(String v, String name) { |
||||||
|
if (v == null || v.trim().isEmpty()) { |
||||||
|
throw new IllegalArgumentException(name + " must not be blank"); |
||||||
|
} |
||||||
|
return v.trim(); |
||||||
|
} |
||||||
|
|
||||||
|
public static final class Builder { |
||||||
|
|
||||||
|
private final List<String> warehouseCodes = new ArrayList<String>(); |
||||||
|
private BigDecimal lengthCm; |
||||||
|
private BigDecimal widthCm; |
||||||
|
private BigDecimal heightCm; |
||||||
|
private BigDecimal weightGrams; |
||||||
|
private Money insuredValue; |
||||||
|
private String receiveCountry; |
||||||
|
private String receiveState; |
||||||
|
private String receiveCity; |
||||||
|
private String receivePostal; |
||||||
|
private String receiveAddress; |
||||||
|
private Boolean residential; |
||||||
|
private String logisticsServiceCode; |
||||||
|
private String logisticsProductCode; |
||||||
|
private String signService; |
||||||
|
|
||||||
|
public Builder warehouseCode(String v) { |
||||||
|
if (v != null && !v.trim().isEmpty()) { |
||||||
|
this.warehouseCodes.add(v.trim()); |
||||||
|
} |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder lengthCm(BigDecimal v) { |
||||||
|
this.lengthCm = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder widthCm(BigDecimal v) { |
||||||
|
this.widthCm = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder heightCm(BigDecimal v) { |
||||||
|
this.heightCm = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder weightGrams(BigDecimal v) { |
||||||
|
this.weightGrams = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder insuredValue(Money v) { |
||||||
|
this.insuredValue = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder receiveCountry(String v) { |
||||||
|
this.receiveCountry = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder receiveState(String v) { |
||||||
|
this.receiveState = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder receiveCity(String v) { |
||||||
|
this.receiveCity = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder receivePostal(String v) { |
||||||
|
this.receivePostal = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder receiveAddress(String v) { |
||||||
|
this.receiveAddress = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder residential(Boolean v) { |
||||||
|
this.residential = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder logisticsServiceCode(String v) { |
||||||
|
this.logisticsServiceCode = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder logisticsProductCode(String v) { |
||||||
|
this.logisticsProductCode = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder signService(String v) { |
||||||
|
this.signService = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public FeeEstimateQuery build() { |
||||||
|
return new FeeEstimateQuery(this); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
@ -0,0 +1,190 @@ |
|||||||
|
package common.ecommerce.warehouse.model; |
||||||
|
|
||||||
|
import common.ecommerce.shared.support.Money; |
||||||
|
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||||
|
|
||||||
|
import java.util.ArrayList; |
||||||
|
import java.util.Collections; |
||||||
|
import java.util.List; |
||||||
|
|
||||||
|
/** |
||||||
|
* 单个发货仓的运费试算结果。 |
||||||
|
* |
||||||
|
* <p>一个仓下可能有多个可选渠道(承运商 + 物流服务),每个渠道一笔总价与若干细分成本。 |
||||||
|
* 这是<b>报价</b>,不是账单:实际费用以出库结算为准,用 {@link BillingDocument} 承载。</p> |
||||||
|
*/ |
||||||
|
public final class FeeEstimateResult { |
||||||
|
|
||||||
|
private final WarehouseProvider sourceProvider; |
||||||
|
private final String shipOrgWarehouseCode; |
||||||
|
private final List<CarrierQuote> carriers; |
||||||
|
|
||||||
|
private FeeEstimateResult(Builder b) { |
||||||
|
this.sourceProvider = b.sourceProvider; |
||||||
|
this.shipOrgWarehouseCode = require(b.shipOrgWarehouseCode, "shipOrgWarehouseCode"); |
||||||
|
this.carriers = Collections.unmodifiableList(new ArrayList<CarrierQuote>(b.carriers)); |
||||||
|
} |
||||||
|
|
||||||
|
public static Builder builder() { |
||||||
|
return new Builder(); |
||||||
|
} |
||||||
|
|
||||||
|
public WarehouseProvider sourceProvider() { |
||||||
|
return sourceProvider; |
||||||
|
} |
||||||
|
|
||||||
|
/** 发货仓 code(仓方口径)。 */ |
||||||
|
public String shipOrgWarehouseCode() { |
||||||
|
return shipOrgWarehouseCode; |
||||||
|
} |
||||||
|
|
||||||
|
/** 可选渠道报价;可能为空,表示该仓无法承运该包裹。 */ |
||||||
|
public List<CarrierQuote> carriers() { |
||||||
|
return carriers; |
||||||
|
} |
||||||
|
|
||||||
|
private static String require(String v, String name) { |
||||||
|
if (v == null || v.trim().isEmpty()) { |
||||||
|
throw new IllegalArgumentException(name + " must not be blank"); |
||||||
|
} |
||||||
|
return v.trim(); |
||||||
|
} |
||||||
|
|
||||||
|
/** 一个渠道的报价。 */ |
||||||
|
public static final class CarrierQuote { |
||||||
|
|
||||||
|
/** 承运商,如 {@code FEDEX}。 */ |
||||||
|
private final String carrier; |
||||||
|
/** 物流服务码,与查询时的 {@code logisticsServiceCode} 同一套取值。 */ |
||||||
|
private final String logisticsServiceCode; |
||||||
|
/** 总价;仓方未给时为 null。 */ |
||||||
|
private final Money totalRate; |
||||||
|
private final List<CostItem> costItems; |
||||||
|
|
||||||
|
private CarrierQuote(Builder b) { |
||||||
|
this.carrier = b.carrier; |
||||||
|
this.logisticsServiceCode = b.logisticsServiceCode; |
||||||
|
this.totalRate = b.totalRate; |
||||||
|
this.costItems = Collections.unmodifiableList(new ArrayList<CostItem>(b.costItems)); |
||||||
|
} |
||||||
|
|
||||||
|
public static Builder builder() { |
||||||
|
return new Builder(); |
||||||
|
} |
||||||
|
|
||||||
|
public String carrier() { |
||||||
|
return carrier; |
||||||
|
} |
||||||
|
|
||||||
|
public String logisticsServiceCode() { |
||||||
|
return logisticsServiceCode; |
||||||
|
} |
||||||
|
|
||||||
|
public Money totalRate() { |
||||||
|
return totalRate; |
||||||
|
} |
||||||
|
|
||||||
|
public List<CostItem> costItems() { |
||||||
|
return costItems; |
||||||
|
} |
||||||
|
|
||||||
|
/** 细分成本项,如「尾程运费」「燃油附加费」。 */ |
||||||
|
public static final class CostItem { |
||||||
|
|
||||||
|
private final String costName; |
||||||
|
private final Money estimatedCost; |
||||||
|
|
||||||
|
private CostItem(Builder b) { |
||||||
|
this.costName = b.costName; |
||||||
|
this.estimatedCost = b.estimatedCost; |
||||||
|
} |
||||||
|
|
||||||
|
public static Builder builder() { |
||||||
|
return new Builder(); |
||||||
|
} |
||||||
|
|
||||||
|
public String costName() { |
||||||
|
return costName; |
||||||
|
} |
||||||
|
|
||||||
|
public Money estimatedCost() { |
||||||
|
return estimatedCost; |
||||||
|
} |
||||||
|
|
||||||
|
public static final class Builder { |
||||||
|
private String costName; |
||||||
|
private Money estimatedCost; |
||||||
|
|
||||||
|
public Builder costName(String v) { |
||||||
|
this.costName = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder estimatedCost(Money v) { |
||||||
|
this.estimatedCost = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public CostItem build() { |
||||||
|
return new CostItem(this); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
public static final class Builder { |
||||||
|
private String carrier; |
||||||
|
private String logisticsServiceCode; |
||||||
|
private Money totalRate; |
||||||
|
private final List<CostItem> costItems = new ArrayList<CostItem>(); |
||||||
|
|
||||||
|
public Builder carrier(String v) { |
||||||
|
this.carrier = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder logisticsServiceCode(String v) { |
||||||
|
this.logisticsServiceCode = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder totalRate(Money v) { |
||||||
|
this.totalRate = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder costItem(CostItem v) { |
||||||
|
this.costItems.add(v); |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public CarrierQuote build() { |
||||||
|
return new CarrierQuote(this); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
public static final class Builder { |
||||||
|
private WarehouseProvider sourceProvider; |
||||||
|
private String shipOrgWarehouseCode; |
||||||
|
private final List<CarrierQuote> carriers = new ArrayList<CarrierQuote>(); |
||||||
|
|
||||||
|
public Builder sourceProvider(WarehouseProvider v) { |
||||||
|
this.sourceProvider = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder shipOrgWarehouseCode(String v) { |
||||||
|
this.shipOrgWarehouseCode = v; |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public Builder carrier(CarrierQuote v) { |
||||||
|
this.carriers.add(v); |
||||||
|
return this; |
||||||
|
} |
||||||
|
|
||||||
|
public FeeEstimateResult build() { |
||||||
|
return new FeeEstimateResult(this); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
@ -0,0 +1,128 @@ |
|||||||
|
package common.ecommerce.yqn.adapter; |
||||||
|
|
||||||
|
import common.ecommerce.shared.support.Money; |
||||||
|
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||||
|
import common.ecommerce.warehouse.model.FeeEstimateQuery; |
||||||
|
import common.ecommerce.warehouse.model.FeeEstimateResult; |
||||||
|
import common.ecommerce.yqn.dto.YqnDtos; |
||||||
|
|
||||||
|
import java.math.BigDecimal; |
||||||
|
import java.util.ArrayList; |
||||||
|
import java.util.Collections; |
||||||
|
import java.util.List; |
||||||
|
|
||||||
|
/** |
||||||
|
* 运去哪运费试算报文映射(API 121,{@code /v1/saleOrder/calculate})。 |
||||||
|
*/ |
||||||
|
public final class YqnFeeEstimateMapper { |
||||||
|
|
||||||
|
/** 尺寸单位:厘米。 */ |
||||||
|
private static final int SIZE_UNIT_CM = 1; |
||||||
|
/** 重量单位:克。 */ |
||||||
|
private static final int WEIGHT_UNIT_GRAM = 2; |
||||||
|
/** 运去哪未给币种时的回退值;文档所有金额均为 USD。 */ |
||||||
|
private static final String DEFAULT_CURRENCY = "USD"; |
||||||
|
|
||||||
|
private YqnFeeEstimateMapper() { |
||||||
|
} |
||||||
|
|
||||||
|
/** |
||||||
|
* 统一试算条件 → 运去哪请求。 |
||||||
|
* |
||||||
|
* @param query 统一条件(cm / g) |
||||||
|
* @param defaultWarehouseCode 调用方未指定仓时的回退仓 code |
||||||
|
*/ |
||||||
|
public static YqnDtos.CalculateRequest toRequest(FeeEstimateQuery query, String defaultWarehouseCode) { |
||||||
|
YqnDtos.CalculateRequest req = new YqnDtos.CalculateRequest(); |
||||||
|
req.sizeUnit = SIZE_UNIT_CM; |
||||||
|
req.length = toDouble(query.lengthCm()); |
||||||
|
req.width = toDouble(query.widthCm()); |
||||||
|
req.height = toDouble(query.heightCm()); |
||||||
|
req.weightUnit = WEIGHT_UNIT_GRAM; |
||||||
|
req.weight = toDouble(query.weightGrams()); |
||||||
|
if (query.insuredValue() != null) { |
||||||
|
req.insuredValue = query.insuredValue().amount().doubleValue(); |
||||||
|
} |
||||||
|
req.warehouseSkuItem = toWarehouseItems(query.warehouseCodes(), defaultWarehouseCode); |
||||||
|
req.receiveCountry = query.receiveCountry(); |
||||||
|
req.receiveState = query.receiveState(); |
||||||
|
req.receiveCity = query.receiveCity(); |
||||||
|
req.receivePostal = query.receivePostal(); |
||||||
|
req.receiveAddress = query.receiveAddress(); |
||||||
|
if (query.residential() != null) { |
||||||
|
req.isResidential = query.residential() ? 1 : 0; |
||||||
|
} |
||||||
|
req.logisticsServiceCode = query.logisticsServiceCode(); |
||||||
|
req.logisticsProductCode = query.logisticsProductCode(); |
||||||
|
req.signService = query.signService(); |
||||||
|
return req; |
||||||
|
} |
||||||
|
|
||||||
|
private static List<YqnDtos.CalculateRequest.CalculateSkuItem> toWarehouseItems( |
||||||
|
List<String> warehouseCodes, String defaultWarehouseCode) { |
||||||
|
List<String> codes = warehouseCodes; |
||||||
|
if (codes == null || codes.isEmpty()) { |
||||||
|
codes = defaultWarehouseCode == null || defaultWarehouseCode.trim().isEmpty() |
||||||
|
? Collections.<String>emptyList() |
||||||
|
: Collections.singletonList(defaultWarehouseCode); |
||||||
|
} |
||||||
|
if (codes.isEmpty()) { |
||||||
|
throw new IllegalArgumentException( |
||||||
|
"yqn fee estimate needs a shipOrgWarehouseCode; none given and account has none"); |
||||||
|
} |
||||||
|
List<YqnDtos.CalculateRequest.CalculateSkuItem> items = |
||||||
|
new ArrayList<YqnDtos.CalculateRequest.CalculateSkuItem>(codes.size()); |
||||||
|
for (String code : codes) { |
||||||
|
YqnDtos.CalculateRequest.CalculateSkuItem item = |
||||||
|
new YqnDtos.CalculateRequest.CalculateSkuItem(); |
||||||
|
item.shipOrgWarehouseCode = code; |
||||||
|
items.add(item); |
||||||
|
} |
||||||
|
return items; |
||||||
|
} |
||||||
|
|
||||||
|
/** 运去哪一条仓库结果 → 统一结果。 */ |
||||||
|
public static FeeEstimateResult toResult(YqnDtos.CalculateResult row) { |
||||||
|
FeeEstimateResult.Builder builder = FeeEstimateResult.builder() |
||||||
|
.sourceProvider(WarehouseProvider.YQN) |
||||||
|
.shipOrgWarehouseCode(row.shipOrgWarehouseCode); |
||||||
|
if (row.calculationCarrierItems != null) { |
||||||
|
for (YqnDtos.CalculateResult.CalculateCarrierItem carrier : row.calculationCarrierItems) { |
||||||
|
builder.carrier(toQuote(carrier)); |
||||||
|
} |
||||||
|
} |
||||||
|
return builder.build(); |
||||||
|
} |
||||||
|
|
||||||
|
private static FeeEstimateResult.CarrierQuote toQuote( |
||||||
|
YqnDtos.CalculateResult.CalculateCarrierItem item) { |
||||||
|
String currency = hasText(item.currency) ? item.currency.trim() : DEFAULT_CURRENCY; |
||||||
|
FeeEstimateResult.CarrierQuote.Builder quote = FeeEstimateResult.CarrierQuote.builder() |
||||||
|
.carrier(item.carrier) |
||||||
|
.logisticsServiceCode(item.logisticsServiceCode) |
||||||
|
.totalRate(item.totalRate == null ? null : money(item.totalRate, currency)); |
||||||
|
if (item.calculationCostItems != null) { |
||||||
|
for (YqnDtos.CalculateResult.CalculateCostItem cost : item.calculationCostItems) { |
||||||
|
quote.costItem(FeeEstimateResult.CarrierQuote.CostItem.builder() |
||||||
|
.costName(cost.costName) |
||||||
|
.estimatedCost(cost.estimatedCost == null ? null |
||||||
|
: money(cost.estimatedCost, |
||||||
|
hasText(cost.currency) ? cost.currency.trim() : currency)) |
||||||
|
.build()); |
||||||
|
} |
||||||
|
} |
||||||
|
return quote.build(); |
||||||
|
} |
||||||
|
|
||||||
|
private static Money money(Double amount, String currency) { |
||||||
|
return Money.of(BigDecimal.valueOf(amount), currency); |
||||||
|
} |
||||||
|
|
||||||
|
private static Double toDouble(BigDecimal v) { |
||||||
|
return v == null ? null : v.doubleValue(); |
||||||
|
} |
||||||
|
|
||||||
|
private static boolean hasText(String v) { |
||||||
|
return v != null && !v.trim().isEmpty(); |
||||||
|
} |
||||||
|
} |
||||||
@ -0,0 +1,76 @@ |
|||||||
|
package common.ecommerce.yqn.enums; |
||||||
|
|
||||||
|
/** |
||||||
|
* 运去哪物流产品服务码(API 121 的 {@code logisticsServiceCode})。 |
||||||
|
* |
||||||
|
* <p>取值来自接口文档的枚举清单,<b>只有运去哪这一套</b>——core 没有「物流服务渠道」 |
||||||
|
* 的通用枚举,也不打算造一个:各仓的渠道划分口径不同,强行归一必然失真。 |
||||||
|
* 因此本枚举只用来避免调用方手写字符串,不映射到 core。</p> |
||||||
|
* |
||||||
|
* <p>文档把 {@code FedEx_INTERNATIONAL_ECONOMY} 等标注为「国际件」,这只是说明, |
||||||
|
* 不做额外处理。</p> |
||||||
|
*/ |
||||||
|
public enum YqnLogisticsService { |
||||||
|
|
||||||
|
// FedEx
|
||||||
|
FEDEX_GROUND("FedEx_FEDEX_GROUND"), |
||||||
|
FEDEX_GROUND_HOME_DELIVERY("FedEx_GROUND_HOME_DELIVERY"), |
||||||
|
FEDEX_SMART_POST("FedEx_SMART_POST"), |
||||||
|
/** 国际件。 */ |
||||||
|
FEDEX_INTERNATIONAL_ECONOMY("FedEx_INTERNATIONAL_ECONOMY"), |
||||||
|
/** 国际件。 */ |
||||||
|
FEDEX_INTERNATIONAL_PRIORITY("FedEx_INTERNATIONAL_PRIORITY"), |
||||||
|
FEDEX_2_DAY("FedEx_FEDEX_2_DAY"), |
||||||
|
FEDEX_EXPRESS_SAVER("FedEx_FEDEX_EXPRESS_SAVER"), |
||||||
|
FEDEX_PRIORITY_OVERNIGHT("FedEx_PRIORITY_OVERNIGHT"), |
||||||
|
FEDEX_STANDARD_OVERNIGHT("FedEx_STANDARD_OVERNIGHT"), |
||||||
|
FEDEX_FIRST_OVERNIGHT("FedEx_FIRST_OVERNIGHT"), |
||||||
|
|
||||||
|
// UPS
|
||||||
|
UPSA_MAIL_INNOVATIONS("UPSA_Mail_Innovations"), |
||||||
|
UPSA_GROUND("UPSA_GROUND"), |
||||||
|
UPS_GROUND("UPS_Ground"), |
||||||
|
UPS_2DA("UPS_UPS2DAM"), |
||||||
|
UPS_3DAY_SELECT("UPS_3DaySelect"), |
||||||
|
UPS_NEXT_DAY_AIR("UPS_NextDayAir"), |
||||||
|
UPS_NEXT_DAY_AIR_SAVER("UPS_NextDayAirSaver"), |
||||||
|
UPS_NEXT_DAY_AIR_EARLY_AM("UPS_NextDayAirEarlyAM"), |
||||||
|
UPS_2ND_DAY_AIR("UPS_2ndDayAir"), |
||||||
|
/** 国际件。 */ |
||||||
|
UPSCA_XI("UPSCA_XI_UPSGCA_XI"), |
||||||
|
|
||||||
|
// 其它承运商
|
||||||
|
JT_BASIC("JT_Basic"), |
||||||
|
AMAZON_SP_GROUND("AmazonSP_Ground"), |
||||||
|
AMAZON_SP0_GROUND("AmazonSP0_Ground"), |
||||||
|
AMAZON_SP1_GROUND("AmazonSP1_Ground"), |
||||||
|
AMAZON_SP2_GROUND("AmazonSP2_Ground"), |
||||||
|
USPS_GROUND_ADVANTAGE("USPS_Ground_Advantage"), |
||||||
|
USPS_PRIORITY_MAIL("USPS_Priority_Mail"), |
||||||
|
ONTRAC_GROUND("Ontrac_Ground"), |
||||||
|
IMILE_BASIC("iMile_Basic"); |
||||||
|
|
||||||
|
private final String code; |
||||||
|
|
||||||
|
YqnLogisticsService(String code) { |
||||||
|
this.code = code; |
||||||
|
} |
||||||
|
|
||||||
|
/** 运去哪请求里要填的原值。 */ |
||||||
|
public String code() { |
||||||
|
return code; |
||||||
|
} |
||||||
|
|
||||||
|
/** 按码值反查;未知返回 null(调用方可继续用字符串透传未收录的码)。 */ |
||||||
|
public static YqnLogisticsService of(String code) { |
||||||
|
if (code == null) { |
||||||
|
return null; |
||||||
|
} |
||||||
|
for (YqnLogisticsService v : values()) { |
||||||
|
if (v.code.equals(code)) { |
||||||
|
return v; |
||||||
|
} |
||||||
|
} |
||||||
|
return null; |
||||||
|
} |
||||||
|
} |
||||||
@ -0,0 +1,186 @@ |
|||||||
|
package common.ecommerce.yqn.adapter; |
||||||
|
|
||||||
|
import common.ecommerce.http.JacksonJsonCodec; |
||||||
|
import common.ecommerce.shared.spi.ChannelSecret; |
||||||
|
import common.ecommerce.shared.support.Money; |
||||||
|
import common.ecommerce.shared.testkit.RecordingTransport; |
||||||
|
import common.ecommerce.shared.testkit.Responses; |
||||||
|
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 common.ecommerce.yqn.YqnConstants; |
||||||
|
import common.ecommerce.yqn.enums.YqnLogisticsService; |
||||||
|
import org.junit.jupiter.api.Test; |
||||||
|
|
||||||
|
import java.math.BigDecimal; |
||||||
|
import java.time.Clock; |
||||||
|
import java.time.Instant; |
||||||
|
import java.time.ZoneOffset; |
||||||
|
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.assertNull; |
||||||
|
import static org.junit.jupiter.api.Assertions.assertThrows; |
||||||
|
import static org.junit.jupiter.api.Assertions.assertTrue; |
||||||
|
|
||||||
|
/** |
||||||
|
* 订单测算 / 运费试算(API 121)契约测试。 |
||||||
|
*/ |
||||||
|
class YqnFeeEstimateTest { |
||||||
|
|
||||||
|
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC); |
||||||
|
|
||||||
|
private static WarehouseContext ctx() { |
||||||
|
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", |
||||||
|
WarehouseConnection.of(YqnConstants.PR_BASE_URL, |
||||||
|
ChannelSecret.builder().appSecret("key-1").build()), |
||||||
|
"req-estimate", CLOCK); |
||||||
|
} |
||||||
|
|
||||||
|
private static FeeEstimateQuery query() { |
||||||
|
return FeeEstimateQuery.builder() |
||||||
|
.warehouseCode("RF_NY_US") |
||||||
|
.lengthCm(new BigDecimal("30")) |
||||||
|
.widthCm(new BigDecimal("20")) |
||||||
|
.heightCm(new BigDecimal("10")) |
||||||
|
.weightGrams(new BigDecimal("500")) |
||||||
|
.insuredValue(Money.of("100.00", "USD")) |
||||||
|
.receiveCountry("US") |
||||||
|
.receiveState("NY") |
||||||
|
.receiveCity("New York") |
||||||
|
.receivePostal("10001") |
||||||
|
.receiveAddress("1 Main St") |
||||||
|
.residential(true) |
||||||
|
.logisticsServiceCode(YqnLogisticsService.FEDEX_GROUND.code()) |
||||||
|
.signService("SIGNATURE") |
||||||
|
.build(); |
||||||
|
} |
||||||
|
|
||||||
|
@Test |
||||||
|
void sendsUnitsInCmAndGrams() { |
||||||
|
RecordingTransport transport = RecordingTransport.create() |
||||||
|
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||||
|
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[]}")); |
||||||
|
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), query()); |
||||||
|
|
||||||
|
String body = transport.lastDataRequest().body(); |
||||||
|
assertTrue(body.contains("\"sizeUnit\":1"), body); |
||||||
|
assertTrue(body.contains("\"weightUnit\":2"), body); |
||||||
|
assertTrue(body.contains("\"length\":30.0"), body); |
||||||
|
assertTrue(body.contains("\"weight\":500.0"), body); |
||||||
|
assertTrue(body.contains("\"isResidential\":1"), body); |
||||||
|
assertTrue(body.contains("\"shipOrgWarehouseCode\":\"RF_NY_US\""), body); |
||||||
|
assertTrue(body.contains("\"logisticsServiceCode\":\"FedEx_FEDEX_GROUND\""), body); |
||||||
|
assertTrue(body.contains("\"receivePostal\":\"10001\""), body); |
||||||
|
} |
||||||
|
|
||||||
|
@Test |
||||||
|
void omitsResidentialWhenNotGiven() { |
||||||
|
FeeEstimateQuery withoutResidential = FeeEstimateQuery.builder() |
||||||
|
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE) |
||||||
|
.weightGrams(BigDecimal.ONE) |
||||||
|
.receiveCountry("US").receivePostal("10001") |
||||||
|
.logisticsServiceCode(YqnLogisticsService.UPS_GROUND.code()) |
||||||
|
.build(); |
||||||
|
RecordingTransport transport = RecordingTransport.create() |
||||||
|
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||||
|
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":[]}")); |
||||||
|
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), withoutResidential); |
||||||
|
|
||||||
|
assertFalse(transport.lastDataRequest().body().contains("isResidential")); |
||||||
|
} |
||||||
|
|
||||||
|
@Test |
||||||
|
void fallsBackToAccountWarehouseWhenNoneGiven() { |
||||||
|
FeeEstimateQuery noWarehouse = FeeEstimateQuery.builder() |
||||||
|
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE) |
||||||
|
.weightGrams(BigDecimal.ONE) |
||||||
|
.receiveCountry("US").receivePostal("10001") |
||||||
|
.logisticsServiceCode(YqnLogisticsService.USPS_PRIORITY_MAIL.code()) |
||||||
|
.build(); |
||||||
|
RecordingTransport transport = RecordingTransport.create() |
||||||
|
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||||
|
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":[]}")); |
||||||
|
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), noWarehouse); |
||||||
|
|
||||||
|
assertTrue(transport.lastDataRequest().body() |
||||||
|
.contains("\"shipOrgWarehouseCode\":\"RF_NY_US\"")); |
||||||
|
} |
||||||
|
|
||||||
|
@Test |
||||||
|
void mapsCarriersAndCostItems() { |
||||||
|
RecordingTransport transport = RecordingTransport.create() |
||||||
|
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||||
|
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[" |
||||||
|
+ "{\"shipOrgWarehouseCode\":\"RF_NY_US\",\"calculationCarrierItems\":[" |
||||||
|
+ "{\"carrier\":\"FEDEX\",\"logisticsServiceCode\":\"FedEx_FEDEX_GROUND\"," |
||||||
|
+ "\"currency\":\"USD\",\"totalRate\":12.5," |
||||||
|
+ "\"calculationCostItems\":[" |
||||||
|
+ "{\"costName\":\"尾程运费\",\"estimatedCost\":10.0,\"currency\":\"USD\"}," |
||||||
|
+ "{\"costName\":\"燃油附加费\",\"estimatedCost\":2.5,\"currency\":\"USD\"}]}]}]}")); |
||||||
|
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||||
|
|
||||||
|
List<FeeEstimateResult> results = adapter.estimate(ctx(), query()); |
||||||
|
|
||||||
|
assertEquals(1, results.size()); |
||||||
|
FeeEstimateResult result = results.get(0); |
||||||
|
assertEquals(WarehouseProvider.YQN, result.sourceProvider()); |
||||||
|
assertEquals("RF_NY_US", result.shipOrgWarehouseCode()); |
||||||
|
assertEquals(1, result.carriers().size()); |
||||||
|
|
||||||
|
FeeEstimateResult.CarrierQuote quote = result.carriers().get(0); |
||||||
|
assertEquals("FEDEX", quote.carrier()); |
||||||
|
assertEquals("FedEx_FEDEX_GROUND", quote.logisticsServiceCode()); |
||||||
|
assertEquals(new BigDecimal("12.5"), quote.totalRate().amount()); |
||||||
|
assertEquals("USD", quote.totalRate().currency().getCurrencyCode()); |
||||||
|
assertEquals(2, quote.costItems().size()); |
||||||
|
assertEquals("尾程运费", quote.costItems().get(0).costName()); |
||||||
|
assertEquals(new BigDecimal("10.0"), quote.costItems().get(0).estimatedCost().amount()); |
||||||
|
} |
||||||
|
|
||||||
|
@Test |
||||||
|
void emptyDataIsNotAnError() { |
||||||
|
RecordingTransport transport = RecordingTransport.create() |
||||||
|
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||||
|
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[]}")); |
||||||
|
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||||
|
|
||||||
|
assertTrue(adapter.estimate(ctx(), query()).isEmpty()); |
||||||
|
} |
||||||
|
|
||||||
|
@Test |
||||||
|
void declaresFeeEstimateCapability() { |
||||||
|
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); |
||||||
|
assertTrue(adapter.capabilities().contains(WarehouseCapability.FEE_ESTIMATE)); |
||||||
|
// 试算与结算明细是两个能力,互不替代
|
||||||
|
assertTrue(adapter.capabilities().contains(WarehouseCapability.FEE_SETTLEMENT)); |
||||||
|
} |
||||||
|
|
||||||
|
@Test |
||||||
|
void queryRequiresPositiveDimensions() { |
||||||
|
assertThrows(IllegalArgumentException.class, () -> FeeEstimateQuery.builder() |
||||||
|
.lengthCm(BigDecimal.ZERO).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE) |
||||||
|
.weightGrams(BigDecimal.ONE) |
||||||
|
.receiveCountry("US").receivePostal("10001") |
||||||
|
.logisticsServiceCode("x") |
||||||
|
.build()); |
||||||
|
assertThrows(IllegalArgumentException.class, () -> FeeEstimateQuery.builder() |
||||||
|
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE) |
||||||
|
.weightGrams(BigDecimal.ONE) |
||||||
|
.receiveCountry("US") |
||||||
|
.logisticsServiceCode("x") |
||||||
|
.build()); |
||||||
|
} |
||||||
|
|
||||||
|
@Test |
||||||
|
void logisticsServiceEnumRoundTrips() { |
||||||
|
assertEquals("iMile_Basic", YqnLogisticsService.IMILE_BASIC.code()); |
||||||
|
assertEquals(YqnLogisticsService.UPS_GROUND, YqnLogisticsService.of("UPS_Ground")); |
||||||
|
assertNull(YqnLogisticsService.of("SOME_NEW_CHANNEL")); |
||||||
|
assertNull(YqnLogisticsService.of(null)); |
||||||
|
} |
||||||
|
} |
||||||
Loading…
Reference in new issue