diff --git a/README.md b/README.md
index 45e7cc5..54813e3 100644
--- a/README.md
+++ b/README.md
@@ -135,7 +135,7 @@ sequenceDiagram
| `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter |
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
-| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除) |
+| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道) |
依赖方向:
```
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseChannelRecommendCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseChannelRecommendCapable.java
new file mode 100644
index 0000000..368393c
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseChannelRecommendCapable.java
@@ -0,0 +1,28 @@
+package common.ecommerce.warehouse.capability;
+
+import common.ecommerce.warehouse.model.ChannelRecommendQuery;
+import common.ecommerce.warehouse.model.ChannelRecommendResult;
+import common.ecommerce.warehouse.sdk.WarehouseAdapter;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+
+/**
+ * 最优渠道推荐能力:给定 SKU 与目的地邮编,由仓给出推荐仓 + 渠道与全部报价。
+ *
+ *
与 {@link WarehouseFeeEstimateCapable} 不是一回事:那个要求调用方
+ * 指定包裹尺寸重量与物流渠道,问「这么发多少钱」;本能力只给货品与邮编,
+ * 由仓回答「发哪儿、走哪条渠道、多少钱」。
+ *
+ * 只读操作,无幂等要求。
+ */
+public interface WarehouseChannelRecommendCapable extends WarehouseAdapter {
+
+ /**
+ * 询价并取推荐方案。
+ *
+ * @param query SKU 与件数、目的地邮编;必填项在构造期已校验
+ * @return 仓方推荐方案 + 全部仓 × 渠道报价
+ * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
+ * 该仓不声明 {@code CHANNEL_RECOMMEND}
+ */
+ ChannelRecommendResult recommend(WarehouseContext ctx, ChannelRecommendQuery query);
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
index f0e082d..f6e0652 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
@@ -44,6 +44,8 @@ public enum WarehouseCapability {
FEE_SETTLEMENT(170, "费用结算"),
/** 费用试算 */
FEE_ESTIMATE(180, "费用试算"),
+ /** 最优渠道推荐(按 SKU + 邮编由仓择优) */
+ CHANNEL_RECOMMEND(200, "最优渠道推荐"),
/** 状态回调推送 */
WEBHOOK(190, "状态回调");
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendQuery.java
new file mode 100644
index 0000000..012d3b6
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendQuery.java
@@ -0,0 +1,129 @@
+package common.ecommerce.warehouse.model;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 最优渠道询价条件:按商品 SKU + 目的地邮编,让仓给出推荐渠道与各仓各渠道报价。
+ *
+ * 与 {@link FeeEstimateQuery} 不是一回事:那个要求调用方给包裹尺寸重量与
+ * 指定物流渠道,属于「已知怎么发、问多少钱」;本类只给货品与邮编,由仓决定
+ * 「发哪个仓、走哪个渠道、多少钱」,所以不需要尺寸重量。
+ *
+ * 只读操作,无幂等要求。
+ */
+public final class ChannelRecommendQuery {
+
+ private final List products;
+ private final String postalCode;
+ /** 是否需要签名服务;null 表示按仓默认。 */
+ private final Boolean signatureRequired;
+ /** 指定发货仓;(null/空)表示让仓在所有仓里择优。 */
+ private final String warehouseCode;
+
+ private ChannelRecommendQuery(Builder b) {
+ if (b.products.isEmpty()) {
+ throw new IllegalArgumentException("products must not be empty");
+ }
+ this.products = Collections.unmodifiableList(new ArrayList(b.products));
+ this.postalCode = require(b.postalCode, "postalCode");
+ this.signatureRequired = b.signatureRequired;
+ this.warehouseCode = b.warehouseCode;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public List products() {
+ return products;
+ }
+
+ /** 目的地邮编。 */
+ public String postalCode() {
+ return postalCode;
+ }
+
+ /** 是否需要签名服务;null 表示不传。 */
+ public Boolean signatureRequired() {
+ return signatureRequired;
+ }
+
+ /** 指定发货仓;null 表示由仓择优。 */
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ 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();
+ }
+
+ /** 一行商品:SKU 与件数。 */
+ public static final class SkuQuantity {
+
+ private final String sku;
+ private final int quantity;
+
+ public SkuQuantity(String sku, int quantity) {
+ if (sku == null || sku.trim().isEmpty()) {
+ throw new IllegalArgumentException("sku must not be blank");
+ }
+ if (quantity <= 0) {
+ throw new IllegalArgumentException("quantity must be positive");
+ }
+ this.sku = sku.trim();
+ this.quantity = quantity;
+ }
+
+ public String sku() {
+ return sku;
+ }
+
+ public int quantity() {
+ return quantity;
+ }
+ }
+
+ public static final class Builder {
+
+ private final List products = new ArrayList();
+ private String postalCode;
+ private Boolean signatureRequired;
+ private String warehouseCode;
+
+ public Builder product(String sku, int quantity) {
+ this.products.add(new SkuQuantity(sku, quantity));
+ return this;
+ }
+
+ public Builder products(List products) {
+ if (products != null) {
+ this.products.addAll(products);
+ }
+ return this;
+ }
+
+ public Builder postalCode(String v) {
+ this.postalCode = v;
+ return this;
+ }
+
+ public Builder signatureRequired(Boolean v) {
+ this.signatureRequired = v;
+ return this;
+ }
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public ChannelRecommendQuery build() {
+ return new ChannelRecommendQuery(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendResult.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendResult.java
new file mode 100644
index 0000000..bea7e3d
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendResult.java
@@ -0,0 +1,341 @@
+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;
+
+/**
+ * 最优渠道询价结果:一个仓方的推荐结论 + 全部仓 × 渠道的报价明细。
+ *
+ * 文档给两层:一层是「最优方案」(单条),一层是「所有仓库费用列表」。
+ * 两层都保留——只给最优就没法比价,只给明细又得让每个调用方自己算最小值。
+ *
+ * 这是报价,不是账单:实际费用以出库结算为准。
+ */
+public final class ChannelRecommendResult {
+
+ /** 接入通道。 */
+ private final WarehouseProvider sourceProvider;
+ /** 最优方案;仓方没给出时为 null。 */
+ private final OptimalPlan optimalPlan;
+ /** 所有仓库的报价;可能为空。 */
+ private final List warehouseQuotes;
+
+ private ChannelRecommendResult(Builder b) {
+ this.sourceProvider = b.sourceProvider;
+ this.optimalPlan = b.optimalPlan;
+ this.warehouseQuotes = Collections.unmodifiableList(new ArrayList(b.warehouseQuotes));
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public WarehouseProvider sourceProvider() {
+ return sourceProvider;
+ }
+
+ /** 最优方案;可能为 null。 */
+ public OptimalPlan optimalPlan() {
+ return optimalPlan;
+ }
+
+ /** 所有仓库的报价;可能为空。 */
+ public List warehouseQuotes() {
+ return warehouseQuotes;
+ }
+
+ /** 仓方的推荐方案。 */
+ public static final class OptimalPlan {
+
+ private final String warehouseCode;
+ private final String serviceCode;
+ private final Money total;
+
+ private OptimalPlan(Builder b) {
+ this.warehouseCode = require(b.warehouseCode, "warehouseCode");
+ this.serviceCode = require(b.serviceCode, "serviceCode");
+ this.total = b.total;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 推荐发货仓。 */
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ /** 推荐物流方式(仓方渠道码)。 */
+ public String serviceCode() {
+ return serviceCode;
+ }
+
+ /** 总费用;仓方未给时为 null。 */
+ public Money total() {
+ return total;
+ }
+
+ 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 String warehouseCode;
+ private String serviceCode;
+ private Money total;
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public Builder serviceCode(String v) {
+ this.serviceCode = v;
+ return this;
+ }
+
+ public Builder total(Money v) {
+ this.total = v;
+ return this;
+ }
+
+ public OptimalPlan build() {
+ return new OptimalPlan(this);
+ }
+ }
+ }
+
+ /** 单个仓库的报价:库存是否够 + 各渠道报价。 */
+ public static final class WarehouseQuote {
+
+ private final String warehouseCode;
+ /** 库存是否足够;null 表示仓方没给。 */
+ private final Boolean inventoryEnough;
+ /** 库存不足的原因;正常为空。 */
+ private final String insufficientStockError;
+ private final List services;
+
+ private WarehouseQuote(Builder b) {
+ this.warehouseCode = require(b.warehouseCode, "warehouseCode");
+ this.inventoryEnough = b.inventoryEnough;
+ this.insufficientStockError = b.insufficientStockError;
+ this.services = Collections.unmodifiableList(new ArrayList(b.services));
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ /** 库存是否足够;null 表示未知。 */
+ public Boolean inventoryEnough() {
+ return inventoryEnough;
+ }
+
+ /** 库存不足的原因;无则为 null。 */
+ public String insufficientStockError() {
+ return insufficientStockError;
+ }
+
+ /** 该仓下的渠道报价;可能为空。 */
+ public List services() {
+ return services;
+ }
+
+ 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 String warehouseCode;
+ private Boolean inventoryEnough;
+ private String insufficientStockError;
+ private final List services = new ArrayList();
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public Builder inventoryEnough(Boolean v) {
+ this.inventoryEnough = v;
+ return this;
+ }
+
+ public Builder insufficientStockError(String v) {
+ this.insufficientStockError = v;
+ return this;
+ }
+
+ public Builder service(ServiceQuote v) {
+ this.services.add(v);
+ return this;
+ }
+
+ public WarehouseQuote build() {
+ return new WarehouseQuote(this);
+ }
+ }
+ }
+
+ /** 单个物流渠道的报价。 */
+ public static final class ServiceQuote {
+
+ private final String serviceCode;
+ private final Money total;
+ private final List fees;
+
+ private ServiceQuote(Builder b) {
+ this.serviceCode = require(b.serviceCode, "serviceCode");
+ this.total = b.total;
+ this.fees = Collections.unmodifiableList(new ArrayList(b.fees));
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 物流方式(仓方渠道码)。 */
+ public String serviceCode() {
+ return serviceCode;
+ }
+
+ /** 总费用;仓方未给时为 null。 */
+ public Money total() {
+ return total;
+ }
+
+ /** 费用明细。 */
+ public List fees() {
+ return fees;
+ }
+
+ 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 String serviceCode;
+ private Money total;
+ private final List fees = new ArrayList();
+
+ public Builder serviceCode(String v) {
+ this.serviceCode = v;
+ return this;
+ }
+
+ public Builder total(Money v) {
+ this.total = v;
+ return this;
+ }
+
+ public Builder fee(FeeItem v) {
+ this.fees.add(v);
+ return this;
+ }
+
+ public ServiceQuote build() {
+ return new ServiceQuote(this);
+ }
+ }
+ }
+
+ /** 一条费用明细。 */
+ public static final class FeeItem {
+
+ /** 一级分类,如「快递费」。 */
+ private final String bigFeeType;
+ /** 费用项,如「燃油附加费」。 */
+ private final String feeType;
+ private final Money fee;
+
+ private FeeItem(Builder b) {
+ this.bigFeeType = b.bigFeeType;
+ this.feeType = b.feeType;
+ this.fee = b.fee;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public String bigFeeType() {
+ return bigFeeType;
+ }
+
+ public String feeType() {
+ return feeType;
+ }
+
+ public Money fee() {
+ return fee;
+ }
+
+ public static final class Builder {
+ private String bigFeeType;
+ private String feeType;
+ private Money fee;
+
+ public Builder bigFeeType(String v) {
+ this.bigFeeType = v;
+ return this;
+ }
+
+ public Builder feeType(String v) {
+ this.feeType = v;
+ return this;
+ }
+
+ public Builder fee(Money v) {
+ this.fee = v;
+ return this;
+ }
+
+ public FeeItem build() {
+ return new FeeItem(this);
+ }
+ }
+ }
+
+ public static final class Builder {
+ private WarehouseProvider sourceProvider;
+ private OptimalPlan optimalPlan;
+ private final List warehouseQuotes = new ArrayList();
+
+ public Builder sourceProvider(WarehouseProvider v) {
+ this.sourceProvider = v;
+ return this;
+ }
+
+ public Builder optimalPlan(OptimalPlan v) {
+ this.optimalPlan = v;
+ return this;
+ }
+
+ public Builder warehouseQuote(WarehouseQuote v) {
+ this.warehouseQuotes.add(v);
+ return this;
+ }
+
+ public ChannelRecommendResult build() {
+ return new ChannelRecommendResult(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 1b9751e..9b8378d 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
@@ -10,6 +10,7 @@ import common.ecommerce.warehouse.capability.DestructionCapable;
import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
+import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
@@ -20,6 +21,8 @@ import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.capability.WarehouseWebhookCapable;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.BillingDocument;
+import common.ecommerce.warehouse.model.ChannelRecommendQuery;
+import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
@@ -402,6 +405,22 @@ public final class WarehouseOperations {
() -> ((WarehouseFeeEstimateCapable) adapter).estimate(ctx, query));
}
+ /**
+ * 最优渠道推荐:给定 SKU 与邮编,由仓择优并给出全部报价。
+ *
+ * 只读,不走幂等。与 {@link #estimate(FeeEstimateQuery)} 的区别见
+ * {@code WarehouseChannelRecommendCapable}。
+ */
+ public ChannelRecommendResult recommend(ChannelRecommendQuery query) {
+ require(WarehouseCapability.CHANNEL_RECOMMEND, WarehouseChannelRecommendCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.channel.recommend",
+ CallSupport.params("postalCode", query.postalCode(),
+ "productCount", query.products().size(),
+ "warehouseCode", query.warehouseCode()),
+ r -> r.warehouseQuotes().size(),
+ () -> ((WarehouseChannelRecommendCapable) adapter).recommend(ctx, query));
+ }
+
/** 按条件拉取费用明细(预估与实际用 BillingDocument.estimated() 区分)。 */
public List settlements(FeeQuery query) {
require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class);
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
index 77cdcac..3d3e267 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
@@ -59,6 +59,15 @@ public final class XincangConstants {
/** 删除订单;{@code order_no} 与 {@code ckh} 二选一,空 body。 */
public static final String PATH_ORDER_DELETE = "/api.delete_order";
+ /**
+ * 最优渠道。
+ *
+ * 待核对:文档标注为 {@code GET} + {@code application/json} 请求体,
+ * 但 OkHttp 不支持 GET 带 body(会直接抛异常)。这里按「POST + JSON body」下发,
+ * 联调时若仓方只认 GET,需要换传输实现——只改这一处的调用方式。
+ */
+ public static final String PATH_CHANNEL_RECOMMEND = "/api.calculate_order_v3";
+
/** 新增转运({@code application/json})。 */
public static final String PATH_TRANSFER_CREATE = "/fba.do_fba";
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
index e9d9a39..7f5709a 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
@@ -12,6 +12,7 @@ import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.OutboundCapable;
+import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
@@ -22,6 +23,8 @@ import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.model.CancelCommand;
+import common.ecommerce.warehouse.model.ChannelRecommendQuery;
+import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
@@ -61,7 +64,7 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。
*/
public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable,
- TransferCapable {
+ TransferCapable, WarehouseChannelRecommendCapable {
private static final String OP_PRODUCT_QUERY = "warehouse.product.query";
private static final String OP_PRODUCT_ADD = "warehouse.product.add";
@@ -110,7 +113,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
@Override
public EnumSet capabilities() {
return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
- WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT);
+ WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT,
+ WarehouseCapability.CHANNEL_RECOMMEND);
}
/**
@@ -416,6 +420,30 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
"warehouse.transfer.delete");
}
+ // ------------------------------------------------------------------ 最优渠道
+
+ /**
+ * 最优渠道({@code api.calculate_order_v3})。
+ *
+ * 按 SKU + 邮编让仓给出推荐仓 / 渠道与全部报价,两层结果都保留。
+ *
+ * 协议待核对:文档写 GET + JSON body,OkHttp 不支持 GET 带 body,
+ * 这里按 POST + JSON body 下发,见 {@code XincangConstants.PATH_CHANNEL_RECOMMEND}。
+ */
+ @Override
+ public ChannelRecommendResult recommend(WarehouseContext ctx, ChannelRecommendQuery query) {
+ XincangDtos.CalculateV3Request body = XincangChannelRecommendMapper.toRequest(query);
+ String raw = execute(ctx, XincangConstants.PATH_CHANNEL_RECOMMEND, body, login(ctx),
+ "warehouse.channel.recommend");
+ XincangDtos.CalculateV3Result rst =
+ json.fromJson(raw, XincangDtos.CalculateV3Response.class).rst;
+ if (rst == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.channel.recommend",
+ "xincang calculate_order_v3 returned no rst");
+ }
+ return XincangChannelRecommendMapper.toResult(rst);
+ }
+
// ------------------------------------------------------------------ internals
/** 写接口:JSON 请求体(含 token)+ query token。 */
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java
new file mode 100644
index 0000000..3005fe2
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java
@@ -0,0 +1,155 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.ChannelRecommendQuery;
+import common.ecommerce.warehouse.model.ChannelRecommendResult;
+import common.ecommerce.xincang.dto.XincangDtos;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 最优渠道报文映射({@code api.calculate_order_v3})。
+ *
+ * 请求体:{@code products[{sku, qty}]} + {@code postcode} + {@code is_sign},
+ * 币种固定 USD(信仓文档金额口径)。
+ *
+ * 响应两层都映射:{@code optimalPlan} 原样给,{@code warehouseFeeList}
+ * 逐仓逐渠道展开,费用项保留一级分类与费用名。
+ */
+public final class XincangChannelRecommendMapper {
+
+ private static final String CURRENCY_USD = "USD";
+ /** 信仓只收「是 / 否」。 */
+ private static final String YES = "是";
+ private static final String NO = "否";
+ /** 未指定时按「否」下发(文档必填项)。 */
+ private static final String DEFAULT_SIGN = NO;
+
+ private XincangChannelRecommendMapper() {
+ }
+
+ /** 统一询价条件 → 信仓请求体。 */
+ public static XincangDtos.CalculateV3Request toRequest(ChannelRecommendQuery query) {
+ XincangDtos.CalculateV3Request req = new XincangDtos.CalculateV3Request();
+ List products =
+ new ArrayList(query.products().size());
+ for (ChannelRecommendQuery.SkuQuantity item : query.products()) {
+ XincangDtos.CalculateV3Request.Product product = new XincangDtos.CalculateV3Request.Product();
+ product.sku = item.sku();
+ product.qty = String.valueOf(item.quantity());
+ products.add(product);
+ }
+ req.products = products;
+ req.postcode = query.postalCode();
+ req.isSign = query.signatureRequired() == null
+ ? DEFAULT_SIGN
+ : (query.signatureRequired() ? YES : NO);
+ req.warehouseCode = blankToNull(query.warehouseCode());
+ return req;
+ }
+
+ /** 信仓响应 → 统一结果。 */
+ public static ChannelRecommendResult toResult(XincangDtos.CalculateV3Result rst) {
+ ChannelRecommendResult.Builder builder = ChannelRecommendResult.builder()
+ .sourceProvider(WarehouseProvider.XINCANG);
+ if (rst.optimalPlan != null) {
+ builder.optimalPlan(ChannelRecommendResult.OptimalPlan.builder()
+ .warehouseCode(blankToNull(rst.optimalPlan.warehouse) == null
+ ? "-" : rst.optimalPlan.warehouse.trim())
+ .serviceCode(blankToNull(rst.optimalPlan.serviceCode) == null
+ ? "-" : rst.optimalPlan.serviceCode.trim())
+ .total(parseMoney(rst.optimalPlan.sum))
+ .build());
+ }
+ if (rst.warehouseFeeList != null) {
+ for (XincangDtos.CalculateV3Result.WarehouseFee warehouse : rst.warehouseFeeList) {
+ if (warehouse == null) {
+ continue;
+ }
+ builder.warehouseQuote(toQuote(warehouse));
+ }
+ }
+ return builder.build();
+ }
+
+ private static ChannelRecommendResult.WarehouseQuote toQuote(
+ XincangDtos.CalculateV3Result.WarehouseFee warehouse) {
+ ChannelRecommendResult.WarehouseQuote.Builder builder =
+ ChannelRecommendResult.WarehouseQuote.builder()
+ .warehouseCode(blankToNull(warehouse.warehouse) == null
+ ? "-" : warehouse.warehouse.trim())
+ .inventoryEnough(parseFlag(warehouse.isInventoryEnough))
+ .insufficientStockError(blankToNull(warehouse.insufficientStockError));
+ if (warehouse.logisticsService != null) {
+ for (XincangDtos.CalculateV3Result.LogisticsService service : warehouse.logisticsService) {
+ if (service == null || blankToNull(service.serviceCode) == null) {
+ continue;
+ }
+ builder.service(toService(service));
+ }
+ }
+ return builder.build();
+ }
+
+ private static ChannelRecommendResult.ServiceQuote toService(
+ XincangDtos.CalculateV3Result.LogisticsService service) {
+ ChannelRecommendResult.ServiceQuote.Builder builder =
+ ChannelRecommendResult.ServiceQuote.builder()
+ .serviceCode(service.serviceCode.trim())
+ .total(parseMoney(service.sum));
+ if (service.fees != null) {
+ for (XincangDtos.CalculateV3Result.Fee fee : service.fees) {
+ if (fee == null) {
+ continue;
+ }
+ builder.fee(ChannelRecommendResult.FeeItem.builder()
+ .bigFeeType(blankToNull(fee.bigFeeType))
+ .feeType(blankToNull(fee.feeType))
+ .fee(parseMoney(fee.customerFee))
+ .build());
+ }
+ }
+ return builder.build();
+ }
+
+ /**
+ * 库存是否足够:文档示例给的是 {@code "1"} / {@code "0"}。
+ *
+ * 历史接口里 {@code isInventoryEnough} 有过 boolean 改成 string 的破坏性变更
+ * (见迁移说明),所以这里同时接受 {@code 1/0} 与 {@code true/false};
+ * 认不出返回 null,不猜。
+ */
+ static Boolean parseFlag(String raw) {
+ if (raw == null) {
+ return null;
+ }
+ String s = raw.trim();
+ if ("1".equals(s) || "true".equalsIgnoreCase(s) || "是".equals(s)) {
+ return Boolean.TRUE;
+ }
+ if ("0".equals(s) || "false".equalsIgnoreCase(s) || "否".equals(s)) {
+ return Boolean.FALSE;
+ }
+ return null;
+ }
+
+ /** 金额字符串 → USD;空值 / 非法返回 null。 */
+ static Money parseMoney(String raw) {
+ if (raw == null || raw.trim().isEmpty()) {
+ return null;
+ }
+ try {
+ BigDecimal amount = new BigDecimal(raw.trim());
+ return Money.of(amount, CURRENCY_USD);
+ } catch (RuntimeException e) {
+ return null;
+ }
+ }
+
+ private static String blankToNull(String v) {
+ return v == null || v.trim().isEmpty() ? null : v.trim();
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
index 6ecba19..cafdd30 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
@@ -736,6 +736,135 @@ public final class XincangDtos {
public OrderDetail rst;
}
+ /**
+ * 最优渠道请求({@code GET api.calculate_order_v3} 的 JSON body)。
+ *
+ * 文档写的是 GET + {@code application/json} body;信仓其它 GET 都是 query,
+ * 这里按文档原样用 JSON body。
+ */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class CalculateV3Request {
+
+ /** 产品信息;必填。 */
+ @JsonProperty("products")
+ public List products;
+
+ /** 邮编;必填。 */
+ @JsonProperty("postcode")
+ public String postcode;
+
+ /** 是否签名:是 / 否;必填。 */
+ @JsonProperty("is_sign")
+ public String isSign;
+
+ /** 仓库代码;不传由仓择优。 */
+ @JsonProperty("warehouse_code")
+ public String warehouseCode;
+
+ /** 一行商品。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class Product {
+
+ /** 产品 SKU。 */
+ @JsonProperty("sku")
+ public String sku;
+
+ /** 件数(字符串)。 */
+ @JsonProperty("qty")
+ public String qty;
+ }
+ }
+
+ /** 最优渠道响应 {@code rst}。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class CalculateV3Result {
+
+ /** 最优方案;无可用渠道时为 null。 */
+ @JsonProperty("optimalPlan")
+ public OptimalPlan optimalPlan;
+
+ /** 所有仓库的报价。 */
+ @JsonProperty("warehouseFeeList")
+ public List warehouseFeeList;
+
+ /** 最优方案。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OptimalPlan {
+
+ @JsonProperty("warehouse")
+ public String warehouse;
+
+ /** 物流方式(渠道码)。 */
+ @JsonProperty("service_code")
+ public String serviceCode;
+
+ /** 总费用。 */
+ @JsonProperty("sum")
+ public String sum;
+ }
+
+ /** 单个仓库的费用列表。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class WarehouseFee {
+
+ @JsonProperty("warehouse")
+ public String warehouse;
+
+ /** 库存是否足够:1 够 / 0 不够。 */
+ @JsonProperty("isInventoryEnough")
+ public String isInventoryEnough;
+
+ /** 库存不足原因。 */
+ @JsonProperty("insufficientStockError")
+ public String insufficientStockError;
+
+ /** 该仓下的渠道报价。 */
+ @JsonProperty("logisticsService")
+ public List logisticsService;
+ }
+
+ /** 单个物流渠道的报价。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class LogisticsService {
+
+ @JsonProperty("service_code")
+ public String serviceCode;
+
+ /** 总费用。 */
+ @JsonProperty("sum")
+ public String sum;
+
+ /** 费用明细。 */
+ @JsonProperty("fees")
+ public List fees;
+ }
+
+ /** 一条费用明细。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class Fee {
+
+ /** 一级分类,如「快递费」。 */
+ @JsonProperty("big_fee_type")
+ public String bigFeeType;
+
+ /** 费用项,如「燃油附加费」。 */
+ @JsonProperty("fee_type")
+ public String feeType;
+
+ /** 费用。 */
+ @JsonProperty("customer_fee")
+ public String customerFee;
+ }
+ }
+
+ /** 最优渠道响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class CalculateV3Response {
+
+ @JsonProperty("rst")
+ public CalculateV3Result rst;
+ }
+
/** 新增订单响应外层,用于取 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderResponse {
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
index 52c605f..c981bd4 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
@@ -120,7 +120,8 @@ class XincangAdapterTest {
assertEquals(WarehouseProvider.XINCANG, adapter.provider());
assertEquals(XincangConstants.ADAPTER_ID, adapter.adapterId());
assertEquals(EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
- WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT), adapter.capabilities());
+ WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT,
+ WarehouseCapability.CHANNEL_RECOMMEND), adapter.capabilities());
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND));
// 库存 / 退货等未接入,仍是 false
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangChannelRecommendTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangChannelRecommendTest.java
new file mode 100644
index 0000000..90ee598
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangChannelRecommendTest.java
@@ -0,0 +1,198 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.shared.testkit.MutableClock;
+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.ChannelRecommendQuery;
+import common.ecommerce.warehouse.model.ChannelRecommendResult;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Duration;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 最优渠道({@code api.calculate_order_v3})契约测试。
+ */
+class XincangChannelRecommendTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ /** 文档成功示例(截取两层结构)。 */
+ private static final String OK_BODY = "{\"rst\":{"
+ + "\"optimalPlan\":{\"warehouse\":\"CA-3790\",\"service_code\":\"GOFO-G\",\"sum\":\"20.87\"},"
+ + "\"warehouseFeeList\":["
+ + "{\"warehouse\":\"CA-3790\",\"isInventoryEnough\":\"1\",\"insufficientStockError\":\"\","
+ + "\"logisticsService\":["
+ + "{\"service_code\":\"GOFO-G\",\"sum\":\"20.87\",\"fees\":["
+ + "{\"big_fee_type\":\"快递费\",\"fee_type\":\"基础费\",\"customer_fee\":\"11.87\"},"
+ + "{\"big_fee_type\":\"快递费\",\"fee_type\":\"燃油附加费\",\"customer_fee\":\"5.64\"}]},"
+ + "{\"service_code\":\"USPS-G\",\"sum\":\"22.10\",\"fees\":[]}]},"
+ + "{\"warehouse\":\"NJ-2605\",\"isInventoryEnough\":\"0\","
+ + "\"insufficientStockError\":\"库存不足\",\"logisticsService\":[]}"
+ + "]},"
+ + "\"errno\":0,\"err\":\"\",\"trace_id\":\"t-v3\"}";
+
+ private RecordingTransport transport;
+ private XincangAdapter adapter;
+
+ @BeforeEach
+ void setUp() {
+ transport = RecordingTransport.create();
+ MutableClock clock = MutableClock.atUtc("2026-11-10T00:00:00Z");
+ transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok(
+ "{\"rst\":{\"id\":\"c-1\",\"token\":\"{T-1}\",\"token_expire_time\":\""
+ + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)),
+ XincangConstants.SYSTEM_ZONE)
+ .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}"));
+ adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), clock);
+ }
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("XC-CA-3790", WarehouseProvider.XINCANG, "CA-3790",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ private static ChannelRecommendQuery query() {
+ return ChannelRecommendQuery.builder()
+ .product("NOTEBOOK-MULTI-3", 9)
+ .product("BOX-PENS-10", 3)
+ .postalCode("937862")
+ .signatureRequired(false)
+ .build();
+ }
+
+ @Test
+ void sendsDocumentedRequestShape() {
+ transport.route(XincangConstants.PATH_CHANNEL_RECOMMEND, req -> Responses.ok(OK_BODY));
+
+ adapter.recommend(ctx(), query());
+
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertTrue(req.url().contains("/api.calculate_order_v3?token=%7BT-1%7D"), req.url());
+ assertEquals("application/json", req.contentType());
+
+ String body = req.body();
+ assertTrue(body.contains("\"sku\":\"NOTEBOOK-MULTI-3\""), body);
+ assertTrue(body.contains("\"qty\":\"9\""), body);
+ assertTrue(body.contains("\"sku\":\"BOX-PENS-10\""), body);
+ assertTrue(body.contains("\"qty\":\"3\""), body);
+ assertTrue(body.contains("\"postcode\":\"937862\""), body);
+ assertTrue(body.contains("\"is_sign\":\"否\""), body);
+ // 未指定仓库时不下发 warehouse_code
+ assertFalse(body.contains("warehouse_code"), body);
+ }
+
+ @Test
+ void mapsOptimalPlanAndAllQuotes() {
+ transport.route(XincangConstants.PATH_CHANNEL_RECOMMEND, req -> Responses.ok(OK_BODY));
+
+ ChannelRecommendResult result = adapter.recommend(ctx(), query());
+
+ assertEquals(WarehouseProvider.XINCANG, result.sourceProvider());
+
+ // 最优方案
+ assertNotNull(result.optimalPlan());
+ assertEquals("CA-3790", result.optimalPlan().warehouseCode());
+ assertEquals("GOFO-G", result.optimalPlan().serviceCode());
+ assertEquals(0, result.optimalPlan().total().amount().compareTo(new java.math.BigDecimal("20.87")));
+ assertEquals("USD", result.optimalPlan().total().currencyCode());
+
+ // 所有仓库明细
+ assertEquals(2, result.warehouseQuotes().size());
+ ChannelRecommendResult.WarehouseQuote first = result.warehouseQuotes().get(0);
+ assertEquals("CA-3790", first.warehouseCode());
+ assertEquals(Boolean.TRUE, first.inventoryEnough());
+ assertNull(first.insufficientStockError(), "空串应转 null");
+ assertEquals(2, first.services().size());
+
+ ChannelRecommendResult.ServiceQuote gogo = first.services().get(0);
+ assertEquals("GOFO-G", gogo.serviceCode());
+ assertEquals(2, gogo.fees().size());
+ assertEquals("快递费", gogo.fees().get(0).bigFeeType());
+ assertEquals("燃油附加费", gogo.fees().get(1).feeType());
+ assertEquals(0, gogo.fees().get(1).fee().amount()
+ .compareTo(new java.math.BigDecimal("5.64")));
+
+ ChannelRecommendResult.WarehouseQuote second = result.warehouseQuotes().get(1);
+ assertEquals(Boolean.FALSE, second.inventoryEnough());
+ assertEquals("库存不足", second.insufficientStockError());
+ assertTrue(second.services().isEmpty());
+ }
+
+ @Test
+ void signatureIsSentWhenRequested() {
+ transport.route(XincangConstants.PATH_CHANNEL_RECOMMEND, req -> Responses.ok(OK_BODY));
+ ChannelRecommendQuery signed = ChannelRecommendQuery.builder()
+ .product("SKU-A", 1).postalCode("10001").signatureRequired(true).build();
+
+ adapter.recommend(ctx(), signed);
+
+ assertTrue(transport.lastDataRequest().body().contains("\"is_sign\":\"是\""));
+ }
+
+ @Test
+ void warehouseCodeIsSentWhenSpecified() {
+ transport.route(XincangConstants.PATH_CHANNEL_RECOMMEND, req -> Responses.ok(OK_BODY));
+ ChannelRecommendQuery pinned = ChannelRecommendQuery.builder()
+ .product("SKU-A", 1).postalCode("10001").warehouseCode("CA-3790").build();
+
+ adapter.recommend(ctx(), pinned);
+
+ assertTrue(transport.lastDataRequest().body().contains("\"warehouse_code\":\"CA-3790\""));
+ }
+
+ @Test
+ void emptyOptimalPlanIsNullNotThrow() {
+ transport.route(XincangConstants.PATH_CHANNEL_RECOMMEND, req -> Responses.ok(
+ "{\"rst\":{\"optimalPlan\":null,\"warehouseFeeList\":[]},"
+ + "\"errno\":0,\"err\":\"\",\"trace_id\":\"t-empty\"}"));
+
+ ChannelRecommendResult result = adapter.recommend(ctx(), query());
+
+ assertNull(result.optimalPlan(), "无可用渠道时为 null");
+ assertTrue(result.warehouseQuotes().isEmpty());
+ }
+
+ @Test
+ void missingRstIsNotSilentSuccess() {
+ transport.route(XincangConstants.PATH_CHANNEL_RECOMMEND, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\"}"));
+
+ ValidationException e = assertThrows(ValidationException.class,
+ () -> adapter.recommend(ctx(), query()));
+ assertTrue(e.getMessage().contains("no rst"), e.getMessage());
+ }
+
+ @Test
+ void capabilityDeclared() {
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.CHANNEL_RECOMMEND));
+ assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.CHANNEL_RECOMMEND));
+ }
+
+ @Test
+ void busyFlagAcceptsBothStringForms() {
+ assertEquals(Boolean.TRUE, XincangChannelRecommendMapper.parseFlag("1"));
+ assertEquals(Boolean.TRUE, XincangChannelRecommendMapper.parseFlag("true"));
+ assertEquals(Boolean.FALSE, XincangChannelRecommendMapper.parseFlag("0"));
+ assertEquals(Boolean.FALSE, XincangChannelRecommendMapper.parseFlag("false"));
+ assertNull(XincangChannelRecommendMapper.parseFlag(""));
+ assertNull(XincangChannelRecommendMapper.parseFlag("unknown"));
+ }
+}