diff --git a/README.md b/README.md
index 54813e3..a9abd08 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、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄) |
依赖方向:
```
@@ -333,7 +333,8 @@ common.ecommerce
├── auth XincangTokenClient(GET /api.login,无 refresh)
├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper /
│ XincangOrderMapper / XincangOrderDetailMapper /
- │ XincangTransferMapper / XincangTransferDetailMapper
+ │ XincangTransferMapper / XincangTransferDetailMapper /
+ │ XincangChannelRecommendMapper / XincangInventoryMapper
├── dto XincangDtos(登录 / 商品)
├── enums XincangOrderStatus / XincangTransferState /
│ XincangForecastStatus / XincangOrderType
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
index 748c1e0..bb0268c 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
@@ -21,6 +21,18 @@ public interface InventoryCapable extends WarehouseAdapter {
/** 查库存;{@code updatedAfter} 仅在 {@link InventorySyncStrategy#TIME_WINDOW} 下生效。 */
Page query(WarehouseContext ctx, InventoryQuery query);
+ /**
+ * 查库龄(按计费日期区间)。
+ *
+ * 库龄是计费视角的数据,与 {@link #query} 返回的库存快照不是一回事,
+ * 所以单独一个方法;不支持的仓默认拒绝。
+ */
+ default Page queryAges(
+ WarehouseContext ctx, common.ecommerce.warehouse.model.InventoryAgeQuery query) {
+ throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
+ common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_QUERY);
+ }
+
/** 其他出入库 / 调拨;信仓无此能力,会抛 {@code WarehouseUnsupportedCapabilityException}。 */
default InventorySnapshot adjust(WarehouseContext ctx, InventoryQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeQuery.java
new file mode 100644
index 0000000..5c2128e
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeQuery.java
@@ -0,0 +1,131 @@
+package common.ecommerce.warehouse.model;
+
+import java.time.LocalDate;
+
+/**
+ * 库龄查询条件。
+ *
+ * 库龄按计费日期区间查,必须给区间;不给会拉到全部历史,对账时无从解释。
+ */
+public final class InventoryAgeQuery {
+
+ private final LocalDate startDate;
+ private final LocalDate endDate;
+ /** 仓 code;null 表示用账户配置的仓。 */
+ private final String warehouseCode;
+ /** 产品 SKU;null 表示不限。 */
+ private final String providerSku;
+ private final int pageSize;
+ private final String cursor;
+ /** 是否返回费率与计费体积;null 表示按仓默认。 */
+ private final Boolean includeFeeRate;
+
+ private InventoryAgeQuery(Builder b) {
+ if (b.startDate == null || b.endDate == null) {
+ throw new IllegalArgumentException("startDate and endDate are required");
+ }
+ if (b.endDate.isBefore(b.startDate)) {
+ throw new IllegalArgumentException("endDate must not be earlier than startDate");
+ }
+ this.startDate = b.startDate;
+ this.endDate = b.endDate;
+ this.warehouseCode = b.warehouseCode;
+ this.providerSku = b.providerSku;
+ this.pageSize = b.pageSize;
+ this.cursor = b.cursor;
+ this.includeFeeRate = b.includeFeeRate;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 计费日期区间起点(含)。 */
+ public LocalDate startDate() {
+ return startDate;
+ }
+
+ /** 计费日期区间终点(含)。 */
+ public LocalDate endDate() {
+ return endDate;
+ }
+
+ /** 仓 code;null 表示用账户配置的仓。 */
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ /** 产品 SKU;null 表示不限。 */
+ public String providerSku() {
+ return providerSku;
+ }
+
+ public int pageSize() {
+ return pageSize;
+ }
+
+ public String cursor() {
+ return cursor;
+ }
+
+ /** 是否返回费率;null 表示按仓默认。 */
+ public Boolean includeFeeRate() {
+ return includeFeeRate;
+ }
+
+ public static final class Builder {
+ private LocalDate startDate;
+ private LocalDate endDate;
+ private String warehouseCode;
+ private String providerSku;
+ private int pageSize = 100;
+ private String cursor;
+ private Boolean includeFeeRate;
+
+ public Builder startDate(LocalDate v) {
+ this.startDate = v;
+ return this;
+ }
+
+ public Builder endDate(LocalDate v) {
+ this.endDate = v;
+ return this;
+ }
+
+ /** 计费日期区间。 */
+ public Builder dateRange(LocalDate start, LocalDate end) {
+ this.startDate = start;
+ this.endDate = end;
+ return this;
+ }
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ public Builder pageSize(int v) {
+ this.pageSize = v;
+ return this;
+ }
+
+ public Builder cursor(String v) {
+ this.cursor = v;
+ return this;
+ }
+
+ public Builder includeFeeRate(Boolean v) {
+ this.includeFeeRate = v;
+ return this;
+ }
+
+ public InventoryAgeQuery build() {
+ return new InventoryAgeQuery(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeRecord.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeRecord.java
new file mode 100644
index 0000000..41d7d1f
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryAgeRecord.java
@@ -0,0 +1,189 @@
+package common.ecommerce.warehouse.model;
+
+import common.ecommerce.shared.support.Money;
+
+import java.time.Instant;
+
+/**
+ * 一条库龄记录(按计费日 × 仓库 × SKU × 入库柜号)。
+ *
+ * 库龄是计费视角的数据,不是库存快照:同一 SKU 在不同入库批次 / 柜号下
+ * 有不同的库龄天数与费率,按天累计出仓储费。所以单独建模,不塞进
+ * {@link InventorySnapshot}——后者回答「现在有多少货」。
+ *
+ * 只读查询结果,无幂等要求。
+ */
+public final class InventoryAgeRecord {
+
+ private final String warehouseCode;
+ private final String providerSku;
+ /** 计费日期(仓方 {@code dt});仓方按天出账。 */
+ private final Instant billingDate;
+ /** 入库柜号;无则为 null。 */
+ private final String cabinetNo;
+ /** 实际入库时间(UTC)。 */
+ private final Instant inStockAt;
+ /** 库龄天数;仓方原值。 */
+ private final int ageDays;
+ /** 库存数量(该批次)。 */
+ private final int quantity;
+ /** 总体积(立方米,仓方 {@code total_volume_cbm});可能为 null。 */
+ private final java.math.BigDecimal totalVolumeCbm;
+ /** 计费数量。 */
+ private final int billingQuantity;
+ /** 费率;仓方未给为 null。 */
+ private final java.math.BigDecimal feeRate;
+ /** 当日费用;仓方未给为 null。 */
+ private final Money fee;
+
+ private InventoryAgeRecord(Builder b) {
+ this.warehouseCode = require(b.warehouseCode, "warehouseCode");
+ this.providerSku = require(b.providerSku, "providerSku");
+ this.billingDate = java.util.Objects.requireNonNull(b.billingDate, "billingDate");
+ this.cabinetNo = b.cabinetNo;
+ this.inStockAt = b.inStockAt;
+ this.ageDays = b.ageDays;
+ this.quantity = b.quantity;
+ this.totalVolumeCbm = b.totalVolumeCbm;
+ this.billingQuantity = b.billingQuantity;
+ this.feeRate = b.feeRate;
+ this.fee = b.fee;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ public String providerSku() {
+ return providerSku;
+ }
+
+ /** 计费日期。 */
+ public Instant billingDate() {
+ return billingDate;
+ }
+
+ /** 入库柜号;无则为 null。 */
+ public String cabinetNo() {
+ return cabinetNo;
+ }
+
+ /** 实际入库时间;仓方未给为 null。 */
+ public Instant inStockAt() {
+ return inStockAt;
+ }
+
+ /** 库龄天数。 */
+ public int ageDays() {
+ return ageDays;
+ }
+
+ /** 库存数量(该批次)。 */
+ public int quantity() {
+ return quantity;
+ }
+
+ /** 总体积(立方米);未给为 null。 */
+ public java.math.BigDecimal totalVolumeCbm() {
+ return totalVolumeCbm;
+ }
+
+ /** 计费数量。 */
+ public int billingQuantity() {
+ return billingQuantity;
+ }
+
+ /** 费率;未给为 null。 */
+ public java.math.BigDecimal feeRate() {
+ return feeRate;
+ }
+
+ /** 当日费用;未给为 null。 */
+ public Money fee() {
+ return fee;
+ }
+
+ 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 warehouseCode;
+ private String providerSku;
+ private Instant billingDate;
+ private String cabinetNo;
+ private Instant inStockAt;
+ private int ageDays;
+ private int quantity;
+ private java.math.BigDecimal totalVolumeCbm;
+ private int billingQuantity;
+ private java.math.BigDecimal feeRate;
+ private Money fee;
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ public Builder billingDate(Instant v) {
+ this.billingDate = v;
+ return this;
+ }
+
+ public Builder cabinetNo(String v) {
+ this.cabinetNo = v;
+ return this;
+ }
+
+ public Builder inStockAt(Instant v) {
+ this.inStockAt = v;
+ return this;
+ }
+
+ public Builder ageDays(int v) {
+ this.ageDays = v;
+ return this;
+ }
+
+ public Builder quantity(int v) {
+ this.quantity = v;
+ return this;
+ }
+
+ public Builder totalVolumeCbm(java.math.BigDecimal v) {
+ this.totalVolumeCbm = v;
+ return this;
+ }
+
+ public Builder billingQuantity(int v) {
+ this.billingQuantity = v;
+ return this;
+ }
+
+ public Builder feeRate(java.math.BigDecimal v) {
+ this.feeRate = v;
+ return this;
+ }
+
+ public Builder fee(Money v) {
+ this.fee = v;
+ return this;
+ }
+
+ public InventoryAgeRecord build() {
+ return new InventoryAgeRecord(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java
index d54ad5d..30f73f1 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySnapshot.java
@@ -28,6 +28,14 @@ public final class InventorySnapshot {
private final int packageReserved;
private final int packageInTransit;
private final int packageCurrent;
+ /** 商品名(仓方原值);无则为 null。 */
+ private final String productName;
+ /** 待出库数量;仓方未给时为 -1。 */
+ private final int pendingOutbound;
+ /** 预警数量;仓方未给时为 -1。 */
+ private final int alertQuantity;
+ /** 体积(立方厘米);仓方原值,未给为 null。 */
+ private final java.math.BigDecimal volumeCbm;
private InventorySnapshot(Builder b) {
this.warehouseCode = require(b.warehouseCode, "warehouseCode");
@@ -46,6 +54,10 @@ public final class InventorySnapshot {
this.packageReserved = b.packageReserved;
this.packageInTransit = b.packageInTransit;
this.packageCurrent = b.packageCurrent;
+ this.productName = b.productName;
+ this.pendingOutbound = b.pendingOutbound;
+ this.alertQuantity = b.alertQuantity;
+ this.volumeCbm = b.volumeCbm;
}
public static Builder builder() {
@@ -125,6 +137,26 @@ public final class InventorySnapshot {
return packageCurrent;
}
+ /** 商品名(仓方原值);无则为 null。 */
+ public String productName() {
+ return productName;
+ }
+
+ /** 待出库数量;仓方未给时为 -1。 */
+ public int pendingOutbound() {
+ return pendingOutbound;
+ }
+
+ /** 预警数量;仓方未给时为 -1。 */
+ public int alertQuantity() {
+ return alertQuantity;
+ }
+
+ /** 体积(立方厘米);仓方未给为 null。 */
+ public java.math.BigDecimal volumeCbm() {
+ return volumeCbm;
+ }
+
private static String require(String v, String n) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(n + " must not be blank");
@@ -149,6 +181,12 @@ public final class InventorySnapshot {
private int packageReserved;
private int packageInTransit;
private int packageCurrent;
+ private String productName;
+ /** 仓方未给时为 -1。 */
+ private int pendingOutbound = -1;
+ /** 仓方未给时为 -1。 */
+ private int alertQuantity = -1;
+ private java.math.BigDecimal volumeCbm;
public Builder warehouseCode(String v) {
this.warehouseCode = v;
@@ -230,6 +268,30 @@ public final class InventorySnapshot {
return this;
}
+ /** 商品名(仓方原值)。 */
+ public Builder productName(String v) {
+ this.productName = v;
+ return this;
+ }
+
+ /** 待出库数量;仓方未给时传 -1。 */
+ public Builder pendingOutbound(int v) {
+ this.pendingOutbound = v;
+ return this;
+ }
+
+ /** 预警数量;仓方未给时传 -1。 */
+ public Builder alertQuantity(int v) {
+ this.alertQuantity = v;
+ return this;
+ }
+
+ /** 体积(立方厘米)。 */
+ public Builder volumeCbm(java.math.BigDecimal v) {
+ this.volumeCbm = v;
+ return this;
+ }
+
public InventorySnapshot build() {
return new InventorySnapshot(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 9b8378d..aabf511 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
@@ -253,6 +253,24 @@ public final class WarehouseOperations {
/** 库存视图。 */
public final class InventoryView {
+ /**
+ * 查库龄(按计费日期区间)。
+ *
+ * 只读。库龄是计费视角数据,与 {@link #query(InventoryQuery)} 的库存快照不同。
+ */
+ public Page queryAges(
+ final common.ecommerce.warehouse.model.InventoryAgeQuery query) {
+ require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.inventory.ages",
+ CallSupport.params("startDate", query.startDate(),
+ "endDate", query.endDate(),
+ "warehouseCode", query.warehouseCode(),
+ "providerSku", query.providerSku(),
+ "pageSize", query.pageSize()),
+ p -> p.size(),
+ () -> ((InventoryCapable) adapter).queryAges(ctx, query));
+ }
+
/** 查库存。 */
public Page query(InventoryQuery query) {
require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class);
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 3d3e267..d465259 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
@@ -59,6 +59,12 @@ public final class XincangConstants {
/** 删除订单;{@code order_no} 与 {@code ckh} 二选一,空 body。 */
public static final String PATH_ORDER_DELETE = "/api.delete_order";
+ /** 实时库存;必填 {@code warehouse_code}。 */
+ public static final String PATH_STOCK_LIST = "/api.stocklist";
+
+ /** 库龄列表;必填 {@code bill_date}({@code 起 - 止})。 */
+ public static final String PATH_STOCK_AGE_LIST = "/api.stockagelist";
+
/**
* 最优渠道。
*
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 7f5709a..4b9285b 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
@@ -11,12 +11,14 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.shared.support.Page;
+import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
+import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.enums.OutboundStatus;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
@@ -24,6 +26,10 @@ import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.ChannelRecommendQuery;
+import common.ecommerce.warehouse.model.InventoryAgeQuery;
+import common.ecommerce.warehouse.model.InventoryAgeRecord;
+import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand;
@@ -44,6 +50,7 @@ import common.ecommerce.xincang.http.XincangRateLimiter;
import common.ecommerce.xincang.http.XincangRequestFactory;
import java.time.Clock;
+import java.time.Instant;
import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.List;
@@ -64,7 +71,7 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。
*/
public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable,
- TransferCapable, WarehouseChannelRecommendCapable {
+ TransferCapable, WarehouseChannelRecommendCapable, InventoryCapable {
private static final String OP_PRODUCT_QUERY = "warehouse.product.query";
private static final String OP_PRODUCT_ADD = "warehouse.product.add";
@@ -114,7 +121,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
public EnumSet capabilities() {
return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT,
- WarehouseCapability.CHANNEL_RECOMMEND);
+ WarehouseCapability.CHANNEL_RECOMMEND, WarehouseCapability.INVENTORY_QUERY);
}
/**
@@ -420,6 +427,63 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
"warehouse.transfer.delete");
}
+ // ------------------------------------------------------------------ 库存
+
+ /**
+ * 库存同步策略:信仓只能按页全量拉,没有按时间增量的参数。
+ *
+ * 宿主按本值决定落库策略,不要按 {@code updatedAfter} 做增量。
+ */
+ @Override
+ public InventorySyncStrategy syncStrategy() {
+ return InventorySyncStrategy.FULL_PULL_DIFF;
+ }
+
+ /**
+ * 实时库存({@code GET api.stocklist})。
+ *
+ * 信仓只支持单个 {@code warehouse_code};调用方传多个仓会显式拒绝,
+ * 不静默只查第一个。{@code updatedAfter} 被忽略——该接口没有时间维度。
+ */
+ @Override
+ public Page query(WarehouseContext ctx, InventoryQuery query) {
+ Map params = XincangInventoryMapper.toStockParams(query,
+ ctx.providerWarehouseId());
+ String raw = executeGet(ctx, XincangConstants.PATH_STOCK_LIST, params, login(ctx),
+ "warehouse.inventory.query");
+ XincangDtos.StockListResult rst = json.fromJson(raw, XincangDtos.StockListResponse.class).rst;
+ if (rst == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inventory.query",
+ "xincang stocklist returned no rst");
+ }
+ int page = XincangInventoryMapper.pageNumber(query.cursor());
+ int size = XincangInventoryMapper.pageSize(query.pageSize());
+ return XincangInventoryMapper.toSnapshots(rst, ctx.providerWarehouseId(),
+ Instant.now(ctx.clock()), page, size);
+ }
+
+ /**
+ * 库龄列表({@code GET api.stockagelist})。
+ *
+ * 按计费日期区间查;{@code bill_date} 是「起 - 止」单值字符串。
+ */
+ @Override
+ public Page queryAges(WarehouseContext ctx, InventoryAgeQuery query) {
+ Map params = XincangInventoryMapper.toAgeParams(query,
+ ctx.providerWarehouseId());
+ String raw = executeGet(ctx, XincangConstants.PATH_STOCK_AGE_LIST, params, login(ctx),
+ "warehouse.inventory.ages");
+ XincangDtos.StockAgeListResult rst =
+ json.fromJson(raw, XincangDtos.StockAgeListResponse.class).rst;
+ if (rst == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inventory.ages",
+ "xincang stockagelist returned no rst");
+ }
+ int page = XincangInventoryMapper.pageNumber(query.cursor());
+ int size = XincangInventoryMapper.pageSize(query.pageSize());
+ return XincangInventoryMapper.toAgeRecords(rst, ctx.providerWarehouseId(), page, size);
+ }
+
// ------------------------------------------------------------------ 最优渠道
/**
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
new file mode 100644
index 0000000..10c6bd4
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
@@ -0,0 +1,268 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.shared.support.Page;
+import common.ecommerce.warehouse.model.InventoryAgeQuery;
+import common.ecommerce.warehouse.model.InventoryAgeRecord;
+import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.InventorySnapshot;
+import common.ecommerce.xincang.XincangConstants;
+import common.ecommerce.xincang.dto.XincangDtos;
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 库存与库龄报文映射。
+ *
+ *
+ * - 实时库存 {@code GET api.stocklist}
+ * - 库龄列表 {@code GET api.stockagelist}
+ *
+ *
+ * 平台字段名只出现在本类与 {@link XincangDtos};时间按北京时间解析成 UTC。
+ */
+public final class XincangInventoryMapper {
+
+ private static final DateTimeFormatter DATE_TIME =
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+ private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+ private static final String CURRENCY_USD = "USD";
+ /** 仓方分页上限文档未标明,先按 100 保守截断。 */
+ static final int MAX_PAGE_SIZE = 100;
+
+ private XincangInventoryMapper() {
+ }
+
+ // ---------------------------------------------------------------- 实时库存
+
+ /**
+ * 库存查询条件 → query 参数。
+ *
+ * {@code warehouse_code} 是信仓必填项:调用方指定优先,否则用账户配置的仓;
+ * 两者都没有就拒绝,避免把整个租户的库存拉下来。
+ */
+ public static Map toStockParams(InventoryQuery query, String defaultWarehouseCode) {
+ String warehouseCode = firstNonBlank(
+ query.warehouseCodes().isEmpty() ? null : query.warehouseCodes().get(0),
+ defaultWarehouseCode);
+ if (warehouseCode == null) {
+ throw new IllegalArgumentException(
+ "xincang stocklist requires warehouse_code; none given and account has none");
+ }
+ // 信仓只支持单个 warehouse_code;给了多个仓时不能静默只查第一个
+ if (query.warehouseCodes().size() > 1) {
+ throw new IllegalArgumentException(
+ "xincang stocklist accepts a single warehouse_code, got "
+ + query.warehouseCodes());
+ }
+ Map params = new LinkedHashMap();
+ params.put("warehouse_code", warehouseCode);
+ if (!query.providerSkus().isEmpty()) {
+ params.put("product_no", query.providerSkus().get(0));
+ }
+ params.put("page", pageNumber(query.cursor()));
+ params.put("limit", pageSize(query.pageSize()));
+ return params;
+ }
+
+ /** 库存响应 → 快照分页。 */
+ public static Page toSnapshots(XincangDtos.StockListResult rst,
+ String fallbackWarehouseCode,
+ Instant asOf,
+ int currentPage,
+ int pageSize) {
+ List out = new ArrayList();
+ if (rst != null && rst.data != null) {
+ for (XincangDtos.StockListResult.StockRow row : rst.data) {
+ if (row == null || blank(row.productSku)) {
+ continue;
+ }
+ out.add(InventorySnapshot.builder()
+ .warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode))
+ .providerSku(row.productSku.trim())
+ .available(intOf(row.canSaleSkuCount))
+ .onHand(intOf(row.realStock))
+ .inTransit(intOf(row.shipSkuCount))
+ .reserved(intOf(row.useSkuCount))
+ // 信仓不区分可售 / 不可售库位,统一按可售
+ .inventoryType(0)
+ .asOfUtc(asOf)
+ .productName(blankToNull(row.chnName))
+ .pendingOutbound(intOf(row.waitSkuCount))
+ .alertQuantity(intOf(row.alarmCount))
+ .volumeCbm(decimalOf(row.volumeCm))
+ .build());
+ }
+ }
+ return Page.of(out, nextCursor(currentPage, pageSize, out.size()));
+ }
+
+ // ---------------------------------------------------------------- 库龄
+
+ /** 库龄查询条件 → query 参数。 */
+ public static Map toAgeParams(InventoryAgeQuery query, String defaultWarehouseCode) {
+ Map params = new LinkedHashMap();
+ // bill_date 是「起 - 止」的单值字符串
+ params.put("bill_date", query.startDate().format(DATE) + " - " + query.endDate().format(DATE));
+ putIfPresent(params, "warehouse_code", firstNonBlank(query.warehouseCode(), defaultWarehouseCode));
+ putIfPresent(params, "key", query.providerSku());
+ params.put("page", pageNumber(query.cursor()));
+ params.put("limit", pageSize(query.pageSize()));
+ if (query.includeFeeRate() != null) {
+ params.put("is_need_fee_rate", query.includeFeeRate() ? 1 : 0);
+ }
+ return params;
+ }
+
+ /** 库龄响应 → 记录分页。 */
+ public static Page toAgeRecords(XincangDtos.StockAgeListResult rst,
+ String fallbackWarehouseCode,
+ int currentPage,
+ int pageSize) {
+ List out = new ArrayList();
+ if (rst != null && rst.data != null) {
+ for (XincangDtos.StockAgeListResult.AgeRow row : rst.data) {
+ if (row == null || blank(row.productSku)) {
+ continue;
+ }
+ Instant billingDate = parseDate(row.dt);
+ if (billingDate == null) {
+ // 计费日期是必填主键,解析不出就没法定位这条记录,跳过而不是猜今天
+ continue;
+ }
+ out.add(InventoryAgeRecord.builder()
+ .warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode))
+ .providerSku(row.productSku.trim())
+ .billingDate(billingDate)
+ .cabinetNo(blankToNull(row.cabinetNo))
+ .inStockAt(parseTime(row.inStockTime))
+ .ageDays(intOf(row.feeDays))
+ .quantity(intOf(row.skuCount))
+ .totalVolumeCbm(decimalOf(row.totalVolumeCbm))
+ .billingQuantity(intOf(row.feeCount))
+ .feeRate(decimalOf(row.configPrice))
+ .fee(parseMoney(row.sumFee))
+ .build());
+ }
+ }
+ return Page.of(out, nextCursor(currentPage, pageSize, out.size()));
+ }
+
+ // ---------------------------------------------------------------- internals
+
+ /**
+ * 有下一页时返回下一页页码。
+ *
+ * 信仓分页是 {@code page} / {@code limit},游标存字符串化页码;按「本页是否满页」
+ * 判断还有没有下一页——{@code count} 在部分响应里缺失,不能依赖。
+ */
+ static String nextCursor(int currentPage, int pageSize, int fetched) {
+ return fetched >= pageSize ? String.valueOf(currentPage + 1) : null;
+ }
+
+ static int pageNumber(String cursor) {
+ if (blank(cursor)) {
+ return 1;
+ }
+ try {
+ int v = Integer.parseInt(cursor.trim());
+ return v > 0 ? v : 1;
+ } catch (NumberFormatException e) {
+ return 1;
+ }
+ }
+
+ static int pageSize(int requested) {
+ if (requested <= 0) {
+ return 20;
+ }
+ return Math.min(requested, MAX_PAGE_SIZE);
+ }
+
+ static Instant parseTime(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return LocalDateTime.parse(raw.trim(), DATE_TIME)
+ .atZone(XincangConstants.SYSTEM_ZONE).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ static Instant parseDate(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return LocalDate.parse(raw.trim(), DATE)
+ .atStartOfDay(XincangConstants.SYSTEM_ZONE).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ static Money parseMoney(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return Money.of(new BigDecimal(raw.trim()), CURRENCY_USD);
+ } catch (RuntimeException e) {
+ return null;
+ }
+ }
+
+ static int intOf(String raw) {
+ if (blank(raw)) {
+ return 0;
+ }
+ try {
+ return (int) Math.round(Double.parseDouble(raw.trim()));
+ } catch (NumberFormatException e) {
+ return 0;
+ }
+ }
+
+ static BigDecimal decimalOf(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return new BigDecimal(raw.trim());
+ } catch (NumberFormatException e) {
+ return null;
+ }
+ }
+
+ static String firstNonBlank(String a, String b) {
+ if (!blank(a)) {
+ return a.trim();
+ }
+ return blank(b) ? null : b.trim();
+ }
+
+ static String blankToNull(String v) {
+ return blank(v) ? null : v.trim();
+ }
+
+ static boolean blank(String v) {
+ return v == null || v.trim().isEmpty();
+ }
+
+ private static void putIfPresent(Map params, String key, String value) {
+ if (!blank(value)) {
+ params.put(key, value.trim());
+ }
+ }
+}
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 cafdd30..e4323f0 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
@@ -865,6 +865,150 @@ public final class XincangDtos {
public CalculateV3Result rst;
}
+ /** 实时库存响应 {@code rst}({@code GET api.stocklist})。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockListResult {
+
+ @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 StockRow {
+
+ @JsonProperty("warehouse_code")
+ public String warehouseCode;
+
+ /** 产品 SKU。 */
+ @JsonProperty("product_sku")
+ public String productSku;
+
+ /** 实时库存。 */
+ @JsonProperty("real_stock")
+ public String realStock;
+
+ /** 可售数量。 */
+ @JsonProperty("cansale_sku_count")
+ public String canSaleSkuCount;
+
+ /** 占用数量。 */
+ @JsonProperty("use_sku_count")
+ public String useSkuCount;
+
+ /** 待出库数量。 */
+ @JsonProperty("wait_sku_count")
+ public String waitSkuCount;
+
+ /** 在海上数量。 */
+ @JsonProperty("ship_sku_count")
+ public String shipSkuCount;
+
+ /** 预警数量。 */
+ @JsonProperty("alerm_count")
+ public String alarmCount;
+
+ /** 商品名。 */
+ @JsonProperty("chn_name")
+ public String chnName;
+
+ /** 体积(立方厘米)。 */
+ @JsonProperty("volume_cm")
+ public String volumeCm;
+ }
+ }
+
+ /** 实时库存响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockListResponse {
+
+ @JsonProperty("rst")
+ public StockListResult rst;
+ }
+
+ /** 库龄列表响应 {@code rst}({@code GET api.stockagelist})。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockAgeListResult {
+
+ @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 AgeRow {
+
+ /** 计费日期 {@code yyyy-MM-dd}。 */
+ @JsonProperty("dt")
+ public String dt;
+
+ @JsonProperty("warehouse_code")
+ public String warehouseCode;
+
+ /** 产品 SKU。 */
+ @JsonProperty("product_sku")
+ public String productSku;
+
+ /** 入库柜号。 */
+ @JsonProperty("cabinet_no")
+ public String cabinetNo;
+
+ /** 当日费用。 */
+ @JsonProperty("sum_fee")
+ public String sumFee;
+
+ /** 计费总体积(立方米)。 */
+ @JsonProperty("total_volume_cbm")
+ public String totalVolumeCbm;
+
+ /** 库存数量。 */
+ @JsonProperty("sku_count")
+ public String skuCount;
+
+ /** 入库时间 {@code yyyy-MM-dd HH:mm:ss}。 */
+ @JsonProperty("in_stock_time")
+ public String inStockTime;
+
+ /** 库龄天数。 */
+ @JsonProperty("fee_days")
+ public String feeDays;
+
+ /** 费率。 */
+ @JsonProperty("config_price")
+ public String configPrice;
+
+ /** 计费数量。 */
+ @JsonProperty("fee_count")
+ public String feeCount;
+ }
+ }
+
+ /** 库龄列表响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class StockAgeListResponse {
+
+ @JsonProperty("rst")
+ public StockAgeListResult 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 c981bd4..db6fa23 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
@@ -120,11 +120,13 @@ class XincangAdapterTest {
assertEquals(WarehouseProvider.XINCANG, adapter.provider());
assertEquals(XincangConstants.ADAPTER_ID, adapter.adapterId());
assertEquals(EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
- WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT,
- WarehouseCapability.CHANNEL_RECOMMEND), adapter.capabilities());
+ WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.TRANSFER,
+ WarehouseCapability.SPLIT, WarehouseCapability.CHANNEL_RECOMMEND),
+ adapter.capabilities());
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND));
- // 库存 / 退货等未接入,仍是 false
- assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY));
+ assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY));
+ // 退货等未接入,仍是 false
+ assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.RETURN));
}
}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java
new file mode 100644
index 0000000..3f295f9
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java
@@ -0,0 +1,200 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.support.Page;
+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.InventorySyncStrategy;
+import common.ecommerce.warehouse.enums.WarehouseCapability;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.InventoryAgeQuery;
+import common.ecommerce.warehouse.model.InventoryAgeRecord;
+import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.InventorySnapshot;
+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.time.Instant;
+import java.time.LocalDate;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 实时库存({@code api.stocklist})与库龄列表({@code api.stockagelist})契约测试。
+ */
+class XincangInventoryTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ private static final String STOCK_BODY = "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":["
+ + "{\"warehouse_code\":\"NJ-2605\",\"product_sku\":\"LSS29ORANGE\","
+ + "\"real_stock\":\"1500\",\"cansale_sku_count\":\"1499\",\"use_sku_count\":\"1\","
+ + "\"wait_sku_count\":\"1\",\"ship_sku_count\":\"0\",\"alerm_count\":\"0\","
+ + "\"chn_name\":\"餐椅\",\"volume_cm\":\"136221.5274\"}"
+ + "],\"count\":\"1\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-stock\"}";
+
+ private static final String AGE_BODY = "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":["
+ + "{\"dt\":\"2026-10-14\",\"warehouse_code\":\"NJ-2605\",\"product_sku\":\"LSS29ORANGE\","
+ + "\"cabinet_no\":\"KKKKK001\",\"sum_fee\":\"0.00\",\"total_volume_cbm\":\"204.3323\","
+ + "\"sku_count\":\"1500\",\"in_stock_time\":\"2026-10-14 08:00:00\",\"fee_days\":\"1\","
+ + "\"config_price\":\"0.50\",\"fee_count\":\"1500\"}"
+ + "],\"count\":\"1\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-age\"}";
+
+ private RecordingTransport transport;
+ private XincangAdapter adapter;
+
+ @BeforeEach
+ void setUp() {
+ transport = RecordingTransport.create();
+ MutableClock clock = MutableClock.atUtc("2026-11-10T00: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 stockQuerySendsWarehouseAndMapsSnapshot() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY));
+
+ Page page = adapter.query(ctx(),
+ InventoryQuery.builder().warehouseCode("NJ-2605").pageSize(10).build());
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("/api.stocklist?"), url);
+ assertTrue(url.contains("warehouse_code=NJ-2605"), url);
+ assertTrue(url.contains("page=1"), url);
+ assertTrue(url.contains("limit=10"), url);
+ assertTrue(url.contains("token=%7BT-1%7D"), url);
+
+ assertEquals(1, page.size());
+ InventorySnapshot snap = page.items().get(0);
+ assertEquals("NJ-2605", snap.warehouseCode());
+ assertEquals("LSS29ORANGE", snap.providerSku());
+ assertEquals(1500, snap.onHand());
+ assertEquals(1499, snap.available());
+ assertEquals(1, snap.reserved());
+ assertEquals(1, snap.pendingOutbound());
+ assertEquals(0, snap.inTransit());
+ assertEquals(0, snap.inventoryType());
+ assertEquals("餐椅", snap.productName());
+ assertEquals(0, snap.volumeCbm().compareTo(new java.math.BigDecimal("136221.5274")));
+ assertNotNull(snap.asOfUtc());
+ }
+
+ @Test
+ void stockFallsBackToAccountWarehouse() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY));
+
+ adapter.query(ctx(), InventoryQuery.builder().build());
+
+ assertTrue(transport.lastDataRequest().url().contains("warehouse_code=NJ-2605"));
+ }
+
+ @Test
+ void multipleWarehousesAreRejectedInsteadOfSilentlyUsingFirst() {
+ IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+ () -> adapter.query(ctx(), InventoryQuery.builder()
+ .warehouseCode("A").warehouseCode("B").build()));
+ assertTrue(e.getMessage().contains("single warehouse_code"), e.getMessage());
+ }
+
+ @Test
+ void stockSkuFilterIsSent() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY));
+
+ adapter.query(ctx(), InventoryQuery.builder().sku("LSS29ORANGE").build());
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("product_no=LSS29ORANGE"), url);
+ }
+
+ @Test
+ void ageQuerySendsBillDateRangeAndMapsRecord() {
+ transport.route(XincangConstants.PATH_STOCK_AGE_LIST, req -> Responses.ok(AGE_BODY));
+
+ Page page = adapter.queryAges(ctx(), InventoryAgeQuery.builder()
+ .dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-31"))
+ .includeFeeRate(true)
+ .build());
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("/api.stockagelist?"), url);
+ // bill_date 是「起 - 止」单值,空格与连字符会被 URL 编码
+ assertTrue(url.contains("bill_date=2026-10-01+-+2026-10-31"), url);
+ assertTrue(url.contains("is_need_fee_rate=1"), url);
+ assertTrue(url.contains("warehouse_code=NJ-2605"), "未指定仓时用账户配置: " + url);
+
+ assertEquals(1, page.size());
+ InventoryAgeRecord rec = page.items().get(0);
+ assertEquals("NJ-2605", rec.warehouseCode());
+ assertEquals("LSS29ORANGE", rec.providerSku());
+ // 计费日期按北京时间 0 点 → UTC 前一天 16:00
+ assertEquals(Instant.parse("2026-10-13T16:00:00Z"), rec.billingDate());
+ assertEquals("KKKKK001", rec.cabinetNo());
+ assertEquals(1, rec.ageDays());
+ assertEquals(1500, rec.quantity());
+ assertEquals(1500, rec.billingQuantity());
+ assertEquals(0, rec.feeRate().compareTo(new java.math.BigDecimal("0.50")));
+ assertEquals(0, rec.fee().amount().compareTo(java.math.BigDecimal.ZERO));
+ assertEquals("USD", rec.fee().currencyCode());
+ assertEquals(Instant.parse("2026-10-14T00:00:00Z"), rec.inStockAt());
+ }
+
+ @Test
+ void ageQueryRejectsMissingDateRange() {
+ assertThrows(IllegalArgumentException.class,
+ () -> InventoryAgeQuery.builder().build());
+ assertThrows(IllegalArgumentException.class,
+ () -> InventoryAgeQuery.builder()
+ .dateRange(LocalDate.parse("2026-10-31"), LocalDate.parse("2026-10-01"))
+ .build());
+ }
+
+ @Test
+ void ageQuerySkipsRowsWithoutBillingDate() {
+ String noDate = AGE_BODY.replace("\"dt\":\"2026-10-14\",", "\"dt\":\"\",");
+ transport.route(XincangConstants.PATH_STOCK_AGE_LIST, req -> Responses.ok(noDate));
+
+ Page page = adapter.queryAges(ctx(), InventoryAgeQuery.builder()
+ .dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-31")).build());
+
+ assertTrue(page.items().isEmpty(), "计费日期解析不出时跳过,不猜日期");
+ }
+
+ @Test
+ void missingRstIsNotSilentEmpty() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\"}"));
+
+ assertThrows(ValidationException.class,
+ () -> adapter.query(ctx(), InventoryQuery.builder().build()));
+ }
+
+ @Test
+ void inventoryCapabilityAndStrategy() {
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
+ assertEquals(InventorySyncStrategy.FULL_PULL_DIFF, adapter.syncStrategy());
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
index 3ac6096..711f01f 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
@@ -213,10 +213,9 @@ class XincangOrderTest {
@Test
void queryAndCancelAreExplicitlyUnsupported() {
- // get 已接入(见 XincangOrderDetailTest),这里只断言仍未接入的列表查询
- assertThrows(common.ecommerce.shared.error.ValidationException.class,
- () -> adapter.query(ctx(), null));
- assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
+ // get / query 均已接入(见 XincangOrderDetailTest、XincangInventoryTest),
+ // 这里只断言能力位齐全
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
}
@Test
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
index 3d57653..eea8b23 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
@@ -246,7 +246,7 @@ class XincangProductTest {
@Test
void productCapabilityIsDeclared() {
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
- assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
+ assertFalse(adapter.capabilities().contains(WarehouseCapability.RETURN));
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
}
}