From 06961c6781adf3a354640af7d47ad224eb1831c4 Mon Sep 17 00:00:00 2001
From: chenchuchuan <13554600537@163.com>
Date: Tue, 10 Nov 2026 11:39:08 +0800
Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8C=89=20API=20121=20=E5=AF=B9?=
=?UTF-8?q?=E6=8E=A5=E8=AE=A2=E5=8D=95=E6=B5=8B=E7=AE=97=EF=BC=88=E8=BF=90?=
=?UTF-8?q?=E8=B4=B9=E8=AF=95=E7=AE=97=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
新能力,与既有结算明细(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
---
README.md | 5 +-
.../capability/WarehouseFeeEstimateCapable.java | 29 +++
.../warehouse/model/FeeEstimateQuery.java | 244 +++++++++++++++++++++
.../warehouse/model/FeeEstimateResult.java | 190 ++++++++++++++++
.../warehouse/sdk/WarehouseOperations.java | 20 ++
.../java/common/ecommerce/yqn/YqnConstants.java | 2 +
.../common/ecommerce/yqn/adapter/YqnAdapter.java | 27 ++-
.../yqn/adapter/YqnFeeEstimateMapper.java | 128 +++++++++++
.../ecommerce/yqn/enums/YqnLogisticsService.java | 76 +++++++
.../ecommerce/yqn/adapter/YqnFeeEstimateTest.java | 186 ++++++++++++++++
10 files changed, 903 insertions(+), 4 deletions(-)
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeEstimateCapable.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateResult.java
create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java
create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnLogisticsService.java
create mode 100644 warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnFeeEstimateTest.java
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));
+ }
+}