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