Browse Source

feat(xincang): 对接最优渠道 api.calculate_order_v3

按 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 <noreply@anthropic.com>
feature/supplier-lingxing
lml 2 weeks ago
parent
commit
bedc6798e1
  1. 2
      README.md
  2. 28
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseChannelRecommendCapable.java
  3. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
  4. 129
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendQuery.java
  5. 341
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendResult.java
  6. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  7. 9
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
  8. 32
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  9. 155
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java
  10. 129
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
  11. 3
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
  12. 198
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangChannelRecommendTest.java

2
README.md

@ -135,7 +135,7 @@ sequenceDiagram @@ -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、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道) |
依赖方向:
```

28
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseChannelRecommendCapable.java

@ -0,0 +1,28 @@ @@ -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 与目的地邮编,由仓给出推荐仓 + 渠道与全部报价。
*
* <p><b>与 {@link WarehouseFeeEstimateCapable} 不是一回事</b>:那个要求调用方
* 指定包裹尺寸重量与物流渠道,问「这么发多少钱」;本能力只给货品与邮编,
* 由仓回答「发哪儿、走哪条渠道、多少钱」。</p>
*
* <p>只读操作,无幂等要求。</p>
*/
public interface WarehouseChannelRecommendCapable extends WarehouseAdapter {
/**
* 询价并取推荐方案。
*
* @param query SKU 与件数、目的地邮编;必填项在构造期已校验
* @return 仓方推荐方案 + 全部仓 × 渠道报价
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不声明 {@code CHANNEL_RECOMMEND}
*/
ChannelRecommendResult recommend(WarehouseContext ctx, ChannelRecommendQuery query);
}

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java

@ -44,6 +44,8 @@ public enum WarehouseCapability { @@ -44,6 +44,8 @@ public enum WarehouseCapability {
FEE_SETTLEMENT(170, "费用结算"),
/** 费用试算 */
FEE_ESTIMATE(180, "费用试算"),
/** 最优渠道推荐(按 SKU + 邮编由仓择优) */
CHANNEL_RECOMMEND(200, "最优渠道推荐"),
/** 状态回调推送 */
WEBHOOK(190, "状态回调");

129
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendQuery.java

@ -0,0 +1,129 @@ @@ -0,0 +1,129 @@
package common.ecommerce.warehouse.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 最优渠道询价条件:按商品 SKU + 目的地邮编,让仓给出推荐渠道与各仓各渠道报价。
*
* <p><b>与 {@link FeeEstimateQuery} 不是一回事</b>:那个要求调用方给包裹尺寸重量与
* 指定物流渠道,属于「已知怎么发、问多少钱」;本类只给货品与邮编,由仓决定
* 「发哪个仓、走哪个渠道、多少钱」,所以不需要尺寸重量。</p>
*
* <p>只读操作,无幂等要求。</p>
*/
public final class ChannelRecommendQuery {
private final List<SkuQuantity> 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<SkuQuantity>(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<SkuQuantity> 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<SkuQuantity> products = new ArrayList<SkuQuantity>();
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<SkuQuantity> 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);
}
}
}

341
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ChannelRecommendResult.java

@ -0,0 +1,341 @@ @@ -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;
/**
* 最优渠道询价结果:一个仓方的推荐结论 + 全部仓 × 渠道的报价明细。
*
* <p>文档给两层:一层是「最优方案」(单条),一层是「所有仓库费用列表」。
* 两层都保留——只给最优就没法比价,只给明细又得让每个调用方自己算最小值。</p>
*
* <p>这是<b>报价</b>,不是账单:实际费用以出库结算为准。</p>
*/
public final class ChannelRecommendResult {
/** 接入通道。 */
private final WarehouseProvider sourceProvider;
/** 最优方案;仓方没给出时为 null。 */
private final OptimalPlan optimalPlan;
/** 所有仓库的报价;可能为空。 */
private final List<WarehouseQuote> warehouseQuotes;
private ChannelRecommendResult(Builder b) {
this.sourceProvider = b.sourceProvider;
this.optimalPlan = b.optimalPlan;
this.warehouseQuotes = Collections.unmodifiableList(new ArrayList<WarehouseQuote>(b.warehouseQuotes));
}
public static Builder builder() {
return new Builder();
}
public WarehouseProvider sourceProvider() {
return sourceProvider;
}
/** 最优方案;可能为 null。 */
public OptimalPlan optimalPlan() {
return optimalPlan;
}
/** 所有仓库的报价;可能为空。 */
public List<WarehouseQuote> 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<ServiceQuote> 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<ServiceQuote>(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<ServiceQuote> 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<ServiceQuote> services = new ArrayList<ServiceQuote>();
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<FeeItem> fees;
private ServiceQuote(Builder b) {
this.serviceCode = require(b.serviceCode, "serviceCode");
this.total = b.total;
this.fees = Collections.unmodifiableList(new ArrayList<FeeItem>(b.fees));
}
public static Builder builder() {
return new Builder();
}
/** 物流方式(仓方渠道码)。 */
public String serviceCode() {
return serviceCode;
}
/** 总费用;仓方未给时为 null。 */
public Money total() {
return total;
}
/** 费用明细。 */
public List<FeeItem> 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<FeeItem> fees = new ArrayList<FeeItem>();
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<WarehouseQuote> warehouseQuotes = new ArrayList<WarehouseQuote>();
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);
}
}
}

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

@ -10,6 +10,7 @@ import common.ecommerce.warehouse.capability.DestructionCapable; @@ -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; @@ -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 { @@ -402,6 +405,22 @@ public final class WarehouseOperations {
() -> ((WarehouseFeeEstimateCapable) adapter).estimate(ctx, query));
}
/**
* 最优渠道推荐:给定 SKU 与邮编,由仓择优并给出全部报价。
*
* <p>只读,不走幂等。与 {@link #estimate(FeeEstimateQuery)} 的区别见
* {@code WarehouseChannelRecommendCapable}。</p>
*/
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<BillingDocument> settlements(FeeQuery query) {
require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class);

9
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java

@ -59,6 +59,15 @@ public final class XincangConstants { @@ -59,6 +59,15 @@ public final class XincangConstants {
/** 删除订单;{@code order_no} 与 {@code ckh} 二选一,空 body。 */
public static final String PATH_ORDER_DELETE = "/api.delete_order";
/**
* 最优渠道。
*
* <p><b>待核对</b>:文档标注为 {@code GET} + {@code application/json} 请求体,
* 但 OkHttp 不支持 GET 带 body(会直接抛异常)。这里按「POST + JSON body」下发,
* 联调时若仓方只认 GET,需要换传输实现——只改这一处的调用方式。</p>
*/
public static final String PATH_CHANNEL_RECOMMEND = "/api.calculate_order_v3";
/** 新增转运({@code application/json})。 */
public static final String PATH_TRANSFER_CREATE = "/fba.do_fba";

32
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java

@ -12,6 +12,7 @@ import common.ecommerce.shared.spi.LockProvider; @@ -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; @@ -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; @@ -61,7 +64,7 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。</p>
*/
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 @@ -110,7 +113,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
@Override
public EnumSet<WarehouseCapability> 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 @@ -416,6 +420,30 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
"warehouse.transfer.delete");
}
// ------------------------------------------------------------------ 最优渠道
/**
* 最优渠道({@code api.calculate_order_v3})。
*
* <p>按 SKU + 邮编让仓给出推荐仓 / 渠道与全部报价,两层结果都保留。</p>
*
* <p><b>协议待核对</b>:文档写 GET + JSON body,OkHttp 不支持 GET 带 body,
* 这里按 POST + JSON body 下发,见 {@code XincangConstants.PATH_CHANNEL_RECOMMEND}。</p>
*/
@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。 */

155
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java

@ -0,0 +1,155 @@ @@ -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})。
*
* <p>请求体:{@code products[{sku, qty}]} + {@code postcode} + {@code is_sign},
* 币种固定 USD(信仓文档金额口径)。</p>
*
* <p>响应两层都映射:{@code optimalPlan} 原样给,{@code warehouseFeeList}
* 逐仓逐渠道展开,费用项保留一级分类与费用名。</p>
*/
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<XincangDtos.CalculateV3Request.Product> products =
new ArrayList<XincangDtos.CalculateV3Request.Product>(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"}。
*
* <p>历史接口里 {@code isInventoryEnough} 有过 boolean 改成 string 的破坏性变更
* (见迁移说明),所以这里同时接受 {@code 1/0} 与 {@code true/false};
* 认不出返回 null,不猜。</p>
*/
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();
}
}

129
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java

@ -736,6 +736,135 @@ public final class XincangDtos { @@ -736,6 +736,135 @@ public final class XincangDtos {
public OrderDetail rst;
}
/**
* 最优渠道请求({@code GET api.calculate_order_v3} 的 JSON body)。
*
* <p>文档写的是 GET + {@code application/json} body;信仓其它 GET 都是 query,
* 这里按文档原样用 JSON body。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CalculateV3Request {
/** 产品信息;必填。 */
@JsonProperty("products")
public List<Product> 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<WarehouseFee> 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> logisticsService;
}
/** 单个物流渠道的报价。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class LogisticsService {
@JsonProperty("service_code")
public String serviceCode;
/** 总费用。 */
@JsonProperty("sum")
public String sum;
/** 费用明细。 */
@JsonProperty("fees")
public List<Fee> 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 {

3
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java

@ -120,7 +120,8 @@ class XincangAdapterTest { @@ -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

198
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangChannelRecommendTest.java

@ -0,0 +1,198 @@ @@ -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"));
}
}
Loading…
Cancel
Save