From bedc6798e133d6381a362001396296c1e90f13bf Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Tue, 10 Nov 2026 17:30:34 +0800 Subject: [PATCH] =?UTF-8?q?feat(xincang):=20=E5=AF=B9=E6=8E=A5=E6=9C=80?= =?UTF-8?q?=E4=BC=98=E6=B8=A0=E9=81=93=20api.calculate=5Forder=5Fv3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按 SKU + 邮编由仓择优,与既有「运费试算」语义不同,core 新增独立能力: - WarehouseChannelRecommendCapable.recommend(ctx, query) - ChannelRecommendQuery:products[sku,qty] + postcode + signatureRequired + warehouseCode - ChannelRecommendResult:文档两层结构原样保留 optimalPlan(仓 / 渠道 / 总价)+ warehouseQuotes[] (每仓含 inventoryEnough、库存不足原因、各渠道报价与费用明细) - WarehouseCapability 追加 CHANNEL_RECOMMEND(200),既有值未动 - 门面入口 fees().recommend(query),只读、不走幂等 信仓实现: - 请求体 products / postcode / is_sign(是/否),未指定仓时不下发 warehouse_code - isInventoryEnough 兼容 1/0、true/false、是/否,认不出返回 null - optimalPlan 为空是合法结果(该城无可用渠道),返回空而非抛异常; 仅 rst 整体缺失才抛 ValidationException 待核对:文档标注 GET + application/json body,但 OkHttp 不支持 GET 带 body (会直接丢弃),这里按 POST + JSON body 下发,联调时若仓方只认 GET 需换传输实现,改动集中在 XincangConstants.PATH_CHANNEL_RECOMMEND 一处。 Co-Authored-By: Claude Code --- README.md | 2 +- .../WarehouseChannelRecommendCapable.java | 28 ++ .../warehouse/enums/WarehouseCapability.java | 2 + .../warehouse/model/ChannelRecommendQuery.java | 129 ++++++++ .../warehouse/model/ChannelRecommendResult.java | 341 +++++++++++++++++++++ .../warehouse/sdk/WarehouseOperations.java | 19 ++ .../common/ecommerce/xincang/XincangConstants.java | 9 + .../ecommerce/xincang/adapter/XincangAdapter.java | 32 +- .../adapter/XincangChannelRecommendMapper.java | 155 ++++++++++ .../common/ecommerce/xincang/dto/XincangDtos.java | 129 ++++++++ .../xincang/adapter/XincangAdapterTest.java | 3 +- .../adapter/XincangChannelRecommendTest.java | 198 ++++++++++++ 12 files changed, 1043 insertions(+), 4 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseChannelRecommendCapable.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendQuery.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendResult.java create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangChannelRecommendTest.java 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")); + } +}