diff --git a/docs-warehouse/architecture.md b/docs-warehouse/architecture.md
index 7e12139..58cdddf 100644
--- a/docs-warehouse/architecture.md
+++ b/docs-warehouse/architecture.md
@@ -85,7 +85,7 @@ public enum YqnOutboundStatus {
`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略,
调用方不应假定排序一定生效。
-`WarehouseCapability`(26 个):
+`WarehouseCapability`(27 个):
| 能力 | 说明 | 运去哪 | 信仓 |
|---|---|:---:|:---:|
@@ -99,7 +99,7 @@ public enum YqnOutboundStatus {
| `BOX_LABEL` | 入库箱标(异步) | ✅ | — |
| `SKU_LABEL` | SKU 标(异步) | ✅ | — |
| `LOGISTICS_PRODUCT` | 物流产品清单 | ✅ | ✅ |
-| `WAREHOUSE_DIRECTORY` | 仓库目录 | ✅ | — |
+| `DIRECTORY` | 仓库 / 承运商目录 | ✅ | — |
| `WEBHOOK` | 状态回调 | ✅ | — |
| `TRANSFER` | 仓间调拨 | ✅ | ✅ |
| `RETURN` | 退货发起 / 查询 | ✅ | — |
@@ -107,6 +107,7 @@ public enum YqnOutboundStatus {
| `TRACKING` | 物流轨迹 | ✅ | — |
| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
| `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — |
+| `CASE_MARK_PRINT` | 箱唛打印(同步 PDF) | — | — |
| `DESTRUCTION` | 销毁 / 报废 | ✅ | — |
| `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — |
| `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — |
diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md
index 90ab88b..0069713 100644
--- a/docs-warehouse/edayun/README.md
+++ b/docs-warehouse/edayun/README.md
@@ -8,6 +8,7 @@
| 适配器 / 工厂 | ✅ 类型就绪,能力位为空 |
| 获取 token | ✅ 已对接(`POST /oauth/token`) |
| 创建产品 | ✅ 已对接(`POST /webApi/skuInfo/v1/createProduct`) |
+| 商品查询 | ✅ 已对接(`POST /webApi/skuInfo/v1/listProductPage`) |
| 创建出库单 | ✅ 已对接(`POST /webApi/order/v1/createOrder`) |
| 查询出库单 | ✅ 已对接(`POST /webApi/order/v1/getOrderInfo`) |
| 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) |
@@ -28,7 +29,7 @@
| 物流产品清单 | ✅ 已对接(`POST /webApi/order/listByLogisticProductHasPerm`) |
| 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) |
| 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) |
-| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** |
+| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMark`),**真机未启用** |
| 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) |
| 仓库清单 | ✅ 已对接(`warehouse/listWarehouseHasPerm` + `warehouse/listActive`) |
| 其它业务接口 | ⬜ 等文档 |
@@ -156,6 +157,55 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false -Dedayun.probe.product=tr
... -Dedayun.probe.write=true -Dedayun.probe.token=... -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=...
```
+## 商品查询
+
+```
+POST /webApi/skuInfo/v1/listProductPage → Page
+```
+
+### 三个坑
+
+**1. SKU 是逗号拼接的单个字符串,且一次最多 50 个。**
+
+```java
+req.skuCode = String.join(",", query.providerSkus()); // "A,B,C"
+```
+统一模型是 `List`,超 50 本地拒绝(不截断)。
+
+**2. 没有数据时回 `code=500, msg=查询无数据`。**
+
+这是「查不到」不是「调用失败」,按空页处理——与轨迹接口的「未匹配到轨迹」同一处理。
+其它 500 仍抛异常。
+
+**3. 查询条件全空时默认只查最近一个月。**
+
+`ybtest` 创建于 2021 年,不带时间窗就查不到。查老数据必须显式给时间窗。
+
+### 尺寸取实际值,缺失才回落预报值
+
+| 易达云 | 我们用的 |
+|---|---|
+| `length/width/height/weight` | **优先**(仓方当前存的值) |
+| `forecastLength/...` | 实际值缺失时回落 |
+
+真机对比很能说明问题:`ybtest` 的 `length` 是 55(实际量过),
+`forecastLength` 是 10(预报时填的)——两者差 5 倍,拿错会算错运费。
+
+### 页码从 1 开始,单页最多 200
+
+### 真机验证(2026-11-17)
+
+| 场景 | 结果 |
+|---|---|
+| 只给 `pageNum/pageSize`(不带时间窗) | `total=52244`(全量) |
+| `skuCode=ybtest` | `total=1`,实际尺寸 55×4×3、重量 1 |
+| `skuCode=ybtest` + 最近 30 天窗口 | **`code=500 查询无数据`**(该 SKU 建于 2021) |
+| 不存在的 SKU / 条码 | 同样「查询无数据」 |
+| 10 年窗口 + `ybtest` | 1 行,`createdAt=2021-02-04` |
+
+**SKU 是仓侧 SKU**:`ybtest` 既是 OMS SKU 也是建档时下发的 `providerSku`,
+所以看不出口径差异;若两者不同,必须传仓侧那串(见下方「SKU 口径」)。
+
## 创建出库单
```
@@ -913,10 +963,10 @@ POST /webApi/rma/info/v1/saveAndPublish → WarehouseReturn
| 方法 | 状态 |
|---|---|
-| `queryReturns(ctx, cursor)` | ❌ 文档只给了按单号查,没有列表接口 |
+| `queryReturns(ReturnQuery)` | ✅ 已实现(`selectRmaInfoList`) |
| `process(ctx, cmd)` | ❌ 要仓侧明细行 id,而详情响应里**没有行 id**(`checkList` / `skuList` / `shelfList` 都没有) |
-`queryReturns` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。
+`process` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。
### 探针
@@ -1154,7 +1204,7 @@ POST /webApi/track/getTrackInfoList → List / TrackingInfo
| 端点 | 实际打印 | 我们的方法 | 能力位 |
|---|---|---|---|
| `/webApi/skuInfo/v2/printBarcode` | **箱唛**(外箱标) | `printCaseMarks(...)` | `CASE_MARK_PRINT` |
-| `/webApi/entryInfo/v1/newPrintCaseMarkContentType` | **SKU 标** | `printSkuLabel(...)` | 走入库 `SKU_LABEL` 语义 |
+| `/webApi/entryInfo/v1/newPrintCaseMark` | **SKU 标** | `printSkuLabel(...)` | 走入库 `SKU_LABEL` 语义 |
**不要被路径名误导**。代码里两个方法的 javadoc 都写了这条提醒。
@@ -1192,10 +1242,10 @@ POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel
仓方其它校验:缺 `productInfos` →「产品信息不能为空」、缺 `pageSize` →
「纸张尺寸不能为空」、SKU 不存在 →「sku=XXX信息不存在」。
-### SKU 标(newPrintCaseMarkContentType)
+### SKU 标(newPrintCaseMark)
```
-POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel
+POST /webApi/entryInfo/v1/newPrintCaseMark → WarehouseLabel
```
**真机未启用**:PR 环境该路径报「接口不存在或未启用」,去掉
@@ -1317,6 +1367,23 @@ DTO 按 `List` 收。
`listWarehouseHasPerm` 只有 17 个。DTO 只声明统一模型用得上的十几个——
Jackson 会忽略未知字段。
+## SKU 口径:传的是 OMS SKU 还是仓侧 SKU?
+
+**结论:两边都必须是仓侧 SKU(建档时下发的那串)。**
+
+代码依据:
+
+- 建档:`YqnProductMapper.skuOf()` / `EdayunProductMapper.skuOf()` 都是
+ **`providerSku` 优先,为空才回退 `omsSku`**
+- 出库行:`OutboundLine` 同时有 `omsSku` 与 `providerSku`,映射时同样 providerSku 优先
+- 商品查询:`ProductQuery.providerSkus()` 是仓侧 SKU,**SDK 不做 OMS→仓侧转换**
+
+所以仓方库里存的永远是「我们建档时下发的那串」。如果宿主给 `providerSku`
+建了档,那么查询也必须用它;只有两者相同时(如 `ybtest`)才能混用。
+
+**SDK 不会静默转换的原因**:OMS→仓侧 SKU 的映射表在宿主手里(供应商编码规则、
+按仓不同的前缀等),SDK 猜不出来。查错了会拿到空结果或错的商品,比报错更难发现。
+
## 待确认(问易达云)
| # | 要确认 |
diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md
index ff9756e..01119f6 100644
--- a/docs-warehouse/edayun/TODO.md
+++ b/docs-warehouse/edayun/TODO.md
@@ -5,6 +5,7 @@
## 待仓方确认
| # | 问题 | 当前处理 | 影响 |
+|---|---|---|---|
| 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 |
| 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 |
| 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 |
@@ -37,7 +38,7 @@
| 35 | 入库明细接口不回仓库 / 创建时间 / 到仓时间 / 箱号 | 仓库用 OMS 配置;时间与箱明细为 null | 拿不到完整单据,需要 entryInfo 单头查询接口 |
| 36 | 是否有入库单列表 / 时间窗查询 | `query()` 的 cursor 当 entryCode 用 | 无法做增量同步,只能按单号轮询 |
| 37 | `forecastWeight` / `weight` 是克、`firstWeight` 是千克 | 未映射(统一模型没有行级重量) | 想按箱对账重量时需要 |
-| 38 | 退货单**没有列表查询** | `queryReturns` 显式拒绝 | 无法批量同步退货单 |
+| 38 | ~~退货单没有列表查询~~ ✅ 已对接 `selectRmaInfoList` | `queryReturns(ReturnQuery)` | 无 |
| 39 | 退货 `skus[].command` 码表(文档只写「1 上架 / 2 销毁」) | 只确定 DESTROY→2,其余都归 1 | 非销毁类处理方式可能与仓方预期不符 |
| 40 | 退货 `valueAddedService` / `shelveSkuCode` / `catalog` / `picUrls` 码值与语义 | 不下发 | 重新包装 / 换标上架等场景发不了 |
| 41 | 未妥投 / 返邮 / FBA 三种退货方式要不要做 | 只实现 `returnType=2` | 买家退货的返邮面单、FBA 退货都得人工 |
@@ -64,10 +65,10 @@
| 62 | PR 环境查不到任何轨迹(连出库单里的真实跟踪号都「未匹配到轨迹」) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 |
| 63 | 轨迹接口一次可查多个跟踪号,统一模型只有单号口径 | 逐个查、按单号匹配 | 批量查只能循环调用 |
| 64 | 轨迹的 `eventStatus` 取值(文档示例是 `"string"` 占位) | 原样透传 | 宿主无法按事件类型分支 |
-| 65 | 条码打印的纸张尺寸只有 4 档(7×3/10×6/6×4/A4),与入库贴标的 14 种不重叠 | 独立枚举 `BarcodePaperSize` | 宿主换标签纸时要选对枚举 |
+| 65 | 箱唛纸张尺寸只有 4 档,与入库贴标的 14 种不重叠 | 独立枚举 `CaseMarkPaperSize`(按实测尺寸命名) | 宿主换标签纸时要选对枚举 |
| 66 | 条码文件地址的**有效期**未知(OSS 链接) | 原样返回,不缓存 | 宿主存旧链接可能 403 |
| 67 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 |
-| 68 | **箱唛接口在 PR 环境未启用**(`newPrintCaseMarkContentType` 报「接口不存在或未启用」;去掉后缀的 `newPrintCaseMark` 能过参数校验但一律「内部服务器错误」) | 按文档实现,映射只有单测 | 上线前必须真机验证 |
+| 68 | **SKU 标接口调通但仓方内部报错**:路径 `/webApi/entryInfo/v1/newPrintCaseMark` 确认存在(缺参数有中文校验提示),但参数补全后一律「内部服务器错误」,试过 6 种 pageSize、madeInChina 0/1、separation、箱序号区间、skuCode、caseCodeList、不存在的 entryCode 都一样 | 按文档实现,映射只有单测 | 上线前必须真机验证 |
| 69 | SKU 标纸张码值 4/2/5 不连续 | 独立枚举 `EdayunSkuLabelPaper`,按映射表走 | 无(已规避) |
| 72 | **`printBarcode` 的 pageSize=2 / pageSize=3 文档标称与实际相反**(文档 2=6×4cm、3=A4;实测 2=100×150mm、3=60×40mm) | 枚举按实测尺寸命名,码值不变 | 按文档标称选纸会打错 |
| 73 | 两个端点名与实际语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标) | 代码按实际语义命名并在 javadoc 标注 | 无(已规避) |
diff --git a/docs-warehouse/yqn/README.md b/docs-warehouse/yqn/README.md
index d784d05..71eaf31 100644
--- a/docs-warehouse/yqn/README.md
+++ b/docs-warehouse/yqn/README.md
@@ -206,6 +206,36 @@ WarehouseConnection.of(
**未指定时按 UTC 解释,不猜成北京时间。**
+## 9.5 商品查询(API 113)
+
+```
+POST /v1/product/findPage → Page
+```
+
+### 页码从 0 开始
+
+文档原文「起始页为从0开始」。统一模型的游标就是页码字符串,**不做 ±1 换算**——
+空游标 = 第 0 页。这和运去哪其它分页接口(从 1 开始)不一致,容易踩。
+
+### 单页上限 100,SKU 上限 100
+
+`pageSize` 默认 100、最大 100;`skuList` 最大 100 个。超了各自本地拒绝。
+
+### 只支持 SKU 过滤
+
+运去哪这个接口没有条码 / 创建时间过滤,`ProductQuery` 里传了这两个会本地拒绝,
+不静默忽略。
+
+### 翻页优先看 `last`
+
+响应是 Spring Data 风格,`last=true` 即末页。缺失时用 `number + 1 < totalPages`
+推断,再缺失才按「本页是否满页」兜底。
+
+### 成本要带币种才是 Money
+
+`cost` 与 `currency` 是两列;没有币种时只保留数字会丢单位,所以
+没有 `currency` 时 `cost()` 为 null。
+
## 10. 联调探针
两个探针,默认跳过:
@@ -235,4 +265,5 @@ mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \
| 库存调整 | 运去哪无此接口 |
| 换货 / 无头件 / BOL | 仓方无对应接口 |
| 退货查询列表 | 只有按单号查,无列表接口 |
+| 商品查询的条码 / 时间窗过滤 | API 113 只接受 skuList 与分页 |
| 出库列表 / 时间窗查询 | 只有按单号查 |
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java
index 7f8211f..d37c3aa 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java
@@ -21,7 +21,7 @@ public interface CaseMarkPrintCapable extends WarehouseAdapter {
*
* @return 已生成的文件(地址或 base64);仓方未返回文件时抛出异常,不返回 null
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
- * 该仓不声明 {@code BARCODE_PRINT}
+ * 该仓不声明 {@code CASE_MARK_PRINT}
*/
WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd);
}
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
index cbdfa19..371ac8d 100644
--- 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
@@ -44,22 +44,18 @@ public interface WarehouseDirectoryCapable extends WarehouseAdapter {
* 与 {@link #carriers} 的区别:那个只给一串物流方式码,这个是承运商 →
* 物流服务的两层结构,宿主要做下拉框或按承运商筛选时用这个。
*
- * 默认走 {@link #carriers} 把码包装成没有名称的条目;能给出结构的仓应覆盖。
+ * 默认不支持,不拿 {@link #carriers} 的码硬凑成两层结构——
+ * 那样会得到 {@code carrierId == nameEn == "FEDEX-G"} 这种假条目,
+ * 宿主若按类注释「下单时 carrierName 填 nameEn()」使用,就会把物流方式码
+ * 当成承运商名发出去。能给出真实结构的仓自己覆盖。
*
* @return 承运商列表;仓方返回空时为 empty list(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
- * 该仓不声明 {@code DIRECTORY} 或没有承运商接口
+ * 该仓没有承运商目录接口
*/
default List carrierDirectory(
WarehouseContext ctx) {
- List out =
- new java.util.ArrayList();
- for (String code : carriers(ctx)) {
- out.add(common.ecommerce.warehouse.model.WarehouseCarrier.builder()
- .carrierId(code)
- .nameEn(code)
- .build());
- }
- return out;
+ throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
+ common.ecommerce.warehouse.enums.WarehouseCapability.DIRECTORY);
}
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
index 1b5e249..9c40eb9 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
@@ -19,6 +19,24 @@ import java.util.Objects;
public final class WarehouseProduct {
private final String omsSku;
+ /**
+ * 仓侧 SKU——建档时下发给仓方的那串,之后所有查询 / 下单都用它。
+ *
+ * 各适配器在建档时按「{@code providerSku} 优先,为空才回退 {@link #omsSku}」
+ * 决定仓方库里存什么,字段名各不相同(易达云 {@code skuCode}、
+ * 运去哪 {@code sku})。仓方一旦落库,之后按 SKU 查询、下单、查库存都必须传
+ * 同一串——所以它不一定等于 {@link #omsSku()}:
+ *
+ *
+ * - 给了 {@code providerSku}(如 {@code AP0000X9US0010601})→ 仓方存它,
+ * 后续传入 {@code ProductQuery.providerSkus()} / {@code InventoryQuery.providerSkus()}
+ * / {@code OutboundLine.providerSku()} 时也必须是它
+ * - 没给 → 仓方存的就是 {@code omsSku},两者同名
+ *
+ *
+ * SDK 不做 OMS→仓侧 SKU 的转换:映射表在宿主手里,静默转换会拿回
+ * 空结果或错商品,比报错更难发现。
+ */
private final String providerSku;
private final String customItemNo;
private final String barcode;
@@ -161,43 +179,6 @@ public final class WarehouseProduct {
*/
private final Boolean specialOuterPackaging;
- // ==================== 查询结果才有(下发时忽略)====================
-
- /**
- * 仓侧商品 id。查询结果里有;建档时忽略。
- *
- * 信仓 {@code id}、恒健无此字段。
- */
- private final String providerProductId;
- /**
- * 仓方实测尺寸 / 重量;null 表示仓方未给。
- *
- * 与 {@link #lengthCm()} 等不是一回事:那些是我们申报的尺寸,
- * 这些是仓方收货后实测的(恒健 {@code measurement*})。下标成本、抛重都以实测为准。
- */
- private final Double measuredLengthCm;
- private final Double measuredWidthCm;
- private final Double measuredHeightCm;
- private final Double measuredWeightGrams;
- /** 仓方记录的创建时间(UTC);查询结果才有。 */
- private final java.time.Instant createdAt;
- /** 仓方记录的更新时间(UTC);查询结果才有。 */
- private final java.time.Instant updatedAt;
- /**
- * 仓方状态原值;查询结果才有,建档时为 null。
- *
- * 信仓 {@code state}:0 临时 / 1 正式;恒健无状态字段。
- */
- private final String rawState;
- /** 仓方状态中文名(信仓 {@code state_name});无则为 null。 */
- private final String stateName;
- /**
- * 体积(立方厘米);仓方原值。
- *
- * 信仓 {@code volume_cm};恒健无此字段。
- */
- private final java.math.BigDecimal volumeCm3;
-
/**
* 产品图片地址;null 表示不传。
*
@@ -220,23 +201,10 @@ public final class WarehouseProduct {
// 不在构造期强制:这是运去哪的必填项,信仓不需要。必填性由各适配器按自己的
// 协议校验,见 YqnProductMapper;未给时保持 -1 表示「不传」。
this.packingType = b.packingType;
- if (b.allowUnknownDimensions) {
- // 查询结果:仓方可能没给尺寸 / 重量。用 0 表示「未给」,
- // 不伪造一个值——伪造会让计费与抛重计算拿到假数据。
- requireNonNegative(b.lengthCm, "lengthCm");
- requireNonNegative(b.widthCm, "widthCm");
- requireNonNegative(b.heightCm, "heightCm");
- requireNonNegative(b.weightGrams, "weightGrams");
- this.lengthCm = b.lengthCm;
- this.widthCm = b.widthCm;
- this.heightCm = b.heightCm;
- this.weightGrams = b.weightGrams;
- } else {
- this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
- this.widthCm = requirePositive(b.widthCm, "widthCm");
- this.heightCm = requirePositive(b.heightCm, "heightCm");
- this.weightGrams = requirePositive(b.weightGrams, "weightGrams");
- }
+ this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
+ this.widthCm = requirePositive(b.widthCm, "widthCm");
+ this.heightCm = requirePositive(b.heightCm, "heightCm");
+ this.weightGrams = requirePositive(b.weightGrams, "weightGrams");
this.itemLengthCm = b.itemLengthCm;
this.itemWidthCm = b.itemWidthCm;
this.itemHeightCm = b.itemHeightCm;
@@ -256,16 +224,6 @@ public final class WarehouseProduct {
new java.util.ArrayList(b.imageUrls));
this.specialOuterPackaging = b.specialOuterPackaging;
this.imageUrl = b.imageUrl;
- this.providerProductId = b.providerProductId;
- this.measuredLengthCm = b.measuredLengthCm;
- this.measuredWidthCm = b.measuredWidthCm;
- this.measuredHeightCm = b.measuredHeightCm;
- this.measuredWeightGrams = b.measuredWeightGrams;
- this.createdAt = b.createdAt;
- this.updatedAt = b.updatedAt;
- this.rawState = b.rawState;
- this.stateName = b.stateName;
- this.volumeCm3 = b.volumeCm3;
this.expirationControl = b.expirationControl;
this.expirationDays = b.expirationDays;
this.packedQuantity = b.packedQuantity;
@@ -293,7 +251,7 @@ public final class WarehouseProduct {
return omsSku;
}
- /** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。 */
+ /** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。详见字段注释。 */
public String providerSku() {
return providerSku;
}
@@ -492,17 +450,6 @@ public final class WarehouseProduct {
return v != null && !v.trim().isEmpty();
}
- /** 尺寸 / 重量是否为「未给」(0 表示仓方没给,仅查询结果适用)。 */
- public boolean hasDimensions() {
- return lengthCm > 0 && widthCm > 0 && heightCm > 0 && weightGrams > 0;
- }
-
- private static void requireNonNegative(double v, String name) {
- if (v < 0) {
- throw new IllegalArgumentException(name + " must not be negative");
- }
- }
-
private static String require(String v, String n) {
if (!hasText(v)) {
throw new IllegalArgumentException(n + " must not be blank");
@@ -517,56 +464,6 @@ public final class WarehouseProduct {
return v;
}
- /** 仓侧商品 id;查询结果才有。 */
- public String providerProductId() {
- return providerProductId;
- }
-
- /** 仓方实测长(cm);未给为 null。 */
- public Double measuredLengthCm() {
- return measuredLengthCm;
- }
-
- /** 仓方实测宽(cm);未给为 null。 */
- public Double measuredWidthCm() {
- return measuredWidthCm;
- }
-
- /** 仓方实测高(cm);未给为 null。 */
- public Double measuredHeightCm() {
- return measuredHeightCm;
- }
-
- /** 仓方实测重量(g);未给为 null。 */
- public Double measuredWeightGrams() {
- return measuredWeightGrams;
- }
-
- /** 仓方记录的创建时间(UTC);未给为 null。 */
- public java.time.Instant createdAt() {
- return createdAt;
- }
-
- /** 仓方记录的更新时间(UTC);未给为 null。 */
- public java.time.Instant updatedAt() {
- return updatedAt;
- }
-
- /** 仓方状态原值;建档时为 null。 */
- public String rawState() {
- return rawState;
- }
-
- /** 仓方状态中文名;无则为 null。 */
- public String stateName() {
- return stateName;
- }
-
- /** 体积(立方厘米);未给为 null。 */
- public java.math.BigDecimal volumeCm3() {
- return volumeCm3;
- }
-
public static final class Builder {
private String omsSku;
@@ -598,22 +495,6 @@ public final class WarehouseProduct {
private String remark;
private Integer productCategory;
private String imageUrl;
- private String providerProductId;
- private Double measuredLengthCm;
- private Double measuredWidthCm;
- private Double measuredHeightCm;
- private Double measuredWeightGrams;
- private java.time.Instant createdAt;
- private java.time.Instant updatedAt;
- private String rawState;
- private String stateName;
- private java.math.BigDecimal volumeCm3;
- /**
- * 允许尺寸 / 重量为 0(表示仓方未给)。
- *
- * 只给查询结果用:建档时仍然必须给正数。不设这个开关时行为不变。
- */
- private boolean allowUnknownDimensions;
private final List imageUrls = new java.util.ArrayList();
private Boolean specialOuterPackaging;
private Boolean expirationControl;
@@ -859,76 +740,6 @@ public final class WarehouseProduct {
/**
* @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐
*/
- /**
- * 允许尺寸 / 重量为 0(表示仓方未给)。
- *
- * 只在把查询结果映射成模型时使用;建档仍是必填正数。
- */
- public Builder allowUnknownDimensions(boolean v) {
- this.allowUnknownDimensions = v;
- return this;
- }
-
- /** 仓侧商品 id(查询结果才有)。 */
- public Builder providerProductId(String v) {
- this.providerProductId = v;
- return this;
- }
-
- /** 仓方实测长(cm)。 */
- public Builder measuredLengthCm(Double v) {
- this.measuredLengthCm = v;
- return this;
- }
-
- /** 仓方实测宽(cm)。 */
- public Builder measuredWidthCm(Double v) {
- this.measuredWidthCm = v;
- return this;
- }
-
- /** 仓方实测高(cm)。 */
- public Builder measuredHeightCm(Double v) {
- this.measuredHeightCm = v;
- return this;
- }
-
- /** 仓方实测重量(g)。 */
- public Builder measuredWeightGrams(Double v) {
- this.measuredWeightGrams = v;
- return this;
- }
-
- /** 仓方记录的创建时间(UTC)。 */
- public Builder createdAt(java.time.Instant v) {
- this.createdAt = v;
- return this;
- }
-
- /** 仓方记录的更新时间(UTC)。 */
- public Builder updatedAt(java.time.Instant v) {
- this.updatedAt = v;
- return this;
- }
-
- /** 仓方状态原值。 */
- public Builder rawState(String v) {
- this.rawState = v;
- return this;
- }
-
- /** 仓方状态中文名。 */
- public Builder stateName(String v) {
- this.stateName = v;
- return this;
- }
-
- /** 体积(立方厘米)。 */
- public Builder volumeCm3(java.math.BigDecimal v) {
- this.volumeCm3 = v;
- return this;
- }
-
public WarehouseProduct build() {
return new WarehouseProduct(this);
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java
index d5f960f..3812aee 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java
@@ -10,17 +10,19 @@ public interface WarehouseProductCapable extends WarehouseAdapter {
ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product);
/**
- * 分页查商品。只读,不走幂等。
+ * 批量 / 分页查询仓侧商品资料。
*
- * 各仓支持的过滤维度不同:不支持的维度由适配器显式拒绝,
- * 不静默忽略——忽略一个过滤条件会让调用方以为「仓里就这些商品」。
+ * 查询用的 SKU 是仓侧 SKU(建档时下发的那串,通常是
+ * {@code WarehouseProduct.providerSku()},没给映射时等于 OMS SKU)。
+ * SDK 不做 OMS→仓侧 SKU 的转换——映射表在宿主手里,静默转换会让结果对不上。
*
- * @param query 查询条件;游标为空表示第一页
- * @return 当前页商品;{@code nextCursor} 非空表示还有下一页
+ * 默认不支持:只有提供商品查询接口的仓才覆盖。
+ *
+ * @return 分页结果;仓方无数据时为空页(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
- * 该仓不支持商品查询
+ * 该仓不提供商品查询
*/
- default common.ecommerce.shared.support.Page queryProducts(
+ default common.ecommerce.shared.support.Page query(
WarehouseContext ctx, common.ecommerce.warehouse.model.ProductQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.PRODUCT);
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
index ff61d4e..5932b5a 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
@@ -40,6 +40,26 @@ public interface WarehouseReturnCapable extends WarehouseAdapter {
Page queryReturns(WarehouseContext ctx, ReturnQuery query);
/**
+ * 分页查退货处理单(仓方收货检验后按明细行拆出的处理单元)。
+ *
+ * 只有提供该接口的仓才覆盖;默认不支持。
+ *
+ * 与 {@link #queryReturns} 的区别:那个查「一张退货计划」,
+ * 这个查「计划下每一行 SKU 的待处理记录」。填处理方式要用的四项定位
+ * (计划单号 + 处理单号 + SKU + tracking)就在返回的
+ * {@link common.ecommerce.warehouse.model.ReturnHandle} 里。
+ *
+ * @return 分页结果;仓方无数据时为空页(不是错误)
+ * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
+ * 该仓不提供处理单查询
+ */
+ default Page queryHandles(
+ WarehouseContext ctx, ReturnQuery query) {
+ throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
+ common.ecommerce.warehouse.enums.WarehouseCapability.RETURN);
+ }
+
+ /**
* 按明细行设置检验后处理方式。写操作,幂等键
* {@code warehouseCode + providerReturnNo + lineId + "process"}。
*/
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
index 1d74310..c0b67dc 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
@@ -37,6 +37,13 @@ public final class InventoryQuery {
return new Builder();
}
+ /**
+ * 仓侧 SKU 列表;空表示不按 SKU 过滤。
+ *
+ * 同 {@link ProductQuery#providerSkus()}:必须是建档时下发的仓侧 SKU
+ * ({@code WarehouseProduct.providerSku()},未给映射时即 {@code omsSku()}),
+ * 不一定是 OMS SKU。
+ */
public List providerSkus() {
return providerSkus;
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java
new file mode 100644
index 0000000..7ec609b
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java
@@ -0,0 +1,632 @@
+package common.ecommerce.warehouse.model;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 仓侧商品资料(查询结果)。
+ *
+ * 与 {@link common.ecommerce.warehouse.capability.WarehouseProduct} 的区别:
+ * 那个是建档入参(我们下发给仓方),这个是查询结果(仓方存着什么)。
+ * 两者字段高度重叠但语义不同——入参里没有 id / 状态 / 创建时间,
+ * 结果里也没有「要求仓方必填」这类约束,所以不复用同一个类。
+ *
+ * 单位与入参一致:尺寸 cm、重量 g。
+ */
+public final class ProductInfo {
+
+ /** 仓侧 SKU(建档时下发的那串)。 */
+ private final String providerSku;
+ /** OMS 侧 SKU;仓方不回时为 null(SDK 不做反查)。 */
+ private final String omsSku;
+ /** 仓方内部商品 id;不同仓给不给不一。 */
+ private final String providerProductId;
+ /** 自定义产品编码。 */
+ private final String customItemNo;
+ private final String barcode;
+ private final List extraBarcodes;
+
+ private final String name;
+ private final String nameEn;
+ private final String description;
+
+ /** 产品类型:1 成品 / 2 配件 / 3 耗材;未给为 -1。 */
+ private final int productType;
+
+ /** 外箱 / 整箱尺寸重量。 */
+ private final double lengthCm;
+ private final double widthCm;
+ private final double heightCm;
+ private final double weightGrams;
+
+ /** 单品尺寸;未给为 null。 */
+ private final Double itemLengthCm;
+ private final Double itemWidthCm;
+ private final Double itemHeightCm;
+
+ /** 装箱数量;未给为 null。 */
+ private final Integer packedQuantity;
+ private final Double packedLengthCm;
+ private final Double packedWidthCm;
+ private final Double packedHeightCm;
+ private final Double packedWeightGrams;
+
+ /** 是否需要 SN;未给为 null。 */
+ private final Boolean requireSn;
+ /** 成本;未给为 null。 */
+ private final Money cost;
+
+ /** 仓方状态原值(如 edayun 的 0 草稿 / 1 已发布);未给为 null。 */
+ private final Integer rawStatus;
+ /** 仓方状态名原值。 */
+ private final String rawStatusName;
+
+ /** 创建时间;未给为 null。 */
+ private final Instant createdAt;
+ /** 更新时间;仓方未给为 null。 */
+ private final Instant updatedAt;
+ private final String remark;
+ /** 该商品来自哪家仓。 */
+ private final WarehouseProvider sourceProvider;
+
+ // ==================== 仓方实测尺寸(恒健 measurement*)====================
+
+ /**
+ * 仓方收货后实测尺寸 / 重量;未给为 null。
+ *
+ * 与 {@link #lengthCm()} 等不是一回事:那些是我们申报的。
+ * 下标成本、抛重计算都以实测为准。
+ */
+ private final Double measuredLengthCm;
+ private final Double measuredWidthCm;
+ private final Double measuredHeightCm;
+ private final Double measuredWeightGrams;
+
+ // ==================== 申报价值 / 保价(恒健、信仓)====================
+
+ /** 申报价值;恒健 {@code cost}+{@code currency}、信仓 {@code amount}(USD);未给为 null。 */
+ private final Money declaredValue;
+ /** 是否保价;恒健 {@code isInsuranceFlag}(Y/N);未给为 null。 */
+ private final Boolean insured;
+ /** 保价费用;恒健 {@code isInsuranceRate};未给为 null。 */
+ private final Money insuranceFee;
+
+ // ==================== 保质期(恒健)====================
+
+ /** 是否开启保质期管理;未给为 null。 */
+ private final Boolean expirationControl;
+ /** 保质期天数;未给为 null。 */
+ private final Integer expirationDays;
+
+ // ==================== 体积 / 图片 / 状态名(信仓、恒健)====================
+
+ /** 体积(立方厘米);未给为 null。 */
+ private final java.math.BigDecimal volumeCm3;
+ /** 商品图片 URL;仓方未给为 null。 */
+ private final String imageUrl;
+ /** 仓方状态码的原值文本(信仓 {@code state} 是字符串 0/1);未给为 null。 */
+ private final String rawState;
+
+ private ProductInfo(Builder b) {
+ this.providerSku = require(b.providerSku, "providerSku");
+ this.omsSku = b.omsSku;
+ this.providerProductId = b.providerProductId;
+ this.customItemNo = b.customItemNo;
+ this.barcode = b.barcode;
+ this.extraBarcodes = Collections.unmodifiableList(
+ new ArrayList(b.extraBarcodes));
+ this.name = b.name;
+ this.nameEn = b.nameEn;
+ this.description = b.description;
+ this.productType = b.productType;
+ this.lengthCm = b.lengthCm;
+ this.widthCm = b.widthCm;
+ this.heightCm = b.heightCm;
+ this.weightGrams = b.weightGrams;
+ this.itemLengthCm = b.itemLengthCm;
+ this.itemWidthCm = b.itemWidthCm;
+ this.itemHeightCm = b.itemHeightCm;
+ this.packedQuantity = b.packedQuantity;
+ this.packedLengthCm = b.packedLengthCm;
+ this.packedWidthCm = b.packedWidthCm;
+ this.packedHeightCm = b.packedHeightCm;
+ this.packedWeightGrams = b.packedWeightGrams;
+ this.requireSn = b.requireSn;
+ this.cost = b.cost;
+ this.rawStatus = b.rawStatus;
+ this.rawStatusName = b.rawStatusName;
+ this.createdAt = b.createdAt;
+ this.updatedAt = b.updatedAt;
+ this.remark = b.remark;
+ this.sourceProvider = b.sourceProvider;
+ this.measuredLengthCm = b.measuredLengthCm;
+ this.measuredWidthCm = b.measuredWidthCm;
+ this.measuredHeightCm = b.measuredHeightCm;
+ this.measuredWeightGrams = b.measuredWeightGrams;
+ this.declaredValue = b.declaredValue;
+ this.insured = b.insured;
+ this.insuranceFee = b.insuranceFee;
+ this.expirationControl = b.expirationControl;
+ this.expirationDays = b.expirationDays;
+ this.volumeCm3 = b.volumeCm3;
+ this.imageUrl = b.imageUrl;
+ this.rawState = b.rawState;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public String providerSku() {
+ return providerSku;
+ }
+
+ /** OMS SKU;仓方不回时为 null。 */
+ public String omsSku() {
+ return omsSku;
+ }
+
+ public String providerProductId() {
+ return providerProductId;
+ }
+
+ public String customItemNo() {
+ return customItemNo;
+ }
+
+ public String barcode() {
+ return barcode;
+ }
+
+ /** 额外条码(仓方支持多个时);不可变。 */
+ public List extraBarcodes() {
+ return extraBarcodes;
+ }
+
+ public String name() {
+ return name;
+ }
+
+ public String nameEn() {
+ return nameEn;
+ }
+
+ public String description() {
+ return description;
+ }
+
+ /** 产品类型:1 成品 / 2 配件 / 3 耗材;未给为 -1。 */
+ public int productType() {
+ return productType;
+ }
+
+ public double lengthCm() {
+ return lengthCm;
+ }
+
+ public double widthCm() {
+ return widthCm;
+ }
+
+ public double heightCm() {
+ return heightCm;
+ }
+
+ public double weightGrams() {
+ return weightGrams;
+ }
+
+ public Double itemLengthCm() {
+ return itemLengthCm;
+ }
+
+ public Double itemWidthCm() {
+ return itemWidthCm;
+ }
+
+ public Double itemHeightCm() {
+ return itemHeightCm;
+ }
+
+ public Integer packedQuantity() {
+ return packedQuantity;
+ }
+
+ public Double packedLengthCm() {
+ return packedLengthCm;
+ }
+
+ public Double packedWidthCm() {
+ return packedWidthCm;
+ }
+
+ public Double packedHeightCm() {
+ return packedHeightCm;
+ }
+
+ public Double packedWeightGrams() {
+ return packedWeightGrams;
+ }
+
+ public Boolean requireSn() {
+ return requireSn;
+ }
+
+ public Money cost() {
+ return cost;
+ }
+
+ /** 仓方状态原值。 */
+ public Integer rawStatus() {
+ return rawStatus;
+ }
+
+ /** 仓方状态名原值。 */
+ public String rawStatusName() {
+ return rawStatusName;
+ }
+
+ public Instant createdAt() {
+ return createdAt;
+ }
+
+ public String remark() {
+ return remark;
+ }
+
+ public WarehouseProvider sourceProvider() {
+ return sourceProvider;
+ }
+
+ /** 更新时间;仓方未给为 null。 */
+ public Instant updatedAt() {
+ return updatedAt;
+ }
+
+ /** 仓方实测长(cm);未给为 null。 */
+ public Double measuredLengthCm() {
+ return measuredLengthCm;
+ }
+
+ /** 仓方实测宽(cm);未给为 null。 */
+ public Double measuredWidthCm() {
+ return measuredWidthCm;
+ }
+
+ /** 仓方实测高(cm);未给为 null。 */
+ public Double measuredHeightCm() {
+ return measuredHeightCm;
+ }
+
+ /** 仓方实测重量(g);未给为 null。 */
+ public Double measuredWeightGrams() {
+ return measuredWeightGrams;
+ }
+
+ /** 申报价值;未给为 null。 */
+ public Money declaredValue() {
+ return declaredValue;
+ }
+
+ /** 是否保价;未给为 null。 */
+ public Boolean insured() {
+ return insured;
+ }
+
+ /** 保价费用;未给为 null。 */
+ public Money insuranceFee() {
+ return insuranceFee;
+ }
+
+ /** 是否开启保质期管理;未给为 null。 */
+ public Boolean expirationControl() {
+ return expirationControl;
+ }
+
+ /** 保质期天数;未给为 null。 */
+ public Integer expirationDays() {
+ return expirationDays;
+ }
+
+ /** 体积(立方厘米);未给为 null。 */
+ public java.math.BigDecimal volumeCm3() {
+ return volumeCm3;
+ }
+
+ /** 商品图片 URL;未给为 null。 */
+ public String imageUrl() {
+ return imageUrl;
+ }
+
+ /** 仓方状态码原值文本;未给为 null。 */
+ public String rawState() {
+ return rawState;
+ }
+
+ 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 String providerSku;
+ private String omsSku;
+ private String providerProductId;
+ private String customItemNo;
+ private String barcode;
+ private final List extraBarcodes = new ArrayList();
+ private String name;
+ private String nameEn;
+ private String description;
+ private int productType = -1;
+ private double lengthCm;
+ private double widthCm;
+ private double heightCm;
+ private double weightGrams;
+ private Double itemLengthCm;
+ private Double itemWidthCm;
+ private Double itemHeightCm;
+ private Integer packedQuantity;
+ private Double packedLengthCm;
+ private Double packedWidthCm;
+ private Double packedHeightCm;
+ private Double packedWeightGrams;
+ private Boolean requireSn;
+ private Money cost;
+ private Integer rawStatus;
+ private String rawStatusName;
+ private Instant createdAt;
+ private Instant updatedAt;
+ private String remark;
+ private WarehouseProvider sourceProvider;
+ private Double measuredLengthCm;
+ private Double measuredWidthCm;
+ private Double measuredHeightCm;
+ private Double measuredWeightGrams;
+ private Money declaredValue;
+ private Boolean insured;
+ private Money insuranceFee;
+ private Boolean expirationControl;
+ private Integer expirationDays;
+ private java.math.BigDecimal volumeCm3;
+ private String imageUrl;
+ private String rawState;
+
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ public Builder omsSku(String v) {
+ this.omsSku = v;
+ return this;
+ }
+
+ public Builder providerProductId(String v) {
+ this.providerProductId = v;
+ return this;
+ }
+
+ public Builder customItemNo(String v) {
+ this.customItemNo = v;
+ return this;
+ }
+
+ public Builder barcode(String v) {
+ this.barcode = v;
+ return this;
+ }
+
+ public Builder extraBarcode(String v) {
+ if (v != null && !v.trim().isEmpty()) {
+ this.extraBarcodes.add(v.trim());
+ }
+ return this;
+ }
+
+ public Builder name(String v) {
+ this.name = v;
+ return this;
+ }
+
+ public Builder nameEn(String v) {
+ this.nameEn = v;
+ return this;
+ }
+
+ public Builder description(String v) {
+ this.description = v;
+ return this;
+ }
+
+ /** 产品类型:1 成品 / 2 配件 / 3 耗材;-1 表示未给。 */
+ public Builder productType(int v) {
+ this.productType = v;
+ return this;
+ }
+
+ public Builder lengthCm(double v) {
+ this.lengthCm = v;
+ return this;
+ }
+
+ public Builder widthCm(double v) {
+ this.widthCm = v;
+ return this;
+ }
+
+ public Builder heightCm(double v) {
+ this.heightCm = v;
+ return this;
+ }
+
+ public Builder weightGrams(double v) {
+ this.weightGrams = v;
+ return this;
+ }
+
+ public Builder itemLengthCm(Double v) {
+ this.itemLengthCm = v;
+ return this;
+ }
+
+ public Builder itemWidthCm(Double v) {
+ this.itemWidthCm = v;
+ return this;
+ }
+
+ public Builder itemHeightCm(Double v) {
+ this.itemHeightCm = v;
+ return this;
+ }
+
+ public Builder packedQuantity(Integer v) {
+ this.packedQuantity = v;
+ return this;
+ }
+
+ public Builder packedLengthCm(Double v) {
+ this.packedLengthCm = v;
+ return this;
+ }
+
+ public Builder packedWidthCm(Double v) {
+ this.packedWidthCm = v;
+ return this;
+ }
+
+ public Builder packedHeightCm(Double v) {
+ this.packedHeightCm = v;
+ return this;
+ }
+
+ public Builder packedWeightGrams(Double v) {
+ this.packedWeightGrams = v;
+ return this;
+ }
+
+ public Builder requireSn(Boolean v) {
+ this.requireSn = v;
+ return this;
+ }
+
+ public Builder cost(Money v) {
+ this.cost = v;
+ return this;
+ }
+
+ public Builder rawStatus(Integer v) {
+ this.rawStatus = v;
+ return this;
+ }
+
+ public Builder rawStatusName(String v) {
+ this.rawStatusName = v;
+ return this;
+ }
+
+ public Builder createdAt(Instant v) {
+ this.createdAt = v;
+ return this;
+ }
+
+ public Builder remark(String v) {
+ this.remark = v;
+ return this;
+ }
+
+ /** 更新时间。 */
+ public Builder updatedAt(Instant v) {
+ this.updatedAt = v;
+ return this;
+ }
+
+ /** 仓方实测长(cm)。 */
+ public Builder measuredLengthCm(Double v) {
+ this.measuredLengthCm = v;
+ return this;
+ }
+
+ /** 仓方实测宽(cm)。 */
+ public Builder measuredWidthCm(Double v) {
+ this.measuredWidthCm = v;
+ return this;
+ }
+
+ /** 仓方实测高(cm)。 */
+ public Builder measuredHeightCm(Double v) {
+ this.measuredHeightCm = v;
+ return this;
+ }
+
+ /** 仓方实测重量(g)。 */
+ public Builder measuredWeightGrams(Double v) {
+ this.measuredWeightGrams = v;
+ return this;
+ }
+
+ /** 申报价值。 */
+ public Builder declaredValue(Money v) {
+ this.declaredValue = v;
+ return this;
+ }
+
+ /** 是否保价。 */
+ public Builder insured(Boolean v) {
+ this.insured = v;
+ return this;
+ }
+
+ /** 保价费用。 */
+ public Builder insuranceFee(Money v) {
+ this.insuranceFee = v;
+ return this;
+ }
+
+ /** 是否开启保质期管理。 */
+ public Builder expirationControl(Boolean v) {
+ this.expirationControl = v;
+ return this;
+ }
+
+ /** 保质期天数。 */
+ public Builder expirationDays(Integer v) {
+ this.expirationDays = v;
+ return this;
+ }
+
+ /** 体积(立方厘米)。 */
+ public Builder volumeCm3(java.math.BigDecimal v) {
+ this.volumeCm3 = v;
+ return this;
+ }
+
+ /** 商品图片 URL。 */
+ public Builder imageUrl(String v) {
+ this.imageUrl = v;
+ return this;
+ }
+
+ /** 仓方状态码原值文本。 */
+ public Builder rawState(String v) {
+ this.rawState = v;
+ return this;
+ }
+
+ public Builder sourceProvider(WarehouseProvider v) {
+ this.sourceProvider = v;
+ return this;
+ }
+
+ public ProductInfo build() {
+ return new ProductInfo(this);
+ }
+ }
+}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java
index aab234e..e286538 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java
@@ -1,35 +1,48 @@
package common.ecommerce.warehouse.model;
+import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
- * 商品查询条件。
+ * 商品查询条件(批量 / 分页)。
*
- * 与 {@code WarehouseProductCapable.createOrUpdate} 的区别:那个是写,这个是读。
- * 各仓支持的维度不同:不支持的维度由适配器显式拒绝,不静默忽略——
- * 忽略一个过滤条件会让调用方以为「仓里就这些商品」。
+ * 与 {@link InventoryQuery} 的口径一致:{@code providerSkus} 是仓侧 SKU,
+ * 即建档时下发给仓方的那一串(通常等于 {@code WarehouseProduct.providerSku()},
+ * 没给映射时就是 OMS SKU)。SDK 不做 OMS→仓侧 SKU 的转换——
+ * 那张映射表在宿主手里,这里静默转换会让查回来的东西对不上。
*
- * 目前两家仓(恒健 {@code /v2/product/queryPage}、信仓 {@code api.productlist})
- * 都只支持按 SKU 过滤 + 分页,所以模型只放这两个维度。
+ * 各仓支持的过滤维度不同,不支持的由适配器显式拒绝,
+ * 不静默忽略——忽略一个过滤条件会让结果对不上。
*/
public final class ProductQuery {
- /**
- * 仓方 SKU 列表;空表示不限。
- *
- * 恒健是 {@code skus} 数组(一次可传多个);信仓是 {@code key} 单值(精确匹配)。
- * 信仓收到多个 SKU 时由适配器拒绝而不是只取第一个。
- */
+ /** 单次最多查多少个 SKU(各仓不同,由适配器按自己的上限再校验)。 */
+ public static final int MAX_SKUS = 100;
+
private final List providerSkus;
- /** 每页条数;0 表示用仓方默认。 */
+ /** 条码(UPC / 仓方条码)。 */
+ private final String barcode;
+ private final Instant createdAfter;
+ private final Instant createdBefore;
private final int pageSize;
- /** 页码游标;null 表示第一页。 */
private final String cursor;
- private ProductQuery(Builder b) {
- this.providerSkus = Collections.unmodifiableList(new ArrayList(b.providerSkus));
+ public ProductQuery(Builder b) {
+ this.providerSkus = Collections.unmodifiableList(
+ new ArrayList(b.providerSkus));
+ if (this.providerSkus.size() > MAX_SKUS) {
+ throw new IllegalArgumentException(
+ "at most " + MAX_SKUS + " skus per query, got " + this.providerSkus.size());
+ }
+ if (b.createdAfter != null && b.createdBefore != null
+ && !b.createdAfter.isBefore(b.createdBefore)) {
+ throw new IllegalArgumentException("createdAfter must be before createdBefore");
+ }
+ this.barcode = b.barcode;
+ this.createdAfter = b.createdAfter;
+ this.createdBefore = b.createdBefore;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
@@ -38,48 +51,82 @@ public final class ProductQuery {
return new Builder();
}
- /** 仓方 SKU 列表;空表示不限。不可变。 */
+ /**
+ * 仓侧 SKU 列表;空表示不按 SKU 过滤。
+ *
+ * 这串必须等于建档时下发给仓方的 SKU({@code WarehouseProduct.providerSku()},
+ * 未给映射时即 {@code omsSku()})。各仓入库字段不同:易达云 {@code skuCode}
+ * (逗号拼接,≤50)/ 运去哪 {@code skuList}(JSON 数组,≤100)。
+ * 传错不会报错,只会查不到——SDK 不做 OMS→仓侧转换。
+ */
public List providerSkus() {
return providerSkus;
}
- /** 每页条数;0 表示用仓方默认。 */
+ /** 条码;null 表示不按条码过滤。 */
+ public String barcode() {
+ return barcode;
+ }
+
+ public Instant createdAfter() {
+ return createdAfter;
+ }
+
+ public Instant createdBefore() {
+ return createdBefore;
+ }
+
+ /** 是否给了完整的创建时间窗。 */
+ public boolean hasCreatedRange() {
+ return createdAfter != null && createdBefore != null;
+ }
+
public int pageSize() {
return pageSize;
}
- /** 页码游标;null 表示第一页。 */
+ /** 分页游标;null 表示第一页。 */
public String cursor() {
return cursor;
}
- public Builder toBuilder() {
- Builder b = builder().pageSize(pageSize).cursor(cursor);
- b.providerSkus.addAll(providerSkus);
- return b;
- }
-
public static final class Builder {
private final List providerSkus = new ArrayList();
- private int pageSize;
+ private String barcode;
+ private Instant createdAfter;
+ private Instant createdBefore;
+ private int pageSize = 100;
private String cursor;
+ /** 一个仓侧 SKU;空串忽略。 */
+ public Builder providerSku(String v) {
+ if (v != null && !v.trim().isEmpty()) {
+ this.providerSkus.add(v.trim());
+ }
+ return this;
+ }
+
public Builder providerSkus(List v) {
- this.providerSkus.clear();
if (v != null) {
- for (String sku : v) {
- if (sku != null && !sku.trim().isEmpty()) {
- this.providerSkus.add(sku.trim());
- }
+ for (String s : v) {
+ providerSku(s);
}
}
return this;
}
- public Builder providerSku(String v) {
- if (v != null && !v.trim().isEmpty()) {
- this.providerSkus.add(v.trim());
- }
+ public Builder barcode(String v) {
+ this.barcode = v;
+ return this;
+ }
+
+ public Builder createdAfter(Instant v) {
+ this.createdAfter = v;
+ return this;
+ }
+
+ public Builder createdBefore(Instant v) {
+ this.createdBefore = v;
return this;
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnHandle.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnHandle.java
new file mode 100644
index 0000000..f4781ed
--- /dev/null
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnHandle.java
@@ -0,0 +1,336 @@
+package common.ecommerce.warehouse.model;
+
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+
+import java.time.Instant;
+import java.util.List;
+
+/**
+ * 退货处理单(仓方收货检验后按明细行拆出的处理单元)。
+ *
+ * 与 {@link WarehouseReturn} 的区别:那是一张退货计划,
+ * 这是计划下一行 SKU 的一条待处理记录——一张计划可以有多个处理单,
+ * 每行可以分别拍照 / 销毁 / 上架。
+ *
+ * 填写处理方式({@code ReturnProcessCommand})要用的定位字段就在本对象里:
+ * {@link #returnPlanNo()} + {@link #returnHandleNo()} + {@link #providerSku()}
+ * + {@link #trackingNumber()}。
+ */
+public final class ReturnHandle {
+
+ private final String returnPlanNo;
+ private final String returnHandleNo;
+ private final String returnNo;
+ private final String trackingNumber;
+ private final String providerSku;
+ private final String changeSku;
+ private final Integer quantity;
+ private final Integer handledQuantity;
+ private final Integer photosQuantity;
+ private final Integer inventoryType;
+ private final String handlingStatus;
+ private final String handlingStatusName;
+ private final String primaryHandlingMethod;
+ private final String sourceNo;
+ private final String warehouseCode;
+ private final String errorStatus;
+ private final String errorMessage;
+ private final List photoUrls;
+ private final List handledPhotoUrls;
+ private final Instant createdAt;
+ private final Instant updatedAt;
+ private final Instant completedAt;
+ private final WarehouseProvider sourceProvider;
+
+ private ReturnHandle(Builder b) {
+ if (b.returnPlanNo == null || b.returnPlanNo.trim().isEmpty()) {
+ throw new IllegalArgumentException("returnPlanNo must not be blank");
+ }
+ this.returnPlanNo = b.returnPlanNo.trim();
+ this.returnHandleNo = b.returnHandleNo;
+ this.returnNo = b.returnNo;
+ this.trackingNumber = b.trackingNumber;
+ this.providerSku = b.providerSku;
+ this.changeSku = b.changeSku;
+ this.quantity = b.quantity;
+ this.handledQuantity = b.handledQuantity;
+ this.photosQuantity = b.photosQuantity;
+ this.inventoryType = b.inventoryType;
+ this.handlingStatus = b.handlingStatus;
+ this.handlingStatusName = b.handlingStatusName;
+ this.primaryHandlingMethod = b.primaryHandlingMethod;
+ this.sourceNo = b.sourceNo;
+ this.warehouseCode = b.warehouseCode;
+ this.errorStatus = b.errorStatus;
+ this.errorMessage = b.errorMessage;
+ this.photoUrls = java.util.Collections.unmodifiableList(
+ new java.util.ArrayList(b.photoUrls));
+ this.handledPhotoUrls = java.util.Collections.unmodifiableList(
+ new java.util.ArrayList(b.handledPhotoUrls));
+ this.createdAt = b.createdAt;
+ this.updatedAt = b.updatedAt;
+ this.completedAt = b.completedAt;
+ this.sourceProvider = b.sourceProvider;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 退货计划单号;必填。 */
+ public String returnPlanNo() {
+ return returnPlanNo;
+ }
+
+ /** 仓侧处理单号(恒健 {@code returnPlanHandleItemsNo})。 */
+ public String returnHandleNo() {
+ return returnHandleNo;
+ }
+
+ /** 退货编码;部分仓单独给一个(恒健「退货编码」)。 */
+ public String returnNo() {
+ return returnNo;
+ }
+
+ /** tracking 号。 */
+ public String trackingNumber() {
+ return trackingNumber;
+ }
+
+ /** 仓侧 SKU。 */
+ public String providerSku() {
+ return providerSku;
+ }
+
+ /** 换标后的 SKU;非换标为 null。 */
+ public String changeSku() {
+ return changeSku;
+ }
+
+ public Integer quantity() {
+ return quantity;
+ }
+
+ /** 已处理数量;未给为 null。 */
+ public Integer handledQuantity() {
+ return handledQuantity;
+ }
+
+ /** 已拍照片数量;未给为 null。 */
+ public Integer photosQuantity() {
+ return photosQuantity;
+ }
+
+ /** 库存类型:0 可售 / 1 不可售;未给为 null。 */
+ public Integer inventoryType() {
+ return inventoryType;
+ }
+
+ /** 处理状态原值。 */
+ public String handlingStatus() {
+ return handlingStatus;
+ }
+
+ /** 处理状态中文名;仓方未给为 null。 */
+ public String handlingStatusName() {
+ return handlingStatusName;
+ }
+
+ /** 主要处理方式原值(仓方码,如恒健 101~206)。 */
+ public String primaryHandlingMethod() {
+ return primaryHandlingMethod;
+ }
+
+ /** 来源单号。 */
+ public String sourceNo() {
+ return sourceNo;
+ }
+
+ public String warehouseCode() {
+ return warehouseCode;
+ }
+
+ /** 异常码原值;无异常为 null。 */
+ public String errorStatus() {
+ return errorStatus;
+ }
+
+ public String errorMessage() {
+ return errorMessage;
+ }
+
+ /** 照片 URL;不可变。 */
+ public List photoUrls() {
+ return photoUrls;
+ }
+
+ /** 处理后照片 URL;不可变。 */
+ public List handledPhotoUrls() {
+ return handledPhotoUrls;
+ }
+
+ public Instant createdAt() {
+ return createdAt;
+ }
+
+ public Instant updatedAt() {
+ return updatedAt;
+ }
+
+ public Instant completedAt() {
+ return completedAt;
+ }
+
+ public WarehouseProvider sourceProvider() {
+ return sourceProvider;
+ }
+
+ public static final class Builder {
+ private String returnPlanNo;
+ private String returnHandleNo;
+ private String returnNo;
+ private String trackingNumber;
+ private String providerSku;
+ private String changeSku;
+ private Integer quantity;
+ private Integer handledQuantity;
+ private Integer photosQuantity;
+ private Integer inventoryType;
+ private String handlingStatus;
+ private String handlingStatusName;
+ private String primaryHandlingMethod;
+ private String sourceNo;
+ private String warehouseCode;
+ private String errorStatus;
+ private String errorMessage;
+ private final List photoUrls = new java.util.ArrayList();
+ private final List handledPhotoUrls = new java.util.ArrayList();
+ private Instant createdAt;
+ private Instant updatedAt;
+ private Instant completedAt;
+ private WarehouseProvider sourceProvider;
+
+ public Builder returnPlanNo(String v) {
+ this.returnPlanNo = v;
+ return this;
+ }
+
+ public Builder returnHandleNo(String v) {
+ this.returnHandleNo = v;
+ return this;
+ }
+
+ public Builder returnNo(String v) {
+ this.returnNo = v;
+ return this;
+ }
+
+ public Builder trackingNumber(String v) {
+ this.trackingNumber = v;
+ return this;
+ }
+
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ public Builder changeSku(String v) {
+ this.changeSku = v;
+ return this;
+ }
+
+ public Builder quantity(Integer v) {
+ this.quantity = v;
+ return this;
+ }
+
+ public Builder handledQuantity(Integer v) {
+ this.handledQuantity = v;
+ return this;
+ }
+
+ public Builder photosQuantity(Integer v) {
+ this.photosQuantity = v;
+ return this;
+ }
+
+ public Builder inventoryType(Integer v) {
+ this.inventoryType = v;
+ return this;
+ }
+
+ public Builder handlingStatus(String v) {
+ this.handlingStatus = v;
+ return this;
+ }
+
+ public Builder handlingStatusName(String v) {
+ this.handlingStatusName = v;
+ return this;
+ }
+
+ public Builder primaryHandlingMethod(String v) {
+ this.primaryHandlingMethod = v;
+ return this;
+ }
+
+ public Builder sourceNo(String v) {
+ this.sourceNo = v;
+ return this;
+ }
+
+ public Builder warehouseCode(String v) {
+ this.warehouseCode = v;
+ return this;
+ }
+
+ public Builder errorStatus(String v) {
+ this.errorStatus = v;
+ return this;
+ }
+
+ public Builder errorMessage(String v) {
+ this.errorMessage = v;
+ return this;
+ }
+
+ public Builder photoUrl(String v) {
+ if (v != null && !v.trim().isEmpty()) {
+ this.photoUrls.add(v.trim());
+ }
+ return this;
+ }
+
+ public Builder handledPhotoUrl(String v) {
+ if (v != null && !v.trim().isEmpty()) {
+ this.handledPhotoUrls.add(v.trim());
+ }
+ return this;
+ }
+
+ public Builder createdAt(Instant v) {
+ this.createdAt = v;
+ return this;
+ }
+
+ public Builder updatedAt(Instant v) {
+ this.updatedAt = v;
+ return this;
+ }
+
+ public Builder completedAt(Instant v) {
+ this.completedAt = v;
+ return this;
+ }
+
+ public Builder sourceProvider(WarehouseProvider v) {
+ this.sourceProvider = v;
+ return this;
+ }
+
+ public ReturnHandle build() {
+ return new ReturnHandle(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 5a33493..cdd0200 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
@@ -40,6 +40,8 @@ import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
+import common.ecommerce.warehouse.model.ProductInfo;
+import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.LabelPrintTask;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.ReturnCommand;
@@ -96,19 +98,20 @@ public final class WarehouseOperations {
}
/**
- * 分页查商品。只读,不走幂等。
+ * 批量 / 分页查询仓侧商品资料。只读,不走幂等。
*
- * 与 {@link #createProduct} 相对:那个写,这个读。
+ * 查询入参的 {@code providerSkus} 是仓侧 SKU(建档时下发的那串)。
+ * SDK 不做 OMS→仓侧 SKU 转换。
*/
- public common.ecommerce.shared.support.Page<
- common.ecommerce.warehouse.capability.WarehouseProduct> queryProducts(
- final common.ecommerce.warehouse.model.ProductQuery query) {
+ public Page queryProducts(ProductQuery query) {
require(WarehouseCapability.PRODUCT, WarehouseProductCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.product.query",
CallSupport.params("skuCount", query.providerSkus().size(),
- "pageSize", query.pageSize(), "cursor", query.cursor()),
+ "barcode", query.barcode(),
+ "hasCreatedRange", query.hasCreatedRange(),
+ "cursor", query.cursor()),
p -> p.size(),
- () -> ((WarehouseProductCapable) adapter).queryProducts(ctx, query));
+ () -> ((WarehouseProductCapable) adapter).query(ctx, query));
}
/**
@@ -460,7 +463,10 @@ public final class WarehouseOperations {
/** 本仓默认的库存同步策略。 */
public InventorySyncStrategy inventorySyncStrategy() {
require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class);
- return ((InventoryCapable) adapter).syncStrategy();
+ return CallSupport.observe(observer, ctx, "warehouse.inventory.syncStrategy",
+ CallSupport.params(),
+ r -> CallSupport.NO_COUNT,
+ () -> ((InventoryCapable) adapter).syncStrategy());
}
private void require(WarehouseCapability cap, Class> type) {
@@ -534,16 +540,21 @@ public final class WarehouseOperations {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final InboundCapable capable = (InboundCapable) adapter;
- common.ecommerce.shared.idempotency.WriteResult result =
- guard.execute(
- WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
- cmd.inboundRequestNo(), "create"),
- () -> capable.create(ctx, cmd),
- receipt -> receipt.providerInboundId());
- if (result.alreadyCompleted()) {
- return InboundReceipt.of(cmd.inboundRequestNo(), result.resultRef());
- }
- return result.value();
+ return CallSupport.observe(observer, ctx, "warehouse.inbound.create",
+ CallSupport.params("inboundRequestNo", cmd.inboundRequestNo()),
+ r -> CallSupport.NO_COUNT,
+ () -> {
+ common.ecommerce.shared.idempotency.WriteResult result =
+ guard.execute(
+ WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
+ cmd.inboundRequestNo(), "create"),
+ () -> capable.create(ctx, cmd),
+ receipt -> receipt.providerInboundId());
+ if (result.alreadyCompleted()) {
+ return InboundReceipt.of(cmd.inboundRequestNo(), result.resultRef());
+ }
+ return result.value();
+ });
}
/** 查入库单。 */
@@ -631,7 +642,10 @@ public final class WarehouseOperations {
/** BOL 文档。 */
public List bols(String inboundRef) {
require(WarehouseCapability.INBOUND, InboundCapable.class);
- return ((InboundCapable) adapter).bols(ctx, inboundRef);
+ return CallSupport.observe(observer, ctx, "warehouse.inbound.bols",
+ CallSupport.params("inboundRef", inboundRef),
+ List::size,
+ () -> ((InboundCapable) adapter).bols(ctx, inboundRef));
}
/**
@@ -683,20 +697,25 @@ public final class WarehouseOperations {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final WarehouseReturnCapable capable = (WarehouseReturnCapable) adapter;
- common.ecommerce.shared.idempotency.WriteResult result =
- guard.execute(
- WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
- cmd.returnRequestNo(), "create"),
- () -> capable.create(ctx, cmd),
- ret -> ret.providerReturnId());
- if (result.alreadyCompleted()) {
- return WarehouseReturn.builder()
- .returnRequestNo(cmd.returnRequestNo())
- .providerReturnId(result.resultRef())
- .warehouseCode(account.warehouseCode())
- .build();
- }
- return result.value();
+ return CallSupport.observe(observer, ctx, "warehouse.return.create",
+ CallSupport.params("returnRequestNo", cmd.returnRequestNo()),
+ r -> CallSupport.NO_COUNT,
+ () -> {
+ common.ecommerce.shared.idempotency.WriteResult result =
+ guard.execute(
+ WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
+ cmd.returnRequestNo(), "create"),
+ () -> capable.create(ctx, cmd),
+ ret -> ret.providerReturnId());
+ if (result.alreadyCompleted()) {
+ return WarehouseReturn.builder()
+ .returnRequestNo(cmd.returnRequestNo())
+ .providerReturnId(result.resultRef())
+ .warehouseCode(account.warehouseCode())
+ .build();
+ }
+ return result.value();
+ });
}
public WarehouseReturn get(String returnRequestNo) {
@@ -725,6 +744,22 @@ public final class WarehouseOperations {
}
/**
+ * 分页查退货处理单。只读,不走幂等。
+ *
+ * 与 {@link #query(ReturnQuery)} 的区别:那个查一张退货计划,
+ * 这个查计划下每一行 SKU 的待处理记录。填处理方式要用的四项定位就在结果里。
+ */
+ public Page queryHandles(ReturnQuery query) {
+ require(WarehouseCapability.RETURN, WarehouseReturnCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.return.queryHandles",
+ CallSupport.params("cursor", query.cursor(),
+ "orderNo", query.orderNo(),
+ "warehouseCode", query.warehouseCode()),
+ p -> p.size(),
+ () -> ((WarehouseReturnCapable) adapter).queryHandles(ctx, query));
+ }
+
+ /**
* 按明细行设置检验后处理方式。写操作:强制经幂等守卫,幂等键
* {@code warehouseCode + providerReturnNo + lineId + process}。
*
@@ -765,12 +800,17 @@ public final class WarehouseOperations {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final WarehouseReturnCapable capable = (WarehouseReturnCapable) adapter;
- common.ecommerce.shared.idempotency.WriteResult result = guard.execute(
- WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
- providerReturnNo, "cancel"),
- () -> capable.cancel(ctx, providerReturnNo),
- ok -> Boolean.TRUE.equals(ok) ? "true" : null);
- return result.alreadyCompleted() || Boolean.TRUE.equals(result.value());
+ return CallSupport.observe(observer, ctx, "warehouse.return.cancel",
+ CallSupport.params("providerReturnNo", providerReturnNo),
+ r -> CallSupport.NO_COUNT,
+ () -> {
+ common.ecommerce.shared.idempotency.WriteResult result = guard.execute(
+ WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
+ providerReturnNo, "cancel"),
+ () -> capable.cancel(ctx, providerReturnNo),
+ ok -> Boolean.TRUE.equals(ok) ? "true" : null);
+ return result.alreadyCompleted() || Boolean.TRUE.equals(result.value());
+ });
}
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java
index 903cbf9..73d97d3 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java
@@ -57,16 +57,26 @@ public final class WarehouseOutbounds {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final OutboundCapable capable = (OutboundCapable) adapter;
- WriteIdentity scope = WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
+ final WriteIdentity scope = WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
cmd.outboundRequestNo(), "create");
- common.ecommerce.shared.idempotency.WriteResult result =
- guard.execute(scope, () -> capable.create(ctx, cmd),
- receipt -> receipt.providerOrderId());
- if (result.alreadyCompleted()) {
- // 回放:本次没有调仓,只有上次记录的结果引用
- return OutboundReceipt.of(cmd.outboundRequestNo(), result.resultRef(), "ALREADY_COMPLETED");
- }
- return result.value();
+ // 写操作也要有一条门面级记录:幂等层只记 writes.create 的裁决,
+ // 不记「这次调了仓、成功还是失败」。缺了它,操作日志里就看不到下发动作。
+ return common.ecommerce.shared.audit.CallSupport.observe(observer, ctx,
+ "warehouse.outbound.create",
+ common.ecommerce.shared.audit.CallSupport.params(
+ "outboundRequestNo", cmd.outboundRequestNo()),
+ r -> common.ecommerce.shared.audit.CallSupport.NO_COUNT,
+ () -> {
+ common.ecommerce.shared.idempotency.WriteResult result =
+ guard.execute(scope, () -> capable.create(ctx, cmd),
+ receipt -> receipt.providerOrderId());
+ if (result.alreadyCompleted()) {
+ // 回放:本次没有调仓,只有上次记录的结果引用
+ return OutboundReceipt.of(cmd.outboundRequestNo(), result.resultRef(),
+ "ALREADY_COMPLETED");
+ }
+ return result.value();
+ });
}
/** 按仓单号或 OMS 单号查单。 */
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
index 80a1a2b..23e829f 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
@@ -36,6 +36,9 @@ public final class EdayunConstants {
/** 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。 */
public static final String PATH_PRODUCT_CREATE = "/webApi/skuInfo/v1/createProduct";
+ /** 批量查询产品分页({@code POST /webApi/skuInfo/v1/listProductPage})。 */
+ public static final String PATH_PRODUCT_LIST = "/webApi/skuInfo/v1/listProductPage";
+
/** 创建出库单({@code POST /webApi/order/v1/createOrder})。 */
public static final String PATH_ORDER_CREATE = "/webApi/order/v1/createOrder";
@@ -108,12 +111,12 @@ public final class EdayunConstants {
public static final String PATH_CASE_MARK_PRINT = "/webApi/skuInfo/v2/printBarcode";
/**
- * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
+ * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
*
* 端点名是 newPrintCaseMark,实际打的是 SKU 标——已与仓方确认。
*/
public static final String PATH_SKU_LABEL_PRINT =
- "/webApi/entryInfo/v1/newPrintCaseMarkContentType";
+ "/webApi/entryInfo/v1/newPrintCaseMark";
/** 查询客户自有物流服务(承运商)({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。 */
public static final String PATH_CARRIERS = "/webApi/carrier/v1/listCarrierByWarehouse";
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
index 37e2107..a08bf2a 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
@@ -18,6 +18,7 @@ import common.ecommerce.edayun.dto.EdayunInboundQueryDtos;
import common.ecommerce.edayun.dto.EdayunInventoryDtos;
import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos;
import common.ecommerce.edayun.dto.EdayunOrderCostDtos;
+import common.ecommerce.edayun.dto.EdayunProductQueryDtos;
import common.ecommerce.edayun.dto.EdayunRentDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
@@ -77,6 +78,8 @@ import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.PackageResult;
+import common.ecommerce.warehouse.model.ProductQuery;
+import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
@@ -98,8 +101,8 @@ import java.util.List;
/**
* 易达云适配器。
*
- * 已实现:商品建档、创建出库单。其余能力不声明,门面调用会显式抛
- * {@code WarehouseUnsupportedCapabilityException},不返回空集合。
+ * 已实现的能力见 {@link #capabilities()};没声明的能力门面会显式抛
+ * {@code WarehouseUnsupportedCapabilityException},不返回空集合。
*
* 适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。
@@ -213,6 +216,40 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
parsed.data == null ? null : parsed.data.skuId);
}
+ /**
+ * 批量查询仓侧商品资料({@code POST /webApi/skuInfo/v1/listProductPage})。
+ *
+ * 入参 SKU 是仓侧 SKU,即建档时下发到 {@code skuCode} 字段的那串
+ * ({@link EdayunProductMapper} 的 {@code skuOf}),不一定等于 OMS SKU。
+ * 易达云的 {@code skuCode} 是逗号拼接的
+ * 单个字符串且一次最多 50 个,超了本地拒绝(不截断)。
+ * 审核时间窗统一模型没有对应字段,不传。
+ *
+ * 查询条件全空时仓方默认按创建时间查最近一个月——这一点由仓方兜底,
+ * 本地不补默认值。
+ */
+ @Override
+ public Page query(WarehouseContext ctx, ProductQuery query) {
+ int pageNum = EdayunProductQueryMapper.pageNumber(query.cursor());
+ EdayunProductQueryDtos.ListProductRequest body =
+ EdayunProductQueryMapper.toRequest(query, ctx.zone(), pageNum);
+ String bodyJson = json.toJson(body);
+
+ HttpResponse resp = send(ctx, EdayunConstants.PATH_PRODUCT_LIST, bodyJson,
+ "warehouse.product.query");
+ EdayunProductQueryDtos.ListProductResponse parsed =
+ json.fromJson(resp.body(), EdayunProductQueryDtos.ListProductResponse.class);
+ // 「查询无数据」是空结果,不是失败——易达云对查不到的 SKU / 条码回 code=500,
+ // 但语义与「运单还没轨迹」同类。
+ if (parsed != null && isNoData(parsed.msg)) {
+ return Page.empty();
+ }
+ requireSuccess(ctx, parsed == null ? null : parsed.code,
+ parsed == null ? null : parsed.msg, resp, "warehouse.product.query");
+
+ return EdayunProductQueryMapper.toPage(parsed, pageNum, body.pageSize);
+ }
+
// ------------------------------------------------------------------ 出库
/**
@@ -905,7 +942,9 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
// 统一模型不区分业务类型,默认查「店铺订单」(1);
// 不传反而返回全账号的产品,量太大
EdayunLogisticsProductDtos.ListProductRequest body = EdayunLogisticsProductMapper.toRequest(
- ctx.providerWarehouseId(), APPLICABLE_BUSINESS_STORE_ORDER);
+ EdayunLogisticsProductMapper.resolveWarehouseId(
+ warehouseCode, ctx.providerWarehouseId()),
+ APPLICABLE_BUSINESS_STORE_ORDER);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_LOGISTICS_PRODUCTS, bodyJson,
@@ -962,7 +1001,7 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
HttpResponse resp = send(ctx, EdayunConstants.PATH_TRACK, bodyJson, operation);
EdayunTrackDtos.GetTrackResponse parsed =
json.fromJson(resp.body(), EdayunTrackDtos.GetTrackResponse.class);
- if (parsed != null && isNoTrackFound(parsed.msg)) {
+ if (parsed != null && isNoData(parsed.msg)) {
return null;
}
requireSuccess(ctx, parsed == null ? null : parsed.code,
@@ -971,9 +1010,10 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
return EdayunTrackMapper.find(parsed, trackingNumber);
}
- /** 仓方「没有轨迹」的提示语。 */
- private static boolean isNoTrackFound(String msg) {
- return msg != null && (msg.contains("未匹配到轨迹") || msg.contains("跟踪号为空"));
+ /** 仓方「没有数据」的提示语:查不到不等于调用失败。 */
+ private static boolean isNoData(String msg) {
+ return msg != null && (msg.contains("查询无数据") || msg.contains("未匹配到轨迹")
+ || msg.contains("跟踪号为空"));
}
// ------------------------------------------------------------------ 条码打印
@@ -1023,7 +1063,7 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
// ------------------------------------------------------------------ SKU 标
/**
- * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
+ * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
*
* 端点名叫 newPrintCaseMark,但实际打的是 SKU 标——已与仓方确认。
* 箱唛走 {@code printCaseMarks}(端点 {@code printBarcode})。
@@ -1031,12 +1071,13 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
* 统一模型的 {@code BoxLabelCommand} 没有「选哪些箱」的字段,
* 所以默认整单打印;要打部分箱用重载。
*
- * 真机未验证:PR 环境该接口返回「接口不存在或未启用」,
- * 换到 {@code /newPrintCaseMark}(无 ContentType 后缀)能过参数校验
- * (缺 pageSize 报「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」),
- * 但补全后一律「内部服务器错误」。见 docs-warehouse/edayun/TODO.md。
+ * 刻意不是 public、也没声明 {@code SKU_LABEL} 能力位:该接口在 PR 环境
+ * 参数齐全后一律「内部服务器错误」(路径已确认存在,缺参数有中文校验提示),
+ * 属于仓方服务端异常。放成 public 会让调用方以为门面够得到,实际门面按
+ * {@code SKU_LABEL} 门控、会直接抛不支持。等仓方修复后再提升可见性并声明能力位。
+ * 见 docs-warehouse/edayun/TODO.md #68。
*/
- public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) {
+ WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) {
EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd);
return sendSkuLabel(ctx, body);
}
@@ -1046,8 +1087,8 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
*
* @param selection 选箱条件;四选一,全空时本地拒绝
*/
- public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd,
- EdayunSkuLabelMapper.CaseSelection selection) {
+ WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd,
+ EdayunSkuLabelMapper.CaseSelection selection) {
EdayunSkuLabelDtos.PrintSkuLabelRequest body =
EdayunSkuLabelMapper.toRequest(cmd, selection);
return sendSkuLabel(ctx, body);
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java
index 7156fa4..092cff6 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java
@@ -8,7 +8,6 @@ import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
-import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory;
/**
* 易达云适配器工厂。
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java
index 2319de1..753d3e6 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java
@@ -36,6 +36,26 @@ public final class EdayunLogisticsProductMapper {
return req;
}
+ /**
+ * 解析仓方仓 id:显式指定的 {@code warehouseCode} 优先,否则用账户配置的。
+ *
+ * 两者都必须是易达云的数字仓 id——统一模型叫 {@code warehouseCode}
+ * 但易达云这个接口只认数字 id。给了非数字就本地拒绝,避免静默退回账户仓
+ * (那样调用方以为按自己的仓查了,实际不是)。
+ */
+ static String resolveWarehouseId(String warehouseCode, String providerWarehouseId) {
+ String explicit = warehouseCode == null ? null : warehouseCode.trim();
+ if (explicit != null && !explicit.isEmpty()) {
+ if (warehouseIdOf(explicit) == null) {
+ throw new IllegalArgumentException(
+ "edayun logistics products need a numeric warehouse id, got: " + explicit
+ + " (the unified warehouseCode must carry edayun's numeric id here)");
+ }
+ return explicit;
+ }
+ return providerWarehouseId;
+ }
+
/** 响应 → 统一产品清单;跳过 {@code -998} 与无效行。 */
public static List toProducts(
List rows, String warehouseCode) {
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java
index 635da78..49a0416 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java
@@ -163,6 +163,8 @@ public final class EdayunOrderMapper {
for (OutboundLine line : lines) {
EdayunCreateOrderDtos.CreateOrderRequest.ProductItem item =
new EdayunCreateOrderDtos.CreateOrderRequest.ProductItem();
+ // 必须与建档时下发的 skuCode 一致(providerSku 优先,见 EdayunProductMapper.skuOf)。
+ // 传 OMS SKU 而建档时用的是 providerSku 的话,仓方会报 SKU 不存在。
item.productSku = firstNonBlank(line.providerSku(), line.omsSku());
item.quantity = line.quantity();
Money value = line.declareValue();
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java
index 7a19a29..d93d645 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java
@@ -128,6 +128,26 @@ public final class EdayunProductMapper {
return d;
}
+ /**
+ * 下发到易达云 {@code skuCode} 字段的值——整条链路都以这个为准。
+ *
+ * 规则:{@code providerSku} 优先,为空才回退 {@code omsSku}。
+ *
+ * 为什么这条规则要写在建档这里:易达云把 {@code skuCode} 当唯一键落库,
+ * 之后查商品({@code listProductPage} 的 {@code skuCode})、建出库单
+ * (商品行 {@code productSku})、查库存({@code skuCodeList})全都按这串匹配。
+ * 所以:
+ *
+ * - 宿主给了 {@code providerSku} → 仓方库里存它,之后所有查询 / 下单都必须传它,
+ * 不等于 OMS SKU
+ * - 宿主没给(如 {@code ybtest})→ 仓方库里存的就是 OMS SKU,两者同名
+ *
+ *
+ * SDK 不做 OMS→仓侧 SKU 的转换:映射表在宿主手里(供应商编码规则、
+ * 按仓不同的前缀),SDK 猜不出来;静默转换会拿回空结果或错商品,比报错更难发现。
+ *
+ * 出库行同理,见 {@code EdayunOrderMapper}({@code firstNonBlank(providerSku, omsSku)})。
+ */
private static String skuOf(WarehouseProduct product) {
String sku = product.providerSku();
return sku != null && !sku.trim().isEmpty() ? sku.trim() : product.omsSku();
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java
new file mode 100644
index 0000000..64b7159
--- /dev/null
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java
@@ -0,0 +1,153 @@
+package common.ecommerce.edayun.adapter;
+
+import common.ecommerce.edayun.dto.EdayunProductQueryDtos;
+import common.ecommerce.shared.support.Page;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.ProductInfo;
+import common.ecommerce.warehouse.model.ProductQuery;
+
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 易达云商品查询映射({@code /webApi/skuInfo/v1/listProductPage})。
+ *
+ * SKU 过滤用逗号拼接的单个字符串({@code skuCode}),
+ * 且一次最多 50 个——与统一模型的 {@code providerSkus} 列表不同,这里要拼。
+ *
+ * 页码从 1 开始,单页最多 200。
+ */
+public final class EdayunProductQueryMapper {
+
+ static final int MAX_PAGE_SIZE = 200;
+ /** skuCode 一次最多查多少个(文档:50)。 */
+ static final int MAX_SKUS = 50;
+
+ private EdayunProductQueryMapper() {
+ }
+
+ /**
+ * 统一查询条件 → 仓方请求。
+ *
+ * @param zone 解释创建时间窗的时区(仓方口径)
+ */
+ public static EdayunProductQueryDtos.ListProductRequest toRequest(ProductQuery query,
+ ZoneId zone,
+ int pageNum) {
+ EdayunProductQueryDtos.ListProductRequest req =
+ new EdayunProductQueryDtos.ListProductRequest();
+ req.pageNum = pageNum;
+ req.pageSize = pageSize(query.pageSize());
+
+ if (!query.providerSkus().isEmpty()) {
+ if (query.providerSkus().size() > MAX_SKUS) {
+ throw new IllegalArgumentException(
+ "edayun product query accepts at most " + MAX_SKUS + " skus, got "
+ + query.providerSkus().size()
+ + "; split into multiple queries");
+ }
+ req.skuCode = String.join(",", query.providerSkus());
+ }
+ if (query.barcode() != null && !query.barcode().trim().isEmpty()) {
+ req.barcode = query.barcode().trim();
+ }
+ if (query.hasCreatedRange()) {
+ req.startCreateTime = query.createdAfter().toEpochMilli();
+ req.endCreateTime = query.createdBefore().toEpochMilli();
+ }
+ return req;
+ }
+
+ /** 每页条数:默认 100、上限 200。 */
+ static int pageSize(int requested) {
+ if (requested <= 0) {
+ return 100;
+ }
+ return Math.min(requested, MAX_PAGE_SIZE);
+ }
+
+ /** 游标是字符串化的页码(从 1 开始)。 */
+ static int pageNumber(String cursor) {
+ if (cursor == null || cursor.trim().isEmpty()) {
+ return 1;
+ }
+ try {
+ int v = Integer.parseInt(cursor.trim());
+ return v > 0 ? v : 1;
+ } catch (NumberFormatException e) {
+ return 1;
+ }
+ }
+
+ /** 响应 → 分页结果。 */
+ public static Page toPage(EdayunProductQueryDtos.ListProductResponse response,
+ int currentPage, int pageSize) {
+ if (response == null || response.rows == null || response.rows.isEmpty()) {
+ return Page.empty();
+ }
+ List out = new ArrayList(response.rows.size());
+ for (EdayunProductQueryDtos.ProductRow row : response.rows) {
+ ProductInfo info = toInfo(row);
+ if (info != null) {
+ out.add(info);
+ }
+ }
+ return Page.of(out, nextCursor(response.total, currentPage, pageSize, out.size()));
+ }
+
+ /** 有下一页时返回下一页页码;优先用 {@code total}(总行数)。 */
+ static String nextCursor(Long total, int currentPage, int pageSize, int fetched) {
+ boolean more = total != null
+ ? (long) currentPage * pageSize < total
+ : fetched >= pageSize;
+ return more ? String.valueOf(currentPage + 1) : null;
+ }
+
+ /**
+ * 一行 → 统一商品资料。
+ *
+ * 尺寸取实际({@code length/width/height/weight}),缺失才回落
+ * 预报值({@code forecast*})——查询商品资料的目的就是拿到仓方当前存的值。
+ */
+ static ProductInfo toInfo(EdayunProductQueryDtos.ProductRow row) {
+ if (row == null || row.skuCode == null || row.skuCode.trim().isEmpty()) {
+ return null;
+ }
+ ProductInfo.Builder b = ProductInfo.builder()
+ .sourceProvider(WarehouseProvider.EDAYUN)
+ .providerSku(row.skuCode.trim())
+ .providerProductId(trimToNull(row.skuId))
+ .barcode(trimToNull(row.barcode))
+ .name(trimToNull(row.skuName))
+ .nameEn(trimToNull(row.skuNameEn))
+ .lengthCm(numberOf(row.length, row.forecastLength))
+ .widthCm(numberOf(row.width, row.forecastWidth))
+ .heightCm(numberOf(row.height, row.forecastHeight))
+ .weightGrams(numberOf(row.weight, row.forecastWeight))
+ .remark(trimToNull(row.remark))
+ .createdAt(instantOf(row.createTime));
+ b.extraBarcode(row.extraBarcode1);
+ b.extraBarcode(row.extraBarcode2);
+ b.extraBarcode(row.extraBarcode3);
+ return b.build();
+ }
+
+ /** 优先实际值,缺失回落预报值;都缺为 0。 */
+ private static double numberOf(Double actual, Double forecast) {
+ if (actual != null) {
+ return actual;
+ }
+ return forecast == null ? 0 : forecast;
+ }
+
+ private static Instant instantOf(Long millis) {
+ return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis);
+ }
+
+ private static String trimToNull(String v) {
+ return v == null || v.trim().isEmpty() ? null : v.trim();
+ }
+}
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java
index 9c420fc..49844e7 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java
@@ -56,8 +56,10 @@ public final class EdayunReturnDetailMapper {
.returnRequestNo(basic == null ? trimToNull(requestedRmaCode)
: firstNonBlank(basic.relationNo, basic.rmaCode, requestedRmaCode))
.providerReturnId(basic == null ? trimToNull(requestedRmaCode) : basic.rmaCode)
- .warehouseCode(firstNonBlank(
- basic == null ? null : basic.warehouseName, warehouseCode))
+ // 响应只有仓名(美西1仓)与数字 id,没有仓编码。
+ // warehouseCode 这一列必须放「编码」,不能退化成展示名——
+ // 宿主会拿它做 equals / 回传查询,放中文名会全线失效。
+ .warehouseCode(trimToNull(warehouseCode))
.orderRef(basic == null ? null : basic.relationNo)
.type(basic == null ? null : basic.returnTypeName)
.status(EdayunRmaStatus.toCore(
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java
index 168556a..0883904 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java
@@ -46,6 +46,8 @@ public final class EdayunReturnMapper {
*/
public static EdayunReturnDtos.SaveReturnRequest toRequest(ReturnCommand cmd,
String providerWarehouseId) {
+ requireHonorable(cmd);
+
EdayunReturnDtos.SaveReturnRequest req = new EdayunReturnDtos.SaveReturnRequest();
req.returnType = RETURN_TYPE_SELF_SHIP;
@@ -62,6 +64,35 @@ public final class EdayunReturnMapper {
}
/**
+ * 本适配器不支持的命令字段在本地拒绝,不静默丢弃。
+ *
+ * 静默丢弃的后果是调用方以为条件生效了,实际没有。三个字段的情况:
+ *
+ * - {@code lineName}(项目):易达云退货单没有项目概念
+ * - {@code estimatedReceiveDate}:易达云按关联单号推,不接受预计到仓日
+ * - {@code returnReason}:易达云要 Integer 字典码({@code wms_rma_return_reason}),
+ * 统一模型给的是自由文本,对不上——见 TODO
+ *
+ */
+ private static void requireHonorable(ReturnCommand cmd) {
+ if (hasText(cmd.lineName())) {
+ throw new IllegalArgumentException(
+ "edayun return create does not support lineName (project): " + cmd.lineName());
+ }
+ if (cmd.estimatedReceiveDate() != null) {
+ throw new IllegalArgumentException(
+ "edayun return create does not support estimatedReceiveDate: "
+ + cmd.estimatedReceiveDate());
+ }
+ if (hasText(cmd.returnReason())) {
+ throw new IllegalArgumentException(
+ "edayun return create needs a numeric returnReason dictionary code"
+ + " (wms_rma_return_reason), got free text: " + cmd.returnReason()
+ + "; vendor dictionary mapping not implemented yet");
+ }
+ }
+
+ /**
* 仓:{@code warehouseId} 数字优先,否则 {@code warehouseCode}。
*
* 命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。
@@ -134,6 +165,10 @@ public final class EdayunReturnMapper {
}
}
+ private static boolean hasText(String v) {
+ return v != null && !v.trim().isEmpty();
+ }
+
private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) {
return a.trim();
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java
index 235181e..df9f963 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java
@@ -64,12 +64,7 @@ public final class EdayunRmaListMapper {
req.trackingNos = query.trackingNo().trim();
}
- Long warehouseId = warehouseIdOf(providerWarehouseId);
- if (warehouseId != null) {
- req.warehouseId = warehouseId;
- } else if (hasText(query.warehouseCode())) {
- req.warehouseCode = query.warehouseCode().trim();
- }
+ applyWarehouseFilter(req, query, providerWarehouseId);
if (hasText(query.providerSku())) {
req.skuCode = query.providerSku().trim();
@@ -87,6 +82,32 @@ public final class EdayunRmaListMapper {
}
/**
+ * 仓过滤:账户仓 id 与调用方给的仓编码只能二选一。
+ *
+ * 易达云文档写明「{@code warehouseCode}(优先使用仓库 id)」,两者同时给时
+ * 仓方会忽略编码。若调用方显式指定了另一个仓编码,静默按账户仓查会把
+ * 过滤条件丢掉、结果反而变宽——这种冲突在本地拒绝,不猜。
+ */
+ private static void applyWarehouseFilter(EdayunRmaListDtos.SelectRmaListRequest req,
+ ReturnQuery query, String providerWarehouseId) {
+ Long warehouseId = warehouseIdOf(providerWarehouseId);
+ String requested = hasText(query.warehouseCode()) ? query.warehouseCode().trim() : null;
+
+ if (warehouseId != null) {
+ if (requested != null && !requested.equals(String.valueOf(warehouseId))) {
+ throw new IllegalArgumentException(
+ "edayun return list cannot filter by warehouseCode '" + requested
+ + "' while the account is bound to numeric warehouse id "
+ + warehouseId + "; the vendor would ignore warehouseCode"
+ + " and query the account warehouse instead");
+ }
+ req.warehouseId = warehouseId;
+ return;
+ }
+ req.warehouseCode = requested;
+ }
+
+ /**
* 单号类型 → 易达云 {@code orderNoSearchType}。
*
* null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。
@@ -153,9 +174,10 @@ public final class EdayunRmaListMapper {
// 列表没有来源单号字段,用 RMA 号兜底;orderRef 用平台 / 出库单号
.returnRequestNo(firstNonBlank(row.rmaCode, row.ordOrderCode))
.providerReturnId(row.rmaCode)
- // 文档响应示例没有 warehouseCode,但真机会返回,优先用它
- .warehouseCode(firstNonBlank(row.warehouseCode, row.warehouseName,
- fallbackWarehouseCode))
+ // 列表有 warehouseCode(真机返回,文档示例里没有)就直接用;
+ // **不能退化成 warehouseName**——那是展示名(美西1仓),
+ // 宿主拿 warehouseCode 做 equals / 回传查询会全线失效。
+ .warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode))
.orderRef(firstNonBlank(row.platformOrderCode, row.ordOrderCode))
.type(row.returnTypeName)
.status(EdayunRmaStatus.toCore(row.status, row.statusName))
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java
index 23631ad..569fc9d 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java
@@ -8,7 +8,7 @@ import common.ecommerce.warehouse.model.WarehouseLabel;
import java.util.List;
/**
- * 易达云 SKU 标映射({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
+ * 易达云 SKU 标映射({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
*
* 统一模型只能表达「整单打印」:{@code BoxLabelCommand} 没有「选哪些箱」
* 的字段,所以选箱条件(系统箱号列表 / SKU / 箱序号区间 / 客户箱号区间)
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
index 5726b17..e753c08 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
@@ -66,7 +66,9 @@ public final class EdayunTrackMapper {
.carrier(track.carrierName)
// 仓方状态是数字码,码表没给;保留原值而不是猜成某个字符串
.status(track.status == null ? null : String.valueOf(track.status))
- .signedBy(track.receiver)
+ // track.receiver 是「收件人」,不是「签收人」——在途就有值。
+ // signedBy 的约定是「未签收为 null」,映射它会让每个在途包裹都被
+ // 判成已签收。易达云响应里没有签收人字段,宁可不填。
.firstOnlineAt(parseLocal(track.onlineTime, zone))
.deliveredAt(parseLocal(track.deliveredTime, zone));
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java
new file mode 100644
index 0000000..d67295f
--- /dev/null
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java
@@ -0,0 +1,96 @@
+package common.ecommerce.edayun.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+import java.util.List;
+
+/**
+ * 易达云报文结构:批量查询产品分页
+ * ({@code POST /webApi/skuInfo/v1/listProductPage})。
+ *
+ *
一个文件对应一个接口。查询条件全空时仓方默认按创建时间查最近一个月,
+ * 页码从 1 开始,单页最多 200 条。
+ */
+public final class EdayunProductQueryDtos {
+
+ private EdayunProductQueryDtos() {
+ }
+
+ /** 查询请求。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class ListProductRequest {
+ /** 产品状态:0 草稿 / 1 已发布。 */
+ public String status;
+ /** 每页条数,最多 200。 */
+ public Integer pageSize;
+ /** 页码,从 1 开始。 */
+ public Integer pageNum;
+
+ public String barcode;
+ /** SKU 编码,多个用英文逗号拼接,一次最多 50 个。 */
+ public String skuCode;
+ public String extraBarcode;
+ /** 中文品名。 */
+ public String skuName;
+
+ /** 创建时间窗(毫秒)。 */
+ public Long startCreateTime;
+ public Long endCreateTime;
+ /** 审核时间窗(毫秒)。 */
+ public Long startAuditTime;
+ public Long endAuditTime;
+ }
+
+ /** 查询响应。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class ListProductResponse {
+ public Long total;
+ public List rows;
+ public Integer code;
+ public String msg;
+ }
+
+ /** 一行商品。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class ProductRow {
+ /** 创建时间(毫秒)。 */
+ public Long createTime;
+ public String remark;
+ /** 仓方商品 id。 */
+ public String skuId;
+ public String skuCode;
+ /** 中文品名。 */
+ public String skuName;
+ public String skuNameEn;
+ public String barcode;
+ /** 外部条码 1/2/3。 */
+ public String extraBarcode1;
+ public String extraBarcode2;
+ public String extraBarcode3;
+
+ /** 预报尺寸(cm)与重量;量级像克。 */
+ public Double forecastLength;
+ public Double forecastWidth;
+ public Double forecastHeight;
+ public Double forecastWeight;
+
+ /** 实际尺寸(cm)与重量;量级像克。 */
+ public Double length;
+ public Double width;
+ public Double height;
+ public Double weight;
+
+ /** 带电标志:0 是 / 1 否(同其它接口的反向布尔)。 */
+ public Integer electricFlag;
+ public Integer electricType;
+ public Integer electricPackage;
+ public Integer electricPower;
+ public String electricUrl;
+
+ /** 商品图片。 */
+ public String skuUrl;
+ /** 品牌标志:0 是 / 1 否。 */
+ public Integer brandFlag;
+ public String brandName;
+ }
+}
diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java
index 64ffb89..2d92700 100644
--- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java
+++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java
@@ -6,7 +6,7 @@ import java.util.List;
/**
* 易达云报文结构:打印 SKU 标
- * ({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
+ * ({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
*
* 一个文件对应一个接口。响应 {@code data} 是PDF 地址字符串,同步生成。
*
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java
index 2080f8b..b471856 100644
--- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java
@@ -18,7 +18,6 @@ import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
-import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
@@ -150,11 +149,4 @@ class EdayunCarrierTest {
assertTrue(transport.lastDataRequest().body().contains("\"warehouseId\":2"));
}
- /** 仓库列表接口易达云没有,显式拒绝而不是空列表。 */
- @Test
- void warehousesAreUnsupported() {
- assertThrows(RuntimeException.class,
- () -> new EdayunAdapter(stub("{}"), new JacksonJsonCodec())
- .warehouses(ctx("2")));
- }
}
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java
index 1e33d4d..da18447 100644
--- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java
@@ -165,7 +165,8 @@ class EdayunInventoryTest {
/** 仓编码缺失时回退 OMS 仓编码,快照必须有 warehouseCode。 */
@Test
- void warehouseCodeFallsBack() { EdayunInventoryDtos.InventoryRow r = row();
+ void warehouseCodeFallsBack() {
+ EdayunInventoryDtos.InventoryRow r = row();
r.warehouseCode = null;
assertEquals("EDY-WH", EdayunInventoryMapper.toPage(
@@ -173,7 +174,8 @@ class EdayunInventoryTest {
.items().get(0).warehouseCode());
}
- /** 没有 SKU 的行跳过,不应让整页失败。 */ @Test
+ /** 没有 SKU 的行跳过,不应让整页失败。 */
+ @Test
void rowsWithoutSkuAreSkipped() {
EdayunInventoryDtos.InventoryRow dirty = row();
dirty.skuCode = " ";
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java
new file mode 100644
index 0000000..c82c702
--- /dev/null
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java
@@ -0,0 +1,215 @@
+package common.ecommerce.edayun.adapter;
+
+import common.ecommerce.edayun.dto.EdayunProductQueryDtos;
+import common.ecommerce.http.JacksonJsonCodec;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.support.Page;
+import common.ecommerce.shared.testkit.RecordingTransport;
+import common.ecommerce.shared.testkit.Responses;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.ProductInfo;
+import common.ecommerce.warehouse.model.ProductQuery;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.time.ZoneOffset;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 商品查询({@code /webApi/skuInfo/v1/listProductPage})映射。
+ *
+ * 重点:SKU 是逗号拼接的单个字符串、一次最多 50 个、页码从 1 开始、
+ * 实际尺寸优先于预报尺寸。
+ */
+class EdayunProductQueryTest {
+
+ private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC);
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, "2",
+ WarehouseConnection.of("https://test.example/openapi",
+ ChannelSecret.builder().appKey("k").appSecret("s")
+ .clientId("c").clientSecret("cs").build()),
+ "req-product-query", CLOCK);
+ }
+
+ private static RecordingTransport stub(String body) {
+ return RecordingTransport.create()
+ .route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
+ "{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
+ .route(common.ecommerce.edayun.EdayunConstants.PATH_PRODUCT_LIST,
+ req -> Responses.ok(body));
+ }
+
+ // ------------------------------------------------------------ 请求
+
+ /** SKU 列表要拼成逗号分隔的单个字符串。 */
+ @Test
+ void skusAreJoinedWithComma() {
+ EdayunProductQueryDtos.ListProductRequest req =
+ EdayunProductQueryMapper.toRequest(
+ ProductQuery.builder().providerSku("A").providerSku("B").build(),
+ ZoneOffset.UTC, 1);
+
+ assertEquals("A,B", req.skuCode);
+ }
+
+ /** 一次最多 50 个 SKU,超了本地拒绝(不截断)。 */
+ @Test
+ void moreThan50SkusRejected() {
+ ProductQuery.Builder b = ProductQuery.builder();
+ for (int i = 0; i < 51; i++) {
+ b.providerSku("SKU-" + i);
+ }
+
+ IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+ () -> EdayunProductQueryMapper.toRequest(b.build(), ZoneOffset.UTC, 1));
+
+ assertTrue(ex.getMessage().contains("at most 50"), ex.getMessage());
+ }
+
+ @Test
+ void pageSizeCappedAt200() {
+ assertEquals(200, EdayunProductQueryMapper.pageSize(1000));
+ assertEquals(100, EdayunProductQueryMapper.pageSize(0));
+ }
+
+ /** 页码从 1 开始。 */
+ @Test
+ void pageNumberStartsAtOne() {
+ assertEquals(1, EdayunProductQueryMapper.pageNumber(null));
+ assertEquals(1, EdayunProductQueryMapper.pageNumber("0"));
+ assertEquals(3, EdayunProductQueryMapper.pageNumber("3"));
+ }
+
+ /** 创建时间窗按毫秒下发;只给一端时不下发(避免半开区间语义不明)。 */
+ @Test
+ void createdRangeIsMillis() {
+ EdayunProductQueryDtos.ListProductRequest req = EdayunProductQueryMapper.toRequest(
+ ProductQuery.builder()
+ .createdAfter(Instant.parse("2026-01-01T00:00:00Z"))
+ .createdBefore(Instant.parse("2026-02-01T00:00:00Z"))
+ .build(), ZoneOffset.UTC, 1);
+
+ assertEquals(Long.valueOf(Instant.parse("2026-01-01T00:00:00Z").toEpochMilli()),
+ req.startCreateTime);
+ assertEquals(Long.valueOf(Instant.parse("2026-02-01T00:00:00Z").toEpochMilli()),
+ req.endCreateTime);
+
+ assertNull(EdayunProductQueryMapper.toRequest(
+ ProductQuery.builder().createdAfter(Instant.parse("2026-01-01T00:00:00Z")).build(),
+ ZoneOffset.UTC, 1).startCreateTime);
+ }
+
+ // ------------------------------------------------------------ 响应
+
+ private static EdayunProductQueryDtos.ProductRow row() {
+ EdayunProductQueryDtos.ProductRow r = new EdayunProductQueryDtos.ProductRow();
+ r.skuCode = "ybtest";
+ r.skuId = "1001";
+ r.skuName = "苹果14";
+ r.skuNameEn = "iphone14";
+ r.barcode = "N94902313123";
+ r.extraBarcode1 = "E1";
+ r.extraBarcode3 = "E3";
+ r.length = 12.0;
+ r.width = 11.0;
+ r.height = 10.0;
+ r.weight = 600.0;
+ r.forecastLength = 99.0;
+ r.createTime = 1745473090263L;
+ return r;
+ }
+
+ /** 实际尺寸优先于预报尺寸。 */
+ @Test
+ void actualSizeWinsOverForecast() {
+ ProductInfo info = EdayunProductQueryMapper.toInfo(row());
+
+ assertEquals(12.0, info.lengthCm());
+ assertEquals(11.0, info.widthCm());
+ assertEquals(600.0, info.weightGrams());
+ assertEquals("ybtest", info.providerSku());
+ assertEquals("1001", info.providerProductId());
+ assertEquals(2, info.extraBarcodes().size());
+ assertEquals(WarehouseProvider.EDAYUN, info.sourceProvider());
+ assertEquals(Instant.ofEpochMilli(1745473090263L), info.createdAt());
+ }
+
+ /** 实际尺寸缺失才回落预报值。 */
+ @Test
+ void fallsBackToForecastSize() {
+ EdayunProductQueryDtos.ProductRow r = row();
+ r.length = null;
+ r.weight = null;
+
+ ProductInfo info = EdayunProductQueryMapper.toInfo(r);
+
+ assertEquals(99.0, info.lengthCm());
+ assertEquals(0.0, info.weightGrams());
+ }
+
+ /** 没有 SKU 的行跳过。 */
+ @Test
+ void rowsWithoutSkuAreSkipped() {
+ EdayunProductQueryDtos.ProductRow bad = row();
+ bad.skuCode = " ";
+
+ assertNull(EdayunProductQueryMapper.toInfo(bad));
+ assertNull(EdayunProductQueryMapper.toInfo(null));
+ }
+
+ /** 「查询无数据」是空结果,不抛异常(同轨迹接口的处理)。 */
+ @Test
+ void noDataYieldsEmptyPage() {
+ RecordingTransport transport = stub(
+ "{\"total\":0,\"rows\":null,\"code\":500,\"msg\":\"查询无数据\"}");
+
+ Page page = new EdayunAdapter(transport, new JacksonJsonCodec())
+ .query(ctx(), ProductQuery.builder().providerSku("NOPE").build());
+
+ assertTrue(page.items().isEmpty());
+ assertTrue(!page.hasMore());
+ }
+
+ /** 其它业务错误仍然抛。 */
+ @Test
+ void otherBusinessErrorsStillThrow() {
+ RecordingTransport transport = stub("{\"code\":500,\"msg\":\"系统异常\"}");
+
+ assertThrows(RuntimeException.class,
+ () -> new EdayunAdapter(transport, new JacksonJsonCodec())
+ .query(ctx(), ProductQuery.builder().build()));
+ }
+
+ @Test
+ void nextCursorUsesTotal() {
+ assertEquals("2", EdayunProductQueryMapper.nextCursor(250L, 1, 100, 100));
+ assertNull(EdayunProductQueryMapper.nextCursor(250L, 3, 100, 50));
+ // total 缺失时按满页判断
+ assertEquals("2", EdayunProductQueryMapper.nextCursor(null, 1, 100, 100));
+ }
+
+ @Test
+ void adapterQueriesProducts() {
+ RecordingTransport transport = stub("{\"total\":1,\"code\":200,\"msg\":\"成功\",\"rows\":[{"
+ + "\"skuCode\":\"ybtest\",\"skuName\":\"苹果14\",\"length\":12,\"width\":11,"
+ + "\"height\":10,\"weight\":600,\"createTime\":1745473090263}]}");
+
+ Page page = new EdayunAdapter(transport, new JacksonJsonCodec())
+ .query(ctx(), ProductQuery.builder().providerSku("ybtest").build());
+
+ assertEquals(1, page.size());
+ assertEquals("ybtest", page.items().get(0).providerSku());
+ String body = transport.lastDataRequest().body();
+ assertTrue(body.contains("\"skuCode\":\"ybtest\""), body);
+ assertTrue(body.contains("\"pageNum\":1"), body);
+ }
+}
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java
index 19f5921..f81e129 100644
--- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java
@@ -84,6 +84,41 @@ class EdayunReturnTest {
EdayunReturnMapper.toRequest(cmd, "2").relationNo);
}
+ /** 易达云不接受的命令字段要在本地拒绝,不能静默丢弃。 */
+ @Test
+ void unsupportedCommandFieldsAreRejected() {
+ assertTrue(throwsOn(ReturnCommand.builder()
+ .returnRequestNo("RT-9").saleOrderNo("SO-1")
+ .returnTrackingNo("1Z1").carrierCode("UPS")
+ .lineName("默认项目")
+ .line("sku", 1, ReturnDealMethod.DESTROY).build())
+ .contains("lineName"));
+
+ assertTrue(throwsOn(ReturnCommand.builder()
+ .returnRequestNo("RT-9").saleOrderNo("SO-1")
+ .returnTrackingNo("1Z1").carrierCode("UPS")
+ .estimatedReceiveDate(java.time.LocalDate.of(2026, 12, 1))
+ .line("sku", 1, ReturnDealMethod.DESTROY).build())
+ .contains("estimatedReceiveDate"));
+
+ assertTrue(throwsOn(ReturnCommand.builder()
+ .returnRequestNo("RT-9").saleOrderNo("SO-1")
+ .returnTrackingNo("1Z1").carrierCode("UPS")
+ .returnReason("damaged")
+ .line("sku", 1, ReturnDealMethod.DESTROY).build())
+ .contains("returnReason"));
+ }
+
+ private static String throwsOn(ReturnCommand cmd) {
+ try {
+ EdayunReturnMapper.toRequest(cmd, "2");
+ org.junit.jupiter.api.Assertions.fail("should have thrown");
+ return "";
+ } catch (IllegalArgumentException e) {
+ return e.getMessage();
+ }
+ }
+
@Test
void nonNumericWarehouseGoesToWarehouseCode() {
ReturnCommand noWarehouse = ReturnCommand.builder()
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java
index 3496789..10cc8d6 100644
--- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java
@@ -102,6 +102,29 @@ class EdayunRmaListTest {
EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PLATFORM_ORDER_NO));
}
+ /**
+ * 账户绑了数字仓 id 时,调用方再传一个不同的仓编码要本地拒绝——
+ * 仓方会忽略 warehouseCode,静默按账户仓查会让结果反而变宽。
+ */
+ @Test
+ void conflictingWarehouseCodeIsRejected() {
+ IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+ () -> EdayunRmaListMapper.toRequest(
+ base().warehouseCode("USNY").build(), "2", ZoneOffset.UTC, 1));
+
+ assertTrue(ex.getMessage().contains("cannot filter by warehouseCode"), ex.getMessage());
+ }
+
+ /** 传的仓编码与账户仓 id 一致时放行。 */
+ @Test
+ void matchingWarehouseCodeIsAccepted() {
+ EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
+ base().warehouseCode("2").build(), "2", ZoneOffset.UTC, 1);
+
+ assertEquals(Long.valueOf(2L), req.warehouseId);
+ assertNull(req.warehouseCode);
+ }
+
@Test
void warehouseIdGoesNumeric() {
EdayunRmaListDtos.SelectRmaListRequest numeric =
@@ -155,6 +178,7 @@ class EdayunRmaListTest {
row.ordOrderCode = "ORD822935302";
row.trackingNo = "ORD822935302";
row.warehouseName = "美西1仓";
+ row.warehouseCode = "USLA";
row.warehouseId = 2L;
row.returnType = 0;
row.returnTypeName = "未妥投退回";
@@ -170,7 +194,8 @@ class EdayunRmaListTest {
assertEquals("RMA2411058099", ret.returnRequestNo());
assertEquals("RMA2411058099", ret.providerReturnId());
- assertEquals("美西1仓", ret.warehouseCode());
+ // warehouseCode 必须是仓编码,不能是展示名(美西1仓)
+ assertEquals("USLA", ret.warehouseCode());
assertEquals("102002", ret.orderRef());
assertEquals("未妥投退回", ret.type());
// 6 = 处理中-等待指令 → 待收货
@@ -191,11 +216,11 @@ class EdayunRmaListTest {
assertEquals("USLA", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode());
}
- /** 没有仓编码时回退仓名,再回退 OMS 仓编码。 */
+ /** 响应没有仓编码时直接回退 OMS 仓编码——**不能**退化成仓名(美西1仓)。 */
@Test
- void warehouseCodeFallsBackToOms() {
+ void warehouseCodeFallsBackToOmsNotDisplayName() {
EdayunRmaListDtos.RmaRow r = row();
- r.warehouseName = null;
+ r.warehouseCode = null;
assertEquals("EDY-WH", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode());
}
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java
index 845a4e7..df8dd7d 100644
--- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java
@@ -15,7 +15,7 @@ import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
- * SKU 标打印({@code newPrintCaseMarkContentType})映射。
+ * SKU 标打印({@code newPrintCaseMark})映射。
*
* 重点:码值不连续(4/2/5)、统一模型只能表达整单打印、
* Made in China 与分隔符默认关。
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java
index 407616e..bbdfa95 100644
--- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java
@@ -102,7 +102,8 @@ class EdayunTrackTest {
assertEquals("LF-1741871641090", info.trackingNumber());
assertEquals("fedex", info.carrier());
assertEquals("1", info.status());
- assertEquals("123", info.signedBy());
+ // receiver 是收件人,不是签收人;signedBy 必须为空(未签收契约)
+ assertNull(info.signedBy());
// 上网 / 妥投时间按 GMT-04:00 解释
assertEquals(Instant.parse("2025-08-19T12:17:00Z"), info.firstOnlineAt());
assertEquals(Instant.parse("2025-08-20T14:00:00Z"), info.deliveredAt());
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java
new file mode 100644
index 0000000..aef7104
--- /dev/null
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java
@@ -0,0 +1,106 @@
+package common.ecommerce.edayun.probe;
+
+import common.ecommerce.edayun.EdayunConstants;
+import common.ecommerce.edayun.adapter.EdayunAdapter;
+import common.ecommerce.http.JacksonJsonCodec;
+import common.ecommerce.http.OkHttpTransport;
+import common.ecommerce.shared.error.ChannelException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.support.Page;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.ProductInfo;
+import common.ecommerce.warehouse.model.ProductQuery;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import org.junit.jupiter.api.Assumptions;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
+
+import java.time.Clock;
+import java.util.Arrays;
+import java.util.UUID;
+
+/**
+ * 商品查询联调探针:只读。
+ *
+ *
+ * # 只看报文(不联网)
+ * mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
+ * -Dedayun.probe.productQuery=true -Dtest=EdayunProductQueryProbeTest test
+ *
+ * # 真查(只读)
+ * ... -Dedayun.probe.productQuery=true -Dedayun.probe.call=true \
+ * -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
+ * -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
+ * [-Dedayun.probe.sku=ybtest] [-Dedayun.probe.days=30]
+ *
+ */
+@EnabledIfSystemProperty(named = "edayun.probe.productQuery", matches = "true")
+class EdayunProductQueryProbeTest {
+
+ private static final String BASE_URL = opt("edayun.probe.baseUrl", EdayunConstants.PR_BASE_URL);
+ private static final String CLIENT_ID = System.getProperty("edayun.probe.clientId", "");
+ private static final String CLIENT_SECRET = System.getProperty("edayun.probe.clientSecret", "");
+ private static final String APP_KEY = System.getProperty("edayun.probe.appKey", "");
+ private static final String APP_SECRET = System.getProperty("edayun.probe.appSecret", "");
+ private static final String SKU = System.getProperty("edayun.probe.sku", "ybtest");
+ private static final int DAYS = Integer.getInteger("edayun.probe.days", 30);
+ private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
+
+ @Test
+ void probeProductQuery() {
+ ProductQuery query = ProductQuery.builder()
+ .providerSku(SKU)
+ .createdAfter(java.time.Instant.now().minus(java.time.Duration.ofDays(DAYS)))
+ .createdBefore(java.time.Instant.now())
+ .build();
+
+ System.out.println("\n================ edayun / POST "
+ + EdayunConstants.PATH_PRODUCT_LIST + " ================");
+ System.out.println("[probe] baseUrl=" + BASE_URL + " sku=" + SKU + " days=" + DAYS);
+
+ Assumptions.assumeTrue(CALL, "dry-run:未加 -Dedayun.probe.call=true,不实际调用");
+ Assumptions.assumeTrue(!CLIENT_ID.trim().isEmpty() && !CLIENT_SECRET.trim().isEmpty()
+ && !APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(),
+ "真查需要 -Dedayun.probe.clientId / clientSecret / appKey / appSecret");
+
+ try {
+ WarehouseContext ctx = WarehouseContext.of("EDY-PROBE", WarehouseProvider.EDAYUN, "2",
+ WarehouseConnection.of(BASE_URL,
+ ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret(APP_SECRET)
+ .clientId(CLIENT_ID).clientSecret(CLIENT_SECRET)
+ .build()),
+ "probe-" + UUID.randomUUID(), Clock.systemUTC());
+ EdayunAdapter adapter = new EdayunAdapter(
+ new OkHttpTransport("common-ecommerce/1.0.0 (edayun-probe)", 10_000, 60_000),
+ new JacksonJsonCodec());
+
+ Page page = adapter.query(ctx, query);
+ System.out.println("[OK] rows=" + page.size() + " hasMore=" + page.hasMore()
+ + " nextCursor=" + page.nextCursor());
+ for (ProductInfo p : page.items()) {
+ System.out.println(" " + p.providerSku() + " " + p.name()
+ + " lwh=" + p.lengthCm() + "x" + p.widthCm() + "x" + p.heightCm()
+ + " weight=" + p.weightGrams()
+ + " barcode=" + p.barcode()
+ + " createdAt=" + p.createdAt());
+ }
+ } catch (RuntimeException e) {
+ String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage();
+ System.out.println("[ERROR] " + e.getClass().getSimpleName() + ": "
+ + (msg.length() <= 800 ? msg : msg.substring(0, 800) + "…"));
+ if (e instanceof ChannelException) {
+ ChannelException ce = (ChannelException) e;
+ System.out.println(" platformCode=" + ce.platformCode()
+ + " retryable=" + ce.retryable());
+ }
+ }
+ }
+
+ private static String opt(String name, String fallback) {
+ String value = System.getProperty(name, "");
+ String trimmed = value == null ? "" : value.trim();
+ return trimmed.isEmpty() ? fallback : trimmed;
+ }
+}
diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java
new file mode 100644
index 0000000..0f09551
--- /dev/null
+++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java
@@ -0,0 +1,436 @@
+package common.ecommerce.edayun.sdk;
+
+import common.ecommerce.edayun.EdayunConstants;
+import common.ecommerce.edayun.adapter.EdayunAdapter;
+import common.ecommerce.edayun.adapter.EdayunAdapterFactory;
+import common.ecommerce.shared.model.Platform;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.shared.testkit.InMemoryIdempotencyStore;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.http.JacksonJsonCodec;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.shared.testkit.RecordingTransport;
+import common.ecommerce.shared.testkit.Responses;
+import common.ecommerce.warehouse.enums.CaseMarkPaperSize;
+import common.ecommerce.warehouse.enums.CancelEligibility;
+import common.ecommerce.warehouse.enums.ReturnDealMethod;
+import common.ecommerce.warehouse.enums.WarehouseCapability;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
+import common.ecommerce.warehouse.model.BolDocument;
+import common.ecommerce.warehouse.model.CancelCommand;
+import common.ecommerce.warehouse.model.CancelResult;
+import common.ecommerce.warehouse.model.FeeEstimateQuery;
+import common.ecommerce.warehouse.model.FeeEstimateResult;
+import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.InventorySnapshot;
+import common.ecommerce.warehouse.model.LogisticsProduct;
+import common.ecommerce.warehouse.model.OutboundCommand;
+import common.ecommerce.warehouse.model.OutboundLine;
+import common.ecommerce.warehouse.model.OutboundOrder;
+import common.ecommerce.warehouse.model.OutboundReceipt;
+import common.ecommerce.warehouse.model.OutboundRef;
+import common.ecommerce.warehouse.model.ReturnCommand;
+import common.ecommerce.warehouse.model.ReturnQuery;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.model.TrackEvent;
+import common.ecommerce.warehouse.model.TrackingInfo;
+import common.ecommerce.warehouse.model.WarehouseCarrier;
+import common.ecommerce.warehouse.model.WarehouseFacility;
+import common.ecommerce.warehouse.model.WarehouseLabel;
+import common.ecommerce.warehouse.model.WarehouseReturn;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseSdk;
+import common.ecommerce.warehouse.spi.WarehouseAccount;
+import common.ecommerce.warehouse.testkit.InMemoryWarehouses;
+import org.junit.jupiter.api.Test;
+
+import java.math.BigDecimal;
+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.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 易达云 SDK 装配链路冒烟。
+ *
+ * 不联网:走 {@link WarehouseSdk} 门面 → 工厂 → 适配器 → 假传输层,
+ * 用真实报文样本验一遍「能不能装起来、能力位对不对、字段有没有搬对」。
+ *
+ * 覆盖的业务场景:
+ *
+ * - 主数据:仓库 / 承运商 / 物流产品
+ * - 发货:试算 → 建单 → 查单 → 面单 → 取消
+ * - 库存:查询
+ * - 退货:建单 → 查详情 → 列表 → 取消
+ * - 单据 / 轨迹 / 打印
+ *
+ */
+class EdayunSdkSmokeTest {
+
+ private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC);
+ private static final String WH = "EDY-USLA";
+ private static final String BASE = "https://test.omniselling.com.cn/saas-service/openapi/microService";
+
+ private static WarehouseSdk sdk(RecordingTransport transport) {
+ InMemoryWarehouses repo = new InMemoryWarehouses().put(WarehouseAccount.builder()
+ .warehouseCode(WH)
+ .provider(WarehouseProvider.EDAYUN.name())
+ .providerWarehouseId("2")
+ .credentialRef("kms://test/edayun")
+ .timeZone("America/Los_Angeles")
+ .build());
+ // 直接注册适配器实例:把传输层换成假的,其余装配(token 缓存 / 锁 / 时钟)与
+ // 生产走同一套构造参数。工厂路径由 factoryAssemblesAdapter 单独验证。
+ EdayunAdapter adapter = new EdayunAdapter(transport, new JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), CLOCK);
+ return WarehouseSdk.builder()
+ .warehouseRepository(repo)
+ .idempotencyStore(new InMemoryIdempotencyStore())
+ .clock(CLOCK)
+ .register(adapter)
+ .build();
+ }
+
+ private static WarehouseConnection conn() {
+ return WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey("ak").appSecret("sk")
+ .clientId("cid").clientSecret("cs")
+ .build());
+ }
+
+ /** 所有业务接口共用的假传输层:token + 按路径路由。 */
+ private static RecordingTransport transport() {
+ return RecordingTransport.create()
+ .route(EdayunConstants.PATH_TOKEN, req -> Responses.ok(
+ "{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
+ .route(EdayunConstants.PATH_WAREHOUSE_PERMITTED, req -> Responses.ok(
+ "{\"code\":200,\"data\":[{\"warehouseId\":\"2\",\"warehouseName\":\"美西1仓\","
+ + "\"warehouseCode\":\"USLA\",\"countryCode\":\"US\"}]}"))
+ .route(EdayunConstants.PATH_CARRIERS, req -> Responses.ok(
+ "{\"code\":200,\"data\":[{\"carrierId\":\"1\",\"carrierNameEn\":\"FedEx\","
+ + "\"carrierNameCn\":\"FedEx\",\"ownLogisticList\":["
+ + "{\"logisticId\":\"250\",\"logisticName\":\"FedEx-express\"}]}]}"))
+ .route(EdayunConstants.PATH_LOGISTICS_PRODUCTS, req -> Responses.ok(
+ "{\"code\":200,\"data\":[{\"productId\":\"133\",\"productName\":\"USPS\"},"
+ + "{\"productId\":\"-998\",\"productName\":\"使用分物流规则\"}]}"))
+ .route(EdayunConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"successItems\":[{"
+ + "\"logisticProductId\":\"80\",\"logisticProductName\":\"美国经济派送\","
+ + "\"currencyCode\":\"USD\",\"estimatedPrice\":5.315,"
+ + "\"detailList\":[{\"billingItemName\":\"尾程配送费\","
+ + "\"estimatedPrice\":3.315,\"currencyCode\":\"USD\"}]}],"
+ + "\"failItems\":[]}}"))
+ .route(EdayunConstants.PATH_ORDER_CREATE, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"orderNo\":\"ORD1001\","
+ + "\"poNumber\":\"SO-1\"}}"))
+ .route(EdayunConstants.PATH_ORDER_GET, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"orderNo\":\"ORD1001\","
+ + "\"poNumber\":\"SO-1\",\"orderStatus\":\"Shipped\","
+ + "\"trackingNo\":\"1Z111\"}}"))
+ .route(EdayunConstants.PATH_ORDER_LABEL, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"orderNo\":\"ORD1001\","
+ + "\"trackingNo\":\"1Z111\",\"labels\":\"https://oss/l1.pdf\"}}"))
+ .route(EdayunConstants.PATH_ORDER_CHECK_CANCEL, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":\"Published\"}"))
+ .route(EdayunConstants.PATH_ORDER_CANCEL, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":true}"))
+ .route(EdayunConstants.PATH_INVENTORY, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"success\",\"total\":1,\"rows\":[{"
+ + "\"skuCode\":\"ybtest\",\"stock\":\"4\",\"totalStock\":\"10\","
+ + "\"inTransitStock\":\"20\",\"frozenStock\":\"1\","
+ + "\"toDeliverStock\":\"2\",\"safeStock\":null,"
+ + "\"warehouseCode\":\"USLA\"}]}"))
+ .route(EdayunConstants.PATH_RETURN_CREATE, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":\"RMA1001\"}"))
+ .route(EdayunConstants.PATH_RETURN_DETAIL, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"basicInfo\":{"
+ + "\"rmaCode\":\"RMA1001\",\"status\":5,\"statusName\":\"已处理\","
+ + "\"relationNo\":\"SO-1\",\"warehouseName\":\"美西1仓\"},"
+ + "\"checkList\":[{\"skuCode\":\"ybtest\",\"skuNum\":1,"
+ + "\"commandName\":\"上架\"}]}}"))
+ .route(EdayunConstants.PATH_RETURN_LIST, req -> Responses.ok(
+ "{\"total\":1,\"code\":200,\"rows\":[{\"rmaCode\":\"RMA1001\","
+ + "\"status\":5,\"statusName\":\"已处理\",\"warehouseName\":\"美西1仓\","
+ + "\"createTime\":1790568000000}]}"))
+ .route(EdayunConstants.PATH_RETURN_CANCEL, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":true}"))
+ .route(EdayunConstants.PATH_BOL_LIST, req -> Responses.ok(
+ "{\"code\":200,\"data\":{\"bolList\":[{\"bolCode\":\"cp005\","
+ + "\"status\":11,\"statusName\":\"已妥投\",\"bolFileUrl\":\"https://oss/b.pdf\"}]}}"))
+ .route(EdayunConstants.PATH_TRACK, req -> Responses.ok(
+ "{\"code\":200,\"data\":[{\"trackingNo\":\"1Z111\",\"status\":1,"
+ + "\"carrierName\":\"fedex\",\"onlineTime\":\"2025-08-19 08:17:00\","
+ + "\"deliveredTime\":\"2025-08-20 10:00:00\",\"timeZone\":\"GMT-04:00\","
+ + "\"trackDetaillVoList\":[{\"recentDescribe\":\"上网\","
+ + "\"recentDescribeTime\":1741145821000}]}]}"))
+ .route(EdayunConstants.PATH_CASE_MARK_PRINT, req -> Responses.ok(
+ "{\"code\":200,\"msg\":\"操作成功\",\"data\":\"https://oss/case.pdf\"}"))
+ .route(EdayunConstants.PATH_INBOUND_SKU_DETAIL, req -> Responses.ok(
+ "{\"total\":1,\"code\":200,\"rows\":[{\"entryCode\":\"REV1\","
+ + "\"skuCode\":\"ybtest\",\"forecastQuantity\":10,"
+ + "\"actualCheckedQuantity\":10,\"shelvesQuantity\":10,"
+ + "\"status\":4,\"statusName\":\"已上架\"}]}"));
+ }
+
+ // ================================================================ 装配
+
+ /**
+ * 工厂装配:不联网,只验证 {@code build()} 能把适配器建出来、
+ * 能力位与 provider 对得上。
+ */
+ @Test
+ void factoryAssemblesAdapter() {
+ InMemoryWarehouses repo = new InMemoryWarehouses().put(WarehouseAccount.builder()
+ .warehouseCode(WH)
+ .provider(WarehouseProvider.EDAYUN.name())
+ .providerWarehouseId("2")
+ .credentialRef("kms://test/edayun")
+ .timeZone("America/Los_Angeles")
+ .build());
+ WarehouseSdk built = WarehouseSdk.builder()
+ .warehouseRepository(repo)
+ .clock(CLOCK)
+ .register(new EdayunAdapterFactory(
+ new InMemoryTokenStore(), new InMemoryLockProvider(), CLOCK))
+ .build();
+
+ assertTrue(built.capabilities(WH).supported().contains(WarehouseCapability.OUTBOUND));
+ // 能按仓解析到适配器:仓库清单会真的打一次仓方,用假传输层接
+ assertNotNull(built.warehouses(WH, conn()));
+ }
+
+ // ================================================================ 能力位
+
+ @Test
+ void declaresAllImplementedCapabilities() {
+ WarehouseSdk sdk = sdk(transport());
+ java.util.EnumSet caps = sdk.capabilities(WH).supported();
+
+ // 已实现
+ assertTrue(caps.contains(WarehouseCapability.PRODUCT), "商品");
+ assertTrue(caps.contains(WarehouseCapability.OUTBOUND), "出库");
+ assertTrue(caps.contains(WarehouseCapability.INVENTORY_QUERY), "库存");
+ assertTrue(caps.contains(WarehouseCapability.INBOUND), "入库");
+ assertTrue(caps.contains(WarehouseCapability.RETURN), "退货");
+ assertTrue(caps.contains(WarehouseCapability.FEE_SETTLEMENT), "费用");
+ assertTrue(caps.contains(WarehouseCapability.FEE_ESTIMATE), "试算");
+ assertTrue(caps.contains(WarehouseCapability.BOL), "BOL");
+ assertTrue(caps.contains(WarehouseCapability.TRACKING), "轨迹");
+ assertTrue(caps.contains(WarehouseCapability.LOGISTICS_PRODUCT), "物流产品");
+ assertTrue(caps.contains(WarehouseCapability.CASE_MARK_PRINT), "箱唛");
+ assertTrue(caps.contains(WarehouseCapability.DIRECTORY), "基础资料");
+
+ // 未实现——调了必须抛,不能返回空
+ assertTrue(!caps.contains(WarehouseCapability.TRANSFER), "易达云没有调拨");
+ assertTrue(!caps.contains(WarehouseCapability.WEBHOOK), "回调文档还没给");
+ assertTrue(!caps.contains(WarehouseCapability.RETURN_DISPOSITION), "缺行 id");
+ }
+
+ // ================================================================ 场景 1:主数据
+
+ @Test
+ void scenario1_masterData() {
+ WarehouseSdk sdk = sdk(transport());
+
+ List warehouses = sdk.warehouses(WH, conn()).warehouses();
+ assertEquals(1, warehouses.size());
+ assertEquals("USLA", warehouses.get(0).warehouseCode());
+ assertEquals("2", warehouses.get(0).providerWarehouseId());
+
+ List carriers = sdk.warehouses(WH, conn()).carrierDirectory();
+ assertEquals(1, carriers.size());
+ assertEquals("FedEx", carriers.get(0).nameEn());
+ assertEquals(1, carriers.get(0).logists().size());
+
+ List products = sdk.warehouses(WH, conn()).logisticsProducts(null);
+ // -998 已跳过
+ assertEquals(1, products.size());
+ assertEquals("133", products.get(0).logisticsProductCode());
+ }
+
+ // ================================================================ 场景 2:发货
+
+ @Test
+ void scenario2_shipping() {
+ RecordingTransport transport = transport();
+ WarehouseSdk sdk = sdk(transport);
+
+ // 2.1 发货前试算
+ List quotes = sdk.warehouses(WH, conn()).fees().estimate(
+ FeeEstimateQuery.builder()
+ .lengthCm(new BigDecimal("22")).widthCm(new BigDecimal("22"))
+ .heightCm(new BigDecimal("22")).weightGrams(new BigDecimal("1000"))
+ .receiveCountry("US").receivePostal("91761")
+ .logisticsServiceCode("80")
+ .build());
+ assertEquals(1, quotes.size());
+ assertEquals(1, quotes.get(0).carriers().size());
+ assertEquals(new BigDecimal("5.315"), quotes.get(0).carriers().get(0).totalRate().amount());
+
+ // 2.2 建单
+ OutboundReceipt receipt = sdk.warehouses(WH, conn()).outbound().create(outbound());
+ assertEquals("ORD1001", receipt.providerOrderId());
+
+ // 2.3 查单
+ OutboundOrder order = sdk.warehouses(WH, conn()).outbound()
+ .get(OutboundRef.ofRequestNo("SO-1"));
+ assertNotNull(order);
+ assertEquals("ORD1001", order.providerOrderId());
+
+ // 2.4 面单
+ assertEquals(1, sdk.warehouses(WH, conn()).outbound()
+ .packages(OutboundRef.ofRequestNo("SO-1")).size());
+
+ // 2.5 取消前校验 → 免费
+ assertEquals(CancelEligibility.FREE, sdk.warehouses(WH, conn()).outbound()
+ .checkCancel(OutboundRef.ofRequestNo("SO-1")));
+
+ // 2.6 取消
+ CancelResult cancelled = sdk.warehouses(WH, conn()).outbound().cancel(
+ CancelCommand.builder().outboundRequestNo("SO-1").providerOrderId("ORD1001").build());
+ assertTrue(cancelled.cancelled());
+ }
+
+ /** 建单幂等:同一个 outboundRequestNo 调两次只发一次请求。 */
+ @Test
+ void scenario2_createIsIdempotent() {
+ RecordingTransport transport = transport();
+ WarehouseSdk sdk = sdk(transport);
+
+ sdk.warehouses(WH, conn()).outbound().create(outbound());
+ sdk.warehouses(WH, conn()).outbound().create(outbound());
+
+ long creates = transport.dataRequests().stream()
+ .filter(r -> r.url().endsWith(EdayunConstants.PATH_ORDER_CREATE))
+ .count();
+ assertEquals(1, creates, "第二次应命中幂等,不再调仓");
+ }
+
+ private static OutboundCommand outbound() {
+ return OutboundCommand.builder()
+ .outboundRequestNo("OB-1")
+ .orderRef("SO-1")
+ .warehouseId("2")
+ .currency("USD")
+ .salesPlatform(Platform.AMAZON_SC)
+ .shipTo(ShipTo.builder()
+ .name("Buyer").phone("+1-555-0100")
+ .countryCode("US").stateOrProvince("California")
+ .city("Escondido").addressLine1("1308 E Washington Ave")
+ .postalCode("92027")
+ .build())
+ .line(OutboundLine.builder()
+ .lineNo("1").omsSku("ybtest").quantity(1)
+ .declareValue(Money.of("19.99", "USD"))
+ .build())
+ .build();
+ }
+
+ // ================================================================ 场景 3:库存
+
+ @Test
+ void scenario3_inventory() {
+ WarehouseSdk sdk = sdk(transport());
+
+ List rows = sdk.warehouses(WH, conn()).inventory()
+ .query(InventoryQuery.builder().sku("ybtest").build()).items();
+
+ assertEquals(1, rows.size());
+ InventorySnapshot s = rows.get(0);
+ assertEquals("ybtest", s.providerSku());
+ assertEquals(4, s.available());
+ assertEquals(10, s.onHand());
+ assertEquals(20, s.inTransit());
+ // safeStock 为 null → -1(统一模型约定)
+ assertEquals(-1, s.alertQuantity());
+ }
+
+ // ================================================================ 场景 4:退货
+
+ @Test
+ void scenario4_returns() {
+ WarehouseSdk sdk = sdk(transport());
+
+ // 4.1 建退货单(自行退回)
+ WarehouseReturn created = sdk.warehouses(WH, conn()).returns().create(
+ ReturnCommand.builder()
+ .returnRequestNo("RT-1")
+ .saleOrderNo("SO-1")
+ .returnTrackingNo("1Z999")
+ .carrierCode("FedEx")
+ .warehouseId("2")
+ .line("ybtest", 1, ReturnDealMethod.WAREHOUSE_CONFIRM)
+ .build());
+ assertEquals("RMA1001", created.providerReturnId());
+
+ // 4.2 查详情
+ WarehouseReturn detail = sdk.warehouses(WH, conn()).returns().get("RMA1001");
+ assertNotNull(detail);
+ assertEquals("RMA1001", detail.providerReturnId());
+ assertEquals(1, detail.lines().size());
+
+ // 4.3 列表
+ assertEquals(1, sdk.warehouses(WH, conn()).returns()
+ .query(ReturnQuery.builder().pageSize(100).build()).size());
+
+ // 4.4 取消
+ assertTrue(sdk.warehouses(WH, conn()).returns().cancel("RMA1001"));
+ }
+
+ // ================================================================ 场景 5:单据 / 轨迹 / 打印
+
+ @Test
+ void scenario5_documentsTrackingAndPrinting() {
+ WarehouseSdk sdk = sdk(transport());
+
+ // BOL
+ List bols = sdk.warehouses(WH, conn()).orderBols("FBA1");
+ assertEquals(1, bols.size());
+ assertEquals("cp005", bols.get(0).bolCode());
+
+ // 轨迹:节点
+ List events = sdk.warehouses(WH, conn()).track("1Z111");
+ assertEquals(1, events.size());
+ // 轨迹:运单级,带上网 / 妥投时间
+ TrackingInfo info = sdk.warehouses(WH, conn()).trackShipment("1Z111");
+ assertNotNull(info.firstOnlineAt());
+ assertNotNull(info.deliveredAt());
+
+ // 箱唛(同步 PDF)
+ WarehouseLabel label = sdk.warehouses(WH, conn()).printCaseMarks(
+ CaseMarkPrintCommand.builder()
+ .paperSize(CaseMarkPaperSize.SIZE_70_30)
+ .item("ybtest", 1)
+ .build());
+ assertEquals("https://oss/case.pdf", label.url());
+
+ // 入库单
+ assertNotNull(sdk.warehouses(WH, conn()).inbound().get("REV1"));
+ }
+
+ // ================================================================ 未实现能力
+
+ @Test
+ void unimplementedCapabilitiesThrow() {
+ WarehouseSdk sdk = sdk(transport());
+
+ // 调拨
+ assertThrows(RuntimeException.class,
+ () -> sdk.warehouses(WH, conn()).getTransfer("T-1"));
+ // 退货检验后处理(缺行 id)
+ assertThrows(RuntimeException.class,
+ () -> sdk.warehouses(WH, conn()).returns().process(
+ common.ecommerce.warehouse.model.ReturnProcessCommand.builder()
+ .providerReturnNo("RMA1").lineId(1)
+ .disposition(common.ecommerce.warehouse.enums
+ .ReturnProcessDisposition.RESTOCK)
+ .build()));
+ }
+}
diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
index 2dc2a46..5fc1a69 100644
--- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
+++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
@@ -50,7 +50,6 @@ import common.ecommerce.warehouse.capability.TrackingChangeCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
-import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.AddressType;
import common.ecommerce.warehouse.enums.CancelEligibility;
@@ -85,6 +84,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.ReturnCommand;
+import common.ecommerce.warehouse.model.ReturnHandle;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.TransferQuery;
@@ -94,6 +94,8 @@ import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
+import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
@@ -367,7 +369,33 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
*
* 恒健没有对应的统一模型:这里返回仓方的处理单行,供宿主填写处理方式与回收照片。
*/
- public Page queryReturnHandles(
+ @Override
+ public Page queryHandles(WarehouseContext ctx, ReturnQuery query) {
+ if (query == null) {
+ query = ReturnQuery.builder().build();
+ }
+ // 统一入口只带游标 / 仓库 / 单号;其余维度恒健这里没有对应口径,给了就拒绝
+ if (query.hasCreatedRange() || query.trackingNo() != null
+ || query.providerSku() != null || !query.statuses().isEmpty()
+ || query.orderNoType() != null) {
+ throw validation(ctx, OP_RETURN_HANDLES,
+ "hengjian return handle list takes returnPlanNo / tracking / warehouse / "
+ + "handlingStatus only; use queryHandlesAdvanced for those");
+ }
+ List planNos = query.orderNo() == null
+ ? null : java.util.Collections.singletonList(query.orderNo());
+ List warehouseCodes = query.warehouseCode() == null
+ ? null : java.util.Collections.singletonList(query.warehouseCode());
+ return queryHandlesAdvanced(ctx, planNos, null, warehouseCodes,
+ null, null, null, query.cursor());
+ }
+
+ /**
+ * 多条件分页查退货处理单({@code POST /v1/saleReturn/getReturnPlanHandlePage})。
+ *
+ * 请求是平铺的(无 {@code params} 包裹),与 thirdParty 那两个不同。
+ */
+ public Page queryHandlesAdvanced(
WarehouseContext ctx, List returnPlanNos, List trackingNos,
List warehouseCodes, List handlingStatuses,
String createdStart, String createdEnd, String cursor) {
@@ -1645,7 +1673,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
* 响应 {@code data} 是分页对象(不是数组);{@code total} 用来判断是否还有下一页。
*/
@Override
- public Page queryProducts(WarehouseContext ctx, ProductQuery query) {
+ public Page query(WarehouseContext ctx, ProductQuery query) {
HengjianProductQueryDtos.QueryRequest body = HengjianProductQueryMapper.toRequest(query);
String raw = execute(ctx, HengjianConstants.PATH_PRODUCT_QUERY_PAGE, body, OP_PRODUCT_QUERY);
HengjianProductQueryDtos.QueryResponse resp =
diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java
index cd3762a..c967f98 100644
--- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java
+++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java
@@ -3,7 +3,7 @@ package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianProductQueryDtos;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.Page;
-import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import java.math.BigDecimal;
@@ -80,17 +80,17 @@ public final class HengjianProductQueryMapper {
// ================================================================ 响应
/** 响应 → 分页商品。 */
- public static Page toPage(HengjianProductQueryDtos.PageData data,
+ public static Page toPage(HengjianProductQueryDtos.PageData data,
String requestedCursor, int requestedPageSize) {
if (data == null || data.data == null || data.data.isEmpty()) {
- return Page.last(new ArrayList());
+ return Page.last(new ArrayList());
}
- List out = new ArrayList(data.data.size());
+ List out = new ArrayList(data.data.size());
for (HengjianProductQueryDtos.ProductRow row : data.data) {
if (row == null) {
continue;
}
- WarehouseProduct product = toProduct(row);
+ ProductInfo product = toProduct(row);
if (product != null) {
out.add(product);
}
@@ -99,7 +99,7 @@ public final class HengjianProductQueryMapper {
}
/** 按 {@code total} 判断是否还有下一页。 */
- static Page nextPage(List items, Long totalRaw,
+ static Page nextPage(List items, Long totalRaw,
String requestedCursor, int requestedPageSize) {
int page = pageOf(requestedCursor);
if (totalRaw == null) {
@@ -112,16 +112,13 @@ public final class HengjianProductQueryMapper {
return Page.of(items, String.valueOf(page + 1));
}
- /** 一条商品 → 统一模型;{@code sku} 缺失时返回 null(跳过脏数据,不整页失败)。 */
- static WarehouseProduct toProduct(HengjianProductQueryDtos.ProductRow row) {
+ /** 一条商品 → 查询结果模型;{@code sku} 缺失时返回 null(跳过脏数据,不整页失败)。 */
+ static ProductInfo toProduct(HengjianProductQueryDtos.ProductRow row) {
String sku = trimToNull(row.sku);
if (sku == null) {
return null;
}
- WarehouseProduct.Builder b = WarehouseProduct.builder()
- // 查询结果允许尺寸 / 重量缺失(用 0 表示),不伪造
- .allowUnknownDimensions(true)
- .omsSku(sku)
+ ProductInfo.Builder b = ProductInfo.builder()
.providerSku(sku)
.name(firstNonBlank(row.name, row.nameEn, sku))
.nameEn(trimToNull(row.nameEn))
@@ -133,9 +130,9 @@ public final class HengjianProductQueryMapper {
.widthCm(doubleOrZero(row.width))
.heightCm(doubleOrZero(row.height))
.weightGrams(doubleOrZero(row.weight))
- .itemLengthCm(doubleOrZero(row.itemLength))
- .itemWidthCm(doubleOrZero(row.itemWidth))
- .itemHeightCm(doubleOrZero(row.itemHeight))
+ .itemLengthCm(doubleOrNull(row.itemLength))
+ .itemWidthCm(doubleOrNull(row.itemWidth))
+ .itemHeightCm(doubleOrNull(row.itemHeight))
// 仓库实测,与申报尺寸分开存
.measuredLengthCm(doubleOrNull(row.measurementLength))
.measuredWidthCm(doubleOrNull(row.measurementWidth))
@@ -149,7 +146,8 @@ public final class HengjianProductQueryMapper {
.packedWeightGrams(doubleOrNull(row.packedWeight))
// 保质期
.expirationControl(oneZeroToBoolean(row.expirationControl))
- .expirationDays(intOrNull(row.expirationDate));
+ .expirationDays(intOrNull(row.expirationDate))
+ .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.HENGJIAN);
Integer productType = intOrNull(row.productType);
if (productType != null) {
@@ -160,11 +158,11 @@ public final class HengjianProductQueryMapper {
if (insured != null) {
b.insured("Y".equalsIgnoreCase(insured));
}
- // 成本:带币种
+ // 成本 + 币种
BigDecimal cost = decimalOrNull(row.cost);
String currency = trimToNull(row.currency);
if (cost != null && currency != null) {
- b.cost(Money.of(cost, currency));
+ b.declaredValue(Money.of(cost, currency));
}
BigDecimal rate = decimalOrNull(row.isInsuranceRate);
if (rate != null && currency != null) {
diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java
index 6d85e09..de14035 100644
--- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java
+++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java
@@ -8,6 +8,7 @@ import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.ReturnHandle;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseAttachment;
import common.ecommerce.warehouse.model.WarehouseReturn;
@@ -260,16 +261,16 @@ public final class HengjianReturnQueryMapper {
}
/** 处理单列表 → 统一 Page(每行是一条处理单,不是退货单)。 */
- public static Page toHandlePage(
+ public static Page toHandlePage(
HengjianReturnHandleDtos.HandlePageData data, String cursor, int requestedRows) {
if (data == null) {
- return Page.last(new ArrayList());
+ return Page.last(new ArrayList());
}
- List out = new ArrayList();
+ List out = new ArrayList();
if (data.content != null) {
for (HengjianReturnHandleDtos.HandleRow row : data.content) {
if (row != null) {
- out.add(row);
+ out.add(toHandle(row));
}
}
}
@@ -282,6 +283,97 @@ public final class HengjianReturnQueryMapper {
return Page.of(out, String.valueOf(next));
}
+ /**
+ * 一条处理单 → 统一模型。
+ *
+ * 恒健的处理单行没给「退货编码」({@code returnNo}),那个字段只在
+ * 填写处理方式时必填。所以这里 {@code returnNo} 留 null——不拿处理单号冒充,
+ * 两者语义不同。调用方填处理方式时需要从别处拿到它。
+ */
+ static ReturnHandle toHandle(HengjianReturnHandleDtos.HandleRow row) {
+ ReturnHandle.Builder b = ReturnHandle.builder()
+ .returnPlanNo(row.returnPlanNo)
+ .returnHandleNo(trimToNull(row.returnPlanHandleItemsNo))
+ .trackingNumber(trimToNull(row.tracking))
+ .providerSku(trimToNull(row.erpSku))
+ .changeSku(trimToNull(row.changeErpsku))
+ .quantity(row.quantity)
+ .handledQuantity(row.handlingQuantity)
+ .photosQuantity(row.photosQuantity)
+ .inventoryType(parseIntOrNull(row.inventoryType))
+ .handlingStatus(trimToNull(row.handlingStatus))
+ .handlingStatusName(handlingStatusName(row.handlingStatus))
+ .primaryHandlingMethod(trimToNull(row.primaryHandlingMethod))
+ .sourceNo(firstNonBlank(row.sourceNo, row.openSourceNo))
+ .warehouseCode(trimToNull(row.orgWarehouseCode))
+ .errorStatus(trimToNull(row.errorStatus))
+ .createdAt(parseTime(row.createdAt))
+ .updatedAt(parseTime(row.updatedAt))
+ .completedAt(parseTime(row.completeAt))
+ .sourceProvider(WarehouseProvider.HENGJIAN);
+ for (String url : urls(row.fileUrlList)) {
+ b.photoUrl(url);
+ }
+ for (String url : urls(row.handleFileUrlList)) {
+ b.handledPhotoUrl(url);
+ }
+ return b.build();
+ }
+
+ /** 处理状态码 → 中文名;认不出的返回 null,不猜。 */
+ static String handlingStatusName(String raw) {
+ String v = trimToNull(raw);
+ if (v == null) {
+ return null;
+ }
+ switch (v) {
+ case "5":
+ return "待处理";
+ case "10":
+ return "处理中";
+ case "15":
+ return "已完成";
+ case "20":
+ return "已取消";
+ default:
+ return null;
+ }
+ }
+
+ /** 照片字段文档标 string、实际可能是数组:两种都接。 */
+ static List urls(Object raw) {
+ List out = new ArrayList();
+ if (raw == null) {
+ return out;
+ }
+ if (raw instanceof List) {
+ for (Object o : (List>) raw) {
+ String v = trimToNull(o == null ? null : String.valueOf(o));
+ if (v != null) {
+ out.add(v);
+ }
+ }
+ return out;
+ }
+ String v = trimToNull(String.valueOf(raw));
+ if (v != null) {
+ out.add(v);
+ }
+ return out;
+ }
+
+ static Integer parseIntOrNull(String raw) {
+ String v = trimToNull(raw);
+ if (v == null) {
+ return null;
+ }
+ try {
+ return Integer.valueOf(v);
+ } catch (NumberFormatException e) {
+ return null;
+ }
+ }
+
// ================================================================ 处理方式
/**
diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java
index 96edc6e..d5287c6 100644
--- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java
+++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java
@@ -6,7 +6,7 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
-import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
@@ -69,7 +69,7 @@ class HengjianProductQueryTest {
@Test
void sendsPagingAsString() {
RecordingTransport transport = listing(body(ONE_ROW, 1));
- adapter(transport).queryProducts(CTX, ProductQuery.builder().pageSize(50).build());
+ adapter(transport).query(CTX, ProductQuery.builder().pageSize(50).build());
String json = transport.lastDataRequest().body();
assertTrue(json.contains("\"pageSize\":\"50\""), json);
@@ -79,11 +79,11 @@ class HengjianProductQueryTest {
@Test
void sendsSkusOnlyWhenGiven() {
RecordingTransport absent = listing(body("", 0));
- adapter(absent).queryProducts(CTX, ProductQuery.builder().build());
+ adapter(absent).query(CTX, ProductQuery.builder().build());
assertFalse(absent.lastDataRequest().body().contains("\"skus\""));
RecordingTransport present = listing(body("", 0));
- adapter(present).queryProducts(CTX, ProductQuery.builder()
+ adapter(present).query(CTX, ProductQuery.builder()
.providerSkus(java.util.Arrays.asList("A", "B")).build());
String json = present.lastDataRequest().body();
assertTrue(json.contains("\"skus\":[\"A\",\"B\"]"), json);
@@ -92,7 +92,7 @@ class HengjianProductQueryTest {
@Test
void cursorBecomesPageNum() {
RecordingTransport transport = listing(body(ONE_ROW, 1000));
- adapter(transport).queryProducts(CTX, ProductQuery.builder().cursor("3").pageSize(10).build());
+ adapter(transport).query(CTX, ProductQuery.builder().cursor("3").pageSize(10).build());
assertTrue(transport.lastDataRequest().body().contains("\"pageNum\":\"3\""));
}
@@ -100,7 +100,7 @@ class HengjianProductQueryTest {
@Test
void rejectsPageSizeAboveMax() {
assertThrows(IllegalArgumentException.class,
- () -> adapter(listing(body("", 0))).queryProducts(CTX,
+ () -> adapter(listing(body("", 0))).query(CTX,
ProductQuery.builder().pageSize(500).build()));
}
@@ -108,12 +108,12 @@ class HengjianProductQueryTest {
@Test
void mapsProductFields() {
- Page page = adapter(listing(body(ONE_ROW, 1)))
- .queryProducts(CTX, ProductQuery.builder().build());
+ Page page = adapter(listing(body(ONE_ROW, 1)))
+ .query(CTX, ProductQuery.builder().build());
assertEquals(1, page.size());
- WarehouseProduct p = page.items().get(0);
- assertEquals("SKU-A", p.omsSku());
+ ProductInfo p = page.items().get(0);
+ assertEquals("SKU-A", p.providerSku());
assertEquals("小部件", p.name());
assertEquals("Widget", p.nameEn());
assertEquals("UPC-A", p.barcode());
@@ -134,8 +134,8 @@ class HengjianProductQueryTest {
/** 仓库实测尺寸与申报尺寸分开存。 */
@Test
void keepsMeasuredDimensionsSeparate() {
- WarehouseProduct p = adapter(listing(body(ONE_ROW, 1)))
- .queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
+ ProductInfo p = adapter(listing(body(ONE_ROW, 1)))
+ .query(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(30.0, p.lengthCm(), 0.001);
assertEquals(30.5, p.measuredLengthCm(), 0.001);
@@ -147,8 +147,8 @@ class HengjianProductQueryTest {
void fallsBackToItemLengthWhenLengthMissing() {
String row = "{\"sku\":\"SKU-B\",\"width\":20,\"height\":10,\"weight\":100,"
+ "\"itemLength\":29,\"itemWidth\":19,\"itemHeight\":9}";
- WarehouseProduct p = adapter(listing(body(row, 1)))
- .queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
+ ProductInfo p = adapter(listing(body(row, 1)))
+ .query(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(29.0, p.lengthCm(), 0.001, "没有 length 时用 itemLength");
}
@@ -156,21 +156,21 @@ class HengjianProductQueryTest {
/** total 决定是否还有下一页。 */
@Test
void pagingUsesTotal() {
- Page more = adapter(listing(body(ONE_ROW, 500)))
- .queryProducts(CTX, ProductQuery.builder().pageSize(100).build());
+ Page more = adapter(listing(body(ONE_ROW, 500)))
+ .query(CTX, ProductQuery.builder().pageSize(100).build());
assertTrue(more.hasMore());
assertEquals("2", more.nextCursor());
- Page done = adapter(listing(body(ONE_ROW, 1)))
- .queryProducts(CTX, ProductQuery.builder().pageSize(100).build());
+ Page done = adapter(listing(body(ONE_ROW, 1)))
+ .query(CTX, ProductQuery.builder().pageSize(100).build());
assertFalse(done.hasMore());
assertNull(done.nextCursor());
}
@Test
void emptyPageIsLast() {
- Page page = adapter(listing(body("", 0)))
- .queryProducts(CTX, ProductQuery.builder().build());
+ Page page = adapter(listing(body("", 0)))
+ .query(CTX, ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
assertFalse(page.hasMore());
}
@@ -180,17 +180,17 @@ class HengjianProductQueryTest {
void skipsRowsWithoutSku() {
String row = "{\"name\":\"无SKU\"}";
assertTrue(adapter(listing(body(row, 1)))
- .queryProducts(CTX, ProductQuery.builder().build()).items().isEmpty());
+ .query(CTX, ProductQuery.builder().build()).items().isEmpty());
}
/** 尺寸缺失用 0 表示「仓方未给」。 */
@Test
void missingDimensionsBecomeZero() {
String row = "{\"sku\":\"SKU-C\"}";
- WarehouseProduct p = adapter(listing(body(row, 1)))
- .queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
+ ProductInfo p = adapter(listing(body(row, 1)))
+ .query(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(0.0, p.lengthCm(), 0.001);
- assertFalse(p.hasDimensions());
+ assertEquals(0.0, p.lengthCm(), 0.001);
}
}
diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java
index fbbe274..82ffeeb 100644
--- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java
+++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java
@@ -9,6 +9,7 @@ import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.ReturnStatus;
+import common.ecommerce.warehouse.model.ReturnHandle;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
@@ -229,7 +230,7 @@ class HengjianReturnQueryTest {
@Test
void handleListPostsFlatBody() {
RecordingTransport transport = handling();
- adapter(transport).queryReturnHandles(CTX,
+ adapter(transport).queryHandlesAdvanced(CTX,
Collections.singletonList("RC1"), null, null,
Collections.singletonList(15), null, null, null);
@@ -243,19 +244,18 @@ class HengjianReturnQueryTest {
@Test
void handleListMapsRows() {
- Page page =
- adapter(handling()).queryReturnHandles(CTX,
- Collections.singletonList("RC1"), null, null, null, null, null, null);
+ Page page =
+ adapter(handling()).queryHandlesAdvanced(CTX, Collections.singletonList("RC1"), null, null, null, null, null, null);
assertEquals(1, page.size());
assertTrue(page.hasMore(), "last=false 应给出下一页");
assertEquals("2", page.nextCursor());
- HengjianReturnHandleDtos.HandleRow row = page.items().get(0);
- assertEquals("RC25081300010", row.returnPlanNo);
- assertEquals("RP25081400001", row.returnPlanHandleItemsNo);
- assertEquals("15", row.handlingStatus);
- assertEquals("203", row.primaryHandlingMethod);
- assertEquals("C-2077-BU", row.changeErpsku);
+ ReturnHandle row = page.items().get(0);
+ assertEquals("RC25081300010", row.returnPlanNo());
+ assertEquals("RP25081400001", row.returnHandleNo());
+ assertEquals("15", row.handlingStatus());
+ assertEquals("203", row.primaryHandlingMethod());
+ assertEquals("C-2077-BU", row.changeSku());
}
// ================================================================ 处理方式
diff --git a/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseCallObserverTest.java b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseCallObserverTest.java
new file mode 100644
index 0000000..4b9a375
--- /dev/null
+++ b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseCallObserverTest.java
@@ -0,0 +1,213 @@
+package common.ecommerce.warehouse.sdk;
+
+import common.ecommerce.shared.audit.CallObserver;
+import common.ecommerce.shared.audit.CallRecord;
+import common.ecommerce.shared.testkit.InMemoryIdempotencyStore;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.enums.LabelMode;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.OutboundCommand;
+import common.ecommerce.warehouse.model.OutboundLine;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.testkit.FakeWarehouseAdapter;
+import common.ecommerce.warehouse.testkit.InMemoryWarehouses;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 门面操作日志({@code CallObserver})契约测试。
+ *
+ * 这里验证的是「新仓接入后操作日志默认就通」这个承诺:
+ * 适配器只写协议转换、不自己造门面,宿主注入 {@code callObserver} 之后
+ * 每个门面调用都必然产生一条 {@link CallRecord}。
+ */
+class WarehouseCallObserverTest {
+
+ private static final Instant T0 = Instant.parse("2026-11-09T00:00:00Z");
+ private static final Clock CLOCK = Clock.fixed(T0, ZoneOffset.UTC);
+ private static final String WH = "YQN-RF_NY_US";
+
+ private RecordingObserver observer;
+ private WarehouseSdk sdk;
+
+ @BeforeEach
+ void setUp() {
+ observer = new RecordingObserver();
+ InMemoryWarehouses repo = new InMemoryWarehouses()
+ .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
+ sdk = WarehouseSdk.builder()
+ .warehouseRepository(repo)
+ .idempotencyStore(new InMemoryIdempotencyStore())
+ .clock(CLOCK)
+ .register(new FakeWarehouseAdapter())
+ .callObserver(observer)
+ .build();
+ }
+
+ private static OutboundCommand cmd(String requestNo) {
+ return OutboundCommand.builder()
+ .outboundRequestNo(requestNo)
+ .orderRef("SO-1")
+ .labelMode(LabelMode.WAREHOUSE_LABEL)
+ .salesPlatform(common.ecommerce.shared.model.Platform.WALMART_SC)
+ .shipTo(ShipTo.builder()
+ .name("B") // 测试数据
+ .countryCode("US")
+ .city("New York")
+ .addressLine1("1 Test St")
+ .build())
+ .line(OutboundLine.builder()
+ .lineNo("1")
+ .omsSku("DM00001")
+ .quantity(1)
+ .declareName("Sample")
+ .declareValue(Money.of("10.00", "USD"))
+ .build())
+ .build();
+ }
+
+ /** 成功调用要记一条,operation / provider / 结果都要有。 */
+ @Test
+ void recordsSuccessfulCall() {
+ sdk.warehouses(WH, conn()).outbound().create(cmd("OB-1"));
+
+ CallRecord record = observer.lastOf("warehouse.outbound.create");
+ assertEquals(WarehouseProvider.CUSTOM.name(), record.provider());
+ assertNotNull(record.outcome());
+ assertEquals("OB-1", String.valueOf(record.params().get("outboundRequestNo")));
+ }
+
+ /** 失败也要记:异常不能把日志吞掉。 */
+ @Test
+ void recordsFailedCall() {
+ InMemoryWarehouses repo = new InMemoryWarehouses()
+ .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
+ WarehouseSdk blocking = WarehouseSdk.builder()
+ .warehouseRepository(repo)
+ .idempotencyStore(new InMemoryIdempotencyStore())
+ .clock(CLOCK)
+ .register(new FakeWarehouseAdapter().blockCancel())
+ .callObserver(observer)
+ .build();
+ assertThrows(RuntimeException.class,
+ () -> blocking.warehouses(WH, conn()).outbound()
+ .cancel(common.ecommerce.warehouse.model.CancelCommand.builder()
+ .outboundRequestNo("OB-X")
+ .acceptCharge(false)
+ .build()));
+
+ CallRecord record = observer.lastOf("warehouse.outbound.cancel");
+ assertNotNull(record.errorType(), "失败记录要带异常类型");
+ }
+
+ /** 只读方法同样记。 */
+ @Test
+ void recordsReadOnlyCall() {
+ sdk.warehouses(WH, conn()).outbound().query(
+ common.ecommerce.warehouse.model.OutboundQuery.builder().build());
+
+ assertNotNull(observer.lastOf("warehouse.outbound.query"));
+ }
+
+ /** 同一 SDK 多次调用各记一条,不合并。 */
+ @Test
+ void recordsOnePerCall() {
+ WarehouseOperations ops = sdk.warehouses(WH, conn());
+ ops.outbound().create(cmd("OB-1"));
+ ops.outbound().get(common.ecommerce.warehouse.model.OutboundRef.ofRequestNo("OB-1"));
+
+ assertNotNull(observer.lastOf("warehouse.outbound.create"));
+ assertNotNull(observer.lastOf("warehouse.outbound.get"));
+ assertTrue(observer.records.size() >= 2, "每次门面调用至少一条记录");
+ }
+
+ /** 没注入 observer 时什么都不记,但业务照常跑——不能因为没日志就抛。 */
+ @Test
+ void noObserverMeansNoRecordsButStillWorks() {
+ WarehouseSdk quiet = WarehouseSdk.builder()
+ .warehouseRepository(new InMemoryWarehouses()
+ .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)))
+ .idempotencyStore(new InMemoryIdempotencyStore())
+ .clock(CLOCK)
+ .register(new FakeWarehouseAdapter())
+ .build();
+
+ assertNotNull(quiet.warehouses(WH, conn()).outbound().create(cmd("OB-1")));
+ }
+
+ /** observer 自己抛异常要被吞掉,不能影响业务返回值。 */
+ @Test
+ void observerFailureDoesNotBreakBusinessCall() {
+ WarehouseSdk broken = WarehouseSdk.builder()
+ .warehouseRepository(new InMemoryWarehouses()
+ .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)))
+ .idempotencyStore(new InMemoryIdempotencyStore())
+ .clock(CLOCK)
+ .register(new FakeWarehouseAdapter())
+ .callObserver(record -> {
+ throw new IllegalStateException("observer boom");
+ })
+ .build();
+
+ assertNotNull(broken.warehouses(WH, conn()).outbound().create(cmd("OB-1")));
+ }
+
+ /** 参数摘要里不能出现密钥类字段。 */
+ @Test
+ void paramsDoNotLeakSecrets() {
+ sdk.warehouses(WH, conn()).outbound().create(cmd("OB-1"));
+
+ for (String key : observer.lastOf("warehouse.outbound.create").params().keySet()) {
+ assertFalse(key.toLowerCase().contains("secret"), "params 不应含密钥字段: " + key);
+ assertFalse(key.toLowerCase().contains("token"), "params 不应含 token 字段: " + key);
+ }
+ }
+
+ private static WarehouseConnection conn() {
+ return WarehouseConnection.of("https://example.test",
+ ChannelSecret.builder().appSecret("s").build());
+ }
+
+ /** 记录型观察者。 */
+ private static final class RecordingObserver implements CallObserver {
+ private final List records = new ArrayList();
+
+ @Override
+ public void onCall(CallRecord record) {
+ records.add(record);
+ }
+
+ /** 找指定 operation 的记录(写操作前面还会有幂等审计记录,所以不能只看条数)。 */
+ CallRecord lastOf(String operation) {
+ CallRecord found = null;
+ for (CallRecord record : records) {
+ if (operation.equals(record.operation())) {
+ found = record;
+ }
+ }
+ assertNotNull(found, "没有 " + operation + " 的记录,实际有 " + operations());
+ return found;
+ }
+
+ List operations() {
+ List out = new ArrayList();
+ for (CallRecord record : records) {
+ out.add(record.operation());
+ }
+ return out;
+ }
+ }
+}
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 70ec33d..6185e7f 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
@@ -39,6 +39,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand;
+import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
@@ -228,7 +229,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
* 映射时直接用厘米那套,不做二次换算。
*/
@Override
- public Page queryProducts(WarehouseContext ctx, ProductQuery query) {
+ public Page query(WarehouseContext ctx, ProductQuery query) {
AccessToken token = login(ctx);
Map params = XincangProductQueryMapper.toParams(query);
String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token,
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java
index 3f72b7f..7b63664 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java
@@ -2,7 +2,8 @@ package common.ecommerce.xincang.adapter;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.Page;
-import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangProductListDtos;
@@ -97,17 +98,17 @@ public final class XincangProductQueryMapper {
// ================================================================ 响应
/** 响应 → 分页商品。 */
- public static Page toPage(XincangProductListDtos.ProductListResult rst,
+ public static Page toPage(XincangProductListDtos.ProductListResult rst,
String requestedCursor, int requestedLimit) {
if (rst == null || rst.data == null || rst.data.isEmpty()) {
- return Page.last(new ArrayList());
+ return Page.last(new ArrayList());
}
- List out = new ArrayList(rst.data.size());
+ List out = new ArrayList(rst.data.size());
for (XincangProductListDtos.ProductItem item : rst.data) {
if (item == null) {
continue;
}
- WarehouseProduct product = toProduct(item);
+ ProductInfo product = toProduct(item);
if (product != null) {
out.add(product);
}
@@ -121,7 +122,7 @@ public final class XincangProductQueryMapper {
* 按 {@code rst.count}(总数)判断,不按「本页是否满」——服务端可能对
* {@code limit} 做上限收窄,满页不代表还有。
*/
- static Page nextPage(List items, String totalRaw,
+ static Page nextPage(List items, String totalRaw,
String requestedCursor, int requestedLimit) {
int page = pageOf(requestedCursor);
Integer total = intOrNull(totalRaw);
@@ -142,15 +143,12 @@ public final class XincangProductQueryMapper {
* {@code product_no} 缺失时返回 null(无法定位的商品,跳过而不是抛——
* 列表里一条脏数据不该让整页失败)。
*/
- static WarehouseProduct toProduct(XincangProductListDtos.ProductItem item) {
+ static ProductInfo toProduct(XincangProductListDtos.ProductItem item) {
String sku = trimToNull(item.productNo);
if (sku == null) {
return null;
}
- WarehouseProduct.Builder b = WarehouseProduct.builder()
- // 查询结果允许尺寸 / 重量为 0(仓方没给),不伪造最小值
- .allowUnknownDimensions(true)
- .omsSku(sku)
+ ProductInfo.Builder b = ProductInfo.builder()
.providerSku(sku)
.name(firstNonBlank(item.chnName, item.enName, sku))
.nameEn(trimToNull(item.enName))
@@ -164,12 +162,12 @@ public final class XincangProductQueryMapper {
// 查询结果才有
.providerProductId(trimToNull(item.id))
.rawState(trimToNull(item.state))
- .stateName(trimToNull(item.stateName))
+ .rawStatusName(trimToNull(item.stateName))
.volumeCm3(decimalOrNull(item.volumeCm))
.createdAt(XincangOrderDetailMapper.parseTime(item.gmtCreate))
.updatedAt(XincangOrderDetailMapper.parseTime(item.gmtModify))
.imageUrl(trimToNull(item.imageUrl))
- .remark(null);
+ .sourceProvider(WarehouseProvider.XINCANG);
// packing_rate → 装箱数量
Integer packing = intOrNull(item.packingRate);
@@ -181,7 +179,6 @@ public final class XincangProductQueryMapper {
if (amount != null) {
b.declaredValue(Money.of(amount, "USD"));
}
- // 统一模型没有「长度/重量单位」以外的差异;外箱尺寸信仓不提供,保持 null
return b.build();
}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java
index 61b69a1..b707c96 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java
@@ -6,7 +6,7 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
-import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@@ -94,7 +94,7 @@ class XincangProductQueryTest {
@Test
void sendsMandatoryQueryParams() {
RecordingTransport transport = productListing(listBody(ONE_ROW, "1"));
- adapter(transport).queryProducts(ctx(), ProductQuery.builder().build());
+ adapter(transport).query(ctx(), ProductQuery.builder().build());
String url = productListUrl(transport);
// 四项必填
@@ -108,7 +108,7 @@ class XincangProductQueryTest {
@Test
void alwaysQueriesFormalState() {
RecordingTransport transport = productListing(listBody("", "0"));
- adapter(transport).queryProducts(ctx(), ProductQuery.builder().build());
+ adapter(transport).query(ctx(), ProductQuery.builder().build());
assertTrue(productListUrl(transport).contains("state=1"));
}
@@ -118,7 +118,7 @@ class XincangProductQueryTest {
void rejectsMultipleSkus() {
RecordingTransport transport = productListing(listBody("", "0"));
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
- () -> adapter(transport).queryProducts(ctx(), ProductQuery.builder()
+ () -> adapter(transport).query(ctx(), ProductQuery.builder()
.providerSkus(java.util.Arrays.asList("A", "B")).build()));
assertTrue(ex.getMessage().contains("single sku"), ex.getMessage());
}
@@ -126,7 +126,7 @@ class XincangProductQueryTest {
@Test
void sendsSingleSkuAsKey() {
RecordingTransport transport = productListing(listBody(ONE_ROW, "1"));
- adapter(transport).queryProducts(ctx(), ProductQuery.builder().providerSku("SKU-A").build());
+ adapter(transport).query(ctx(), ProductQuery.builder().providerSku("SKU-A").build());
assertTrue(productListUrl(transport).contains("key=SKU-A"));
}
@@ -135,19 +135,19 @@ class XincangProductQueryTest {
void rejectsLimitAboveMax() {
RecordingTransport transport = productListing(listBody("", "0"));
assertThrows(IllegalArgumentException.class,
- () -> adapter(transport).queryProducts(ctx(), ProductQuery.builder().pageSize(500).build()));
+ () -> adapter(transport).query(ctx(), ProductQuery.builder().pageSize(500).build()));
}
// ---------------------------------------------------------------- 响应
@Test
void mapsProductFields() {
- Page page = adapter(productListing(listBody(ONE_ROW, "1")))
- .queryProducts(ctx(), ProductQuery.builder().build());
+ Page page = adapter(productListing(listBody(ONE_ROW, "1")))
+ .query(ctx(), ProductQuery.builder().build());
assertEquals(1, page.size());
- WarehouseProduct p = page.items().get(0);
- assertEquals("SKU-A", p.omsSku());
+ ProductInfo p = page.items().get(0);
+ assertEquals("SKU-A", p.providerSku());
assertEquals("SKU-A", p.providerSku());
assertEquals("小部件", p.name());
assertEquals("Widget", p.nameEn());
@@ -163,7 +163,7 @@ class XincangProductQueryTest {
assertEquals(0, p.declaredValue().amount().compareTo(new java.math.BigDecimal("12.34")));
assertEquals("9001", p.providerProductId());
assertEquals("1", p.rawState());
- assertEquals("正式产品", p.stateName());
+ assertEquals("正式产品", p.rawStatusName());
assertEquals("https://oss/x.png", p.imageUrl());
// 北京时间 → UTC:10:00 北京 = 02:00 UTC
assertEquals(Instant.parse("2026-11-01T02:00:00Z"), p.createdAt());
@@ -172,21 +172,21 @@ class XincangProductQueryTest {
/** count 决定是否还有下一页,不看本页是否满。 */
@Test
void pagingUsesCount() {
- Page more = adapter(productListing(listBody(ONE_ROW, "50")))
- .queryProducts(ctx(), ProductQuery.builder().pageSize(20).build());
+ Page more = adapter(productListing(listBody(ONE_ROW, "50")))
+ .query(ctx(), ProductQuery.builder().pageSize(20).build());
assertTrue(more.hasMore());
assertEquals("2", more.nextCursor());
- Page done = adapter(productListing(listBody(ONE_ROW, "1")))
- .queryProducts(ctx(), ProductQuery.builder().pageSize(20).build());
+ Page done = adapter(productListing(listBody(ONE_ROW, "1")))
+ .query(ctx(), ProductQuery.builder().pageSize(20).build());
assertFalse(done.hasMore());
assertNull(done.nextCursor());
}
@Test
void emptyDataIsLastPage() {
- Page page = adapter(productListing(listBody("", "0")))
- .queryProducts(ctx(), ProductQuery.builder().build());
+ Page page = adapter(productListing(listBody("", "0")))
+ .query(ctx(), ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
assertFalse(page.hasMore());
}
@@ -195,20 +195,20 @@ class XincangProductQueryTest {
@Test
void missingDimensionsBecomeZero() {
String row = "{\"product_no\":\"SKU-B\",\"state\":\"1\",\"weight_kg\":\"\"}";
- WarehouseProduct p = adapter(productListing(listBody(row, "1")))
- .queryProducts(ctx(), ProductQuery.builder().build()).items().get(0);
+ ProductInfo p = adapter(productListing(listBody(row, "1")))
+ .query(ctx(), ProductQuery.builder().build()).items().get(0);
assertEquals(0.0, p.lengthCm(), 0.001);
assertEquals(0.0, p.weightGrams(), 0.001);
- assertFalse(p.hasDimensions());
+ assertEquals(0.0, p.lengthCm(), 0.001);
}
/** 缺 product_no 的脏数据跳过,不让整页失败。 */
@Test
void skipsRowsWithoutSku() {
String row = "{\"id\":\"1\",\"chn_name\":\"无 SKU\"}";
- Page page = adapter(productListing(listBody(row, "1")))
- .queryProducts(ctx(), ProductQuery.builder().build());
+ Page page = adapter(productListing(listBody(row, "1")))
+ .query(ctx(), ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
}
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 cd27445..031d42d 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
@@ -26,6 +26,9 @@ public final class YqnConstants {
/** 商品创建 / 编辑(V1 推荐版)。 */
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
+
+ /** 批量查询 SKU 分页(API 113)。页码从 0 开始。 */
+ public static final String PATH_PRODUCT_FIND_PAGE = "/v1/product/findPage";
/** 创建销售订单(API 123)。 */
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/** 订单详情(API 128):按来源单号查完整订单。 */
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 9553651..02e5749 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
@@ -13,6 +13,7 @@ import common.ecommerce.yqn.dto.YqnInventoryDtos;
import common.ecommerce.yqn.dto.YqnLogisticsProductDtos;
import common.ecommerce.yqn.dto.YqnOrderDetailDtos;
import common.ecommerce.yqn.dto.YqnProductDtos;
+import common.ecommerce.yqn.dto.YqnProductQueryDtos;
import common.ecommerce.yqn.dto.YqnReturnProcessDtos;
import common.ecommerce.yqn.dto.YqnSaleReturnPlanDtos;
import common.ecommerce.yqn.dto.YqnSkuLabelDtos;
@@ -170,6 +171,35 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
json.stringAt(raw, "message"));
}
+ /**
+ * 批量查询仓侧商品资料(API 113,{@code /v1/product/findPage})。
+ *
+ * 入参 SKU 是仓侧 SKU,即建档时下发到 {@code sku} 字段的那串
+ * ({@link YqnProductMapper#skuOf}),不一定等于 OMS SKU。
+ * 运去哪这个接口没有条码 / 时间窗过滤,传了要本地拒绝而不是静默忽略。
+ *
+ * 页码从 0 开始——游标就是页码字符串,不做 ±1 换算。
+ */
+ @Override
+ public common.ecommerce.shared.support.Page<
+ common.ecommerce.warehouse.model.ProductInfo> query(
+ WarehouseContext ctx, common.ecommerce.warehouse.model.ProductQuery query) {
+ if (query.barcode() != null) {
+ throw new IllegalArgumentException(
+ "yqn product query does not support barcode filter");
+ }
+ if (query.hasCreatedRange()) {
+ throw new IllegalArgumentException(
+ "yqn product query does not support created time range");
+ }
+ YqnProductQueryDtos.FindPageRequest body = YqnProductQueryMapper.toRequest(query);
+ String raw = execute(ctx, YqnConstants.PATH_PRODUCT_FIND_PAGE, body,
+ "warehouse.product.query");
+ YqnProductQueryDtos.FindPageResponse resp =
+ json.fromJson(raw, YqnProductQueryDtos.FindPageResponse.class);
+ return YqnProductQueryMapper.toPage(resp);
+ }
+
// ------------------------------------------------------------------ 出库
@Override
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
index 4386fe5..70ab650 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
@@ -140,6 +140,8 @@ public final class YqnOutboundMapper {
new ArrayList(lines.size());
for (OutboundLine line : lines) {
YqnCreateOrderDtos.CreateOrderRequest.ProductItem item = new YqnCreateOrderDtos.CreateOrderRequest.ProductItem();
+ // 必须与建档时下发给仓方的 sku 一致(providerSku 优先,见 YqnProductMapper.skuOf)。
+ // 传 OMS SKU 而建档时用的是 providerSku 的话,仓方会报 SKU 不存在。
item.sku = line.providerSku() != null ? line.providerSku() : line.omsSku();
item.quantity = line.quantity();
item.lineNo = line.lineNo();
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
index 0f261cb..a08c189 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
@@ -85,7 +85,25 @@ public final class YqnProductMapper {
return req;
}
- /** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */
+ /**
+ * 下发到运去哪 {@code sku} 字段的值——整条链路都以这个为准。
+ *
+ * 规则:{@code providerSku} 优先,为空才回退 {@code omsSku}。
+ *
+ * 为什么这条规则要写在建档这里:运去哪把 {@code sku} 当唯一键落库,
+ * 之后查商品(API 113 {@code skuList})、建出库单(商品行 {@code sku})、
+ * 查库存({@code skuList})全都按这串匹配。所以:
+ *
+ * - 宿主给了 {@code providerSku}(如 {@code AP0000X9US0010601})→ 仓方库里存它,
+ * 之后所有查询 / 下单都必须传它,不等于 OMS SKU
+ * - 宿主没给(如 {@code ybtest})→ 仓方库里存的就是 OMS SKU,两者同名
+ *
+ *
+ * SDK 不做 OMS→仓侧 SKU 的转换:映射表在宿主手里(供应商编码规则、
+ * 按仓不同的前缀),SDK 猜不出来;静默转换会拿回空结果或错商品,比报错更难发现。
+ *
+ * 出库行同理,见 {@code YqnOutboundMapper}({@code providerSku} 优先)。
+ */
public static String skuOf(WarehouseProduct product) {
String providerSku = product.providerSku();
if (providerSku != null && !providerSku.trim().isEmpty()) {
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java
new file mode 100644
index 0000000..77aa590
--- /dev/null
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java
@@ -0,0 +1,175 @@
+package common.ecommerce.yqn.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.shared.support.Page;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.ProductInfo;
+import common.ecommerce.warehouse.model.ProductQuery;
+import common.ecommerce.yqn.dto.YqnProductQueryDtos;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * 运去哪商品查询映射(API 113,{@code /v1/product/findPage})。
+ *
+ * 页码从 0 开始——统一模型的游标语义是「下一页页码」,
+ * 这里用字符串页码原样透传,不做 ±1 换算,免得调用方和仓方口径对不上。
+ */
+public final class YqnProductQueryMapper {
+
+ /** 单页上限(文档:默认 100、最大 100)。 */
+ static final int MAX_PAGE_SIZE = 100;
+
+ /** 一次最多查多少个 SKU(文档:最大 100)。 */
+ static final int MAX_SKUS = 100;
+
+ private YqnProductQueryMapper() {
+ }
+
+ /** 统一查询条件 → 仓方请求。 */
+ public static YqnProductQueryDtos.FindPageRequest toRequest(ProductQuery query) {
+ YqnProductQueryDtos.FindPageRequest req = new YqnProductQueryDtos.FindPageRequest();
+ if (!query.providerSkus().isEmpty()) {
+ if (query.providerSkus().size() > MAX_SKUS) {
+ throw new IllegalArgumentException(
+ "yqn product query accepts at most " + MAX_SKUS + " skus, got "
+ + query.providerSkus().size());
+ }
+ req.skuList = new ArrayList(query.providerSkus());
+ }
+ req.pageSize = pageSize(query.pageSize());
+ req.pageNum = pageNum(query.cursor());
+ return req;
+ }
+
+ /** 每页条数:默认 100、上限 100。 */
+ static int pageSize(int requested) {
+ if (requested <= 0) {
+ return MAX_PAGE_SIZE;
+ }
+ return Math.min(requested, MAX_PAGE_SIZE);
+ }
+
+ /** 游标 → 页码;从 0 开始,空游标即第 0 页。 */
+ static int pageNum(String cursor) {
+ if (cursor == null || cursor.trim().isEmpty()) {
+ return 0;
+ }
+ try {
+ int v = Integer.parseInt(cursor.trim());
+ return Math.max(v, 0);
+ } catch (NumberFormatException e) {
+ return 0;
+ }
+ }
+
+ /** 响应 → 分页结果。 */
+ public static Page toPage(YqnProductQueryDtos.FindPageResponse response) {
+ if (response == null || response.data == null
+ || response.data.content == null || response.data.content.isEmpty()) {
+ return Page.empty();
+ }
+ List out = new ArrayList(response.data.content.size());
+ for (YqnProductQueryDtos.ProductRow row : response.data.content) {
+ ProductInfo info = toInfo(row);
+ if (info != null) {
+ out.add(info);
+ }
+ }
+ return Page.of(out, nextCursor(response.data));
+ }
+
+ /**
+ * 下一页游标。
+ *
+ * 优先用 {@code last}(仓方明确给了是否末页);缺失时用
+ * {@code number+1 < totalPages} 推断。两者都给不出时按「本页是否满页」兜底。
+ */
+ static String nextCursor(YqnProductQueryDtos.ProductPage page) {
+ if (page == null) {
+ return null;
+ }
+ if (page.last != null) {
+ if (page.last) {
+ return null;
+ }
+ int current = page.number == null ? 0 : page.number;
+ return String.valueOf(current + 1);
+ }
+ if (page.number != null && page.totalPages != null) {
+ return page.number + 1 < page.totalPages
+ ? String.valueOf(page.number + 1) : null;
+ }
+ if (page.size != null && page.numberOfElements != null) {
+ return page.numberOfElements < page.size
+ ? null : String.valueOf((page.number == null ? 0 : page.number) + 1);
+ }
+ return null;
+ }
+
+ /** 一行 → 统一商品资料;没有 SKU 的行跳过。 */
+ static ProductInfo toInfo(YqnProductQueryDtos.ProductRow row) {
+ if (row == null || row.sku == null || row.sku.trim().isEmpty()) {
+ return null;
+ }
+ ProductInfo.Builder b = ProductInfo.builder()
+ .sourceProvider(WarehouseProvider.YQN)
+ .providerSku(row.sku.trim())
+ .customItemNo(trimToNull(row.customItemNo))
+ .barcode(trimToNull(row.upc))
+ .name(trimToNull(row.name))
+ .nameEn(trimToNull(row.nameEn))
+ .description(trimToNull(row.description))
+ // 文档:1 成品 / 2 配件 / 3 耗材;未给保持 -1
+ .productType(row.productType == null ? -1 : row.productType)
+ .lengthCm(numberOf(row.length))
+ .widthCm(numberOf(row.width))
+ .heightCm(numberOf(row.height))
+ .weightGrams(numberOf(row.weight))
+ .itemLengthCm(row.itemLength)
+ .itemWidthCm(row.itemWidth)
+ .itemHeightCm(row.itemHeight)
+ .packedQuantity(row.packedQty)
+ .packedLengthCm(row.packedLength)
+ .packedWidthCm(row.packedWidth)
+ .packedHeightCm(row.packedHeight)
+ .packedWeightGrams(row.packedWeight)
+ .requireSn(flagOf(row.isRequireSn))
+ .remark(trimToNull(row.remark));
+
+ // 成本:文档标 integer,但货币是另一列;没有币种时不造 Money
+ if (row.cost != null && trimToNull(row.currency) != null) {
+ b.cost(Money.of(java.math.BigDecimal.valueOf(row.cost), row.currency.trim()));
+ }
+ return b.build();
+ }
+
+ /**
+ * 文档把 {@code isRequireSn} 标成 string,真机可能是数字。
+ * 统一按「是不是 1 / "1" / true」判,认不出返回 null(不猜)。
+ */
+ static Boolean flagOf(String raw) {
+ if (raw == null) {
+ return null;
+ }
+ String v = raw.trim();
+ if ("1".equals(v) || "true".equalsIgnoreCase(v) || "Y".equalsIgnoreCase(v)) {
+ return Boolean.TRUE;
+ }
+ if ("0".equals(v) || "false".equalsIgnoreCase(v) || "N".equalsIgnoreCase(v)) {
+ return Boolean.FALSE;
+ }
+ return null;
+ }
+
+ private static double numberOf(Double v) {
+ return v == null ? 0 : v;
+ }
+
+ private static String trimToNull(String v) {
+ return v == null || v.trim().isEmpty() ? null : v.trim();
+ }
+}
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java
new file mode 100644
index 0000000..bce2159
--- /dev/null
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java
@@ -0,0 +1,112 @@
+package common.ecommerce.yqn.dto;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+import java.util.List;
+
+/**
+ * 运去哪报文结构:批量查询 SKU 分页(API 113,{@code /v1/product/findPage})。
+ *
+ * 一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。
+ *
+ * 页码从 0 开始(文档:「起始页为从0开始」),与其它分页接口不同。
+ * {@code pageSize} 默认 100、最大 100。
+ */
+public final class YqnProductQueryDtos {
+
+ private YqnProductQueryDtos() {
+ }
+
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class FindPageRequest {
+
+ /** 仓侧 SKU 列表,最大 100 个。 */
+ public List skuList;
+ /** 每页大小,默认 100、最大 100。 */
+ public Integer pageSize;
+ /** 页码,从 0 开始。 */
+ public Integer pageNum;
+ }
+
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class FindPageResponse {
+ public Integer code;
+ public String message;
+ public Integer statusCode;
+ public Integer status;
+ public ProductPage data;
+ }
+
+ /** Spring Data 风格的分页载荷。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class ProductPage {
+ public Pageable pageable;
+ public Integer totalElements;
+ public Integer totalPages;
+ public Boolean last;
+ public Boolean first;
+ public Integer numberOfElements;
+ public Integer size;
+ public Integer number;
+ public Boolean empty;
+ public List content;
+ }
+
+ /** 分页元信息(只取用得到的几个)。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class Pageable {
+ public Integer pageNumber;
+ public Integer pageSize;
+ public Integer offset;
+ public Boolean paged;
+ public Boolean unpaged;
+ }
+
+ /** 一行商品。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class ProductRow {
+ public String sku;
+ public String customItemNo;
+ public String upc;
+ /** 1 成品 / 2 配件 / 3 耗材。 */
+ public Integer productType;
+ public String name;
+ public String nameEn;
+ public String description;
+
+ /** 整箱尺寸(cm)与重量(g)。 */
+ public Double length;
+ public Double width;
+ public Double height;
+ public Double weight;
+
+ /** 单品尺寸(cm)。 */
+ public Double itemLength;
+ public Double itemWidth;
+ public Double itemHeight;
+
+ /** 装箱数量 / 外箱尺寸重量。 */
+ public Integer packedQty;
+ public Double packedLength;
+ public Double packedWidth;
+ public Double packedHeight;
+ public Double packedWeight;
+
+ public Double cost;
+ public String currency;
+ public String remark;
+
+ /** 是否需要 SN;文档标 string({@code "0"} / {@code "1"})。 */
+ public String isRequireSn;
+
+ /** 商品形态。 */
+ public Integer saleType;
+ public String parentErpsku;
+ public Integer standardQuantity;
+
+ public String customName;
+ public String customNameEn;
+ /** 是否启用。 */
+ public Integer enable;
+ }
+}
diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java
new file mode 100644
index 0000000..7286e17
--- /dev/null
+++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java
@@ -0,0 +1,190 @@
+package common.ecommerce.yqn.adapter;
+
+import common.ecommerce.http.JacksonJsonCodec;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.support.Page;
+import common.ecommerce.shared.testkit.RecordingTransport;
+import common.ecommerce.shared.testkit.Responses;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.ProductInfo;
+import common.ecommerce.warehouse.model.ProductQuery;
+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 static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 商品查询(API 113,{@code /v1/product/findPage})映射。
+ *
+ * 重点:页码从 0 开始、单页上限 100、{@code last} 优先判断翻页。
+ */
+class YqnProductQueryTest {
+
+ private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC);
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("YQN-WH", WarehouseProvider.YQN, "RF_NY_US",
+ WarehouseConnection.of(YqnConstants.PR_BASE_URL,
+ ChannelSecret.builder().appSecret("key-1").build()),
+ "req-product-query", CLOCK);
+ }
+
+ private static RecordingTransport stub(String body) {
+ return RecordingTransport.create()
+ .route(YqnConstants.PATH_PRODUCT_FIND_PAGE, req -> Responses.ok(body));
+ }
+
+ // ------------------------------------------------------------ 请求
+
+ /** 游标为空 → 第 0 页(不是第 1 页)。 */
+ @Test
+ void emptyCursorMeansPageZero() {
+ assertEquals(0, YqnProductQueryMapper.pageNum(null));
+ assertEquals(0, YqnProductQueryMapper.pageNum(" "));
+ assertEquals(0, YqnProductQueryMapper.pageNum("abc"));
+ assertEquals(3, YqnProductQueryMapper.pageNum("3"));
+ // 负数归 0
+ assertEquals(0, YqnProductQueryMapper.pageNum("-1"));
+ }
+
+ /** 单页上限 100。 */
+ @Test
+ void pageSizeCappedAt100() {
+ assertEquals(100, YqnProductQueryMapper.pageSize(0));
+ assertEquals(100, YqnProductQueryMapper.pageSize(500));
+ assertEquals(50, YqnProductQueryMapper.pageSize(50));
+ }
+
+ @Test
+ void mapsSkusAndPaging() {
+ common.ecommerce.yqn.dto.YqnProductQueryDtos.FindPageRequest req =
+ YqnProductQueryMapper.toRequest(
+ ProductQuery.builder().providerSku("SKU-1").providerSku("SKU-2")
+ .pageSize(20).cursor("2").build());
+
+ assertEquals(java.util.Arrays.asList("SKU-1", "SKU-2"), req.skuList);
+ assertEquals(Integer.valueOf(20), req.pageSize);
+ assertEquals(Integer.valueOf(2), req.pageNum);
+ }
+
+ @Test
+ void moreThan100SkusRejected() {
+ ProductQuery.Builder b = ProductQuery.builder();
+ for (int i = 0; i < 101; i++) {
+ b.providerSku("SKU-" + i);
+ }
+ assertThrows(IllegalArgumentException.class, () -> b.build());
+ }
+
+ /** 运去哪这个接口没有条码 / 时间窗过滤,传了要本地拒绝。 */
+ @Test
+ void unsupportedFiltersAreRejected() {
+ assertThrows(IllegalArgumentException.class,
+ () -> new YqnAdapter(stub("{}"), new JacksonJsonCodec()).query(ctx(),
+ ProductQuery.builder().barcode("UPC1").build()));
+
+ assertThrows(IllegalArgumentException.class,
+ () -> new YqnAdapter(stub("{}"), new JacksonJsonCodec()).query(ctx(),
+ ProductQuery.builder()
+ .createdAfter(Instant.parse("2026-01-01T00:00:00Z"))
+ .createdBefore(Instant.parse("2026-02-01T00:00:00Z"))
+ .build()));
+ }
+
+ // ------------------------------------------------------------ 响应
+
+ private static String pageBody(boolean last, int number, Integer totalPages) {
+ return "{\"code\":200,\"message\":\"ok\",\"data\":{"
+ + "\"pageable\":{\"pageNumber\":" + number + ",\"pageSize\":100},"
+ + "\"numberOfElements\":1,\"size\":100,\"number\":" + number + ","
+ + "\"last\":" + last + ","
+ + (totalPages == null ? "" : "\"totalPages\":" + totalPages + ",")
+ + "\"content\":[{\"sku\":\"SKU-1\",\"name\":\"商品1\",\"nameEn\":\"P1\","
+ + "\"upc\":\"UPC1\",\"productType\":1,\"length\":10,\"width\":8,\"height\":6,"
+ + "\"weight\":500,\"packedQty\":12,\"isRequireSn\":\"0\","
+ + "\"cost\":9.5,\"currency\":\"USD\",\"enable\":1}]}}";
+ }
+
+ @Test
+ void mapsRow() {
+ Page page = YqnProductQueryMapper.toPage(
+ new JacksonJsonCodec().fromJson(pageBody(true, 0, null),
+ common.ecommerce.yqn.dto.YqnProductQueryDtos.FindPageResponse.class));
+
+ assertEquals(1, page.size());
+ ProductInfo p = page.items().get(0);
+ assertEquals("SKU-1", p.providerSku());
+ assertEquals("商品1", p.name());
+ assertEquals("UPC1", p.barcode());
+ assertEquals(1, p.productType());
+ assertEquals(10.0, p.lengthCm());
+ assertEquals(500.0, p.weightGrams());
+ assertEquals(Integer.valueOf(12), p.packedQuantity());
+ assertEquals(Boolean.FALSE, p.requireSn());
+ assertEquals(WarehouseProvider.YQN, p.sourceProvider());
+ // 成本带币种才成 Money
+ assertEquals(0, new java.math.BigDecimal("9.5").compareTo(p.cost().amount()));
+ assertEquals("USD", p.cost().currencyCode());
+ assertFalse(page.hasMore());
+ }
+
+ /** {@code last=false} → 游标 = number + 1。 */
+ @Test
+ void nextCursorUsesLast() {
+ assertEquals("1", YqnProductQueryMapper.nextCursor(page(0, false, null)));
+ assertNull(YqnProductQueryMapper.nextCursor(page(3, true, null)));
+ }
+
+ /** {@code last} 缺失时用 number + 1 < totalPages 推断。 */
+ @Test
+ void nextCursorFallsBackToTotalPages() {
+ assertEquals("2", YqnProductQueryMapper.nextCursor(page(1, null, 3)));
+ assertNull(YqnProductQueryMapper.nextCursor(page(2, null, 3)));
+ }
+
+ private static common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductPage page(
+ int number, Boolean last, Integer totalPages) {
+ common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductPage p =
+ new common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductPage();
+ p.number = number;
+ p.last = last;
+ p.totalPages = totalPages;
+ p.size = 100;
+ p.numberOfElements = 100;
+ return p;
+ }
+
+ /** 没有 SKU 的行跳过,不整页失败。 */
+ @Test
+ void rowsWithoutSkuAreSkipped() {
+ common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductRow bad =
+ new common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductRow();
+ bad.sku = " ";
+ assertNull(YqnProductQueryMapper.toInfo(bad));
+ assertNull(YqnProductQueryMapper.toInfo(null));
+ }
+
+ @Test
+ void adapterQueriesProducts() {
+ RecordingTransport transport = stub(pageBody(true, 0, null));
+
+ Page page = new YqnAdapter(transport, new JacksonJsonCodec())
+ .query(ctx(), ProductQuery.builder().providerSku("SKU-1").build());
+
+ assertEquals(1, page.size());
+ String body = transport.lastDataRequest().body();
+ assertTrue(body.contains("\"skuList\":[\"SKU-1\"]"), body);
+ // 首页必须是 pageNum=0
+ assertTrue(body.contains("\"pageNum\":0"), body);
+ }
+}
diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java
index 3ce3917..bb82be3 100644
--- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java
+++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java
@@ -75,6 +75,39 @@ class YqnReadOnlyProbeTest {
});
}
+ /**
+ * 商品查询(API 113)。
+ *
+ * 不传 {@code skuList} 时仓方返回全量第一页——正好用来验「页码从 0 开始」。
+ * 用 {@code -Dyqn.probe.skuList=A,B} 可以顺带验按 SKU 过滤。
+ */
+ @Test
+ void probeProductQuery() {
+ assumeToken();
+ run("POST /v1/product/findPage", () -> {
+ String raw = System.getProperty("yqn.probe.skuList", "");
+ common.ecommerce.warehouse.model.ProductQuery.Builder q =
+ common.ecommerce.warehouse.model.ProductQuery.builder().pageSize(5);
+ if (!raw.trim().isEmpty()) {
+ q.providerSkus(java.util.Arrays.asList(raw.split(",")));
+ }
+ common.ecommerce.shared.support.Page<
+ common.ecommerce.warehouse.model.ProductInfo> page =
+ adapter().query(ctx(), q.build());
+ System.out.println("[products] 本页 " + page.size()
+ + " hasMore=" + page.hasMore() + " nextCursor=" + page.nextCursor());
+ for (int i = 0; i < Math.min(page.size(), 3); i++) {
+ common.ecommerce.warehouse.model.ProductInfo p = page.items().get(i);
+ System.out.println(" [" + i + "] sku=" + p.providerSku()
+ + " name=" + p.name()
+ + " lwh=" + p.lengthCm() + "x" + p.widthCm() + "x" + p.heightCm()
+ + " weight=" + p.weightGrams()
+ + " packedQty=" + p.packedQuantity()
+ + " productType=" + p.productType());
+ }
+ });
+ }
+
/** 物流产品:验证「GET 但参数写在 query」这条路是否被仓方接受。 */
@Test
void probeLogisticsProducts() {