Browse Source
新能力 WAREHOUSE_DIRECTORY:同步仓方名下可用仓的基础档案, 为库存 / 订单 / 调拨等接口提供合法的 warehouseCode 来源。 - WarehouseInfo:仓 code / 名称 / 国家州城市 / 地址 / 邮编 / 联系人 / 电话 / 邮箱 与 spi.WarehouseAccount 分开:那个是宿主接入配置(含凭证引用), 这个是仓方主数据。两者靠 warehouseCode 对上 - WarehouseDirectoryCapable.warehouses(ctx),门面 sdk.warehouses(...).warehouses() - 只读主数据,不走幂等;空清单按「无可用仓」返回空列表,不当错误 **信封不同,单独处理**:这个接口的响应文档只有 status / message / data, 没有 code,而 YqnEnvelope 要求业务码存在且为 200——直接复用会把成功响应 判成失败。改为:有 code 时按 200 校验,没有则退回看 status==1。 两个分支都有测试覆盖。 PII 提示写进模型 Javadoc:联系人 / 电话 / 邮箱需按宿主安全策略处理。 Co-Authored-By: Claude <noreply@anthropic.com>feature/supplier-lingxing
10 changed files with 491 additions and 4 deletions
@ -0,0 +1,25 @@
@@ -0,0 +1,25 @@
|
||||
package common.ecommerce.warehouse.capability; |
||||
|
||||
import common.ecommerce.warehouse.model.WarehouseInfo; |
||||
import common.ecommerce.warehouse.sdk.WarehouseAdapter; |
||||
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 仓目录能力:查询仓方名下的可用仓库清单。 |
||||
* |
||||
* <p>只读主数据,无幂等。用于宿主初始化 / 定期同步本地仓档案; |
||||
* 不属于业务单据流,也不按单个仓过滤(一次返回组织下全部可用仓)。</p> |
||||
*/ |
||||
public interface WarehouseDirectoryCapable extends WarehouseAdapter { |
||||
|
||||
/** |
||||
* 查仓方名下的仓库清单。 |
||||
* |
||||
* @return 仓库档案;仓方没有可用仓时为空列表(不是错误) |
||||
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException |
||||
* 该仓不声明 {@code WAREHOUSE_DIRECTORY} |
||||
*/ |
||||
List<WarehouseInfo> warehouses(WarehouseContext ctx); |
||||
} |
||||
@ -0,0 +1,187 @@
@@ -0,0 +1,187 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
|
||||
/** |
||||
* 仓方维护的仓库基础档案。 |
||||
* |
||||
* <p>用于宿主初始化 / 同步本地仓档案:{@link #warehouseCode()} 是各类库存、订单、 |
||||
* 调拨接口的核心标识,先把这份清单同步下来,后续传参才有合法来源。</p> |
||||
* |
||||
* <p>与 {@code spi.WarehouseAccount} 的区别:那个是<b>宿主配置</b>(含接入方式与凭证引用), |
||||
* 这个是<b>仓方主数据</b>(只有仓库本身的地址与联系人)。两者靠 {@code warehouseCode} 对上。</p> |
||||
* |
||||
* <p><b>PII</b>:联系人、电话、邮箱属于个人信息,落库与日志需按宿主的安全策略处理。</p> |
||||
*/ |
||||
public final class WarehouseInfo { |
||||
|
||||
private final WarehouseProvider sourceProvider; |
||||
/** 仓方仓库编码;各类业务接口的 warehouseCode 入参。 */ |
||||
private final String warehouseCode; |
||||
private final String name; |
||||
/** 国家,仓方原值(通常是二字码或国名,不做归一)。 */ |
||||
private final String country; |
||||
/** 州 / 省。 */ |
||||
private final String state; |
||||
private final String city; |
||||
private final String address1; |
||||
private final String address2; |
||||
private final String postalCode; |
||||
/** 联系人。 */ |
||||
private final String contactName; |
||||
private final String mobilePhone; |
||||
private final String email; |
||||
|
||||
private WarehouseInfo(Builder b) { |
||||
this.sourceProvider = b.sourceProvider; |
||||
this.warehouseCode = require(b.warehouseCode, "warehouseCode"); |
||||
this.name = b.name; |
||||
this.country = b.country; |
||||
this.state = b.state; |
||||
this.city = b.city; |
||||
this.address1 = b.address1; |
||||
this.address2 = b.address2; |
||||
this.postalCode = b.postalCode; |
||||
this.contactName = b.contactName; |
||||
this.mobilePhone = b.mobilePhone; |
||||
this.email = b.email; |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
public WarehouseProvider sourceProvider() { |
||||
return sourceProvider; |
||||
} |
||||
|
||||
public String warehouseCode() { |
||||
return warehouseCode; |
||||
} |
||||
|
||||
public String name() { |
||||
return name; |
||||
} |
||||
|
||||
public String country() { |
||||
return country; |
||||
} |
||||
|
||||
public String state() { |
||||
return state; |
||||
} |
||||
|
||||
public String city() { |
||||
return city; |
||||
} |
||||
|
||||
public String address1() { |
||||
return address1; |
||||
} |
||||
|
||||
public String address2() { |
||||
return address2; |
||||
} |
||||
|
||||
public String postalCode() { |
||||
return postalCode; |
||||
} |
||||
|
||||
public String contactName() { |
||||
return contactName; |
||||
} |
||||
|
||||
public String mobilePhone() { |
||||
return mobilePhone; |
||||
} |
||||
|
||||
public String email() { |
||||
return email; |
||||
} |
||||
|
||||
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 name; |
||||
private String country; |
||||
private String state; |
||||
private String city; |
||||
private String address1; |
||||
private String address2; |
||||
private String postalCode; |
||||
private String contactName; |
||||
private String mobilePhone; |
||||
private String email; |
||||
|
||||
public Builder sourceProvider(WarehouseProvider v) { |
||||
this.sourceProvider = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder warehouseCode(String v) { |
||||
this.warehouseCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder name(String v) { |
||||
this.name = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder country(String v) { |
||||
this.country = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder state(String v) { |
||||
this.state = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder city(String v) { |
||||
this.city = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder address1(String v) { |
||||
this.address1 = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder address2(String v) { |
||||
this.address2 = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder postalCode(String v) { |
||||
this.postalCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder contactName(String v) { |
||||
this.contactName = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder mobilePhone(String v) { |
||||
this.mobilePhone = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder email(String v) { |
||||
this.email = v; |
||||
return this; |
||||
} |
||||
|
||||
public WarehouseInfo build() { |
||||
return new WarehouseInfo(this); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,42 @@
@@ -0,0 +1,42 @@
|
||||
package common.ecommerce.yqn.adapter; |
||||
|
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.WarehouseInfo; |
||||
import common.ecommerce.yqn.dto.YqnDtos; |
||||
|
||||
import java.util.ArrayList; |
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 运去哪仓库档案映射(API 134)。 |
||||
*/ |
||||
public final class YqnWarehouseMapper { |
||||
|
||||
private YqnWarehouseMapper() { |
||||
} |
||||
|
||||
/** 响应 → 统一仓库档案。 */ |
||||
public static List<WarehouseInfo> toWarehouses(List<YqnDtos.WarehouseRow> rows) { |
||||
if (rows == null || rows.isEmpty()) { |
||||
return new ArrayList<WarehouseInfo>(); |
||||
} |
||||
List<WarehouseInfo> out = new ArrayList<WarehouseInfo>(rows.size()); |
||||
for (YqnDtos.WarehouseRow row : rows) { |
||||
out.add(WarehouseInfo.builder() |
||||
.sourceProvider(WarehouseProvider.YQN) |
||||
.warehouseCode(row.warehouseCode) |
||||
.name(row.name) |
||||
.country(row.country) |
||||
.state(row.state) |
||||
.city(row.city) |
||||
.address1(row.address1) |
||||
.address2(row.address2) |
||||
.postalCode(row.postal) |
||||
.contactName(row.linkman) |
||||
.mobilePhone(row.mobilePhone) |
||||
.email(row.email) |
||||
.build()); |
||||
} |
||||
return out; |
||||
} |
||||
} |
||||
@ -0,0 +1,134 @@
@@ -0,0 +1,134 @@
|
||||
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.WarehouseInfo; |
||||
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.assertThrows; |
||||
import static org.junit.jupiter.api.Assertions.assertTrue; |
||||
|
||||
/** |
||||
* 查询仓库(API 134)契约测试。 |
||||
*/ |
||||
class YqnWarehouseDirectoryTest { |
||||
|
||||
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-warehouses", CLOCK); |
||||
} |
||||
|
||||
private static final String DOC_SHAPE_BODY = |
||||
"{\"status\":1,\"message\":\"ok\",\"data\":[" |
||||
+ "{\"warehouseCode\":\"RF_NY_US\",\"name\":\"润丰纽约仓\",\"country\":\"US\"," |
||||
+ "\"state\":\"NY\",\"city\":\"Newark\",\"address1\":\"1 Main St\"," |
||||
+ "\"address2\":\"Suite 200\",\"postal\":\"07102\",\"linkman\":\"张三\"," |
||||
+ "\"mobilePhone\":\"+1-555-0100\",\"email\":\"wh@example.com\"}]}"; |
||||
|
||||
@Test |
||||
void sendsGetWithNoParams() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_WAREHOUSE_FIND_ALL, req -> Responses.ok(DOC_SHAPE_BODY)); |
||||
new YqnAdapter(transport, new JacksonJsonCodec()).warehouses(ctx()); |
||||
|
||||
String url = transport.lastDataRequest().url(); |
||||
assertEquals("GET", transport.lastDataRequest().method()); |
||||
assertEquals(YqnConstants.PR_BASE_URL + "/v1/warehouse/findAll", url); |
||||
} |
||||
|
||||
/** 文档的这个接口没有 code 字段,只有 status;不能因为缺 code 就判失败。 */ |
||||
@Test |
||||
void acceptsDocumentedEnvelopeWithoutCode() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_WAREHOUSE_FIND_ALL, req -> Responses.ok(DOC_SHAPE_BODY)); |
||||
List<WarehouseInfo> list = new YqnAdapter(transport, new JacksonJsonCodec()).warehouses(ctx()); |
||||
|
||||
assertEquals(1, list.size()); |
||||
} |
||||
|
||||
/** 有 code 时按 200 校验(兼容其它接口的通用信封)。 */ |
||||
@Test |
||||
void honoursCodeWhenPresent() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_WAREHOUSE_FIND_ALL, req -> Responses.ok( |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\"," |
||||
+ "\"data\":[{\"warehouseCode\":\"RF_NY_US\",\"name\":\"仓\"}]}")); |
||||
List<WarehouseInfo> list = new YqnAdapter(transport, new JacksonJsonCodec()).warehouses(ctx()); |
||||
|
||||
assertEquals(1, list.size()); |
||||
} |
||||
|
||||
@Test |
||||
void nonSuccessCodeIsRejected() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_WAREHOUSE_FIND_ALL, req -> Responses.ok( |
||||
"{\"status\":1,\"code\":500,\"message\":\"boom\",\"data\":[]}")); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
RuntimeException ex = assertThrows(RuntimeException.class, () -> adapter.warehouses(ctx())); |
||||
assertTrue(ex.getMessage().contains("code=500"), ex.getMessage()); |
||||
} |
||||
|
||||
@Test |
||||
void nonSuccessStatusIsRejected() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_WAREHOUSE_FIND_ALL, req -> Responses.ok( |
||||
"{\"status\":0,\"message\":\"denied\",\"data\":[]}")); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
RuntimeException ex = assertThrows(RuntimeException.class, () -> adapter.warehouses(ctx())); |
||||
assertTrue(ex.getMessage().contains("status=0"), ex.getMessage()); |
||||
} |
||||
|
||||
@Test |
||||
void mapsAllFields() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_WAREHOUSE_FIND_ALL, req -> Responses.ok(DOC_SHAPE_BODY)); |
||||
WarehouseInfo info = new YqnAdapter(transport, new JacksonJsonCodec()).warehouses(ctx()).get(0); |
||||
|
||||
assertEquals(WarehouseProvider.YQN, info.sourceProvider()); |
||||
assertEquals("RF_NY_US", info.warehouseCode()); |
||||
assertEquals("润丰纽约仓", info.name()); |
||||
assertEquals("US", info.country()); |
||||
assertEquals("NY", info.state()); |
||||
assertEquals("Newark", info.city()); |
||||
assertEquals("1 Main St", info.address1()); |
||||
assertEquals("Suite 200", info.address2()); |
||||
assertEquals("07102", info.postalCode()); |
||||
assertEquals("张三", info.contactName()); |
||||
assertEquals("+1-555-0100", info.mobilePhone()); |
||||
assertEquals("wh@example.com", info.email()); |
||||
} |
||||
|
||||
@Test |
||||
void emptyListIsNotAnError() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_WAREHOUSE_FIND_ALL, req -> Responses.ok( |
||||
"{\"status\":1,\"message\":\"ok\",\"data\":[]}")); |
||||
|
||||
assertTrue(new YqnAdapter(transport, new JacksonJsonCodec()).warehouses(ctx()).isEmpty()); |
||||
} |
||||
|
||||
@Test |
||||
void declaresWarehouseDirectoryCapability() { |
||||
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); |
||||
assertTrue(adapter.capabilities().contains(WarehouseCapability.WAREHOUSE_DIRECTORY)); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue