Browse Source

feat(yqn): 按 API 135 对接物流产品(承运商渠道)清单查询

新能力 LOGISTICS_PRODUCT:下单 / 试算前校验渠道可用性用。

- LogisticsProduct:产品 code / 名称 / 是否跨国 + 来源仓与 provider
- LogisticsProductCapable.products(ctx, warehouseCode),门面
  sdk.warehouses(...).logisticsProducts(warehouseCode)。默认实现抛不支持,
  信仓无此接口不受影响
- 只读主数据,不走幂等;空清单按「该仓无可用渠道」返回空列表,不当错误

两处按既有约定处理:
- 文档把 query.warehouseCode 写在「Body 参数」里但方法是 GET,与库存接口
  (API 107)同样按 query 参数下发
- warehouseCode 显式指定优先,其次账户配置;两者都没有时拒绝,
  不发空值请求

crossCountry 缺失时按「非跨国」处理,不猜成跨国。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
b67caf0c46
  1. 5
      README.md
  2. 26
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/LogisticsProductCapable.java
  3. 4
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
  4. 103
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LogisticsProduct.java
  5. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  6. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  7. 30
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  8. 65
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnLogisticsProductMapper.java
  9. 13
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  10. 132
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnLogisticsProductTest.java

5
README.md

@ -310,12 +310,13 @@ common.ecommerce @@ -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 /

26
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/LogisticsProductCapable.java

@ -0,0 +1,26 @@ @@ -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;
/**
* 物流产品(承运商渠道)查询能力。
*
* <p>这是<b>主数据</b>查询,只读、无幂等。典型的用法是下单前校验:渠道不在清单里就别提交,
* 否则要等仓方报错才知道。</p>
*/
public interface LogisticsProductCapable extends WarehouseAdapter {
/**
* 查某仓支持的物流产品清单。
*
* @param warehouseCode 仓 code(仓方口径);null 时用账户配置的仓
* @return 产品清单;仓无可用渠道时为空列表(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不声明 {@code LOGISTICS_PRODUCT}
*/
List<LogisticsProduct> products(WarehouseContext ctx, String warehouseCode);
}

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

@ -49,7 +49,9 @@ public enum WarehouseCapability { @@ -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;

103
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LogisticsProduct.java

@ -0,0 +1,103 @@ @@ -0,0 +1,103 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.WarehouseProvider;
/**
* 仓支持的物流产品服务(承运商渠道)。
*
* <p>用于「下单前校验渠道可用性」:{@link #logisticsProductCode()} 是创建出库单与
* 运费试算的入参,先查这份清单能避免提交仓不支持的方案。</p>
*
* <p>这是<b>主数据</b>,不是状态:同一仓的渠道清单很少变,适合宿主缓存。</p>
*/
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);
}
}
}

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

@ -9,6 +9,7 @@ import common.ecommerce.warehouse.enums.WarehouseProvider; @@ -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; @@ -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;

2
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -86,6 +86,8 @@ public final class YqnConstants { @@ -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;

30
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -25,6 +25,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot; @@ -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; @@ -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; @@ -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 @@ -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 @@ -498,6 +502,30 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
}
// ------------------------------------------------------------------ 物流产品
/**
* 物流产品服务清单(API 135)。
*
* <p>文档把参数写成 {@code query.warehouseCode} 放在「Body 参数」里但方法是 GET,
* 与库存接口同样按 query 参数下发。</p>
*/
@Override
public List<LogisticsProduct> products(WarehouseContext ctx, String warehouseCode) {
String code = YqnLogisticsProductMapper.resolveWarehouseCode(warehouseCode,
ctx.providerWarehouseId());
Map<String, List<String>> 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<YqnDtos.CarrierGroup> rows = json.listAt(raw, "data", YqnDtos.CarrierGroup.class);
return YqnLogisticsProductMapper.toProducts(rows, code);
}
// ------------------------------------------------------------------ 入库箱标
/**

65
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnLogisticsProductMapper.java

@ -0,0 +1,65 @@ @@ -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 参数。
*
* <p>文档把参数写成 {@code query.warehouseCode} 放在「Body 参数」里,但方法是 GET;
* 按库存接口(API 107)的同样处理,用 query 参数下发。</p>
*/
public static Map<String, List<String>> toParams(String warehouseCode, String defaultWarehouseCode) {
String code = resolveWarehouseCode(warehouseCode, defaultWarehouseCode);
Map<String, List<String>> params = new LinkedHashMap<String, List<String>>();
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<LogisticsProduct> toProducts(List<YqnDtos.CarrierGroup> rows, String warehouseCode) {
if (rows == null || rows.isEmpty()) {
return new ArrayList<LogisticsProduct>();
}
List<LogisticsProduct> out = new ArrayList<LogisticsProduct>(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;
}
}

13
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -1122,4 +1122,17 @@ public final class YqnDtos { @@ -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;
}
}

132
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnLogisticsProductTest.java

@ -0,0 +1,132 @@ @@ -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<LogisticsProduct> 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<LogisticsProduct> products = new YqnAdapter(transport, new JacksonJsonCodec())
.products(ctx(), null);
assertFalse(products.get(0).crossCountry());
}
}
Loading…
Cancel
Save