diff --git a/README.md b/README.md index 8ff74da..9b9d0ca 100644 --- a/README.md +++ b/README.md @@ -307,10 +307,11 @@ common.ecommerce │ │ InboundCommand / InboundLine / InboundCarton / InboundBatch / │ │ InboundReceipt / ReturnCommand / ReturnProcessCommand / │ │ WarehouseReturn / TransferCommand / TransferOrder / -│ │ BillingDocument / FeeQuery / +│ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult / │ │ TrackEvent / DestructionOrder │ ├── capability OutboundCapable / InventoryCapable / InboundCapable / -│ │ WarehouseReturnCapable / WarehouseFeeCapable / TransferCapable / +│ │ WarehouseReturnCapable / WarehouseFeeCapable / +│ │ WarehouseFeeEstimateCapable / TransferCapable / │ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable / │ │ WarehouseProduct / WarehouseProductCapable │ ├── error WarehouseException 及 Unsupported / CancelBlocked / CancelChargeRequired / diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeEstimateCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeEstimateCapable.java new file mode 100644 index 0000000..7ff67c8 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeEstimateCapable.java @@ -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; + +/** + * 运费试算能力:发货前按包裹 + 地址 + 渠道询价。 + * + *

与 {@link WarehouseFeeCapable} 不是一回事:那个查已发生的结算明细, + * 这个在发货前给报价。报价仅供参考,实际费用以结算账单为准。

+ * + *

按仓库维度返回:一个仓下可能有多个可选渠道。只读操作,无幂等要求。

+ */ +public interface WarehouseFeeEstimateCapable extends WarehouseAdapter { + + /** + * 试算运费。 + * + * @param query 包裹尺寸重量、收件地址与物流渠道;必填项在构造期已校验 + * @return 每个发货仓一条结果;仓方无可承运渠道时该仓的 {@code carriers()} 为空 + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不声明 {@code FEE_ESTIMATE} + */ + List estimate(WarehouseContext ctx, FeeEstimateQuery query); +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java new file mode 100644 index 0000000..4a2d638 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java @@ -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; + +/** + * 运费试算条件(下单前的费用预估,不是已发生的账单)。 + * + *

与 {@link FeeQuery} 是两条不同的路径:{@code FeeQuery} 查已经产生的结算明细, + * 本类用于发货前按包裹尺寸重量 + 收件地址 + 物流渠道询价。

+ * + *

单位写进字段名(cm / g),由适配器换算成仓方要求的单位,避免调用方按仓猜单位。

+ * + *

结果是「参考价」:实际费用以出库结算账单为准。

+ */ +public final class FeeEstimateQuery { + + /** 发货仓 code;空表示用账户配置的仓。 */ + private final List 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(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 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 warehouseCodes = new ArrayList(); + 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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateResult.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateResult.java new file mode 100644 index 0000000..3d8d8b4 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateResult.java @@ -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; + +/** + * 单个发货仓的运费试算结果。 + * + *

一个仓下可能有多个可选渠道(承运商 + 物流服务),每个渠道一笔总价与若干细分成本。 + * 这是报价,不是账单:实际费用以出库结算为准,用 {@link BillingDocument} 承载。

+ */ +public final class FeeEstimateResult { + + private final WarehouseProvider sourceProvider; + private final String shipOrgWarehouseCode; + private final List carriers; + + private FeeEstimateResult(Builder b) { + this.sourceProvider = b.sourceProvider; + this.shipOrgWarehouseCode = require(b.shipOrgWarehouseCode, "shipOrgWarehouseCode"); + this.carriers = Collections.unmodifiableList(new ArrayList(b.carriers)); + } + + public static Builder builder() { + return new Builder(); + } + + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + + /** 发货仓 code(仓方口径)。 */ + public String shipOrgWarehouseCode() { + return shipOrgWarehouseCode; + } + + /** 可选渠道报价;可能为空,表示该仓无法承运该包裹。 */ + public List 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 costItems; + + private CarrierQuote(Builder b) { + this.carrier = b.carrier; + this.logisticsServiceCode = b.logisticsServiceCode; + this.totalRate = b.totalRate; + this.costItems = Collections.unmodifiableList(new ArrayList(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 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 costItems = new ArrayList(); + + 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 carriers = new ArrayList(); + + 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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 0734815..6798330 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -11,6 +11,9 @@ import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; +import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; +import common.ecommerce.warehouse.model.FeeEstimateQuery; +import common.ecommerce.warehouse.model.FeeEstimateResult; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable; @@ -306,6 +309,23 @@ public final class WarehouseOperations { /** 费用视图。 */ public final class FeeView { + /** + * 发货前运费试算:按包裹尺寸重量 + 收件地址 + 物流渠道询价。 + * + *

只读,不走幂等。结果是报价,不是账单——实际费用请用 + * {@link #settlements(FeeQuery)} 查结算明细。

+ */ + public List estimate(FeeEstimateQuery query) { + require(WarehouseCapability.FEE_ESTIMATE, WarehouseFeeEstimateCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.fee.estimate", + CallSupport.params("receiveCountry", query.receiveCountry(), + "receivePostal", query.receivePostal(), + "logisticsServiceCode", query.logisticsServiceCode(), + "warehouseCount", query.warehouseCodes().size()), + List::size, + () -> ((WarehouseFeeEstimateCapable) adapter).estimate(ctx, query)); + } + /** 按条件拉取费用明细(预估与实际用 BillingDocument.estimated() 区分)。 */ public List settlements(FeeQuery query) { require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class); diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index f22f270..76cba53 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -50,6 +50,8 @@ public final class YqnConstants { public static final String PATH_TRACKING = "/cloudship/expressdelivery/GetTrackingStatus"; /** 结算明细(API 133):作业费 / 仓储费 / 增值服务费 / 尾程费。 */ public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail"; + /** 订单测算 / 运费试算(API 121):发货前按包裹 + 地址 + 渠道询价。 */ + public static final String PATH_FEE_ESTIMATE = "/v1/saleOrder/calculate"; /** Spec §7.5:三家仓均未公开限流值,保守默认 2 req/s/仓。 */ public static final int PERMITS_PER_SECOND = 2; diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 30c04ad..64f61ac 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -28,6 +28,9 @@ import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; +import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; +import common.ecommerce.warehouse.model.FeeEstimateQuery; +import common.ecommerce.warehouse.model.FeeEstimateResult; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; @@ -66,8 +69,8 @@ import java.util.Map; * 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。

*/ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, - WarehouseFeeCapable, InventoryCapable, InboundCapable, TransferCapable, - WarehouseReturnCapable { + WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable, + TransferCapable, WarehouseReturnCapable { /** 运去哪请求里的时间格式;待核对。 */ private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); @@ -101,6 +104,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl WarehouseCapability.OUTBOUND, WarehouseCapability.SPLIT, WarehouseCapability.FEE_SETTLEMENT, + WarehouseCapability.FEE_ESTIMATE, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND, WarehouseCapability.TRANSFER, @@ -304,6 +308,25 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl return out; } + /** + * 订单测算(API 121):发货前按包裹尺寸重量 + 收件地址 + 物流渠道询价。 + * + *

读接口,不走幂等。结果按仓库维度返回,一个仓下可能有多个渠道报价。 + * 报价仅供参考,实际费用以结算明细(API 133)为准。

+ */ + @Override + public List estimate(WarehouseContext ctx, FeeEstimateQuery query) { + YqnDtos.CalculateRequest body = + YqnFeeEstimateMapper.toRequest(query, ctx.providerWarehouseId()); + String raw = execute(ctx, YqnConstants.PATH_FEE_ESTIMATE, body, "warehouse.fee.estimate"); + List rows = json.listAt(raw, "data", YqnDtos.CalculateResult.class); + List out = new ArrayList(rows.size()); + for (YqnDtos.CalculateResult row : rows) { + out.add(YqnFeeEstimateMapper.toResult(row)); + } + return out; + } + // ------------------------------------------------------------------ 库存 /** diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java new file mode 100644 index 0000000..e6f6d7d --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java @@ -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 toWarehouseItems( + List warehouseCodes, String defaultWarehouseCode) { + List codes = warehouseCodes; + if (codes == null || codes.isEmpty()) { + codes = defaultWarehouseCode == null || defaultWarehouseCode.trim().isEmpty() + ? Collections.emptyList() + : Collections.singletonList(defaultWarehouseCode); + } + if (codes.isEmpty()) { + throw new IllegalArgumentException( + "yqn fee estimate needs a shipOrgWarehouseCode; none given and account has none"); + } + List items = + new ArrayList(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(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnLogisticsService.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnLogisticsService.java new file mode 100644 index 0000000..555bed5 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnLogisticsService.java @@ -0,0 +1,76 @@ +package common.ecommerce.yqn.enums; + +/** + * 运去哪物流产品服务码(API 121 的 {@code logisticsServiceCode})。 + * + *

取值来自接口文档的枚举清单,只有运去哪这一套——core 没有「物流服务渠道」 + * 的通用枚举,也不打算造一个:各仓的渠道划分口径不同,强行归一必然失真。 + * 因此本枚举只用来避免调用方手写字符串,不映射到 core。

+ * + *

文档把 {@code FedEx_INTERNATIONAL_ECONOMY} 等标注为「国际件」,这只是说明, + * 不做额外处理。

+ */ +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; + } +} diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnFeeEstimateTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnFeeEstimateTest.java new file mode 100644 index 0000000..72de513 --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnFeeEstimateTest.java @@ -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 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)); + } +}