diff --git a/README.md b/README.md index ae5de8f..fb98596 100644 --- a/README.md +++ b/README.md @@ -310,12 +310,13 @@ common.ecommerce │ │ WarehouseReturn / TransferCommand / TransferOrder / │ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult / │ │ TrackEvent / TrackingInfo / DestructionCommand / DestructionOrder / -│ │ BoxLabelCommand / SkuLabelCommand / LabelPrintTask / WarehouseLabel +│ │ BoxLabelCommand / SkuLabelCommand / LabelPrintTask / WarehouseLabel / +│ │ LogisticsProduct │ ├── capability OutboundCapable / InventoryCapable / InboundCapable / │ │ WarehouseReturnCapable / WarehouseFeeCapable / │ │ WarehouseFeeEstimateCapable / TransferCapable / │ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable / -│ │ WarehouseProduct / WarehouseProductCapable +│ │ WarehouseProduct / WarehouseProductCapable / LogisticsProductCapable │ ├── error WarehouseException 及 Unsupported / CancelBlocked / CancelChargeRequired / │ │ DuplicateOrder / WebhookVerification │ ├── spi WarehouseRepository / WarehouseSink / WarehouseWebhookDedupStore / diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/LogisticsProductCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/LogisticsProductCapable.java new file mode 100644 index 0000000..5a1d8e3 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/LogisticsProductCapable.java @@ -0,0 +1,26 @@ +package common.ecommerce.warehouse.capability; + +import common.ecommerce.warehouse.model.LogisticsProduct; +import common.ecommerce.warehouse.sdk.WarehouseAdapter; +import common.ecommerce.warehouse.sdk.WarehouseContext; + +import java.util.List; + +/** + * 物流产品(承运商渠道)查询能力。 + * + *

这是主数据查询,只读、无幂等。典型的用法是下单前校验:渠道不在清单里就别提交, + * 否则要等仓方报错才知道。

+ */ +public interface LogisticsProductCapable extends WarehouseAdapter { + + /** + * 查某仓支持的物流产品清单。 + * + * @param warehouseCode 仓 code(仓方口径);null 时用账户配置的仓 + * @return 产品清单;仓无可用渠道时为空列表(不是错误) + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不声明 {@code LOGISTICS_PRODUCT} + */ + List products(WarehouseContext ctx, String warehouseCode); +} 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 9139ea8..94177fd 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 @@ -49,7 +49,9 @@ public enum WarehouseCapability { /** 打印入库计划单箱标(异步任务) */ BOX_LABEL(200, "入库箱标"), /** 打印 SKU 标 */ - SKU_LABEL(210, "SKU标"); + SKU_LABEL(210, "SKU标"), + /** 物流产品 / 承运商渠道清单查询 */ + LOGISTICS_PRODUCT(220, "物流产品"); private final int code; private final String label; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LogisticsProduct.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LogisticsProduct.java new file mode 100644 index 0000000..b393669 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LogisticsProduct.java @@ -0,0 +1,103 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.WarehouseProvider; + +/** + * 仓支持的物流产品服务(承运商渠道)。 + * + *

用于「下单前校验渠道可用性」:{@link #logisticsProductCode()} 是创建出库单与 + * 运费试算的入参,先查这份清单能避免提交仓不支持的方案。

+ * + *

这是主数据,不是状态:同一仓的渠道清单很少变,适合宿主缓存。

+ */ +public final class LogisticsProduct { + + private final WarehouseProvider sourceProvider; + /** 仓 code(仓方口径)。 */ + private final String warehouseCode; + /** 物流产品编码;下单与试算用它。 */ + private final String logisticsProductCode; + /** 产品名称,给人看。 */ + private final String logisticsProductName; + /** 是否跨国运输。 */ + private final boolean crossCountry; + + private LogisticsProduct(Builder b) { + this.sourceProvider = b.sourceProvider; + this.warehouseCode = b.warehouseCode; + this.logisticsProductCode = require(b.logisticsProductCode, "logisticsProductCode"); + this.logisticsProductName = b.logisticsProductName; + this.crossCountry = b.crossCountry; + } + + public static Builder builder() { + return new Builder(); + } + + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + + /** 仓 code(仓方口径);查询时未指定时为空。 */ + public String warehouseCode() { + return warehouseCode; + } + + /** 物流产品编码;出库下单与运费试算的入参。 */ + public String logisticsProductCode() { + return logisticsProductCode; + } + + public String logisticsProductName() { + return logisticsProductName; + } + + /** 是否跨国运输。 */ + public boolean crossCountry() { + return crossCountry; + } + + 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 WarehouseProvider sourceProvider; + private String warehouseCode; + private String logisticsProductCode; + private String logisticsProductName; + private boolean crossCountry; + + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + + public Builder warehouseCode(String v) { + this.warehouseCode = v; + return this; + } + + public Builder logisticsProductCode(String v) { + this.logisticsProductCode = v; + return this; + } + + public Builder logisticsProductName(String v) { + this.logisticsProductName = v; + return this; + } + + public Builder crossCountry(boolean v) { + this.crossCountry = v; + return this; + } + + public LogisticsProduct build() { + return new LogisticsProduct(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 2a1a42a..5983dbe 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 @@ -9,6 +9,7 @@ import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.capability.DestructionCapable; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; +import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; @@ -33,6 +34,7 @@ import common.ecommerce.warehouse.model.InboundCommand; import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.LabelPrintTask; +import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.SkuLabelCommand; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index ec826f9..2b53d88 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -86,6 +86,8 @@ public final class YqnConstants { public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail"; /** 订单测算 / 运费试算(API 121):发货前按包裹 + 地址 + 渠道询价。 */ public static final String PATH_FEE_ESTIMATE = "/v1/saleOrder/calculate"; + /** 物流产品服务清单(API 135):按仓查询可用承运商渠道。 */ + public static final String PATH_LOGISTICS_PRODUCTS = "/v2/sysCarrierGroup/getCarrierGroupList"; /** Spec §7.5:三家仓均未公开限流值,保守默认 2 req/s/仓。 */ public static final int PERMITS_PER_SECOND = 2; diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 2ec26cd..0e36b3c 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -25,6 +25,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.InventoryCapable; +import common.ecommerce.warehouse.capability.LogisticsProductCapable; import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.capability.DestructionCapable; @@ -34,6 +35,7 @@ import common.ecommerce.warehouse.model.BoxLabelCommand; import common.ecommerce.warehouse.model.DestructionCommand; import common.ecommerce.warehouse.model.DestructionOrder; import common.ecommerce.warehouse.model.LabelPrintTask; +import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.SkuLabelCommand; import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.TrackingInfo; @@ -79,7 +81,8 @@ import java.util.Map; */ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable, - TransferCapable, WarehouseReturnCapable, TrackingCapable, DestructionCapable { + TransferCapable, WarehouseReturnCapable, TrackingCapable, DestructionCapable, + LogisticsProductCapable { /** 运去哪请求里的时间格式;待核对。 */ private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); @@ -118,6 +121,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl WarehouseCapability.INBOUND, WarehouseCapability.BOX_LABEL, WarehouseCapability.SKU_LABEL, + WarehouseCapability.LOGISTICS_PRODUCT, WarehouseCapability.TRANSFER, WarehouseCapability.RETURN, WarehouseCapability.RETURN_DISPOSITION, @@ -498,6 +502,30 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); } + // ------------------------------------------------------------------ 物流产品 + + /** + * 物流产品服务清单(API 135)。 + * + *

文档把参数写成 {@code query.warehouseCode} 放在「Body 参数」里但方法是 GET, + * 与库存接口同样按 query 参数下发。

+ */ + @Override + public List products(WarehouseContext ctx, String warehouseCode) { + String code = YqnLogisticsProductMapper.resolveWarehouseCode(warehouseCode, + ctx.providerWarehouseId()); + Map> params = YqnLogisticsProductMapper.toParams(code, null); + rateLimiter.acquire(YqnConstants.PATH_LOGISTICS_PRODUCTS, YqnConstants.PERMITS_PER_SECOND); + HttpRequest req = requestFactory.getMulti(ctx.endpointBaseUrl(), + YqnConstants.PATH_LOGISTICS_PRODUCTS, params, ctx.secret(), ctx, + "warehouse.logistics.products"); + HttpResponse resp = transport.execute(req); + String raw = YqnEnvelope.of(resp, json, "warehouse.logistics.products", + ctx.warehouseCode(), ctx.requestId()).body(); + List rows = json.listAt(raw, "data", YqnDtos.CarrierGroup.class); + return YqnLogisticsProductMapper.toProducts(rows, code); + } + // ------------------------------------------------------------------ 入库箱标 /** diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnLogisticsProductMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnLogisticsProductMapper.java new file mode 100644 index 0000000..5f1589e --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnLogisticsProductMapper.java @@ -0,0 +1,65 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.LogisticsProduct; +import common.ecommerce.yqn.dto.YqnDtos; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 运去哪物流产品清单映射(API 135)。 + */ +public final class YqnLogisticsProductMapper { + + private YqnLogisticsProductMapper() { + } + + /** + * 查询条件 → GET 参数。 + * + *

文档把参数写成 {@code query.warehouseCode} 放在「Body 参数」里,但方法是 GET; + * 按库存接口(API 107)的同样处理,用 query 参数下发。

+ */ + public static Map> toParams(String warehouseCode, String defaultWarehouseCode) { + String code = resolveWarehouseCode(warehouseCode, defaultWarehouseCode); + Map> params = new LinkedHashMap>(); + params.put("query.warehouseCode", java.util.Collections.singletonList(code)); + return params; + } + + /** + * 解析仓 code:显式指定优先,否则用账户配置的;都没有就拒绝—— + * 运去哪这个接口的 warehouseCode 必填,空值拿不到有意义的清单。 + */ + static String resolveWarehouseCode(String warehouseCode, String defaultWarehouseCode) { + if (warehouseCode != null && !warehouseCode.trim().isEmpty()) { + return warehouseCode.trim(); + } + if (defaultWarehouseCode != null && !defaultWarehouseCode.trim().isEmpty()) { + return defaultWarehouseCode.trim(); + } + throw new IllegalArgumentException( + "yqn logistics products need a warehouseCode; none given and account has none"); + } + + /** 响应 → 统一模型。 */ + public static List toProducts(List rows, String warehouseCode) { + if (rows == null || rows.isEmpty()) { + return new ArrayList(); + } + List out = new ArrayList(rows.size()); + for (YqnDtos.CarrierGroup row : rows) { + out.add(LogisticsProduct.builder() + .sourceProvider(WarehouseProvider.YQN) + .warehouseCode(warehouseCode) + .logisticsProductCode(row.logisticsProductCode) + .logisticsProductName(row.logisticsProductName) + .crossCountry(row.crossCountry != null && row.crossCountry) + .build()); + } + return out; + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java index fa37ad4..abf94c3 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java @@ -1122,4 +1122,17 @@ public final class YqnDtos { /** 是否展示 ERP_SKU;默认是。 */ public Boolean isShowErpSku; } + + // ------------------------------------------------------------------ 物流产品(API 135) + + /** 物流产品服务清单的一条(API 135 {@code data[]})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CarrierGroup { + + /** 产品 code;出库下单与运费试算的入参。 */ + public String logisticsProductCode; + public String logisticsProductName; + /** 是否跨国运输。 */ + public Boolean crossCountry; + } } diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnLogisticsProductTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnLogisticsProductTest.java new file mode 100644 index 0000000..e2ecf17 --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnLogisticsProductTest.java @@ -0,0 +1,132 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.spi.ChannelSecret; +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.LogisticsProduct; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.yqn.YqnConstants; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 物流产品服务清单(API 135)契约测试。 + */ +class YqnLogisticsProductTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC); + + private static WarehouseContext ctx() { + return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", + WarehouseConnection.of(YqnConstants.PR_BASE_URL, + ChannelSecret.builder().appSecret("key-1").build()), + "req-carriers", CLOCK); + } + + private static final String OK_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[" + + "{\"crossCountry\":true,\"logisticsProductCode\":\"FEDEX_INTL\"," + + "\"logisticsProductName\":\"FedEx 国际\"}," + + "{\"crossCountry\":false,\"logisticsProductCode\":\"UPS_GROUND\"," + + "\"logisticsProductName\":\"UPS 陆运\"}]}"; + + @Test + void sendsWarehouseCodeAsQueryParam() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_LOGISTICS_PRODUCTS, req -> Responses.ok(OK_BODY)); + new YqnAdapter(transport, new JacksonJsonCodec()).products(ctx(), "RF_NY_US"); + + String url = transport.lastDataRequest().url(); + assertTrue(url.startsWith(YqnConstants.PR_BASE_URL), url); + assertTrue(url.contains("/v2/sysCarrierGroup/getCarrierGroupList"), url); + assertTrue(url.contains("query.warehouseCode=RF_NY_US"), url); + assertEquals("GET", transport.lastDataRequest().method()); + } + + @Test + void fallsBackToAccountWarehouse() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_LOGISTICS_PRODUCTS, req -> Responses.ok(OK_BODY)); + new YqnAdapter(transport, new JacksonJsonCodec()).products(ctx(), null); + + assertTrue(transport.lastDataRequest().url().contains("query.warehouseCode=RF_NY_US")); + } + + /** 两个来源都没有仓 code 时拒绝:空 warehouseCode 拿不到有意义的清单。 */ + @Test + void noWarehouseAnywhereIsRejected() { + WarehouseContext noAccountWarehouse = WarehouseContext.of( + "YQN-X", WarehouseProvider.YQN, null, + WarehouseConnection.of(YqnConstants.PR_BASE_URL, + ChannelSecret.builder().appSecret("key-1").build()), + "req-carriers", CLOCK); + RecordingTransport transport = RecordingTransport.create(); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + assertThrows(IllegalArgumentException.class, () -> adapter.products(noAccountWarehouse, null)); + assertTrue(transport.recorded().isEmpty(), "不应该发出请求"); + } + + @Test + void mapsProducts() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_LOGISTICS_PRODUCTS, req -> Responses.ok(OK_BODY)); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + List products = adapter.products(ctx(), null); + + assertEquals(2, products.size()); + LogisticsProduct first = products.get(0); + assertEquals("FEDEX_INTL", first.logisticsProductCode()); + assertEquals("FedEx 国际", first.logisticsProductName()); + assertTrue(first.crossCountry()); + assertEquals("RF_NY_US", first.warehouseCode()); + assertEquals(WarehouseProvider.YQN, first.sourceProvider()); + + assertFalse(products.get(1).crossCountry()); + assertEquals("UPS_GROUND", products.get(1).logisticsProductCode()); + } + + /** 空清单不是错误:该仓可能确实没有可用渠道。 */ + @Test + void emptyListIsNotAnError() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_LOGISTICS_PRODUCTS, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[]}")); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + assertTrue(adapter.products(ctx(), null).isEmpty()); + } + + @Test + void declaresLogisticsProductCapability() { + YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + assertTrue(adapter.capabilities().contains(WarehouseCapability.LOGISTICS_PRODUCT)); + } + + /** 缺 crossCountry 时按「非跨国」处理,不猜成跨国。 */ + @Test + void missingCrossCountryDefaultsToFalse() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_LOGISTICS_PRODUCTS, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":[" + + "{\"logisticsProductCode\":\"X\",\"logisticsProductName\":\"X\"}]}")); + List products = new YqnAdapter(transport, new JacksonJsonCodec()) + .products(ctx(), null); + + assertFalse(products.get(0).crossCountry()); + } +}