Browse Source

feat(yqn): 按 API 121 对接订单测算(运费试算)

新能力,与既有结算明细(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
chenchuchuan 2 weeks ago
parent
commit
06961c6781
  1. 5
      README.md
  2. 29
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeEstimateCapable.java
  3. 244
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java
  4. 190
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateResult.java
  5. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  6. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  7. 27
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  8. 128
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java
  9. 76
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnLogisticsService.java
  10. 186
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnFeeEstimateTest.java

5
README.md

@ -307,10 +307,11 @@ common.ecommerce @@ -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 /

29
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeEstimateCapable.java

@ -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);
}

244
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java

@ -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);
}
}
}

190
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateResult.java

@ -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);
}
}
}

20
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -11,6 +11,9 @@ import common.ecommerce.warehouse.capability.InboundCapable; @@ -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 { @@ -306,6 +309,23 @@ public final class WarehouseOperations {
/** 费用视图。 */
public final class FeeView {
/**
* 发货前运费试算:按包裹尺寸重量 + 收件地址 + 物流渠道询价。
*
* <p>只读,不走幂等。结果是报价,不是账单——实际费用请用
* {@link #settlements(FeeQuery)} 查结算明细。</p>
*/
public List<FeeEstimateResult> 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<BillingDocument> settlements(FeeQuery query) {
require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class);

2
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -50,6 +50,8 @@ public final class YqnConstants { @@ -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;

27
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -28,6 +28,9 @@ import common.ecommerce.warehouse.capability.InventoryCapable; @@ -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; @@ -66,8 +69,8 @@ import java.util.Map;
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p>
*/
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 @@ -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 @@ -304,6 +308,25 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
return out;
}
/**
* 订单测算(API 121):发货前按包裹尺寸重量 + 收件地址 + 物流渠道询价。
*
* <p>读接口,不走幂等。结果按仓库维度返回,一个仓下可能有多个渠道报价。
* 报价仅供参考,实际费用以结算明细(API 133)为准。</p>
*/
@Override
public List<FeeEstimateResult> 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<YqnDtos.CalculateResult> rows = json.listAt(raw, "data", YqnDtos.CalculateResult.class);
List<FeeEstimateResult> out = new ArrayList<FeeEstimateResult>(rows.size());
for (YqnDtos.CalculateResult row : rows) {
out.add(YqnFeeEstimateMapper.toResult(row));
}
return out;
}
// ------------------------------------------------------------------ 库存
/**

128
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java

@ -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();
}
}

76
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnLogisticsService.java

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

186
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnFeeEstimateTest.java

@ -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…
Cancel
Save