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 @@
@@ -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 @@
@@ -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 @@
@@ -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 @@
@@ -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 @@
@@ -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 @@
@@ -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