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")); + } +}