diff --git a/README.md b/README.md
index 6e2c118..f17c9fc 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、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄) |
依赖方向:
```
@@ -348,9 +348,13 @@ common.ecommerce
└── xincang 信仓三方仓(warehouse-sdk-xincang)
├── XincangConstants 测试基址、路径、query 参数名、单位换算常量、限流
├── auth XincangTokenClient(GET /api.login,无 refresh)
- ├── adapter XincangAdapter / XincangAdapterFactory /
- │ XincangProductMapper / XincangOrderMapper / XincangTransferMapper
+ ├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper /
+ │ XincangOrderMapper / XincangOrderDetailMapper /
+ │ XincangTransferMapper / XincangTransferDetailMapper /
+ │ XincangChannelRecommendMapper / XincangInventoryMapper
├── dto XincangDtos(登录 / 商品)
+ ├── enums XincangOrderStatus / XincangTransferState /
+ │ XincangForecastStatus / XincangOrderType
└── http XincangRequestFactory / XincangMultipart / XincangEnvelope / XincangRateLimiter
```
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
index 9d529e9..e63502e 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
@@ -27,6 +27,18 @@ public interface InventoryCapable extends WarehouseAdapter {
*/
Page query(WarehouseContext ctx, InventoryQuery query);
+ /**
+ * 查库龄(按计费日期区间)。
+ *
+ * 库龄是计费视角的数据,与 {@link #query} 返回的库存快照不是一回事,
+ * 所以单独一个方法;不支持的仓默认拒绝。
+ */
+ default Page queryAges(
+ WarehouseContext ctx, common.ecommerce.warehouse.model.InventoryAgeQuery query) {
+ throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
+ common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_QUERY);
+ }
+
/** 其他出入库 / 调拨;信仓无此能力,会抛 {@code WarehouseUnsupportedCapabilityException}。 */
default InventorySnapshot adjust(WarehouseContext ctx, InventoryQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
index ff69988..f6c0a60 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
@@ -36,4 +36,35 @@ public interface TransferCapable extends WarehouseAdapter {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.TRANSFER);
}
+
+ /**
+ * 按仓侧调拨单号查详情。
+ *
+ * 信仓的「获取详情」({@code GET fba.fba_detail})走这里:
+ * {@code providerTransferNo} 传转运单号 {@code order_no}。
+ *
+ * 方法名带 {@code Transfer} 后缀:{@code InboundCapable} 已有同签名的
+ * {@code get(ctx, String)}(返回 {@code InboundOrder}),同一适配器实现两者时
+ * 返回类型冲突、也无法按泛型区分。
+ *
+ * 查不到时由适配器决定语义(可返回 null);未实现查询的仓默认拒绝。
+ */
+ default TransferOrder getTransfer(WarehouseContext ctx, String providerTransferNo) {
+ throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
+ common.ecommerce.warehouse.enums.WarehouseCapability.TRANSFER);
+ }
+
+ /**
+ * 删除(撤销)调拨单。写操作,幂等键
+ * {@code warehouseCode + providerTransferNo + "delete"}。
+ *
+ * 信仓的「删除转运」({@code POST fba.delete_fba})走这里,且只有待审核状态可删;
+ * 其余状态由仓方拒绝,适配器原样抛出,不擅自改成「取消」。
+ *
+ * 未实现删除的仓默认拒绝。
+ */
+ default void deleteTransfer(WarehouseContext ctx, String providerTransferNo) {
+ throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
+ common.ecommerce.warehouse.enums.WarehouseCapability.TRANSFER);
+ }
}
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/OutboundStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java
index 4214aee..2dfba69 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java
@@ -36,6 +36,22 @@ public enum OutboundStatus {
CANCELLED(80, "已取消", 7),
/** 异常(仓侧拣货失败、地址异常等)。 */
EXCEPTION(90, "异常", 8),
+ /** 仓侧审核中(信仓订单 {@code state=11})。 */
+ REVIEWING(100, "审核中", 9),
+ /** 待审核(信仓订单 {@code state=0})。 */
+ PENDING_REVIEW(110, "待审核", 10),
+ /** 待发货(审核通过、尚未开始作业;信仓订单 {@code state=1})。 */
+ PENDING_SHIPMENT(120, "待发货", 11),
+ /** 已拣货、待打包(信仓订单 {@code state=3})。 */
+ PICKED(130, "已拣货", 12),
+ /** 已拦截(信仓订单 {@code state=6});与「已取消」语义不同,不合并。 */
+ INTERCEPTED(140, "已拦截", 13),
+ /** 审核失败(信仓订单 {@code state=12})。 */
+ REVIEW_FAILED(150, "审核失败", 14),
+ /** 缺货(信仓订单 {@code state=7})。 */
+ OUT_OF_STOCK(160, "缺货", 15),
+ /** 已删除(信仓订单 {@code state=10})。 */
+ DELETED(170, "已删除", 16),
/** 无法识别;原值见 {@code rawStatus},不参与 rank 比较。 */
UNKNOWN(0, "未知", -1);
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java
index cc4b41e..62d659c 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java
@@ -27,6 +27,16 @@ public enum TransferStatus {
CANCELLING(140, "取消中"),
CANCELLED(150, "已取消"),
CANCEL_EXCEPTION(160, "取消异常"),
+ /** 待处理(信仓转运 {@code state=1})。 */
+ PENDING_PROCESSING(170, "待处理"),
+ /** 待拣货(信仓转运 {@code state=2})。 */
+ PENDING_PICK(180, "待拣货"),
+ /** 待贴标(信仓转运 {@code state=3})。 */
+ PENDING_LABELING(190, "待贴标"),
+ /** 待打托(信仓转运 {@code state=4})。 */
+ PENDING_PALLETIZING(200, "待打托"),
+ /** 已发货(信仓转运 {@code state=6});与 {@link #COMPLETED} 不同,尚未确认完成。 */
+ SHIPPED(210, "已发货"),
/** 无法识别;0 保留给 UNKNOWN。 */
UNKNOWN(0, "未知");
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 8abb006..d4135f2 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/model/InventoryAgeQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeQuery.java
new file mode 100644
index 0000000..5c2128e
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeQuery.java
@@ -0,0 +1,131 @@
+package common.ecommerce.warehouse.model;
+
+import java.time.LocalDate;
+
+/**
+ * 库龄查询条件。
+ *
+ * 库龄按计费日期区间查,必须给区间;不给会拉到全部历史,对账时无从解释。
+ */
+public final class InventoryAgeQuery {
+
+ private final LocalDate startDate;
+ private final LocalDate endDate;
+ /** 仓 code;null 表示用账户配置的仓。 */
+ private final String warehouseCode;
+ /** 产品 SKU;null 表示不限。 */
+ private final String providerSku;
+ private final int pageSize;
+ private final String cursor;
+ /** 是否返回费率与计费体积;null 表示按仓默认。 */
+ private final Boolean includeFeeRate;
+
+ private InventoryAgeQuery(Builder b) {
+ if (b.startDate == null || b.endDate == null) {
+ throw new IllegalArgumentException("startDate and endDate are required");
+ }
+ if (b.endDate.isBefore(b.startDate)) {
+ throw new IllegalArgumentException("endDate must not be earlier than startDate");
+ }
+ this.startDate = b.startDate;
+ this.endDate = b.endDate;
+ this.warehouseCode = b.warehouseCode;
+ this.providerSku = b.providerSku;
+ this.pageSize = b.pageSize;
+ this.cursor = b.cursor;
+ this.includeFeeRate = b.includeFeeRate;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 计费日期区间起点(含)。 */
+ public LocalDate startDate() {
+ return startDate;
+ }
+
+ /** 计费日期区间终点(含)。 */
+ public LocalDate endDate() {
+ return endDate;
+ }
+
+ /** 仓 code;null 表示用账户配置的仓。 */
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ /** 产品 SKU;null 表示不限。 */
+ public String providerSku() {
+ return providerSku;
+ }
+
+ public int pageSize() {
+ return pageSize;
+ }
+
+ public String cursor() {
+ return cursor;
+ }
+
+ /** 是否返回费率;null 表示按仓默认。 */
+ public Boolean includeFeeRate() {
+ return includeFeeRate;
+ }
+
+ public static final class Builder {
+ private LocalDate startDate;
+ private LocalDate endDate;
+ private String warehouseCode;
+ private String providerSku;
+ private int pageSize = 100;
+ private String cursor;
+ private Boolean includeFeeRate;
+
+ public Builder startDate(LocalDate v) {
+ this.startDate = v;
+ return this;
+ }
+
+ public Builder endDate(LocalDate v) {
+ this.endDate = v;
+ return this;
+ }
+
+ /** 计费日期区间。 */
+ public Builder dateRange(LocalDate start, LocalDate end) {
+ this.startDate = start;
+ this.endDate = end;
+ return this;
+ }
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ public Builder pageSize(int v) {
+ this.pageSize = v;
+ return this;
+ }
+
+ public Builder cursor(String v) {
+ this.cursor = v;
+ return this;
+ }
+
+ public Builder includeFeeRate(Boolean v) {
+ this.includeFeeRate = v;
+ return this;
+ }
+
+ public InventoryAgeQuery build() {
+ return new InventoryAgeQuery(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeRecord.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeRecord.java
new file mode 100644
index 0000000..41d7d1f
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeRecord.java
@@ -0,0 +1,189 @@
+package common.ecommerce.warehouse.model;
+
+import common.ecommerce.shared.support.Money;
+
+import java.time.Instant;
+
+/**
+ * 一条库龄记录(按计费日 × 仓库 × SKU × 入库柜号)。
+ *
+ * 库龄是计费视角的数据,不是库存快照:同一 SKU 在不同入库批次 / 柜号下
+ * 有不同的库龄天数与费率,按天累计出仓储费。所以单独建模,不塞进
+ * {@link InventorySnapshot}——后者回答「现在有多少货」。
+ *
+ * 只读查询结果,无幂等要求。
+ */
+public final class InventoryAgeRecord {
+
+ private final String warehouseCode;
+ private final String providerSku;
+ /** 计费日期(仓方 {@code dt});仓方按天出账。 */
+ private final Instant billingDate;
+ /** 入库柜号;无则为 null。 */
+ private final String cabinetNo;
+ /** 实际入库时间(UTC)。 */
+ private final Instant inStockAt;
+ /** 库龄天数;仓方原值。 */
+ private final int ageDays;
+ /** 库存数量(该批次)。 */
+ private final int quantity;
+ /** 总体积(立方米,仓方 {@code total_volume_cbm});可能为 null。 */
+ private final java.math.BigDecimal totalVolumeCbm;
+ /** 计费数量。 */
+ private final int billingQuantity;
+ /** 费率;仓方未给为 null。 */
+ private final java.math.BigDecimal feeRate;
+ /** 当日费用;仓方未给为 null。 */
+ private final Money fee;
+
+ private InventoryAgeRecord(Builder b) {
+ this.warehouseCode = require(b.warehouseCode, "warehouseCode");
+ this.providerSku = require(b.providerSku, "providerSku");
+ this.billingDate = java.util.Objects.requireNonNull(b.billingDate, "billingDate");
+ this.cabinetNo = b.cabinetNo;
+ this.inStockAt = b.inStockAt;
+ this.ageDays = b.ageDays;
+ this.quantity = b.quantity;
+ this.totalVolumeCbm = b.totalVolumeCbm;
+ this.billingQuantity = b.billingQuantity;
+ this.feeRate = b.feeRate;
+ this.fee = b.fee;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ public String providerSku() {
+ return providerSku;
+ }
+
+ /** 计费日期。 */
+ public Instant billingDate() {
+ return billingDate;
+ }
+
+ /** 入库柜号;无则为 null。 */
+ public String cabinetNo() {
+ return cabinetNo;
+ }
+
+ /** 实际入库时间;仓方未给为 null。 */
+ public Instant inStockAt() {
+ return inStockAt;
+ }
+
+ /** 库龄天数。 */
+ public int ageDays() {
+ return ageDays;
+ }
+
+ /** 库存数量(该批次)。 */
+ public int quantity() {
+ return quantity;
+ }
+
+ /** 总体积(立方米);未给为 null。 */
+ public java.math.BigDecimal totalVolumeCbm() {
+ return totalVolumeCbm;
+ }
+
+ /** 计费数量。 */
+ public int billingQuantity() {
+ return billingQuantity;
+ }
+
+ /** 费率;未给为 null。 */
+ public java.math.BigDecimal feeRate() {
+ return feeRate;
+ }
+
+ /** 当日费用;未给为 null。 */
+ public Money fee() {
+ return fee;
+ }
+
+ private static String require(String v, String n) {
+ if (v == null || v.trim().isEmpty()) {
+ throw new IllegalArgumentException(n + " must not be blank");
+ }
+ return v.trim();
+ }
+
+ public static final class Builder {
+ private String warehouseCode;
+ private String providerSku;
+ private Instant billingDate;
+ private String cabinetNo;
+ private Instant inStockAt;
+ private int ageDays;
+ private int quantity;
+ private java.math.BigDecimal totalVolumeCbm;
+ private int billingQuantity;
+ private java.math.BigDecimal feeRate;
+ private Money fee;
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ public Builder billingDate(Instant v) {
+ this.billingDate = v;
+ return this;
+ }
+
+ public Builder cabinetNo(String v) {
+ this.cabinetNo = v;
+ return this;
+ }
+
+ public Builder inStockAt(Instant v) {
+ this.inStockAt = v;
+ return this;
+ }
+
+ public Builder ageDays(int v) {
+ this.ageDays = v;
+ return this;
+ }
+
+ public Builder quantity(int v) {
+ this.quantity = v;
+ return this;
+ }
+
+ public Builder totalVolumeCbm(java.math.BigDecimal v) {
+ this.totalVolumeCbm = v;
+ return this;
+ }
+
+ public Builder billingQuantity(int v) {
+ this.billingQuantity = v;
+ return this;
+ }
+
+ public Builder feeRate(java.math.BigDecimal v) {
+ this.feeRate = v;
+ return this;
+ }
+
+ public Builder fee(Money v) {
+ this.fee = v;
+ return this;
+ }
+
+ public InventoryAgeRecord build() {
+ return new InventoryAgeRecord(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java
index d54ad5d..30f73f1 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java
@@ -28,6 +28,14 @@ public final class InventorySnapshot {
private final int packageReserved;
private final int packageInTransit;
private final int packageCurrent;
+ /** 商品名(仓方原值);无则为 null。 */
+ private final String productName;
+ /** 待出库数量;仓方未给时为 -1。 */
+ private final int pendingOutbound;
+ /** 预警数量;仓方未给时为 -1。 */
+ private final int alertQuantity;
+ /** 体积(立方厘米);仓方原值,未给为 null。 */
+ private final java.math.BigDecimal volumeCbm;
private InventorySnapshot(Builder b) {
this.warehouseCode = require(b.warehouseCode, "warehouseCode");
@@ -46,6 +54,10 @@ public final class InventorySnapshot {
this.packageReserved = b.packageReserved;
this.packageInTransit = b.packageInTransit;
this.packageCurrent = b.packageCurrent;
+ this.productName = b.productName;
+ this.pendingOutbound = b.pendingOutbound;
+ this.alertQuantity = b.alertQuantity;
+ this.volumeCbm = b.volumeCbm;
}
public static Builder builder() {
@@ -125,6 +137,26 @@ public final class InventorySnapshot {
return packageCurrent;
}
+ /** 商品名(仓方原值);无则为 null。 */
+ public String productName() {
+ return productName;
+ }
+
+ /** 待出库数量;仓方未给时为 -1。 */
+ public int pendingOutbound() {
+ return pendingOutbound;
+ }
+
+ /** 预警数量;仓方未给时为 -1。 */
+ public int alertQuantity() {
+ return alertQuantity;
+ }
+
+ /** 体积(立方厘米);仓方未给为 null。 */
+ public java.math.BigDecimal volumeCbm() {
+ return volumeCbm;
+ }
+
private static String require(String v, String n) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(n + " must not be blank");
@@ -149,6 +181,12 @@ public final class InventorySnapshot {
private int packageReserved;
private int packageInTransit;
private int packageCurrent;
+ private String productName;
+ /** 仓方未给时为 -1。 */
+ private int pendingOutbound = -1;
+ /** 仓方未给时为 -1。 */
+ private int alertQuantity = -1;
+ private java.math.BigDecimal volumeCbm;
public Builder warehouseCode(String v) {
this.warehouseCode = v;
@@ -230,6 +268,30 @@ public final class InventorySnapshot {
return this;
}
+ /** 商品名(仓方原值)。 */
+ public Builder productName(String v) {
+ this.productName = v;
+ return this;
+ }
+
+ /** 待出库数量;仓方未给时传 -1。 */
+ public Builder pendingOutbound(int v) {
+ this.pendingOutbound = v;
+ return this;
+ }
+
+ /** 预警数量;仓方未给时传 -1。 */
+ public Builder alertQuantity(int v) {
+ this.alertQuantity = v;
+ return this;
+ }
+
+ /** 体积(立方厘米)。 */
+ public Builder volumeCbm(java.math.BigDecimal v) {
+ this.volumeCbm = v;
+ return this;
+ }
+
public InventorySnapshot build() {
return new InventorySnapshot(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 5edb60d..12fbe26 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
@@ -12,6 +12,7 @@ import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
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;
@@ -21,6 +22,8 @@ import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
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;
@@ -139,6 +142,42 @@ public final class WarehouseOperations {
ref -> ref);
}
+ /**
+ * 按仓侧调拨单号查详情。
+ *
+ * @param providerTransferNo 仓侧调拨单号({@code createTransfer} 返回的
+ * {@code providerTransferNo})
+ */
+ public TransferOrder getTransfer(final String providerTransferNo) {
+ require(WarehouseCapability.TRANSFER, TransferCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.transfer.get",
+ CallSupport.params("providerTransferNo", providerTransferNo),
+ o -> o == null ? 0 : 1,
+ () -> ((TransferCapable) adapter).getTransfer(ctx, providerTransferNo));
+ }
+
+ /**
+ * 删除(撤销)调拨单。写操作:强制经幂等守卫,幂等键
+ * {@code warehouseCode + providerTransferNo + delete}。
+ *
+ * @param providerTransferNo 仓侧调拨单号
+ */
+ public void deleteTransfer(final String providerTransferNo) {
+ require(WarehouseCapability.TRANSFER, TransferCapable.class);
+ if (guard == null) {
+ throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
+ }
+ final TransferCapable capable = (TransferCapable) adapter;
+ guard.execute(
+ WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
+ providerTransferNo, "delete"),
+ () -> {
+ capable.deleteTransfer(ctx, providerTransferNo);
+ return providerTransferNo;
+ },
+ ref -> ref);
+ }
+
/** 库存视图。 */
public InventoryView inventory() {
return new InventoryView();
@@ -240,6 +279,24 @@ public final class WarehouseOperations {
/** 库存视图。 */
public final class InventoryView {
+ /**
+ * 查库龄(按计费日期区间)。
+ *
+ * 只读。库龄是计费视角数据,与 {@link #query(InventoryQuery)} 的库存快照不同。
+ */
+ public Page queryAges(
+ final common.ecommerce.warehouse.model.InventoryAgeQuery query) {
+ require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.inventory.ages",
+ CallSupport.params("startDate", query.startDate(),
+ "endDate", query.endDate(),
+ "warehouseCode", query.warehouseCode(),
+ "providerSku", query.providerSku(),
+ "pageSize", query.pageSize()),
+ p -> p.size(),
+ () -> ((InventoryCapable) adapter).queryAges(ctx, query));
+ }
+
/** 查库存。 */
public Page query(InventoryQuery query) {
require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class);
@@ -427,6 +484,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 4551b76..d465259 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
@@ -53,6 +53,27 @@ public final class XincangConstants {
/** 新增订单一单多件({@code multipart/form-data};一票一件请用 {@code api.add_order})。 */
public static final String PATH_ORDER_ADD_MULTIPLE = "/api.add_order_multiple";
+ /** 订单详情;{@code order_no} 与 {@code ckh} 二选一。 */
+ public static final String PATH_ORDER_DETAIL = "/api.get_order";
+
+ /** 删除订单;{@code order_no} 与 {@code ckh} 二选一,空 body。 */
+ public static final String PATH_ORDER_DELETE = "/api.delete_order";
+
+ /** 实时库存;必填 {@code warehouse_code}。 */
+ public static final String PATH_STOCK_LIST = "/api.stocklist";
+
+ /** 库龄列表;必填 {@code bill_date}({@code 起 - 止})。 */
+ public static final String PATH_STOCK_AGE_LIST = "/api.stockagelist";
+
+ /**
+ * 最优渠道。
+ *
+ * 待核对:文档标注为 {@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";
@@ -62,6 +83,12 @@ public final class XincangConstants {
/** 转运列表。 */
public static final String PATH_TRANSFER_LIST = "/fba.fbalist";
+ /** 转运详情;必填 {@code order_no}(转运单号)。 */
+ public static final String PATH_TRANSFER_DETAIL = "/fba.fba_detail";
+
+ /** 删除转运;必填 {@code order_no},仅待审核状态可删。 */
+ public static final String PATH_TRANSFER_DELETE = "/fba.delete_fba";
+
/** 登录响应里的 token 归入哪个作用域;信仓用 query 参数传递,不是 {@code Authorization} 头。 */
public static final String TOKEN_LOCATION = "query";
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 2cbb57c..4b9285b 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
@@ -11,15 +11,26 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.shared.support.Page;
+import common.ecommerce.warehouse.capability.InventoryCapable;
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;
import common.ecommerce.warehouse.enums.CancelEligibility;
+import common.ecommerce.warehouse.enums.InventorySyncStrategy;
+import common.ecommerce.warehouse.enums.OutboundStatus;
import common.ecommerce.warehouse.enums.WarehouseCapability;
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.InventoryAgeQuery;
+import common.ecommerce.warehouse.model.InventoryAgeRecord;
+import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.InventorySnapshot;
+import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
@@ -39,6 +50,7 @@ import common.ecommerce.xincang.http.XincangRateLimiter;
import common.ecommerce.xincang.http.XincangRequestFactory;
import java.time.Clock;
+import java.time.Instant;
import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.List;
@@ -59,7 +71,7 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。
*/
public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable,
- TransferCapable {
+ TransferCapable, WarehouseChannelRecommendCapable, InventoryCapable {
private static final String OP_PRODUCT_QUERY = "warehouse.product.query";
private static final String OP_PRODUCT_ADD = "warehouse.product.add";
@@ -108,7 +120,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, WarehouseCapability.INVENTORY_QUERY);
}
/**
@@ -213,9 +226,33 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
return OutboundReceipt.of(cmd.outboundRequestNo(), result.orderNo, null);
}
+ /**
+ * 查订单详情({@code GET api.get_order})。
+ *
+ * 信仓按 {@code order_no}(系统单号)或 {@code ckh}(参考号)二选一查询。
+ * 引用里的 {@code providerOrderId} 优先当作 {@code order_no},
+ * {@code outboundRequestNo} 当作 {@code ckh}——两者都传时以 provider 侧为准,
+ * 因为只有仓单号能唯一定位。
+ *
+ * 查不到时信仓返回 {@code errno != 0},这里作为业务异常抛出,不返回 null——
+ * 「查不到」与「查到了但没有数据」对调用方的意义不同。
+ */
@Override
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
- throw XincangUnsupportedOutbound.getUnsupported(ctx);
+ Map params = new LinkedHashMap();
+ if (!blank(ref.providerOrderId())) {
+ params.put("order_no", ref.providerOrderId());
+ } else if (!blank(ref.outboundRequestNo())) {
+ params.put("ckh", ref.outboundRequestNo());
+ }
+ String raw = executeGet(ctx, XincangConstants.PATH_ORDER_DETAIL, params, login(ctx),
+ "warehouse.outbound.get");
+ XincangDtos.OrderDetail detail = json.fromJson(raw, XincangDtos.OrderDetailResponse.class).rst;
+ if (detail == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.outbound.get",
+ "xincang get_order returned no rst");
+ }
+ return XincangOrderDetailMapper.toOrder(detail, ctx);
}
@Override
@@ -223,14 +260,79 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
throw XincangUnsupportedOutbound.queryUnsupported(ctx);
}
+ /**
+ * 取消资格预判。
+ *
+ * 信仓没有独立的取消预判接口,也没有收费取消:按订单详情状态推断。
+ * 文档「删除订单」的语义是——待审核→删除、待发货→已取消、拣货中/已拣货→已拦截;
+ * 已发货、已取消、已删除、已拦截都不再接受删除,判为 {@link CancelEligibility#BLOCKED}。
+ *
+ * 查询失败时直接抛出,不猜成 FREE——猜错会下发出一个注定被拒的删除请求。
+ */
@Override
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) {
- throw XincangUnsupportedOutbound.checkCancelUnsupported(ctx);
+ OutboundOrder order = get(ctx, ref);
+ return cancelEligibilityOf(order.status());
}
+ /**
+ * 删除订单({@code POST api.delete_order})。
+ *
+ * 信仓的「删除」按订单状态分流:待审核→删除、待发货→已取消、
+ * 拣货中/已拣货→已拦截,因此统一模型里映射为 {@link CancelResult}。
+ * 仓拒绝时按 {@link OutboundCancelBlockedException} 抛出,方便与参数错误区分。
+ */
@Override
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) {
- throw XincangUnsupportedOutbound.cancelUnsupported(ctx);
+ Map params = new LinkedHashMap();
+ if (!blank(cmd.providerOrderId())) {
+ params.put("order_no", cmd.providerOrderId());
+ } else if (!blank(cmd.outboundRequestNo())) {
+ params.put("ckh", cmd.outboundRequestNo());
+ }
+ try {
+ executePostQuery(ctx, XincangConstants.PATH_ORDER_DELETE, params,
+ "warehouse.outbound.cancel");
+ } catch (PlatformBusinessException e) {
+ // 信仓失败只回 err 文本,无法细分原因;取消场景统一按「不可取消」表达
+ throw new OutboundCancelBlockedException(WarehouseException.builder()
+ .message("xincang refused order deletion: " + e.getMessage())
+ .operation("warehouse.outbound.cancel")
+ .warehouseCode(ctx.warehouseCode())
+ .provider(provider().name())
+ .requestId(ctx.requestId())
+ .platformCode(e.platformCode())
+ .rawResponse(e.rawResponse())
+ .retryable(false));
+ }
+ return CancelResult.builder()
+ .outboundRequestNo(cmd.outboundRequestNo())
+ .providerOrderId(cmd.providerOrderId())
+ .eligibility(CancelEligibility.FREE)
+ .cancelled(true)
+ .build();
+ }
+
+ /**
+ * 取消资格映射。
+ *
+ * 只有「尚未进入不可逆阶段」的状态可删;{@link OutboundStatus#UNKNOWN}
+ * 也判为 BLOCKED,避免拿不准就下写请求。
+ */
+ static CancelEligibility cancelEligibilityOf(OutboundStatus status) {
+ if (status == null) {
+ return CancelEligibility.BLOCKED;
+ }
+ switch (status) {
+ case SHIPPED:
+ case CANCELLED:
+ case INTERCEPTED:
+ case DELETED:
+ case UNKNOWN:
+ return CancelEligibility.BLOCKED;
+ default:
+ return CancelEligibility.FREE;
+ }
}
@Override
@@ -283,6 +385,129 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
"warehouse.transfer.approve");
}
+ /**
+ * 转运详情({@code GET fba.fba_detail})。
+ *
+ * @param providerTransferNo 信仓转运单号 {@code order_no}
+ */
+ @Override
+ public TransferOrder getTransfer(WarehouseContext ctx, String providerTransferNo) {
+ if (blank(providerTransferNo)) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.get",
+ "providerTransferNo must not be blank");
+ }
+ Map params = new LinkedHashMap();
+ params.put("order_no", providerTransferNo);
+ String raw = executeGet(ctx, XincangConstants.PATH_TRANSFER_DETAIL, params, login(ctx),
+ "warehouse.transfer.get");
+ XincangDtos.TransferDetail detail =
+ json.fromJson(raw, XincangDtos.TransferDetailResponse.class).rst;
+ if (detail == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.get",
+ "xincang fba_detail returned no rst");
+ }
+ return XincangTransferDetailMapper.toOrder(detail);
+ }
+
+ /**
+ * 删除转运({@code POST fba.delete_fba})。
+ *
+ * 信仓只允许待审核状态删除,其余状态由仓方拒绝(errno != 0),
+ * 这里原样抛出业务异常,不擅自退化成「取消」。
+ */
+ @Override
+ public void deleteTransfer(WarehouseContext ctx, String providerTransferNo) {
+ if (blank(providerTransferNo)) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.delete",
+ "providerTransferNo must not be blank");
+ }
+ Map params = new LinkedHashMap();
+ params.put("order_no", providerTransferNo);
+ executePostQuery(ctx, XincangConstants.PATH_TRANSFER_DELETE, params,
+ "warehouse.transfer.delete");
+ }
+
+ // ------------------------------------------------------------------ 库存
+
+ /**
+ * 库存同步策略:信仓只能按页全量拉,没有按时间增量的参数。
+ *
+ * 宿主按本值决定落库策略,不要按 {@code updatedAfter} 做增量。
+ */
+ @Override
+ public InventorySyncStrategy syncStrategy() {
+ return InventorySyncStrategy.FULL_PULL_DIFF;
+ }
+
+ /**
+ * 实时库存({@code GET api.stocklist})。
+ *
+ * 信仓只支持单个 {@code warehouse_code};调用方传多个仓会显式拒绝,
+ * 不静默只查第一个。{@code updatedAfter} 被忽略——该接口没有时间维度。
+ */
+ @Override
+ public Page query(WarehouseContext ctx, InventoryQuery query) {
+ Map params = XincangInventoryMapper.toStockParams(query,
+ ctx.providerWarehouseId());
+ String raw = executeGet(ctx, XincangConstants.PATH_STOCK_LIST, params, login(ctx),
+ "warehouse.inventory.query");
+ XincangDtos.StockListResult rst = json.fromJson(raw, XincangDtos.StockListResponse.class).rst;
+ if (rst == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inventory.query",
+ "xincang stocklist returned no rst");
+ }
+ int page = XincangInventoryMapper.pageNumber(query.cursor());
+ int size = XincangInventoryMapper.pageSize(query.pageSize());
+ return XincangInventoryMapper.toSnapshots(rst, ctx.providerWarehouseId(),
+ Instant.now(ctx.clock()), page, size);
+ }
+
+ /**
+ * 库龄列表({@code GET api.stockagelist})。
+ *
+ * 按计费日期区间查;{@code bill_date} 是「起 - 止」单值字符串。
+ */
+ @Override
+ public Page queryAges(WarehouseContext ctx, InventoryAgeQuery query) {
+ Map params = XincangInventoryMapper.toAgeParams(query,
+ ctx.providerWarehouseId());
+ String raw = executeGet(ctx, XincangConstants.PATH_STOCK_AGE_LIST, params, login(ctx),
+ "warehouse.inventory.ages");
+ XincangDtos.StockAgeListResult rst =
+ json.fromJson(raw, XincangDtos.StockAgeListResponse.class).rst;
+ if (rst == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inventory.ages",
+ "xincang stockagelist returned no rst");
+ }
+ int page = XincangInventoryMapper.pageNumber(query.cursor());
+ int size = XincangInventoryMapper.pageSize(query.pageSize());
+ return XincangInventoryMapper.toAgeRecords(rst, ctx.providerWarehouseId(), page, size);
+ }
+
+ // ------------------------------------------------------------------ 最优渠道
+
+ /**
+ * 最优渠道({@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/adapter/XincangInventoryMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
new file mode 100644
index 0000000..10c6bd4
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
@@ -0,0 +1,268 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.shared.support.Page;
+import common.ecommerce.warehouse.model.InventoryAgeQuery;
+import common.ecommerce.warehouse.model.InventoryAgeRecord;
+import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.InventorySnapshot;
+import common.ecommerce.xincang.XincangConstants;
+import common.ecommerce.xincang.dto.XincangDtos;
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 库存与库龄报文映射。
+ *
+ *
+ * - 实时库存 {@code GET api.stocklist}
+ * - 库龄列表 {@code GET api.stockagelist}
+ *
+ *
+ * 平台字段名只出现在本类与 {@link XincangDtos};时间按北京时间解析成 UTC。
+ */
+public final class XincangInventoryMapper {
+
+ private static final DateTimeFormatter DATE_TIME =
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+ private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+ private static final String CURRENCY_USD = "USD";
+ /** 仓方分页上限文档未标明,先按 100 保守截断。 */
+ static final int MAX_PAGE_SIZE = 100;
+
+ private XincangInventoryMapper() {
+ }
+
+ // ---------------------------------------------------------------- 实时库存
+
+ /**
+ * 库存查询条件 → query 参数。
+ *
+ * {@code warehouse_code} 是信仓必填项:调用方指定优先,否则用账户配置的仓;
+ * 两者都没有就拒绝,避免把整个租户的库存拉下来。
+ */
+ public static Map toStockParams(InventoryQuery query, String defaultWarehouseCode) {
+ String warehouseCode = firstNonBlank(
+ query.warehouseCodes().isEmpty() ? null : query.warehouseCodes().get(0),
+ defaultWarehouseCode);
+ if (warehouseCode == null) {
+ throw new IllegalArgumentException(
+ "xincang stocklist requires warehouse_code; none given and account has none");
+ }
+ // 信仓只支持单个 warehouse_code;给了多个仓时不能静默只查第一个
+ if (query.warehouseCodes().size() > 1) {
+ throw new IllegalArgumentException(
+ "xincang stocklist accepts a single warehouse_code, got "
+ + query.warehouseCodes());
+ }
+ Map params = new LinkedHashMap();
+ params.put("warehouse_code", warehouseCode);
+ if (!query.providerSkus().isEmpty()) {
+ params.put("product_no", query.providerSkus().get(0));
+ }
+ params.put("page", pageNumber(query.cursor()));
+ params.put("limit", pageSize(query.pageSize()));
+ return params;
+ }
+
+ /** 库存响应 → 快照分页。 */
+ public static Page toSnapshots(XincangDtos.StockListResult rst,
+ String fallbackWarehouseCode,
+ Instant asOf,
+ int currentPage,
+ int pageSize) {
+ List out = new ArrayList();
+ if (rst != null && rst.data != null) {
+ for (XincangDtos.StockListResult.StockRow row : rst.data) {
+ if (row == null || blank(row.productSku)) {
+ continue;
+ }
+ out.add(InventorySnapshot.builder()
+ .warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode))
+ .providerSku(row.productSku.trim())
+ .available(intOf(row.canSaleSkuCount))
+ .onHand(intOf(row.realStock))
+ .inTransit(intOf(row.shipSkuCount))
+ .reserved(intOf(row.useSkuCount))
+ // 信仓不区分可售 / 不可售库位,统一按可售
+ .inventoryType(0)
+ .asOfUtc(asOf)
+ .productName(blankToNull(row.chnName))
+ .pendingOutbound(intOf(row.waitSkuCount))
+ .alertQuantity(intOf(row.alarmCount))
+ .volumeCbm(decimalOf(row.volumeCm))
+ .build());
+ }
+ }
+ return Page.of(out, nextCursor(currentPage, pageSize, out.size()));
+ }
+
+ // ---------------------------------------------------------------- 库龄
+
+ /** 库龄查询条件 → query 参数。 */
+ public static Map toAgeParams(InventoryAgeQuery query, String defaultWarehouseCode) {
+ Map params = new LinkedHashMap();
+ // bill_date 是「起 - 止」的单值字符串
+ params.put("bill_date", query.startDate().format(DATE) + " - " + query.endDate().format(DATE));
+ putIfPresent(params, "warehouse_code", firstNonBlank(query.warehouseCode(), defaultWarehouseCode));
+ putIfPresent(params, "key", query.providerSku());
+ params.put("page", pageNumber(query.cursor()));
+ params.put("limit", pageSize(query.pageSize()));
+ if (query.includeFeeRate() != null) {
+ params.put("is_need_fee_rate", query.includeFeeRate() ? 1 : 0);
+ }
+ return params;
+ }
+
+ /** 库龄响应 → 记录分页。 */
+ public static Page toAgeRecords(XincangDtos.StockAgeListResult rst,
+ String fallbackWarehouseCode,
+ int currentPage,
+ int pageSize) {
+ List out = new ArrayList();
+ if (rst != null && rst.data != null) {
+ for (XincangDtos.StockAgeListResult.AgeRow row : rst.data) {
+ if (row == null || blank(row.productSku)) {
+ continue;
+ }
+ Instant billingDate = parseDate(row.dt);
+ if (billingDate == null) {
+ // 计费日期是必填主键,解析不出就没法定位这条记录,跳过而不是猜今天
+ continue;
+ }
+ out.add(InventoryAgeRecord.builder()
+ .warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode))
+ .providerSku(row.productSku.trim())
+ .billingDate(billingDate)
+ .cabinetNo(blankToNull(row.cabinetNo))
+ .inStockAt(parseTime(row.inStockTime))
+ .ageDays(intOf(row.feeDays))
+ .quantity(intOf(row.skuCount))
+ .totalVolumeCbm(decimalOf(row.totalVolumeCbm))
+ .billingQuantity(intOf(row.feeCount))
+ .feeRate(decimalOf(row.configPrice))
+ .fee(parseMoney(row.sumFee))
+ .build());
+ }
+ }
+ return Page.of(out, nextCursor(currentPage, pageSize, out.size()));
+ }
+
+ // ---------------------------------------------------------------- internals
+
+ /**
+ * 有下一页时返回下一页页码。
+ *
+ * 信仓分页是 {@code page} / {@code limit},游标存字符串化页码;按「本页是否满页」
+ * 判断还有没有下一页——{@code count} 在部分响应里缺失,不能依赖。
+ */
+ static String nextCursor(int currentPage, int pageSize, int fetched) {
+ return fetched >= pageSize ? String.valueOf(currentPage + 1) : null;
+ }
+
+ static int pageNumber(String cursor) {
+ if (blank(cursor)) {
+ return 1;
+ }
+ try {
+ int v = Integer.parseInt(cursor.trim());
+ return v > 0 ? v : 1;
+ } catch (NumberFormatException e) {
+ return 1;
+ }
+ }
+
+ static int pageSize(int requested) {
+ if (requested <= 0) {
+ return 20;
+ }
+ return Math.min(requested, MAX_PAGE_SIZE);
+ }
+
+ static Instant parseTime(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return LocalDateTime.parse(raw.trim(), DATE_TIME)
+ .atZone(XincangConstants.SYSTEM_ZONE).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ static Instant parseDate(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return LocalDate.parse(raw.trim(), DATE)
+ .atStartOfDay(XincangConstants.SYSTEM_ZONE).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ static Money parseMoney(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return Money.of(new BigDecimal(raw.trim()), CURRENCY_USD);
+ } catch (RuntimeException e) {
+ return null;
+ }
+ }
+
+ static int intOf(String raw) {
+ if (blank(raw)) {
+ return 0;
+ }
+ try {
+ return (int) Math.round(Double.parseDouble(raw.trim()));
+ } catch (NumberFormatException e) {
+ return 0;
+ }
+ }
+
+ static BigDecimal decimalOf(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return new BigDecimal(raw.trim());
+ } catch (NumberFormatException e) {
+ return null;
+ }
+ }
+
+ static String firstNonBlank(String a, String b) {
+ if (!blank(a)) {
+ return a.trim();
+ }
+ return blank(b) ? null : b.trim();
+ }
+
+ static String blankToNull(String v) {
+ return blank(v) ? null : v.trim();
+ }
+
+ static boolean blank(String v) {
+ return v == null || v.trim().isEmpty();
+ }
+
+ private static void putIfPresent(Map params, String key, String value) {
+ if (!blank(value)) {
+ params.put(key, value.trim());
+ }
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
new file mode 100644
index 0000000..6583e83
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
@@ -0,0 +1,203 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.enums.LabelMode;
+import common.ecommerce.warehouse.enums.OutboundStatus;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.OutboundLine;
+import common.ecommerce.warehouse.model.OutboundOrder;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import common.ecommerce.xincang.dto.XincangDtos;
+import common.ecommerce.xincang.enums.XincangOrderStatus;
+
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 信仓订单详情报文 → 统一模型({@code GET api.get_order})。
+ *
+ * 平台字段名只出现在本类与 {@link XincangDtos}。
+ * 时间字段是北京时间 {@code yyyy-MM-dd HH:mm:ss},统一折算成 UTC。
+ */
+public final class XincangOrderDetailMapper {
+
+ private static final DateTimeFormatter DATE_TIME =
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+ private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+ private static final String CURRENCY_USD = "USD";
+
+ private XincangOrderDetailMapper() {
+ }
+
+ /**
+ * 订单详情 → {@link OutboundOrder}。
+ *
+ * @param detail 详情;调用方保证非 null
+ * @param ctx 本次调用上下文(仓编码兜底)
+ */
+ public static OutboundOrder toOrder(XincangDtos.OrderDetail detail, WarehouseContext ctx) {
+ OutboundStatus status = XincangOrderStatus.toCore(detail.state);
+ return OutboundOrder.builder()
+ .warehouseCode(firstNonBlank(detail.warehouseCode, ctx.providerWarehouseId()))
+ // 双号:信仓详情只回系统单号 order_no;
+ // outboundRequestNo 用它兜底,业务侧参考号进 orderRef
+ .outboundRequestNo(firstNonBlank(detail.orderNo, detail.ckh))
+ .providerOrderId(blankToNull(detail.orderNo))
+ .orderRef(blankToNull(detail.ckh))
+ .labelMode(labelModeOf(detail.orderType))
+ .status(status)
+ .rawStatus(detail.state)
+ .carrierCode(blankToNull(detail.logisticsType))
+ .trackingNumber(blankToNull(detail.trackingNumber))
+ .requestedAt(parseTime(detail.gmtCreate))
+ .shippedAt(parseTime(detail.deliveredTime))
+ .sourceProvider(WarehouseProvider.XINCANG)
+ .lines(toLines(detail))
+ .shipTo(toShipTo(detail))
+ .exceptionCode(blankToNull(detail.apiError))
+ .estimatedShippingFee(parseMoney(detail.totalAmount))
+ .currency(CURRENCY_USD)
+ .build();
+ }
+
+ /**
+ * 面单模式:{@code order_type=wayfair} 是自供面单,其余是仓自有面单。
+ *
+ * {@code LabelMode} 表达的正是「谁出面单」,与信仓 order_type 语义一致。
+ */
+ static LabelMode labelModeOf(String orderType) {
+ return "wayfair".equalsIgnoreCase(orderType) ? LabelMode.PLATFORM_LABEL : LabelMode.WAREHOUSE_LABEL;
+ }
+
+ /**
+ * 商品行。
+ *
+ * 详情同时给了 {@code products[]}(一票多件)和 {@code product_sku} / {@code sku_count}
+ * 单值字段;前者非空时以它为准,为空才退回单值字段。数量缺失或非正的行直接跳过——
+ * {@link OutboundLine} 要求数量为正,保留会在构造期抛异常。
+ */
+ static List toLines(XincangDtos.OrderDetail detail) {
+ List lines = new ArrayList();
+ if (detail.products != null && !detail.products.isEmpty()) {
+ int index = 0;
+ for (XincangDtos.OrderDetailProduct product : detail.products) {
+ if (product == null || blank(product.sku)) {
+ continue;
+ }
+ int qty = parsePositiveInt(product.qty);
+ if (qty <= 0) {
+ continue;
+ }
+ index++;
+ lines.add(OutboundLine.builder()
+ .lineNo(String.valueOf(index))
+ .omsSku(product.sku.trim())
+ .providerSku(product.sku.trim())
+ .quantity(qty)
+ .declareName(blankToNull(product.nameZhCn))
+ .build());
+ }
+ return lines;
+ }
+ int qty = parsePositiveInt(detail.skuCount);
+ if (!blank(detail.productSku) && qty > 0) {
+ lines.add(OutboundLine.builder()
+ .lineNo("1")
+ .omsSku(detail.productSku.trim())
+ .providerSku(detail.productSku.trim())
+ .quantity(qty)
+ .declareName(blankToNull(detail.productName))
+ .build());
+ }
+ return lines;
+ }
+
+ private static ShipTo toShipTo(XincangDtos.OrderDetail detail) {
+ if (blank(detail.country) && blank(detail.address) && blank(detail.receiveUser)) {
+ return null;
+ }
+ return ShipTo.builder()
+ .name(blankToNull(detail.receiveUser))
+ .phone(blankToNull(detail.phone))
+ .email(blankToNull(detail.email))
+ .countryCode(blankToNull(detail.country))
+ .stateOrProvince(blankToNull(detail.province))
+ .city(blankToNull(detail.city))
+ .addressLine1(blankToNull(detail.address))
+ .addressLine2(blankToNull(detail.address2))
+ .postalCode(blankToNull(detail.postcode))
+ .build();
+ }
+
+ /** 北京时间 {@code yyyy-MM-dd HH:mm:ss} → UTC;空值 / 非法返回 null。 */
+ static Instant parseTime(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return LocalDateTime.parse(raw.trim(), DATE_TIME)
+ .atZone(XincangConstants.SYSTEM_ZONE).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ /** 日期 {@code yyyy-MM-dd} → 北京时间当天 0 点的 UTC 时刻;空值 / 非法返回 null。 */
+ static Instant parseDate(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return LocalDate.parse(raw.trim(), DATE)
+ .atStartOfDay(XincangConstants.SYSTEM_ZONE).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ /** 金额 → USD;空值 / 非法返回 null(负值保留,费用可能有冲抵)。 */
+ static Money parseMoney(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return Money.of(raw.trim(), CURRENCY_USD);
+ } catch (RuntimeException e) {
+ return null;
+ }
+ }
+
+ static int parsePositiveInt(String raw) {
+ if (blank(raw)) {
+ return 0;
+ }
+ try {
+ int v = Integer.parseInt(raw.trim());
+ return v > 0 ? v : 0;
+ } catch (NumberFormatException e) {
+ return 0;
+ }
+ }
+
+ static String firstNonBlank(String a, String b) {
+ if (!blank(a)) {
+ return a.trim();
+ }
+ return blank(b) ? null : b.trim();
+ }
+
+ static String blankToNull(String v) {
+ return blank(v) ? null : v.trim();
+ }
+
+ static boolean blank(String v) {
+ return v == null || v.trim().isEmpty();
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
index d25cc44..e39c422 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
@@ -11,6 +11,7 @@ import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangDtos;
+import common.ecommerce.xincang.enums.XincangOrderType;
import java.time.Instant;
import java.time.LocalDateTime;
@@ -36,9 +37,6 @@ public final class XincangOrderMapper {
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
/** 地址 1 上限 32 字符,超出部分走 address2。 */
private static final int ADDRESS_MAX = 32;
- /** 订单类型:信仓只接受 common / wayfair。 */
- static final String ORDER_TYPE_COMMON = "common";
- static final String ORDER_TYPE_WAYFAIR = "wayfair";
/** 信仓布尔字段统一用「是 / 否」。 */
private static final String YES = "是";
private static final String NO = "否";
@@ -72,8 +70,8 @@ public final class XincangOrderMapper {
requireText(cmd.carrierCode(), "carrierCode (信仓 logistics_type)", ctx);
Map form = new LinkedHashMap();
- String orderType = orderTypeOf(cmd.salesPlatform());
- form.put("order_type", orderType);
+ XincangOrderType orderType = orderTypeOf(cmd.salesPlatform());
+ form.put("order_type", orderType.rawCode());
form.put("warehouse_code", warehouseCode);
// ckh = 参考号,信仓要求唯一;用 OMS 出库单号,便于回查
form.put("ckh", cmd.outboundRequestNo());
@@ -97,7 +95,7 @@ public final class XincangOrderMapper {
}
// wayfair(自供面单)时 gzh + face_base64 都是必填,缺了必然被仓拒绝,这里提前挡
- if (ORDER_TYPE_WAYFAIR.equals(orderType)) {
+ if (orderType.requiresSelfLabel()) {
requireText(cmd.trackingNumber(), "trackingNumber (信仓 gzh,wayfair 必填)", ctx);
requireText(cmd.labelContentBase64(), "labelContentBase64 (信仓 face_base64,wayfair 必填)", ctx);
}
@@ -139,13 +137,13 @@ public final class XincangOrderMapper {
}
/**
- * 信仓订单类型只接受 {@code common} / {@code wayfair}。
+ * 销售平台 → 信仓订单类型({@link XincangOrderType})。
*
* Wayfair 渠道走 {@code wayfair};其余平台走 {@code common}。
* 信仓不区分其它平台,不做臆造映射。
*/
- static String orderTypeOf(Platform platform) {
- return platform == Platform.WAYFAIR ? ORDER_TYPE_WAYFAIR : ORDER_TYPE_COMMON;
+ static XincangOrderType orderTypeOf(Platform platform) {
+ return platform == Platform.WAYFAIR ? XincangOrderType.WAYFAIR : XincangOrderType.COMMON;
}
/** 地址超过 32 字符的部分截到 address2,避免被仓侧截断丢信息。 */
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
new file mode 100644
index 0000000..1347435
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
@@ -0,0 +1,57 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.warehouse.enums.TransferStatus;
+import common.ecommerce.warehouse.enums.TransferType;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.xincang.dto.XincangDtos;
+import common.ecommerce.xincang.enums.XincangTransferState;
+
+/**
+ * 信仓转运详情报文 → 统一模型({@code GET fba.fba_detail})。
+ *
+ * 信仓的转运 = 从信仓发往平台仓,统一模型里固定为 {@link TransferType#OUTBOUND}。
+ */
+public final class XincangTransferDetailMapper {
+
+ private XincangTransferDetailMapper() {
+ }
+
+ /**
+ * 转运详情 → {@link TransferOrder}。
+ *
+ * @param detail 详情;调用方保证非 null
+ */
+ public static TransferOrder toOrder(XincangDtos.TransferDetail detail) {
+ TransferStatus status = XincangTransferState.toCore(detail.state);
+ return TransferOrder.builder()
+ // 双号:fba_no 是业务侧单号,order_no 是仓侧单号
+ .transferRequestNo(XincangOrderDetailMapper.firstNonBlank(
+ detail.fbaNo, detail.orderNo))
+ .providerTransferNo(XincangOrderDetailMapper.blankToNull(detail.orderNo))
+ .fromWarehouseCode(XincangOrderDetailMapper.blankToNull(detail.fromWarehouseName))
+ .toWarehouseCode(XincangOrderDetailMapper.blankToNull(detail.destWarehouseName))
+ .type(TransferType.OUTBOUND)
+ .status(status)
+ .rawStatus(detail.state)
+ .sourceProvider(WarehouseProvider.XINCANG)
+ .totalQuantity(totalQuantityOf(detail))
+ .estimatedOutboundAt(XincangOrderDetailMapper.parseDate(detail.preSendTime))
+ .remark(XincangOrderDetailMapper.blankToNull(detail.remark))
+ .build();
+ }
+
+ /** 明细件数合计;明细缺失时返回 0(未知,不猜)。 */
+ static int totalQuantityOf(XincangDtos.TransferDetail detail) {
+ if (detail.products == null || detail.products.isEmpty()) {
+ return 0;
+ }
+ int total = 0;
+ for (XincangDtos.TransferDetailProduct product : detail.products) {
+ if (product != null) {
+ total += XincangOrderDetailMapper.parsePositiveInt(product.skuCount);
+ }
+ }
+ return total;
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
index 2bd246b..18beb8f 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
@@ -6,10 +6,10 @@ import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TransferAttachment;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
-import common.ecommerce.warehouse.enums.TransferStatus;
import common.ecommerce.warehouse.enums.TransferType;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.dto.XincangDtos;
+import common.ecommerce.xincang.enums.XincangTransferState;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
@@ -111,15 +111,17 @@ public final class XincangTransferMapper {
/** 转运单创建结果 → 统一模型;信仓只回 {@code order_no},其余字段留空。 */
public static TransferOrder toCreated(TransferCommand cmd, String providerTransferNo) {
+ // 新增成功后处于待审核(state=0);审核走 approve
+ String rawState = XincangTransferState.PENDING_REVIEW.rawCode();
return TransferOrder.builder()
.transferRequestNo(cmd.transferRequestNo())
.providerTransferNo(providerTransferNo)
.fromWarehouseCode(cmd.fromWarehouseCode())
.toWarehouseCode(cmd.toWarehouseCode())
.type(cmd.type())
- // 新增成功后处于待审核;审核走 approve
- .status(TransferStatus.PENDING_REVIEW)
- .rawStatus("0")
+ .status(XincangTransferState.toCore(rawState))
+ .rawStatus(rawState)
+ .sourceProvider(WarehouseProvider.XINCANG)
.build();
}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
index f6cd414..2606380 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
@@ -9,7 +9,8 @@ import common.ecommerce.warehouse.sdk.WarehouseContext;
/**
* 信仓暂时不支持的出库 / 调拨能力。
*
- * 本轮只接入「新增订单」与「转运创建 / 审核」,查询、取消、包裹都还没接。
+ *
「新增订单」「订单详情 / 删除」「转运创建 / 审核 / 详情 / 删除」已接入;
+ * 列表查询与包裹还没接。
* 这里统一抛 {@link ValidationException}({@code retryable=false}),不返回空集合——
* 静默返回 {@code null} / 空会让调用方以为「仓说没有这单」。
*/
@@ -22,22 +23,25 @@ final class XincangUnsupportedOutbound {
throw unsupported(ctx, "warehouse.outbound.query");
}
- static ValidationException getUnsupported(WarehouseContext ctx) {
- throw unsupported(ctx, "warehouse.outbound.get");
- }
-
- static ValidationException checkCancelUnsupported(WarehouseContext ctx) {
- throw unsupported(ctx, "warehouse.outbound.checkCancel");
- }
-
- static ValidationException cancelUnsupported(WarehouseContext ctx) {
- throw unsupported(ctx, "warehouse.outbound.cancel");
- }
-
static ValidationException packagesUnsupported(WarehouseContext ctx) {
throw unsupported(ctx, "warehouse.outbound.packages");
}
+ /**
+ * 查询类接口返回了不可用结果(如报文里没有 {@code rst})。
+ *
+ * 用 {@code ValidationException} 而不是返回 null:调用方需要区分
+ * 「查不到」与「查到了但解析不出」,后者往往是协议变更的信号。
+ */
+ static ValidationException businessError(WarehouseContext ctx, String operation, String message) {
+ return new ValidationException(ChannelException.builder()
+ .message(message)
+ .operation(operation)
+ .provider(WarehouseProvider.XINCANG.name())
+ .requestId(ctx.requestId())
+ .retryable(false));
+ }
+
private static ValidationException unsupported(WarehouseContext ctx, String operation) {
return new ValidationException(ChannelException.builder()
.message("xincang does not implement " + operation + " yet")
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 48f5856..e4323f0 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
@@ -408,6 +408,166 @@ public final class XincangDtos {
public Attachment data;
}
+ /**
+ * 转运单详情({@code GET fba.fba_detail})的 {@code rst}。
+ *
+ * 只声明统一模型用得上的字段与排查必需的字段;附件同时给了对象和
+ * {@code *_url}(签名后可直接下载),这里两者都保留。
+ */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TransferDetail {
+
+ @JsonProperty("id")
+ public String id;
+ /** 转运单号(LTL...);审核与后续查询都用它。 */
+ @JsonProperty("order_no")
+ public String orderNo;
+ /** 业务侧转运单号(我们下发的 {@code fba_no})。 */
+ @JsonProperty("fba_no")
+ public String fbaNo;
+ @JsonProperty("po")
+ public String po;
+
+ /** 发货仓 id / 代码。 */
+ @JsonProperty("from_warehouse")
+ public String fromWarehouseId;
+ @JsonProperty("from_warehouse_name")
+ public String fromWarehouseName;
+ /** 目的仓 id / 代码。 */
+ @JsonProperty("dest_warehouse")
+ public String destWarehouseId;
+ @JsonProperty("dest_warehouse_name")
+ public String destWarehouseName;
+
+ /** 预约发货时间 {@code yyyy-MM-dd}。 */
+ @JsonProperty("pre_send_time")
+ public String preSendTime;
+ /** 状态码,见 {@code XincangTransferState}。 */
+ @JsonProperty("state")
+ public String state;
+ @JsonProperty("state_name")
+ public String stateName;
+
+ /** 是否需要产品贴 / 外箱贴 / 托盘贴:0 否 / 1 是。 */
+ @JsonProperty("is_product_label")
+ public String isProductLabel;
+ @JsonProperty("is_ctn_label")
+ public String isCtnLabel;
+ @JsonProperty("is_pallet_label")
+ public String isPalletLabel;
+ /** 是否打托:0 否 / 1 是。 */
+ @JsonProperty("is_pallet")
+ public String isPallet;
+
+ @JsonProperty("remark")
+ public String remark;
+ @JsonProperty("picking_time")
+ public String pickingTime;
+ @JsonProperty("picked_time")
+ public String pickedTime;
+ @JsonProperty("palleted_time")
+ public String palletedTime;
+ /** 发货时间。 */
+ @JsonProperty("send_time")
+ public String sendTime;
+ @JsonProperty("approve_time")
+ public String approveTime;
+ @JsonProperty("shipping_id")
+ public String shippingId;
+
+ /** 转运类型(字典值)。 */
+ @JsonProperty("delivery_mode")
+ public String deliveryMode;
+ /** 转运方式(字典值)。 */
+ @JsonProperty("delivery_way")
+ public String deliveryWay;
+ /** 订单类型(字典值)。 */
+ @JsonProperty("order_type")
+ public String orderType;
+ @JsonProperty("other_warehouse")
+ public String otherWarehouse;
+ /** 标签需求,逗号分隔。 */
+ @JsonProperty("label_requirement")
+ public String labelRequirement;
+
+ /** 附件对象。 */
+ @JsonProperty("product_label_att")
+ public Attachment productLabelAtt;
+ @JsonProperty("ctn_label_att")
+ public Attachment ctnLabelAtt;
+ @JsonProperty("pallet_label_att")
+ public Attachment palletLabelAtt;
+ @JsonProperty("bol_att")
+ public List bolAtt;
+ @JsonProperty("signature_bol_att")
+ public List signatureBolAtt;
+ @JsonProperty("express_label_att")
+ public Attachment expressLabelAtt;
+ @JsonProperty("other_att")
+ public List otherAtt;
+
+ /** 附件签名 URL(可直接下载)。 */
+ @JsonProperty("product_label_att_url")
+ public String productLabelAttUrl;
+ @JsonProperty("ctn_label_att_url")
+ public String ctnLabelAttUrl;
+ @JsonProperty("pallet_label_att_url")
+ public String palletLabelAttUrl;
+ @JsonProperty("bol_att_url")
+ public String bolAttUrl;
+ @JsonProperty("signature_bol_file")
+ public String signatureBolFile;
+ @JsonProperty("express_label_att_url")
+ public String expressLabelAttUrl;
+ @JsonProperty("other_att_url")
+ public String otherAttUrl;
+
+ /** 总费用。 */
+ @JsonProperty("total_amount")
+ public String totalAmount;
+
+ @JsonProperty("gmt_create")
+ public String gmtCreate;
+ @JsonProperty("gmt_modify")
+ public String gmtModify;
+
+ /** 产品明细。 */
+ @JsonProperty("products")
+ public List products;
+ }
+
+ /** 转运详情里的产品行。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TransferDetailProduct {
+
+ @JsonProperty("product_no")
+ public String productNo;
+ /** 件数。 */
+ @JsonProperty("sku_count")
+ public String skuCount;
+ /** 箱数。 */
+ @JsonProperty("box_count")
+ public String boxCount;
+ @JsonProperty("chn_name")
+ public String chnName;
+ @JsonProperty("packing_rate")
+ public String packingRate;
+ @JsonProperty("remark")
+ public String remark;
+ @JsonProperty("weight_lbs")
+ public String weightLbs;
+ @JsonProperty("weight_kg")
+ public String weightKg;
+ }
+
+ /** 转运详情响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TransferDetailResponse {
+
+ @JsonProperty("rst")
+ public TransferDetail rst;
+ }
+
/** 转运单创建结果 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TransferResult {
@@ -417,6 +577,438 @@ public final class XincangDtos {
public String orderNo;
}
+ /**
+ * 订单详情({@code GET api.get_order})的 {@code rst}。
+ *
+ * 字段名以文档为准;时间均为北京时间 {@code yyyy-MM-dd HH:mm:ss}(日期字段为
+ * {@code yyyy-MM-dd})。空值可能是空串,适配器里统一转 null。
+ */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderDetail {
+
+ /** 订单 id。 */
+ @JsonProperty("id")
+ public String id;
+
+ /** 信仓系统单号(DS-...)。 */
+ @JsonProperty("order_no")
+ public String orderNo;
+
+ /** 订单状态码,见 {@code XincangOrderStatus}。 */
+ @JsonProperty("state")
+ public String state;
+
+ /** 状态名。 */
+ @JsonProperty("state_name")
+ public String stateName;
+
+ /** 仓侧报错信息;正常为空。 */
+ @JsonProperty("api_error")
+ public String apiError;
+
+ /** 跟踪号。 */
+ @JsonProperty("gzh")
+ public String trackingNumber;
+
+ /** 面单 URL。 */
+ @JsonProperty("face_url")
+ public String faceUrl;
+
+ /** 参考号,即我们下发的 {@code ckh}。 */
+ @JsonProperty("ckh")
+ public String ckh;
+
+ /** 订单类型:common / wayfair。 */
+ @JsonProperty("order_type")
+ public String orderType;
+
+ /** 产品明细(一票多件)。 */
+ @JsonProperty("products")
+ public List products;
+
+ /** 件数。 */
+ @JsonProperty("sku_count")
+ public String skuCount;
+
+ @JsonProperty("dim_length")
+ public String dimLength;
+ @JsonProperty("dim_width")
+ public String dimWidth;
+ @JsonProperty("dim_height")
+ public String dimHeight;
+ @JsonProperty("dim_divisor")
+ public String dimDivisor;
+
+ /** 实重(磅)。 */
+ @JsonProperty("weight_lbs")
+ public String weightLbs;
+ /** 计费重(磅)。 */
+ @JsonProperty("billing_weight_lbs")
+ public String billingWeightLbs;
+ /** 体积重(磅)。 */
+ @JsonProperty("volume_weight_lbs")
+ public String volumeWeightLbs;
+
+ @JsonProperty("product_sku")
+ public String productSku;
+ @JsonProperty("product_name")
+ public String productName;
+ @JsonProperty("source_sku")
+ public String sourceSku;
+
+ @JsonProperty("warehouse_id")
+ public String warehouseId;
+ @JsonProperty("warehouse_code")
+ public String warehouseCode;
+
+ @JsonProperty("country")
+ public String country;
+ @JsonProperty("province")
+ public String province;
+ @JsonProperty("city")
+ public String city;
+ @JsonProperty("address")
+ public String address;
+ @JsonProperty("address2")
+ public String address2;
+ @JsonProperty("postcode")
+ public String postcode;
+ @JsonProperty("receive_user")
+ public String receiveUser;
+ @JsonProperty("phone")
+ public String phone;
+ @JsonProperty("email")
+ public String email;
+
+ /** 物流方式字典值。 */
+ @JsonProperty("logistics_type")
+ public String logisticsType;
+ @JsonProperty("is_sign")
+ public String isSign;
+ @JsonProperty("zone")
+ public String zone;
+
+ /** 总费用。 */
+ @JsonProperty("total_amount")
+ public String totalAmount;
+ @JsonProperty("repair_amount")
+ public String repairAmount;
+
+ @JsonProperty("approve_time")
+ public String approveTime;
+ /** 发货时间。 */
+ @JsonProperty("delivered_time")
+ public String deliveredTime;
+ @JsonProperty("shop_name")
+ public String shopName;
+ @JsonProperty("gmt_create")
+ public String gmtCreate;
+ @JsonProperty("gmt_modify")
+ public String gmtModify;
+ @JsonProperty("gmt_cancel")
+ public String gmtCancel;
+ /** 截单时间。 */
+ @JsonProperty("intercept_time")
+ public String interceptTime;
+ }
+
+ /** 订单详情里的产品行。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderDetailProduct {
+
+ @JsonProperty("product_id")
+ public String productId;
+ /** 产品 SKU。 */
+ @JsonProperty("sku")
+ public String sku;
+ /** 数量。 */
+ @JsonProperty("qty")
+ public String qty;
+ @JsonProperty("name_zh_cn")
+ public String nameZhCn;
+ }
+
+ /** 订单详情响应外层,用于取 {@code rst}。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderDetailResponse {
+
+ @JsonProperty("rst")
+ 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}({@code GET api.stocklist})。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockListResult {
+
+ @JsonProperty("code")
+ public String code;
+
+ @JsonProperty("msg")
+ public String msg;
+
+ @JsonProperty("data")
+ public List data;
+
+ /** 总条数(字符串)。 */
+ @JsonProperty("count")
+ public String count;
+
+ /** 一行库存。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockRow {
+
+ @JsonProperty("warehouse_code")
+ public String warehouseCode;
+
+ /** 产品 SKU。 */
+ @JsonProperty("product_sku")
+ public String productSku;
+
+ /** 实时库存。 */
+ @JsonProperty("real_stock")
+ public String realStock;
+
+ /** 可售数量。 */
+ @JsonProperty("cansale_sku_count")
+ public String canSaleSkuCount;
+
+ /** 占用数量。 */
+ @JsonProperty("use_sku_count")
+ public String useSkuCount;
+
+ /** 待出库数量。 */
+ @JsonProperty("wait_sku_count")
+ public String waitSkuCount;
+
+ /** 在海上数量。 */
+ @JsonProperty("ship_sku_count")
+ public String shipSkuCount;
+
+ /** 预警数量。 */
+ @JsonProperty("alerm_count")
+ public String alarmCount;
+
+ /** 商品名。 */
+ @JsonProperty("chn_name")
+ public String chnName;
+
+ /** 体积(立方厘米)。 */
+ @JsonProperty("volume_cm")
+ public String volumeCm;
+ }
+ }
+
+ /** 实时库存响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockListResponse {
+
+ @JsonProperty("rst")
+ public StockListResult rst;
+ }
+
+ /** 库龄列表响应 {@code rst}({@code GET api.stockagelist})。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockAgeListResult {
+
+ @JsonProperty("code")
+ public String code;
+
+ @JsonProperty("msg")
+ public String msg;
+
+ @JsonProperty("data")
+ public List data;
+
+ /** 总条数(字符串)。 */
+ @JsonProperty("count")
+ public String count;
+
+ /** 一行库龄。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class AgeRow {
+
+ /** 计费日期 {@code yyyy-MM-dd}。 */
+ @JsonProperty("dt")
+ public String dt;
+
+ @JsonProperty("warehouse_code")
+ public String warehouseCode;
+
+ /** 产品 SKU。 */
+ @JsonProperty("product_sku")
+ public String productSku;
+
+ /** 入库柜号。 */
+ @JsonProperty("cabinet_no")
+ public String cabinetNo;
+
+ /** 当日费用。 */
+ @JsonProperty("sum_fee")
+ public String sumFee;
+
+ /** 计费总体积(立方米)。 */
+ @JsonProperty("total_volume_cbm")
+ public String totalVolumeCbm;
+
+ /** 库存数量。 */
+ @JsonProperty("sku_count")
+ public String skuCount;
+
+ /** 入库时间 {@code yyyy-MM-dd HH:mm:ss}。 */
+ @JsonProperty("in_stock_time")
+ public String inStockTime;
+
+ /** 库龄天数。 */
+ @JsonProperty("fee_days")
+ public String feeDays;
+
+ /** 费率。 */
+ @JsonProperty("config_price")
+ public String configPrice;
+
+ /** 计费数量。 */
+ @JsonProperty("fee_count")
+ public String feeCount;
+ }
+ }
+
+ /** 库龄列表响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockAgeListResponse {
+
+ @JsonProperty("rst")
+ public StockAgeListResult rst;
+ }
+
/** 新增订单响应外层,用于取 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderResponse {
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangForecastStatus.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangForecastStatus.java
new file mode 100644
index 0000000..33f9a6b
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangForecastStatus.java
@@ -0,0 +1,84 @@
+package common.ecommerce.xincang.enums;
+
+import common.ecommerce.warehouse.enums.InboundStatus;
+
+/**
+ * 信仓预报(头程入库)状态({@code forecast.forecast_detail} 的 {@code state})。
+ *
+ * 码表来自 Apifox「OMS接口文档V2」预报详情:
+ * 0 建仓中 / 1 出运中 / 2 预报完成 / 3 在海上 / 4 送仓中 / 5 卸柜中 /
+ * 6 清点中 / 7 上架中 / 8 上架完成 / 9 已驳回。
+ *
+ * 信仓没有独立的「入库单」接口,预报单即头程入库单,这里映射到统一的
+ * {@link InboundStatus}。映射口径:
+ *
+ * - 0 建仓中 → 草稿(尚未提交)
+ * - 1 出运中 / 3 在海上 → 在途
+ * - 2 预报完成 → 待发货(预报已确认,等待实际发运)
+ * - 6 清点中 → 收货中;7 上架中 → 上架中;8 上架完成 → 已完成
+ *
+ *
+ * 未知码归 {@link #UNKNOWN},不猜。
+ */
+public enum XincangForecastStatus {
+
+ /** 0 建仓中。 */
+ BUILDING("0", InboundStatus.DRAFT),
+ /** 1 出运中。 */
+ SHIPPING("1", InboundStatus.IN_TRANSIT),
+ /** 2 预报完成。 */
+ FORECAST_DONE("2", InboundStatus.PENDING_SHIPMENT),
+ /** 3 在海上。 */
+ ON_SEA("3", InboundStatus.IN_TRANSIT),
+ /** 4 送仓中。 */
+ DELIVERING("4", InboundStatus.IN_TRANSIT),
+ /** 5 卸柜中。 */
+ UNLOADING("5", InboundStatus.RECEIVING),
+ /** 6 清点中。 */
+ COUNTING("6", InboundStatus.RECEIVING),
+ /** 7 上架中。 */
+ SHELVING("7", InboundStatus.STORING),
+ /** 8 上架完成。 */
+ SHELVED("8", InboundStatus.COMPLETED),
+ /** 9 已驳回。 */
+ REJECTED("9", InboundStatus.REJECTED),
+ /** 无法识别。 */
+ UNKNOWN(null, InboundStatus.UNKNOWN);
+
+ private final String rawCode;
+ private final InboundStatus core;
+
+ XincangForecastStatus(String rawCode, InboundStatus core) {
+ this.rawCode = rawCode;
+ this.core = core;
+ }
+
+ /** 信仓状态码;null 表示无法识别。 */
+ public String rawCode() {
+ return rawCode;
+ }
+
+ /** 对应的底层状态。 */
+ public InboundStatus toCore() {
+ return core;
+ }
+
+ /** 信仓状态码 → 平台枚举。 */
+ public static XincangForecastStatus of(String rawStatus) {
+ if (rawStatus == null || rawStatus.trim().isEmpty()) {
+ return UNKNOWN;
+ }
+ String s = rawStatus.trim();
+ for (XincangForecastStatus v : values()) {
+ if (s.equals(v.rawCode)) {
+ return v;
+ }
+ }
+ return UNKNOWN;
+ }
+
+ /** 信仓状态码 → 底层状态。 */
+ public static InboundStatus toCore(String rawStatus) {
+ return of(rawStatus).toCore();
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangOrderStatus.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangOrderStatus.java
new file mode 100644
index 0000000..fd7d946
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangOrderStatus.java
@@ -0,0 +1,93 @@
+package common.ecommerce.xincang.enums;
+
+import common.ecommerce.warehouse.enums.OutboundStatus;
+
+/**
+ * 信仓出库订单状态(订单列表 / 详情 / 删除接口的 {@code state})。
+ *
+ * 码表来自 Apifox「OMS接口文档V2」订单详情:
+ * 0 待审核 / 1 待发货 / 2 拣货中 / 3 已拣货 / 4 已贴单 / 5 已发货 /
+ * 6 已拦截 / 7 缺货 / 8 已取消 / 10 已删除 / 11 审核中 / 12 审核失败。
+ *
+ * 未知码归 {@link #UNKNOWN},不猜;原始值由调用方一起保存
+ * ({@code rawStatus} + {@code sourceProvider})。
+ */
+public enum XincangOrderStatus {
+
+ /** 0 待审核。 */
+ PENDING_REVIEW("0", OutboundStatus.PENDING_REVIEW),
+ /** 1 待发货。 */
+ PENDING_SHIPMENT("1", OutboundStatus.PENDING_SHIPMENT),
+ /** 2 拣货中。 */
+ PICKING("2", OutboundStatus.PICKING),
+ /** 3 已拣货。 */
+ PICKED("3", OutboundStatus.PICKED),
+ /** 4 已贴单(面单已出)。 */
+ LABEL_READY("4", OutboundStatus.LABEL_READY),
+ /** 5 已发货。 */
+ SHIPPED("5", OutboundStatus.SHIPPED),
+ /** 6 已拦截。 */
+ INTERCEPTED("6", OutboundStatus.INTERCEPTED),
+ /** 7 缺货。 */
+ OUT_OF_STOCK("7", OutboundStatus.OUT_OF_STOCK),
+ /** 8 已取消。 */
+ CANCELLED("8", OutboundStatus.CANCELLED),
+ /** 10 已删除。 */
+ DELETED("10", OutboundStatus.DELETED),
+ /** 11 审核中。 */
+ REVIEWING("11", OutboundStatus.REVIEWING),
+ /** 12 审核失败。 */
+ REVIEW_FAILED("12", OutboundStatus.REVIEW_FAILED),
+ /** 无法识别。 */
+ UNKNOWN(null, OutboundStatus.UNKNOWN);
+
+ private final String rawCode;
+ private final OutboundStatus core;
+
+ XincangOrderStatus(String rawCode, OutboundStatus core) {
+ this.rawCode = rawCode;
+ this.core = core;
+ }
+
+ /** 信仓状态码;null 表示无法识别。 */
+ public String rawCode() {
+ return rawCode;
+ }
+
+ /** 对应的底层状态。 */
+ public OutboundStatus toCore() {
+ return core;
+ }
+
+ /** 信仓状态码 → 平台枚举。 */
+ public static XincangOrderStatus of(String rawStatus) {
+ if (rawStatus == null || rawStatus.trim().isEmpty()) {
+ return UNKNOWN;
+ }
+ String s = rawStatus.trim();
+ for (XincangOrderStatus v : values()) {
+ if (s.equals(v.rawCode)) {
+ return v;
+ }
+ }
+ return UNKNOWN;
+ }
+
+ /** 信仓状态码 → 底层状态。 */
+ public static OutboundStatus toCore(String rawStatus) {
+ return of(rawStatus).toCore();
+ }
+
+ /** 底层状态 → 信仓状态码;无对应时返回 null(调用方决定是否拒绝)。 */
+ public static String codeOf(OutboundStatus status) {
+ if (status == null) {
+ return null;
+ }
+ for (XincangOrderStatus v : values()) {
+ if (v.core == status) {
+ return v.rawCode;
+ }
+ }
+ return null;
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangOrderType.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangOrderType.java
new file mode 100644
index 0000000..94da0de
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangOrderType.java
@@ -0,0 +1,49 @@
+package common.ecommerce.xincang.enums;
+
+/**
+ * 信仓下单的订单类型({@code api.add_order_multiple} 的 {@code order_type})。
+ *
+ * 信仓只接受两个值:{@code common}(非自供面单)与 {@code wayfair}(自供面单)。
+ *
+ * 只在这里出现,不映射到 core:这是「由谁提供面单」的仓方协议开关,
+ * core 已有 {@code LabelMode} 表达同一业务语义(仓出单 / 平台面单)。
+ * 两者的判定口径不同——core 看 {@code LabelMode},信仓看渠道平台是不是 Wayfair——
+ * 所以由适配器按自己的规则选择,不做枚举级映射,也不把仓方字符串塞进 core。
+ */
+public enum XincangOrderType {
+
+ /** 非自供面单(默认)。 */
+ COMMON("common"),
+ /** 自供面单;{@code gzh} 与 {@code face_base64} 必填。 */
+ WAYFAIR("wayfair");
+
+ private final String rawCode;
+
+ XincangOrderType(String rawCode) {
+ this.rawCode = rawCode;
+ }
+
+ /** 信仓原值。 */
+ public String rawCode() {
+ return rawCode;
+ }
+
+ /** 是否需要随单提供跟踪号与面单文件。 */
+ public boolean requiresSelfLabel() {
+ return this == WAYFAIR;
+ }
+
+ /** 信仓原值 → 平台枚举;未知返回 null(调用方按错误处理)。 */
+ public static XincangOrderType of(String rawCode) {
+ if (rawCode == null) {
+ return null;
+ }
+ String s = rawCode.trim();
+ for (XincangOrderType v : values()) {
+ if (v.rawCode.equals(s)) {
+ return v;
+ }
+ }
+ return null;
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangTransferState.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangTransferState.java
new file mode 100644
index 0000000..7f3f963
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/enums/XincangTransferState.java
@@ -0,0 +1,87 @@
+package common.ecommerce.xincang.enums;
+
+import common.ecommerce.warehouse.enums.TransferStatus;
+
+/**
+ * 信仓转运单状态({@code fba.fbalist} / {@code fba.fba_detail} 的 {@code state})。
+ *
+ * 码表来自 Apifox「OMS接口文档V2」转运详情:
+ * 0 待审核 / 1 待处理 / 2 待拣货 / 3 待贴标 / 4 待打托 / 5 待发货 / 6 已发货 / 7 已取消。
+ *
+ * 列表接口与详情接口的码表不一致:列表的 {@code state} 说明里写的是
+ * 「0 待审核 1 待处理 2 带拣货 3 待打托 4 待发货 5 已发货 9 取消」(少了「待贴标」、
+ * 后续码值整体前移)。详情接口的码表与 {@code state_name} 说明更完整,这里以详情码表
+ * 为准;联调时如果列表返回的 {@code state} 对不上,原始值仍在 {@code rawStatus} 里,
+ * 只需调整本枚举,不动调用方。
+ */
+public enum XincangTransferState {
+
+ /** 0 待审核。 */
+ PENDING_REVIEW("0", TransferStatus.PENDING_REVIEW),
+ /** 1 待处理。 */
+ PENDING_PROCESSING("1", TransferStatus.PENDING_PROCESSING),
+ /** 2 待拣货。 */
+ PENDING_PICK("2", TransferStatus.PENDING_PICK),
+ /** 3 待贴标。 */
+ PENDING_LABELING("3", TransferStatus.PENDING_LABELING),
+ /** 4 待打托。 */
+ PENDING_PALLETIZING("4", TransferStatus.PENDING_PALLETIZING),
+ /** 5 待发货。 */
+ PENDING_OUTBOUND("5", TransferStatus.PENDING_OUTBOUND),
+ /** 6 已发货。 */
+ SHIPPED("6", TransferStatus.SHIPPED),
+ /** 7 已取消。 */
+ CANCELLED("7", TransferStatus.CANCELLED),
+ /** 无法识别。 */
+ UNKNOWN(null, TransferStatus.UNKNOWN);
+
+ private final String rawCode;
+ private final TransferStatus core;
+
+ XincangTransferState(String rawCode, TransferStatus core) {
+ this.rawCode = rawCode;
+ this.core = core;
+ }
+
+ /** 信仓状态码;null 表示无法识别。 */
+ public String rawCode() {
+ return rawCode;
+ }
+
+ /** 对应的底层状态。 */
+ public TransferStatus toCore() {
+ return core;
+ }
+
+ /** 信仓状态码 → 平台枚举。 */
+ public static XincangTransferState of(String rawStatus) {
+ if (rawStatus == null || rawStatus.trim().isEmpty()) {
+ return UNKNOWN;
+ }
+ String s = rawStatus.trim();
+ for (XincangTransferState v : values()) {
+ if (s.equals(v.rawCode)) {
+ return v;
+ }
+ }
+ return UNKNOWN;
+ }
+
+ /** 信仓状态码 → 底层状态。 */
+ public static TransferStatus toCore(String rawStatus) {
+ return of(rawStatus).toCore();
+ }
+
+ /** 底层状态 → 信仓状态码;无对应时返回 null。 */
+ public static String codeOf(TransferStatus status) {
+ if (status == null) {
+ return null;
+ }
+ for (XincangTransferState v : values()) {
+ if (v.core == status) {
+ return v.rawCode;
+ }
+ }
+ return null;
+ }
+}
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..db6fa23 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,10 +120,13 @@ 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.INVENTORY_QUERY, 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
- assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY));
+ assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY));
+ // 退货等未接入,仍是 false
+ assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.RETURN));
}
}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangCancelOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangCancelOrderTest.java
new file mode 100644
index 0000000..a9e04c4
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangCancelOrderTest.java
@@ -0,0 +1,158 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.PlatformBusinessException;
+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.CancelEligibility;
+import common.ecommerce.warehouse.enums.OutboundStatus;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
+import common.ecommerce.warehouse.model.CancelCommand;
+import common.ecommerce.warehouse.model.CancelResult;
+import common.ecommerce.warehouse.model.OutboundRef;
+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 POST api.delete_order})与取消资格预判契约测试。
+ */
+class XincangCancelOrderTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ private static final String DETAIL_PENDING = "{\"rst\":{"
+ + "\"order_no\":\"DS-1\",\"ckh\":\"OB-1\",\"state\":\"0\",\"state_name\":\"待审核\","
+ + "\"order_type\":\"common\",\"warehouse_code\":\"NJ-2605\","
+ + "\"products\":[{\"sku\":\"SKU-A\",\"qty\":\"1\"}]},"
+ + "\"errno\":0,\"err\":\"\",\"trace_id\":\"t-1\"}";
+
+ 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-NJ-2605", WarehouseProvider.XINCANG, "NJ-2605",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ @Test
+ void cancelByProviderOrderId() {
+ transport.route(XincangConstants.PATH_ORDER_DELETE, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-del\"}"));
+ CancelCommand cmd = CancelCommand.builder()
+ .providerOrderId("DS-1")
+ .outboundRequestNo("OB-1")
+ .build();
+
+ CancelResult result = adapter.cancel(ctx(), cmd);
+
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("POST", req.method());
+ assertTrue(req.url().contains("/api.delete_order?"), req.url());
+ assertTrue(req.url().contains("order_no=DS-1"), req.url());
+ assertFalse(req.url().contains("ckh="), "有仓单号时不再传参考号");
+ assertTrue(req.url().contains("token=%7BT-1%7D"), req.url());
+ assertNull(req.body(), "删除订单无请求体");
+
+ assertTrue(result.cancelled());
+ assertEquals(CancelEligibility.FREE, result.eligibility());
+ assertEquals("DS-1", result.providerOrderId());
+ assertEquals("OB-1", result.outboundRequestNo());
+ }
+
+ @Test
+ void cancelFallsBackToReferenceNumber() {
+ transport.route(XincangConstants.PATH_ORDER_DELETE, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\"}"));
+ CancelCommand cmd = CancelCommand.builder().outboundRequestNo("OB-1").build();
+
+ adapter.cancel(ctx(), cmd);
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("ckh=OB-1"), url);
+ assertFalse(url.contains("order_no="), url);
+ }
+
+ @Test
+ void refusedDeletionBecomesBlockedException() {
+ transport.route(XincangConstants.PATH_ORDER_DELETE, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,"
+ + "\"err\":\"DS-BZY01-26101500005在该状态下不允许修改\",\"trace_id\":\"t-bad\"}"));
+
+ OutboundCancelBlockedException e = assertThrows(OutboundCancelBlockedException.class,
+ () -> adapter.cancel(ctx(), CancelCommand.builder().providerOrderId("DS-1").build()));
+ assertTrue(e.getMessage().contains("该状态下不允许修改"), e.getMessage());
+ assertFalse(e.retryable());
+ }
+
+ @Test
+ void checkCancelUsesOrderStatus() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(DETAIL_PENDING));
+
+ assertEquals(CancelEligibility.FREE,
+ adapter.checkCancel(ctx(), OutboundRef.ofProviderOrderId("DS-1")));
+ }
+
+ @Test
+ void checkCancelMapsTerminalStatesToBlocked() {
+ assertBlocked(OutboundStatus.SHIPPED);
+ assertBlocked(OutboundStatus.CANCELLED);
+ assertBlocked(OutboundStatus.INTERCEPTED);
+ assertBlocked(OutboundStatus.DELETED);
+ assertBlocked(OutboundStatus.UNKNOWN);
+ }
+
+ @Test
+ void checkCancelAllowsPreShipmentStates() {
+ assertFree(OutboundStatus.PENDING_REVIEW);
+ assertFree(OutboundStatus.PENDING_SHIPMENT);
+ assertFree(OutboundStatus.REVIEWING);
+ assertFree(OutboundStatus.PICKING);
+ assertFree(OutboundStatus.PICKED);
+ }
+
+ @Test
+ void checkCancelPropagatesLookupFailure() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,\"err\":\"订单不存在\",\"trace_id\":\"t-404\"}"));
+
+ assertThrows(PlatformBusinessException.class,
+ () -> adapter.checkCancel(ctx(), OutboundRef.ofProviderOrderId("DS-X")));
+ }
+
+ private static void assertBlocked(OutboundStatus status) {
+ assertEquals(CancelEligibility.BLOCKED, XincangAdapter.cancelEligibilityOf(status), status.name());
+ }
+
+ private static void assertFree(OutboundStatus status) {
+ assertEquals(CancelEligibility.FREE, XincangAdapter.cancelEligibilityOf(status), status.name());
+ }
+}
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"));
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDeleteTransferTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDeleteTransferTest.java
new file mode 100644
index 0000000..4e1db7d
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDeleteTransferTest.java
@@ -0,0 +1,89 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.PlatformBusinessException;
+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.WarehouseProvider;
+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 POST fba.delete_fba})契约测试。
+ */
+class XincangDeleteTransferTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ 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-15950", WarehouseProvider.XINCANG, "CA-15950",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ @Test
+ void deletesTransferByOrderNo() {
+ transport.route(XincangConstants.PATH_TRANSFER_DELETE, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-del\"}"));
+
+ adapter.deleteTransfer(ctx(), "LTL26101500002");
+
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("POST", req.method());
+ assertTrue(req.url().contains("/fba.delete_fba?"), req.url());
+ assertTrue(req.url().contains("order_no=LTL26101500002"), req.url());
+ assertTrue(req.url().contains("token=%7BT-1%7D"), req.url());
+ assertNull(req.body(), "删除转运无请求体");
+ }
+
+ @Test
+ void nonPendingTransferIsRejectedByWarehouse() {
+ transport.route(XincangConstants.PATH_TRANSFER_DELETE, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,\"err\":\"只有待审核状态的订单可以删除\",\"trace_id\":\"t-bad\"}"));
+
+ PlatformBusinessException e = assertThrows(PlatformBusinessException.class,
+ () -> adapter.deleteTransfer(ctx(), "LTL-1"));
+ assertTrue(e.getMessage().contains("待审核"), e.getMessage());
+ assertFalse(e.retryable());
+ }
+
+ @Test
+ void blankOrderNoIsRejectedBeforeSending() {
+ ValidationException e = assertThrows(ValidationException.class,
+ () -> adapter.deleteTransfer(ctx(), " "));
+ assertTrue(e.getMessage().contains("providerTransferNo"), e.getMessage());
+ assertFalse(transport.recorded().stream()
+ .anyMatch(r -> r.url().contains(XincangConstants.PATH_TRANSFER_DELETE)));
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java
new file mode 100644
index 0000000..3f295f9
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java
@@ -0,0 +1,200 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.support.Page;
+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.InventorySyncStrategy;
+import common.ecommerce.warehouse.enums.WarehouseCapability;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.InventoryAgeQuery;
+import common.ecommerce.warehouse.model.InventoryAgeRecord;
+import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.InventorySnapshot;
+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 java.time.Instant;
+import java.time.LocalDate;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 实时库存({@code api.stocklist})与库龄列表({@code api.stockagelist})契约测试。
+ */
+class XincangInventoryTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ private static final String STOCK_BODY = "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":["
+ + "{\"warehouse_code\":\"NJ-2605\",\"product_sku\":\"LSS29ORANGE\","
+ + "\"real_stock\":\"1500\",\"cansale_sku_count\":\"1499\",\"use_sku_count\":\"1\","
+ + "\"wait_sku_count\":\"1\",\"ship_sku_count\":\"0\",\"alerm_count\":\"0\","
+ + "\"chn_name\":\"餐椅\",\"volume_cm\":\"136221.5274\"}"
+ + "],\"count\":\"1\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-stock\"}";
+
+ private static final String AGE_BODY = "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":["
+ + "{\"dt\":\"2026-10-14\",\"warehouse_code\":\"NJ-2605\",\"product_sku\":\"LSS29ORANGE\","
+ + "\"cabinet_no\":\"KKKKK001\",\"sum_fee\":\"0.00\",\"total_volume_cbm\":\"204.3323\","
+ + "\"sku_count\":\"1500\",\"in_stock_time\":\"2026-10-14 08:00:00\",\"fee_days\":\"1\","
+ + "\"config_price\":\"0.50\",\"fee_count\":\"1500\"}"
+ + "],\"count\":\"1\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-age\"}";
+
+ 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-NJ-2605", WarehouseProvider.XINCANG, "NJ-2605",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ @Test
+ void stockQuerySendsWarehouseAndMapsSnapshot() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY));
+
+ Page page = adapter.query(ctx(),
+ InventoryQuery.builder().warehouseCode("NJ-2605").pageSize(10).build());
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("/api.stocklist?"), url);
+ assertTrue(url.contains("warehouse_code=NJ-2605"), url);
+ assertTrue(url.contains("page=1"), url);
+ assertTrue(url.contains("limit=10"), url);
+ assertTrue(url.contains("token=%7BT-1%7D"), url);
+
+ assertEquals(1, page.size());
+ InventorySnapshot snap = page.items().get(0);
+ assertEquals("NJ-2605", snap.warehouseCode());
+ assertEquals("LSS29ORANGE", snap.providerSku());
+ assertEquals(1500, snap.onHand());
+ assertEquals(1499, snap.available());
+ assertEquals(1, snap.reserved());
+ assertEquals(1, snap.pendingOutbound());
+ assertEquals(0, snap.inTransit());
+ assertEquals(0, snap.inventoryType());
+ assertEquals("餐椅", snap.productName());
+ assertEquals(0, snap.volumeCbm().compareTo(new java.math.BigDecimal("136221.5274")));
+ assertNotNull(snap.asOfUtc());
+ }
+
+ @Test
+ void stockFallsBackToAccountWarehouse() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY));
+
+ adapter.query(ctx(), InventoryQuery.builder().build());
+
+ assertTrue(transport.lastDataRequest().url().contains("warehouse_code=NJ-2605"));
+ }
+
+ @Test
+ void multipleWarehousesAreRejectedInsteadOfSilentlyUsingFirst() {
+ IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+ () -> adapter.query(ctx(), InventoryQuery.builder()
+ .warehouseCode("A").warehouseCode("B").build()));
+ assertTrue(e.getMessage().contains("single warehouse_code"), e.getMessage());
+ }
+
+ @Test
+ void stockSkuFilterIsSent() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY));
+
+ adapter.query(ctx(), InventoryQuery.builder().sku("LSS29ORANGE").build());
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("product_no=LSS29ORANGE"), url);
+ }
+
+ @Test
+ void ageQuerySendsBillDateRangeAndMapsRecord() {
+ transport.route(XincangConstants.PATH_STOCK_AGE_LIST, req -> Responses.ok(AGE_BODY));
+
+ Page page = adapter.queryAges(ctx(), InventoryAgeQuery.builder()
+ .dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-31"))
+ .includeFeeRate(true)
+ .build());
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("/api.stockagelist?"), url);
+ // bill_date 是「起 - 止」单值,空格与连字符会被 URL 编码
+ assertTrue(url.contains("bill_date=2026-10-01+-+2026-10-31"), url);
+ assertTrue(url.contains("is_need_fee_rate=1"), url);
+ assertTrue(url.contains("warehouse_code=NJ-2605"), "未指定仓时用账户配置: " + url);
+
+ assertEquals(1, page.size());
+ InventoryAgeRecord rec = page.items().get(0);
+ assertEquals("NJ-2605", rec.warehouseCode());
+ assertEquals("LSS29ORANGE", rec.providerSku());
+ // 计费日期按北京时间 0 点 → UTC 前一天 16:00
+ assertEquals(Instant.parse("2026-10-13T16:00:00Z"), rec.billingDate());
+ assertEquals("KKKKK001", rec.cabinetNo());
+ assertEquals(1, rec.ageDays());
+ assertEquals(1500, rec.quantity());
+ assertEquals(1500, rec.billingQuantity());
+ assertEquals(0, rec.feeRate().compareTo(new java.math.BigDecimal("0.50")));
+ assertEquals(0, rec.fee().amount().compareTo(java.math.BigDecimal.ZERO));
+ assertEquals("USD", rec.fee().currencyCode());
+ assertEquals(Instant.parse("2026-10-14T00:00:00Z"), rec.inStockAt());
+ }
+
+ @Test
+ void ageQueryRejectsMissingDateRange() {
+ assertThrows(IllegalArgumentException.class,
+ () -> InventoryAgeQuery.builder().build());
+ assertThrows(IllegalArgumentException.class,
+ () -> InventoryAgeQuery.builder()
+ .dateRange(LocalDate.parse("2026-10-31"), LocalDate.parse("2026-10-01"))
+ .build());
+ }
+
+ @Test
+ void ageQuerySkipsRowsWithoutBillingDate() {
+ String noDate = AGE_BODY.replace("\"dt\":\"2026-10-14\",", "\"dt\":\"\",");
+ transport.route(XincangConstants.PATH_STOCK_AGE_LIST, req -> Responses.ok(noDate));
+
+ Page page = adapter.queryAges(ctx(), InventoryAgeQuery.builder()
+ .dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-31")).build());
+
+ assertTrue(page.items().isEmpty(), "计费日期解析不出时跳过,不猜日期");
+ }
+
+ @Test
+ void missingRstIsNotSilentEmpty() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\"}"));
+
+ assertThrows(ValidationException.class,
+ () -> adapter.query(ctx(), InventoryQuery.builder().build()));
+ }
+
+ @Test
+ void inventoryCapabilityAndStrategy() {
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
+ assertEquals(InventorySyncStrategy.FULL_PULL_DIFF, adapter.syncStrategy());
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderDetailTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderDetailTest.java
new file mode 100644
index 0000000..feac2d3
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderDetailTest.java
@@ -0,0 +1,207 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.PlatformBusinessException;
+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.LabelMode;
+import common.ecommerce.warehouse.enums.OutboundStatus;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.OutboundOrder;
+import common.ecommerce.warehouse.model.OutboundRef;
+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 java.time.Instant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 订单详情({@code GET api.get_order})契约测试。
+ */
+class XincangOrderDetailTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ /** 文档「成功示例」原文。 */
+ private static final String DETAIL = "{"
+ + "\"id\":\"126508095093477568\","
+ + "\"order_no\":\"DS-BZY01-26101600001\","
+ + "\"state\":\"0\","
+ + "\"state_name\":\"待审核\","
+ + "\"api_error\":\"验证订单操作失败\","
+ + "\"gzh\":\"\","
+ + "\"face_url\":\"\","
+ + "\"ckh\":\"Ref26101601\","
+ + "\"order_type\":\"common\","
+ + "\"products\":[{\"product_id\":\"1\",\"sku\":\"LSS29BLACK\",\"qty\":\"1\","
+ + "\"name_zh_cn\":\"餐椅\"}],"
+ + "\"sku_count\":\"1\","
+ + "\"dim_length\":\"25.9840\",\"dim_width\":\"18.8976\",\"dim_height\":\"16.9290\","
+ + "\"dim_divisor\":\"250.00\",\"weight_lbs\":\"23.5000\","
+ + "\"billing_weight_lbs\":\"34.00\",\"volume_weight_lbs\":\"34\","
+ + "\"product_sku\":\"LSS29BLACK\",\"product_name\":\"餐椅\",\"source_sku\":\"LSS29BLACK\","
+ + "\"warehouse_id\":\"84047962479824\",\"warehouse_code\":\"NJ-2605\","
+ + "\"country\":\"US\",\"province\":\"GA\",\"city\":\"STONE MOUNTAIN\","
+ + "\"address\":\"5039 LELAND DR\",\"address2\":\"\",\"postcode\":\"30083-6026\","
+ + "\"receive_user\":\"DARA\",\"phone\":\"+1 480-618-5344\",\"email\":\"\","
+ + "\"logistics_type\":\"FEDEX-G\",\"is_sign\":\"0\",\"zone\":\"5\","
+ + "\"total_amount\":\"0\",\"repair_amount\":\"0\","
+ + "\"approve_time\":\"2026-10-16 16:20:46\",\"delivered_time\":\"\","
+ + "\"shop_name\":\"BZY01-shop\",\"gmt_create\":\"2026-10-16 10:18:00\","
+ + "\"gmt_modify\":\"2026-10-16 10:18:00\",\"gmt_cancel\":\"\",\"intercept_time\":\"\""
+ + "}";
+
+ private static final String OK_BODY = "{\"rst\":" + DETAIL
+ + ",\"errno\":0,\"err\":\"\",\"trace_id\":\"t-1\"}";
+
+ 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-NJ-2605", WarehouseProvider.XINCANG, "NJ-2605",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ @Test
+ void getByProviderOrderIdMapsDetail() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(OK_BODY));
+
+ OutboundOrder order = adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-BZY01-26101600001"));
+
+ // 请求:GET + query token + order_no
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("GET", req.method());
+ assertTrue(req.url().contains("/api.get_order?"), req.url());
+ assertTrue(req.url().contains("order_no=DS-BZY01-26101600001"), req.url());
+ assertTrue(req.url().contains("token=%7BT-1%7D"), req.url());
+ assertFalse(req.url().contains("ckh="), "给了 order_no 就不该再传 ckh");
+
+ // 映射
+ assertEquals("NJ-2605", order.warehouseCode());
+ assertEquals("DS-BZY01-26101600001", order.outboundRequestNo());
+ assertEquals("DS-BZY01-26101600001", order.providerOrderId());
+ assertEquals("Ref26101601", order.orderRef());
+ assertEquals(OutboundStatus.PENDING_REVIEW, order.status());
+ assertEquals("0", order.rawStatus());
+ assertEquals(LabelMode.WAREHOUSE_LABEL, order.labelMode());
+ assertEquals("FEDEX-G", order.carrierCode());
+ assertEquals("验证订单操作失败", order.exceptionCode());
+ assertEquals(WarehouseProvider.XINCANG, order.sourceProvider());
+ // 北京时间 2026-10-16 10:18:00 → UTC 02:18:00
+ assertEquals(Instant.parse("2026-10-16T02:18:00Z"), order.requestedAt());
+ assertNull(order.shippedAt(), "空串的发货时间应为 null");
+
+ assertEquals(1, order.lines().size());
+ assertEquals("LSS29BLACK", order.lines().get(0).omsSku());
+ assertEquals(1, order.lines().get(0).quantity());
+ assertEquals("餐椅", order.lines().get(0).declareName());
+
+ assertEquals("US", order.shipTo().countryCode());
+ assertEquals("GA", order.shipTo().stateOrProvince());
+ assertEquals("DARA", order.shipTo().name());
+ assertNull(order.shipTo().addressLine2(), "空串地址2 应为 null");
+ }
+
+ @Test
+ void getFallsBackToReferenceNumber() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(OK_BODY));
+
+ adapter.get(ctx(), OutboundRef.ofRequestNo("Ref26101601"));
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("ckh=Ref26101601"), url);
+ assertFalse(url.contains("order_no="), "没有仓单号时只传 ckh");
+ }
+
+ @Test
+ void wayfairOrderMapsToPlatformLabel() {
+ String wayfair = OK_BODY.replace("\"order_type\":\"common\"", "\"order_type\":\"wayfair\"");
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(wayfair));
+
+ OutboundOrder order = adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-1"));
+
+ assertEquals(LabelMode.PLATFORM_LABEL, order.labelMode());
+ }
+
+ @Test
+ void fallsBackToSingleSkuWhenProductsMissing() {
+ String single = OK_BODY.replace(
+ "\"products\":[{\"product_id\":\"1\",\"sku\":\"LSS29BLACK\",\"qty\":\"1\",\"name_zh_cn\":\"餐椅\"}]",
+ "\"products\":[]").replace("\"sku_count\":\"1\"", "\"sku_count\":\"3\"");
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(single));
+
+ OutboundOrder order = adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-1"));
+
+ assertEquals(1, order.lines().size());
+ assertEquals("LSS29BLACK", order.lines().get(0).omsSku());
+ assertEquals(3, order.lines().get(0).quantity());
+ }
+
+ @Test
+ void unknownStateIsNotGuessed() {
+ String unknown = OK_BODY.replace("\"state\":\"0\"", "\"state\":\"99\"");
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(unknown));
+
+ OutboundOrder order = adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-1"));
+
+ assertEquals(OutboundStatus.UNKNOWN, order.status());
+ assertEquals("99", order.rawStatus());
+ }
+
+ @Test
+ void businessErrorPropagates() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,\"err\":\"订单不存在\",\"trace_id\":\"t-err\"}"));
+
+ PlatformBusinessException e = assertThrows(PlatformBusinessException.class,
+ () -> adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-NONE")));
+ assertTrue(e.getMessage().contains("订单不存在"), e.getMessage());
+ }
+
+ @Test
+ void emptyRstIsNotSilentNull() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-empty\"}"));
+
+ common.ecommerce.shared.error.ValidationException e =
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-1")));
+ assertTrue(e.getMessage().contains("no rst"), e.getMessage());
+ }
+
+ @Test
+ void timeParsingIsBeijingToUtc() {
+ assertEquals(Instant.parse("2026-10-16T02:18:00Z"),
+ XincangOrderDetailMapper.parseTime("2026-10-16 10:18:00"));
+ assertNull(XincangOrderDetailMapper.parseTime(""));
+ assertNull(XincangOrderDetailMapper.parseTime("not-a-time"));
+ assertEquals(Instant.parse("2026-10-15T16:00:00Z"),
+ XincangOrderDetailMapper.parseDate("2026-10-16"));
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
index 97b9640..711f01f 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
@@ -213,11 +213,9 @@ class XincangOrderTest {
@Test
void queryAndCancelAreExplicitlyUnsupported() {
- assertThrows(common.ecommerce.shared.error.ValidationException.class,
- () -> adapter.get(ctx(), null));
- assertThrows(common.ecommerce.shared.error.ValidationException.class,
- () -> adapter.query(ctx(), null));
- assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
+ // get / query 均已接入(见 XincangOrderDetailTest、XincangInventoryTest),
+ // 这里只断言能力位齐全
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
}
@Test
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
index 3d57653..eea8b23 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
@@ -246,7 +246,7 @@ class XincangProductTest {
@Test
void productCapabilityIsDeclared() {
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
- assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
+ assertFalse(adapter.capabilities().contains(WarehouseCapability.RETURN));
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
}
}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferDetailTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferDetailTest.java
new file mode 100644
index 0000000..1cd0127
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferDetailTest.java
@@ -0,0 +1,178 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.PlatformBusinessException;
+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.TransferStatus;
+import common.ecommerce.warehouse.enums.TransferType;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.TransferOrder;
+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 java.time.Instant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 转运详情({@code GET fba.fba_detail})契约测试。
+ */
+class XincangTransferDetailTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ /** 文档「成功示例」原文(截取与映射相关的字段)。 */
+ private static final String DETAIL = "{"
+ + "\"id\":\"128064084674485505\","
+ + "\"order_no\":\"LTL2610200000271\","
+ + "\"fba_no\":\"ZYDD20261020001\","
+ + "\"po\":\"ZYDD20261020001\","
+ + "\"from_warehouse\":\"84047962307416\","
+ + "\"from_warehouse_name\":\"CA-15950\","
+ + "\"dest_warehouse\":\"0\","
+ + "\"dest_warehouse_name\":\"123\","
+ + "\"pre_send_time\":\"2026-10-21\","
+ + "\"state\":\"6\","
+ + "\"state_name\":\"已发货\","
+ + "\"remark\":\"\","
+ + "\"is_pallet\":\"1\","
+ + "\"delivery_mode\":\"LTL\","
+ + "\"delivery_way\":\"卡车\","
+ + "\"label_requirement\":\"产品贴,外箱标签,托盘标签\","
+ + "\"total_amount\":\"84.25\","
+ + "\"products\":["
+ + "{\"product_no\":\"BOOK\",\"sku_count\":\"10\",\"box_count\":\"5\",\"packing_rate\":\"2\"},"
+ + "{\"product_no\":\"FHCP006\",\"sku_count\":\"10\",\"box_count\":\"5\",\"packing_rate\":\"2\"}"
+ + "]"
+ + "}";
+
+ private static final String OK_BODY = "{\"rst\":" + DETAIL
+ + ",\"errno\":0,\"err\":\"\",\"trace_id\":\"t-1\"}";
+
+ 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-15950", WarehouseProvider.XINCANG, "CA-15950",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ @Test
+ void getMapsTransferDetail() {
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(OK_BODY));
+
+ TransferOrder order = adapter.getTransfer(ctx(), "LTL2610200000271");
+
+ // 请求
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("GET", req.method());
+ assertTrue(req.url().contains("/fba.fba_detail?"), req.url());
+ assertTrue(req.url().contains("order_no=LTL2610200000271"), req.url());
+ assertTrue(req.url().contains("token=%7BT-1%7D"), req.url());
+
+ // 双号:fba_no 是业务单号,order_no 是仓单号
+ assertEquals("ZYDD20261020001", order.transferRequestNo());
+ assertEquals("LTL2610200000271", order.providerTransferNo());
+ assertEquals("CA-15950", order.fromWarehouseCode());
+ assertEquals("123", order.toWarehouseCode());
+ assertEquals(TransferType.OUTBOUND, order.type());
+ assertEquals(TransferStatus.SHIPPED, order.status());
+ assertEquals("6", order.rawStatus());
+ assertEquals(WarehouseProvider.XINCANG, order.sourceProvider());
+ assertEquals(20, order.totalQuantity(), "10 + 10");
+ // pre_send_time 2026-10-21 北京时间 0 点 → UTC 前一天 16:00
+ assertEquals(Instant.parse("2026-10-20T16:00:00Z"), order.estimatedOutboundAt());
+ assertNull(order.remark(), "空串备注应为 null");
+ }
+
+ @Test
+ void unknownTransferStateIsNotGuessed() {
+ String unknown = OK_BODY.replace("\"state\":\"6\"", "\"state\":\"99\"");
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(unknown));
+
+ TransferOrder order = adapter.getTransfer(ctx(), "LTL-1");
+
+ assertEquals(TransferStatus.UNKNOWN, order.status());
+ assertEquals("99", order.rawStatus());
+ }
+
+ @Test
+ void outputStateMapsToShipped() {
+ // 信仓 state=6「已发货」→ core SHIPPED,不是 COMPLETED
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(OK_BODY));
+
+ TransferOrder order = adapter.getTransfer(ctx(), "LTL-1");
+
+ assertEquals(TransferStatus.SHIPPED, order.status());
+ assertFalse(order.completed(), "已发货不等于已完成");
+ }
+
+ @Test
+ void missingProductsMeansUnknownQuantity() {
+ String noProducts = OK_BODY.replace(
+ ",\"products\":["
+ + "{\"product_no\":\"BOOK\",\"sku_count\":\"10\",\"box_count\":\"5\",\"packing_rate\":\"2\"},"
+ + "{\"product_no\":\"FHCP006\",\"sku_count\":\"10\",\"box_count\":\"5\",\"packing_rate\":\"2\"}"
+ + "]", "");
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(noProducts));
+
+ assertEquals(0, adapter.getTransfer(ctx(), "LTL-1").totalQuantity());
+ }
+
+ @Test
+ void blankOrderNoIsRejectedBeforeSending() {
+ common.ecommerce.shared.error.ValidationException e =
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.getTransfer(ctx(), " "));
+ assertTrue(e.getMessage().contains("providerTransferNo"), e.getMessage());
+ assertFalse(transport.recorded().stream()
+ .anyMatch(r -> r.url().contains(XincangConstants.PATH_TRANSFER_DETAIL)));
+ }
+
+ @Test
+ void businessErrorPropagates() {
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,\"err\":\"转运单不存在\",\"trace_id\":\"t-err\"}"));
+
+ PlatformBusinessException e = assertThrows(PlatformBusinessException.class,
+ () -> adapter.getTransfer(ctx(), "LTL-NONE"));
+ assertTrue(e.getMessage().contains("转运单不存在"), e.getMessage());
+ }
+
+ @Test
+ void emptyRstIsNotSilentNull() {
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-empty\"}"));
+
+ common.ecommerce.shared.error.ValidationException e =
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.getTransfer(ctx(), "LTL-1"));
+ assertTrue(e.getMessage().contains("no rst"), e.getMessage());
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/enums/XincangEnumsTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/enums/XincangEnumsTest.java
new file mode 100644
index 0000000..efb28c9
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/enums/XincangEnumsTest.java
@@ -0,0 +1,80 @@
+package common.ecommerce.xincang.enums;
+
+import common.ecommerce.warehouse.enums.InboundStatus;
+import common.ecommerce.warehouse.enums.OutboundStatus;
+import common.ecommerce.warehouse.enums.TransferStatus;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 信仓平台枚举 → core 底层枚举的映射。
+ *
+ * 码表来自 Apifox「OMS接口文档V2」,1:1 对应;认不出的值一律归 UNKNOWN,不猜。
+ */
+class XincangEnumsTest {
+
+ @Test
+ void orderStatusMapsEveryDocumentedCode() {
+ assertEquals(OutboundStatus.PENDING_REVIEW, XincangOrderStatus.toCore("0"));
+ assertEquals(OutboundStatus.PENDING_SHIPMENT, XincangOrderStatus.toCore("1"));
+ assertEquals(OutboundStatus.PICKING, XincangOrderStatus.toCore("2"));
+ assertEquals(OutboundStatus.PICKED, XincangOrderStatus.toCore("3"));
+ assertEquals(OutboundStatus.LABEL_READY, XincangOrderStatus.toCore("4"));
+ assertEquals(OutboundStatus.SHIPPED, XincangOrderStatus.toCore("5"));
+ assertEquals(OutboundStatus.INTERCEPTED, XincangOrderStatus.toCore("6"));
+ assertEquals(OutboundStatus.OUT_OF_STOCK, XincangOrderStatus.toCore("7"));
+ assertEquals(OutboundStatus.CANCELLED, XincangOrderStatus.toCore("8"));
+ assertEquals(OutboundStatus.DELETED, XincangOrderStatus.toCore("10"));
+ assertEquals(OutboundStatus.REVIEWING, XincangOrderStatus.toCore("11"));
+ assertEquals(OutboundStatus.REVIEW_FAILED, XincangOrderStatus.toCore("12"));
+ }
+
+ @Test
+ void unknownOrderStatusIsNotGuessed() {
+ assertEquals(OutboundStatus.UNKNOWN, XincangOrderStatus.toCore("99"));
+ assertEquals(OutboundStatus.UNKNOWN, XincangOrderStatus.toCore(""));
+ assertEquals(OutboundStatus.UNKNOWN, XincangOrderStatus.toCore(null));
+ }
+
+ @Test
+ void transferStateMapsEveryDocumentedCode() {
+ assertEquals(TransferStatus.PENDING_REVIEW, XincangTransferState.toCore("0"));
+ assertEquals(TransferStatus.PENDING_PROCESSING, XincangTransferState.toCore("1"));
+ assertEquals(TransferStatus.PENDING_PICK, XincangTransferState.toCore("2"));
+ assertEquals(TransferStatus.PENDING_LABELING, XincangTransferState.toCore("3"));
+ assertEquals(TransferStatus.PENDING_PALLETIZING, XincangTransferState.toCore("4"));
+ assertEquals(TransferStatus.PENDING_OUTBOUND, XincangTransferState.toCore("5"));
+ assertEquals(TransferStatus.SHIPPED, XincangTransferState.toCore("6"));
+ assertEquals(TransferStatus.CANCELLED, XincangTransferState.toCore("7"));
+ }
+
+ @Test
+ void unknownTransferStateIsNotGuessed() {
+ assertEquals(TransferStatus.UNKNOWN, XincangTransferState.toCore("9"));
+ assertEquals(TransferStatus.UNKNOWN, XincangTransferState.toCore(null));
+ }
+
+ @Test
+ void forecastStatusMapsToInboundStatus() {
+ assertEquals(InboundStatus.DRAFT, XincangForecastStatus.toCore("0"));
+ assertEquals(InboundStatus.IN_TRANSIT, XincangForecastStatus.toCore("1"));
+ assertEquals(InboundStatus.PENDING_SHIPMENT, XincangForecastStatus.toCore("2"));
+ assertEquals(InboundStatus.IN_TRANSIT, XincangForecastStatus.toCore("3"));
+ assertEquals(InboundStatus.RECEIVING, XincangForecastStatus.toCore("6"));
+ assertEquals(InboundStatus.STORING, XincangForecastStatus.toCore("7"));
+ assertEquals(InboundStatus.COMPLETED, XincangForecastStatus.toCore("8"));
+ assertEquals(InboundStatus.REJECTED, XincangForecastStatus.toCore("9"));
+ assertEquals(InboundStatus.UNKNOWN, XincangForecastStatus.toCore("99"));
+ }
+
+ @Test
+ void orderTypeDrivesSelfLabelRequirement() {
+ assertEquals("common", XincangOrderType.COMMON.rawCode());
+ assertEquals("wayfair", XincangOrderType.WAYFAIR.rawCode());
+ assertFalse(XincangOrderType.COMMON.requiresSelfLabel());
+ assertTrue(XincangOrderType.WAYFAIR.requiresSelfLabel());
+ assertEquals(XincangOrderType.WAYFAIR, XincangOrderType.of("wayfair"));
+ assertNull(XincangOrderType.of("unknown"));
+ }
+}