diff --git a/README.md b/README.md index fb98596..be95628 100644 --- a/README.md +++ b/README.md @@ -311,12 +311,13 @@ common.ecommerce │ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult / │ │ TrackEvent / TrackingInfo / DestructionCommand / DestructionOrder / │ │ BoxLabelCommand / SkuLabelCommand / LabelPrintTask / WarehouseLabel / -│ │ LogisticsProduct +│ │ LogisticsProduct / WarehouseInfo │ ├── capability OutboundCapable / InventoryCapable / InboundCapable / │ │ WarehouseReturnCapable / WarehouseFeeCapable / │ │ WarehouseFeeEstimateCapable / TransferCapable / │ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable / -│ │ WarehouseProduct / WarehouseProductCapable / LogisticsProductCapable +│ │ WarehouseProduct / WarehouseProductCapable / LogisticsProductCapable / +│ │ WarehouseDirectoryCapable │ ├── error WarehouseException 及 Unsupported / CancelBlocked / CancelChargeRequired / │ │ DuplicateOrder / WebhookVerification │ ├── spi WarehouseRepository / WarehouseSink / WarehouseWebhookDedupStore / diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java new file mode 100644 index 0000000..f1a4a4d --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java @@ -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; + +/** + * 仓目录能力:查询仓方名下的可用仓库清单。 + * + *
只读主数据,无幂等。用于宿主初始化 / 定期同步本地仓档案; + * 不属于业务单据流,也不按单个仓过滤(一次返回组织下全部可用仓)。
+ */ +public interface WarehouseDirectoryCapable extends WarehouseAdapter { + + /** + * 查仓方名下的仓库清单。 + * + * @return 仓库档案;仓方没有可用仓时为空列表(不是错误) + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不声明 {@code WAREHOUSE_DIRECTORY} + */ + List用于宿主初始化 / 同步本地仓档案:{@link #warehouseCode()} 是各类库存、订单、 + * 调拨接口的核心标识,先把这份清单同步下来,后续传参才有合法来源。
+ * + *与 {@code spi.WarehouseAccount} 的区别:那个是宿主配置(含接入方式与凭证引用), + * 这个是仓方主数据(只有仓库本身的地址与联系人)。两者靠 {@code warehouseCode} 对上。
+ * + *PII:联系人、电话、邮箱属于个人信息,落库与日志需按宿主的安全策略处理。
+ */ +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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 5983dbe..70d6d09 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -10,6 +10,7 @@ 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.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; @@ -35,6 +36,7 @@ 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.WarehouseInfo; import common.ecommerce.warehouse.model.SkuLabelCommand; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index 2b53d88..7c6c714 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -88,6 +88,11 @@ public final class YqnConstants { public static final String PATH_FEE_ESTIMATE = "/v1/saleOrder/calculate"; /** 物流产品服务清单(API 135):按仓查询可用承运商渠道。 */ public static final String PATH_LOGISTICS_PRODUCTS = "/v2/sysCarrierGroup/getCarrierGroupList"; + /** 查询仓库(API 134):组织下全部可用仓的基础档案。 */ + public static final String PATH_WAREHOUSE_FIND_ALL = "/v1/warehouse/findAll"; + + /** 仓库查询接口的成功 status 值;该接口文档没有 {@code code} 字段。 */ + public static final int WAREHOUSE_LIST_SUCCESS_STATUS = 1; /** Spec §7.5:三家仓均未公开限流值,保守默认 2 req/s/仓。 */ public static final int PERMITS_PER_SECOND = 2; diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 0e36b3c..e00ce3e 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -36,12 +36,14 @@ 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.WarehouseInfo; import common.ecommerce.warehouse.model.SkuLabelCommand; import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.TrackingInfo; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; import common.ecommerce.warehouse.model.FeeEstimateQuery; import common.ecommerce.warehouse.model.FeeEstimateResult; +import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; @@ -82,7 +84,7 @@ import java.util.Map; public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable, TransferCapable, WarehouseReturnCapable, TrackingCapable, DestructionCapable, - LogisticsProductCapable { + LogisticsProductCapable, WarehouseDirectoryCapable { /** 运去哪请求里的时间格式;待核对。 */ private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); @@ -122,6 +124,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl WarehouseCapability.BOX_LABEL, WarehouseCapability.SKU_LABEL, WarehouseCapability.LOGISTICS_PRODUCT, + WarehouseCapability.WAREHOUSE_DIRECTORY, WarehouseCapability.TRANSFER, WarehouseCapability.RETURN, WarehouseCapability.RETURN_DISPOSITION, @@ -502,6 +505,68 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); } + // ------------------------------------------------------------------ 仓库目录 + + /** + * 查询仓库(API 134)。 + * + *信封不同:这个接口的响应文档只给 {@code status / message / data}, + * 没有 {@code code},而 {@code YqnEnvelope} 要求业务码存在且为 200。 + * 所以这里不走 envelope,按 {@code status} 判定,并对 {@code code} 做兼容。
+ */ + @Override + public List注意:这个接口的响应文档只给了 {@code status / message / data}, + * 没有 {@code code},与其它接口的信封不同(见适配器里的兼容处理)。
+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class WarehouseRow { + public String warehouseCode; + public String name; + public String country; + public String state; + public String city; + public String address1; + public String address2; + public String postal; + /** 联系人。 */ + public String linkman; + public String mobilePhone; + public String email; + } } diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnWarehouseDirectoryTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnWarehouseDirectoryTest.java new file mode 100644 index 0000000..4a72c0a --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnWarehouseDirectoryTest.java @@ -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