From 19405c553b944a5e515c4e07667c774ebaea05c5 Mon Sep 17 00:00:00 2001
From: lml <1297555865@qq.com>
Date: Wed, 11 Nov 2026 11:19:57 +0800
Subject: [PATCH] =?UTF-8?q?feat(xincang):=20=E5=AF=B9=E6=8E=A5=E5=AE=A2?=
=?UTF-8?q?=E6=88=B7=E4=BB=93=E5=BA=93=E4=B8=8E=E6=89=BF=E8=BF=90=E5=95=86?=
=?UTF-8?q?=E6=9F=A5=E8=AF=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- GET api.get_customer_warehouses → WarehouseDirectoryCapable.warehouses()
- GET api.get_customer_logistics → WarehouseDirectoryCapable.carriers()
core 只新增:
- WarehouseDirectoryCapable(warehouses / carriers)
- WarehouseFacility 模型:仓代码 + 国家 / 省 / 市 / 街道 / 邮编
- WarehouseCapability 追加 DIRECTORY(210)
- WarehouseOperations 增加 warehouses() / carriers(),只读带埋点
未并入 WarehouseRepository:那是宿主维护的 OMS 仓编码 → 账户映射,
这两个接口是仓方返回的可选仓库清单,数据源不同,混用会让宿主分不清信谁。
空 data 返回空列表;只有 rst 缺失(报文结构变化)才抛 ValidationException。
Co-Authored-By: Claude Code
---
README.md | 2 +-
.../capability/WarehouseDirectoryCapable.java | 34 +++++
.../warehouse/enums/WarehouseCapability.java | 2 +
.../warehouse/model/WarehouseFacility.java | 120 +++++++++++++++++
.../warehouse/sdk/WarehouseOperations.java | 27 ++++
.../common/ecommerce/xincang/XincangConstants.java | 6 +
.../ecommerce/xincang/adapter/XincangAdapter.java | 71 +++++++++-
.../common/ecommerce/xincang/dto/XincangDtos.java | 85 ++++++++++++
.../xincang/adapter/XincangAdapterTest.java | 3 +-
.../xincang/adapter/XincangDirectoryTest.java | 144 +++++++++++++++++++++
10 files changed, 490 insertions(+), 4 deletions(-)
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java
create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFacility.java
create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDirectoryTest.java
diff --git a/README.md b/README.md
index 02bedff..4e6ba58 100644
--- a/README.md
+++ b/README.md
@@ -135,7 +135,7 @@ sequenceDiagram
| `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter |
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
-| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报) |
+| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
依赖方向:
```
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..b43906d
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java
@@ -0,0 +1,34 @@
+package common.ecommerce.warehouse.capability;
+
+import common.ecommerce.warehouse.model.WarehouseFacility;
+import common.ecommerce.warehouse.sdk.WarehouseAdapter;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+
+import java.util.List;
+
+/**
+ * 仓方基础资料能力:列出账户下可用的仓库与承运商。
+ *
+ * 用途是让宿主在下单前拿到仓代码 / 物流方式,而不是把取值写死在配置里。
+ * 只读,无幂等要求。
+ */
+public interface WarehouseDirectoryCapable extends WarehouseAdapter {
+
+ /**
+ * 客户名下所有仓库。
+ *
+ * @return 仓库列表;仓方返回空时为 empty list
+ * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
+ * 该仓不声明 {@code DIRECTORY}
+ */
+ List warehouses(WarehouseContext ctx);
+
+ /**
+ * 客户可用的承运商 / 物流方式代码。
+ *
+ * @return 物流方式码列表,如 {@code FEDEX-G};未配置时为空列表
+ * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
+ * 该仓不声明 {@code DIRECTORY}
+ */
+ List carriers(WarehouseContext ctx);
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
index f6e0652..00751c8 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
@@ -46,6 +46,8 @@ public enum WarehouseCapability {
FEE_ESTIMATE(180, "费用试算"),
/** 最优渠道推荐(按 SKU + 邮编由仓择优) */
CHANNEL_RECOMMEND(200, "最优渠道推荐"),
+ /** 仓方基础资料(仓库列表 / 承运商列表) */
+ DIRECTORY(210, "基础资料"),
/** 状态回调推送 */
WEBHOOK(190, "状态回调");
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFacility.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFacility.java
new file mode 100644
index 0000000..4c0d64a
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFacility.java
@@ -0,0 +1,120 @@
+package common.ecommerce.warehouse.model;
+
+/**
+ * 仓方的基础资料:一个可发货的仓库及其地址。
+ *
+ * 用于下单前让宿主拿到「这家仓有哪些仓、仓代码是什么」,而不是把仓代码写死在配置里。
+ * 只读数据,不含库存与能力。
+ */
+public final class WarehouseFacility {
+
+ /** 仓方内部 id(信仓 {@code id});可能为 null。 */
+ private final String providerWarehouseId;
+ /** 仓代码(下单时用的 {@code warehouse_code})。 */
+ private final String warehouseCode;
+ private final String country;
+ private final String province;
+ private final String city;
+ private final String street;
+ private final String postcode;
+
+ private WarehouseFacility(Builder b) {
+ this.providerWarehouseId = b.providerWarehouseId;
+ this.warehouseCode = require(b.warehouseCode, "warehouseCode");
+ this.country = b.country;
+ this.province = b.province;
+ this.city = b.city;
+ this.street = b.street;
+ this.postcode = b.postcode;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 仓方内部 id;可能为 null。 */
+ public String providerWarehouseId() {
+ return providerWarehouseId;
+ }
+
+ /** 仓代码。 */
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ public String country() {
+ return country;
+ }
+
+ public String province() {
+ return province;
+ }
+
+ public String city() {
+ return city;
+ }
+
+ public String street() {
+ return street;
+ }
+
+ public String postcode() {
+ return postcode;
+ }
+
+ private static String require(String v, String n) {
+ if (v == null || v.trim().isEmpty()) {
+ throw new IllegalArgumentException(n + " must not be blank");
+ }
+ return v.trim();
+ }
+
+ public static final class Builder {
+ private String providerWarehouseId;
+ private String warehouseCode;
+ private String country;
+ private String province;
+ private String city;
+ private String street;
+ private String postcode;
+
+ public Builder providerWarehouseId(String v) {
+ this.providerWarehouseId = v;
+ return this;
+ }
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public Builder country(String v) {
+ this.country = v;
+ return this;
+ }
+
+ public Builder province(String v) {
+ this.province = v;
+ return this;
+ }
+
+ public Builder city(String v) {
+ this.city = v;
+ return this;
+ }
+
+ public Builder street(String v) {
+ this.street = v;
+ return this;
+ }
+
+ public Builder postcode(String v) {
+ this.postcode = v;
+ return this;
+ }
+
+ public WarehouseFacility build() {
+ return new WarehouseFacility(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 1b62f7f..f1968f1 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
@@ -11,6 +11,7 @@ import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
+import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
@@ -212,6 +213,32 @@ public final class WarehouseOperations {
() -> ((TrackingCapable) adapter).trackShipment(ctx, trackingNumber));
}
+ /**
+ * 仓方基础资料:客户名下的仓库列表。
+ *
+ * 只读。用于下单前取仓代码,避免把仓代码写死在配置里。
+ */
+ public List warehouses() {
+ require(WarehouseCapability.DIRECTORY, WarehouseDirectoryCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.directory.warehouses",
+ CallSupport.params(),
+ List::size,
+ () -> ((WarehouseDirectoryCapable) adapter).warehouses(ctx));
+ }
+
+ /**
+ * 仓方基础资料:客户可用的承运商 / 物流方式代码。
+ *
+ * 只读。返回的是仓方字典值,可直接传给下单的 {@code carrierCode}。
+ */
+ public List carriers() {
+ require(WarehouseCapability.DIRECTORY, WarehouseDirectoryCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.directory.carriers",
+ CallSupport.params(),
+ List::size,
+ () -> ((WarehouseDirectoryCapable) adapter).carriers(ctx));
+ }
+
/** 费用视图。 */
public FeeView fees() {
return new FeeView();
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
index f2b1952..48ba29c 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
@@ -65,6 +65,12 @@ public final class XincangConstants {
/** 库龄列表;必填 {@code bill_date}({@code 起 - 止})。 */
public static final String PATH_STOCK_AGE_LIST = "/api.stockagelist";
+ /** 获取客户所有仓库。 */
+ public static final String PATH_CUSTOMER_WAREHOUSES = "/api.get_customer_warehouses";
+
+ /** 获取客户所有承运商。 */
+ public static final String PATH_CUSTOMER_LOGISTICS = "/api.get_customer_logistics";
+
/** 新增预报(创建入库单,空明细)。 */
public static final String PATH_FORECAST_CREATE = "/forecast.do_forecast";
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
index ed6dbfe..b016b7d 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
@@ -14,6 +14,7 @@ import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
+import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
@@ -33,6 +34,7 @@ import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.CancelResult;
@@ -55,6 +57,7 @@ import common.ecommerce.xincang.http.XincangRequestFactory;
import java.time.Clock;
import java.time.Instant;
+import java.util.ArrayList;
import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.List;
@@ -75,7 +78,8 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。
*/
public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable,
- TransferCapable, WarehouseChannelRecommendCapable, InventoryCapable, InboundCapable {
+ TransferCapable, WarehouseChannelRecommendCapable, InventoryCapable, InboundCapable,
+ WarehouseDirectoryCapable {
private static final String OP_PRODUCT_QUERY = "warehouse.product.query";
private static final String OP_PRODUCT_ADD = "warehouse.product.add";
@@ -126,7 +130,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT,
WarehouseCapability.CHANNEL_RECOMMEND, WarehouseCapability.INVENTORY_QUERY,
- WarehouseCapability.INBOUND);
+ WarehouseCapability.INBOUND, WarehouseCapability.DIRECTORY);
}
/**
@@ -432,6 +436,69 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
"warehouse.transfer.delete");
}
+ // ------------------------------------------------------------------ 基础资料
+
+ /**
+ * 客户名下所有仓库({@code GET api.get_customer_warehouses})。
+ *
+ * 返回的 {@code warehouse_code} 可直接用于下单、库存查询等接口。
+ */
+ @Override
+ public List warehouses(WarehouseContext ctx) {
+ String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_WAREHOUSES,
+ new LinkedHashMap(), login(ctx), "warehouse.directory.warehouses");
+ XincangDtos.WarehouseListResult rst =
+ json.fromJson(raw, XincangDtos.WarehouseListResponse.class).rst;
+ if (rst == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.directory.warehouses",
+ "xincang get_customer_warehouses returned no rst");
+ }
+ List out = new ArrayList();
+ if (rst.data != null) {
+ for (XincangDtos.WarehouseListResult.WarehouseRow row : rst.data) {
+ if (row == null || XincangForecastMapper.blank(row.warehouseCode)) {
+ continue;
+ }
+ out.add(WarehouseFacility.builder()
+ .providerWarehouseId(XincangForecastMapper.blankToNull(row.id))
+ .warehouseCode(row.warehouseCode.trim())
+ .country(XincangForecastMapper.blankToNull(row.country))
+ .province(XincangForecastMapper.blankToNull(row.province))
+ .city(XincangForecastMapper.blankToNull(row.city))
+ .street(XincangForecastMapper.blankToNull(row.street))
+ .postcode(XincangForecastMapper.blankToNull(row.postcode))
+ .build());
+ }
+ }
+ return out;
+ }
+
+ /**
+ * 客户可用的承运商({@code GET api.get_customer_logistics})。
+ *
+ * 返回的 {@code logistics_type} 可直接作为下单的 {@code carrierCode}。
+ */
+ @Override
+ public List carriers(WarehouseContext ctx) {
+ String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_LOGISTICS,
+ new LinkedHashMap(), login(ctx), "warehouse.directory.carriers");
+ XincangDtos.LogisticsListResult rst =
+ json.fromJson(raw, XincangDtos.LogisticsListResponse.class).rst;
+ if (rst == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.directory.carriers",
+ "xincang get_customer_logistics returned no rst");
+ }
+ List out = new ArrayList();
+ if (rst.data != null) {
+ for (XincangDtos.LogisticsListResult.LogisticsRow row : rst.data) {
+ if (row != null && !XincangForecastMapper.blank(row.logisticsType)) {
+ out.add(row.logisticsType.trim());
+ }
+ }
+ }
+ return out;
+ }
+
// ------------------------------------------------------------------ 头程预报
/**
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
index 22b04ac..2439a53 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
@@ -1327,6 +1327,91 @@ public final class XincangDtos {
public ForecastCreateResult rst;
}
+ /** 客户仓库列表响应 {@code rst}({@code GET api.get_customer_warehouses})。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class WarehouseListResult {
+
+ @JsonProperty("code")
+ public String code;
+
+ @JsonProperty("msg")
+ public String msg;
+
+ @JsonProperty("data")
+ public List data;
+
+ /** 总条数(字符串)。 */
+ @JsonProperty("count")
+ public String count;
+
+ /** 一行仓库。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class WarehouseRow {
+
+ /** 仓方内部 id。 */
+ @JsonProperty("id")
+ public String id;
+
+ /** 仓代码。 */
+ @JsonProperty("warehouse_code")
+ public String warehouseCode;
+
+ @JsonProperty("country")
+ public String country;
+ @JsonProperty("province")
+ public String province;
+ @JsonProperty("city")
+ public String city;
+ @JsonProperty("street")
+ public String street;
+ @JsonProperty("postcode")
+ public String postcode;
+ }
+ }
+
+ /** 客户仓库列表响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class WarehouseListResponse {
+
+ @JsonProperty("rst")
+ public WarehouseListResult rst;
+ }
+
+ /** 客户承运商列表响应 {@code rst}({@code GET api.get_customer_logistics})。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class LogisticsListResult {
+
+ @JsonProperty("code")
+ public String code;
+
+ @JsonProperty("msg")
+ public String msg;
+
+ @JsonProperty("data")
+ public List data;
+
+ /** 总条数(字符串)。 */
+ @JsonProperty("count")
+ public String count;
+
+ /** 一行承运商。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class LogisticsRow {
+
+ /** 物流方式代码,如 {@code FEDEX-G}。 */
+ @JsonProperty("logistics_type")
+ public String logisticsType;
+ }
+ }
+
+ /** 客户承运商列表响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class LogisticsListResponse {
+
+ @JsonProperty("rst")
+ public LogisticsListResult rst;
+ }
+
/** 新增订单响应外层,用于取 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderResponse {
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
index 15d2f21..f9feaad 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
@@ -122,7 +122,8 @@ class XincangAdapterTest {
assertEquals(EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.TRANSFER,
WarehouseCapability.INBOUND, WarehouseCapability.SPLIT,
- WarehouseCapability.CHANNEL_RECOMMEND), adapter.capabilities());
+ WarehouseCapability.CHANNEL_RECOMMEND, WarehouseCapability.DIRECTORY),
+ adapter.capabilities());
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND));
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY));
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDirectoryTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDirectoryTest.java
new file mode 100644
index 0000000..47734e2
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDirectoryTest.java
@@ -0,0 +1,144 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.shared.testkit.MutableClock;
+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.WarehouseFacility;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 基础资料(客户仓库 / 承运商)契约测试。
+ */
+class XincangDirectoryTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ private static final String WAREHOUSES = "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":["
+ + "{\"id\":\"84047962214173\",\"warehouse_code\":\"CA-3790\",\"country\":\"US\","
+ + "\"province\":\"CA\",\"city\":\"JURUPA VALLEY\","
+ + "\"street\":\"3790 DE FOREST CIRCLE, UNIT B\",\"postcode\":\"91752\"},"
+ + "{\"id\":\"84047962479824\",\"warehouse_code\":\"NJ-2605\",\"country\":\"US\","
+ + "\"province\":\"NJ\",\"city\":\"Burlington Township\","
+ + "\"street\":\"2605 Rancocas Road\",\"postcode\":\"08016\"}"
+ + "],\"count\":\"2\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-wh\"}";
+
+ private static final String LOGISTICS = "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":["
+ + "{\"logistics_type\":\"FEDEX-HD\"},{\"logistics_type\":\"FEDEX-G\"}"
+ + "],\"count\":\"2\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-lg\"}";
+
+ private RecordingTransport transport;
+ private XincangAdapter adapter;
+
+ @BeforeEach
+ void setUp() {
+ transport = RecordingTransport.create();
+ MutableClock clock = MutableClock.atUtc("2026-11-11T00:00:00Z");
+ transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok(
+ "{\"rst\":{\"id\":\"c-1\",\"token\":\"{T-1}\",\"token_expire_time\":\""
+ + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)),
+ XincangConstants.SYSTEM_ZONE)
+ .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}"));
+ adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), clock);
+ }
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("XC-NJ-2605", WarehouseProvider.XINCANG, "NJ-2605",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ @Test
+ void listsWarehousesWithAddress() {
+ transport.route(XincangConstants.PATH_CUSTOMER_WAREHOUSES, req -> Responses.ok(WAREHOUSES));
+
+ List warehouses = adapter.warehouses(ctx());
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("/api.get_customer_warehouses?token=%7BT-1%7D"), url);
+
+ assertEquals(2, warehouses.size());
+ WarehouseFacility first = warehouses.get(0);
+ assertEquals("CA-3790", first.warehouseCode());
+ assertEquals("84047962214173", first.providerWarehouseId());
+ assertEquals("US", first.country());
+ assertEquals("CA", first.province());
+ assertEquals("JURUPA VALLEY", first.city());
+ assertEquals("3790 DE FOREST CIRCLE, UNIT B", first.street());
+ assertEquals("91752", first.postcode());
+ assertEquals("NJ-2605", warehouses.get(1).warehouseCode());
+ }
+
+ @Test
+ void listsCarriers() {
+ transport.route(XincangConstants.PATH_CUSTOMER_LOGISTICS, req -> Responses.ok(LOGISTICS));
+
+ List carriers = adapter.carriers(ctx());
+
+ assertTrue(transport.lastDataRequest().url()
+ .contains("/api.get_customer_logistics?"), transport.lastDataRequest().url());
+ assertEquals(2, carriers.size());
+ assertEquals("FEDEX-HD", carriers.get(0));
+ assertEquals("FEDEX-G", carriers.get(1));
+ }
+
+ @Test
+ void emptyDataYieldsEmptyListNotError() {
+ transport.route(XincangConstants.PATH_CUSTOMER_WAREHOUSES, req -> Responses.ok(
+ "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":[],\"count\":\"0\"},"
+ + "\"errno\":0,\"err\":\"\"}"));
+ transport.route(XincangConstants.PATH_CUSTOMER_LOGISTICS, req -> Responses.ok(
+ "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":[],\"count\":\"0\"},"
+ + "\"errno\":0,\"err\":\"\"}"));
+
+ assertTrue(adapter.warehouses(ctx()).isEmpty());
+ assertTrue(adapter.carriers(ctx()).isEmpty());
+ }
+
+ @Test
+ void rowsWithoutWarehouseCodeAreSkipped() {
+ transport.route(XincangConstants.PATH_CUSTOMER_WAREHOUSES, req -> Responses.ok(
+ "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":["
+ + "{\"id\":\"1\",\"warehouse_code\":\"\",\"country\":\"US\"},"
+ + "{\"id\":\"2\",\"warehouse_code\":\"CA-3790\",\"country\":\"US\"}"
+ + "],\"count\":\"2\"},\"errno\":0,\"err\":\"\"}"));
+
+ List warehouses = adapter.warehouses(ctx());
+
+ assertEquals(1, warehouses.size());
+ assertEquals("CA-3790", warehouses.get(0).warehouseCode());
+ }
+
+ @Test
+ void missingRstIsNotSilentEmpty() {
+ transport.route(XincangConstants.PATH_CUSTOMER_LOGISTICS, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\"}"));
+
+ assertThrows(ValidationException.class, () -> adapter.carriers(ctx()));
+ }
+
+ @Test
+ void directoryCapabilityDeclared() {
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.DIRECTORY));
+ assertTrue(adapter.supports("XC-NJ-2605", WarehouseCapability.DIRECTORY));
+ }
+}