Browse Source
新能力 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
10 changed files with 378 additions and 4 deletions
@ -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); |
||||
} |
||||
@ -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); |
||||
} |
||||
} |
||||
} |
||||
@ -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; |
||||
} |
||||
} |
||||
@ -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…
Reference in new issue