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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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