Compare commits

...

8 Commits

Author SHA1 Message Date
chenchuchuan 635fc09883 Merge branch 'master' of http://124.222.6.97:3000/chencc/common-ecommerce 4 days ago
chenchuchuan 5bbfb33261 docs: 写清 SKU 口径——建档下发的那串,之后全程用它 4 days ago
chenchuchuan b5e94c1157 feat: 运去哪 / 易达云 商品查询接口 4 days ago
chenchuchuan efc248c27d docs: 同步 CR 修复后的文档 4 days ago
chenchuchuan 7629a52ab8 fix(edayun): 修 CR 发现的三个真 bug 与若干语义问题 4 days ago
chenchuchuan 8dabf9fb1b test(edayun): 补 SDK 装配链路冒烟(离线,按业务场景) 4 days ago
chenchuchuan 97be2aebe9 docs(edayun): SKU 标接口不是未启用,是仓方内部报错 4 days ago
chenchuchuan 5dce79ea32 fix(edayun): 修正 SKU 标端点路径(去掉 ContentType 后缀) 4 days ago
  1. 5
      docs-warehouse/architecture.md
  2. 79
      docs-warehouse/edayun/README.md
  3. 7
      docs-warehouse/edayun/TODO.md
  4. 31
      docs-warehouse/yqn/README.md
  5. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java
  6. 18
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java
  7. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  8. 21
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java
  9. 7
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
  10. 423
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java
  11. 147
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java
  12. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  13. 7
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  14. 71
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  15. 1
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java
  16. 20
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java
  17. 2
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java
  18. 20
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java
  19. 153
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java
  20. 6
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java
  21. 35
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java
  22. 40
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java
  23. 2
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java
  24. 4
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
  25. 96
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java
  26. 2
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java
  27. 8
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java
  28. 6
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java
  29. 215
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java
  30. 35
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java
  31. 33
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java
  32. 2
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java
  33. 3
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java
  34. 106
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java
  35. 436
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java
  36. 3
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  37. 30
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  38. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
  39. 20
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
  40. 175
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java
  41. 112
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java
  42. 190
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java
  43. 33
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java

5
docs-warehouse/architecture.md

@ -85,7 +85,7 @@ public enum YqnOutboundStatus {
`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略, `sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略,
调用方不应假定排序一定生效。 调用方不应假定排序一定生效。
`WarehouseCapability`(26 个): `WarehouseCapability`(27 个):
| 能力 | 说明 | 运去哪 | 信仓 | | 能力 | 说明 | 运去哪 | 信仓 |
|---|---|:---:|:---:| |---|---|:---:|:---:|
@ -99,7 +99,7 @@ public enum YqnOutboundStatus {
| `BOX_LABEL` | 入库箱标(异步) | ✅ | — | | `BOX_LABEL` | 入库箱标(异步) | ✅ | — |
| `SKU_LABEL` | SKU 标(异步) | ✅ | — | | `SKU_LABEL` | SKU 标(异步) | ✅ | — |
| `LOGISTICS_PRODUCT` | 物流产品清单 | ✅ | ✅ | | `LOGISTICS_PRODUCT` | 物流产品清单 | ✅ | ✅ |
| `WAREHOUSE_DIRECTORY` | 仓库目录 | ✅ | — | | `DIRECTORY` | 仓库 / 承运商目录 | ✅ | — |
| `WEBHOOK` | 状态回调 | ✅ | — | | `WEBHOOK` | 状态回调 | ✅ | — |
| `TRANSFER` | 仓间调拨 | ✅ | ✅ | | `TRANSFER` | 仓间调拨 | ✅ | ✅ |
| `RETURN` | 退货发起 / 查询 | ✅ | — | | `RETURN` | 退货发起 / 查询 | ✅ | — |
@ -107,6 +107,7 @@ public enum YqnOutboundStatus {
| `TRACKING` | 物流轨迹 | ✅ | — | | `TRACKING` | 物流轨迹 | ✅ | — |
| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — | | `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
| `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — | | `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — |
| `CASE_MARK_PRINT` | 箱唛打印(同步 PDF) | — | — |
| `DESTRUCTION` | 销毁 / 报废 | ✅ | — | | `DESTRUCTION` | 销毁 / 报废 | ✅ | — |
| `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — | | `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — |
| `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — | | `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — |

79
docs-warehouse/edayun/README.md

@ -8,6 +8,7 @@
| 适配器 / 工厂 | ✅ 类型就绪,能力位为空 | | 适配器 / 工厂 | ✅ 类型就绪,能力位为空 |
| 获取 token | ✅ 已对接(`POST /oauth/token`) | | 获取 token | ✅ 已对接(`POST /oauth/token`) |
| 创建产品 | ✅ 已对接(`POST /webApi/skuInfo/v1/createProduct`) | | 创建产品 | ✅ 已对接(`POST /webApi/skuInfo/v1/createProduct`) |
| 商品查询 | ✅ 已对接(`POST /webApi/skuInfo/v1/listProductPage`) |
| 创建出库单 | ✅ 已对接(`POST /webApi/order/v1/createOrder`) | | 创建出库单 | ✅ 已对接(`POST /webApi/order/v1/createOrder`) |
| 查询出库单 | ✅ 已对接(`POST /webApi/order/v1/getOrderInfo`) | | 查询出库单 | ✅ 已对接(`POST /webApi/order/v1/getOrderInfo`) |
| 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) | | 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) |
@ -28,7 +29,7 @@
| 物流产品清单 | ✅ 已对接(`POST /webApi/order/listByLogisticProductHasPerm`) | | 物流产品清单 | ✅ 已对接(`POST /webApi/order/listByLogisticProductHasPerm`) |
| 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) | | 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) |
| 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) | | 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) |
| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** | | 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMark`),**真机未启用** |
| 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) | | 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) |
| 仓库清单 | ✅ 已对接(`warehouse/listWarehouseHasPerm` + `warehouse/listActive`) | | 仓库清单 | ✅ 已对接(`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=... ... -Dedayun.probe.write=true -Dedayun.probe.token=... -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=...
``` ```
## 商品查询
```
POST /webApi/skuInfo/v1/listProductPage → Page<ProductInfo>
```
### 三个坑
**1. SKU 是逗号拼接的单个字符串,且一次最多 50 个。**
```java
req.skuCode = String.join(",", query.providerSkus()); // "A,B,C"
```
统一模型是 `List<String>`,超 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` 都没有) | | `process(ctx, cmd)` | ❌ 要仓侧明细行 id,而详情响应里**没有行 id**(`checkList` / `skuList` / `shelfList` 都没有) |
`queryReturns` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。 `process` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。
### 探针 ### 探针
@ -1154,7 +1204,7 @@ POST /webApi/track/getTrackInfoList → List<TrackEvent> / TrackingInfo
| 端点 | 实际打印 | 我们的方法 | 能力位 | | 端点 | 实际打印 | 我们的方法 | 能力位 |
|---|---|---|---| |---|---|---|---|
| `/webApi/skuInfo/v2/printBarcode` | **箱唛**(外箱标) | `printCaseMarks(...)` | `CASE_MARK_PRINT` | | `/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 都写了这条提醒。 **不要被路径名误导**。代码里两个方法的 javadoc 都写了这条提醒。
@ -1192,10 +1242,10 @@ POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel
仓方其它校验:缺 `productInfos` →「产品信息不能为空」、缺 `pageSize` → 仓方其它校验:缺 `productInfos` →「产品信息不能为空」、缺 `pageSize` →
「纸张尺寸不能为空」、SKU 不存在 →「sku=XXX信息不存在」。 「纸张尺寸不能为空」、SKU 不存在 →「sku=XXX信息不存在」。
### SKU 标(newPrintCaseMarkContentType) ### SKU 标(newPrintCaseMark)
``` ```
POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel POST /webApi/entryInfo/v1/newPrintCaseMark → WarehouseLabel
``` ```
**真机未启用**:PR 环境该路径报「接口不存在或未启用」,去掉 **真机未启用**:PR 环境该路径报「接口不存在或未启用」,去掉
@ -1317,6 +1367,23 @@ DTO 按 `List` 收。
`listWarehouseHasPerm` 只有 17 个。DTO 只声明统一模型用得上的十几个—— `listWarehouseHasPerm` 只有 17 个。DTO 只声明统一模型用得上的十几个——
Jackson 会忽略未知字段。 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 猜不出来。查错了会拿到空结果或错的商品,比报错更难发现。
## 待确认(问易达云) ## 待确认(问易达云)
| # | 要确认 | | # | 要确认 |

7
docs-warehouse/edayun/TODO.md

@ -5,6 +5,7 @@
## 待仓方确认 ## 待仓方确认
| # | 问题 | 当前处理 | 影响 | | # | 问题 | 当前处理 | 影响 |
|---|---|---|---|
| 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 | | 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 |
| 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 | | 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 |
| 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 | | 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 |
@ -37,7 +38,7 @@
| 35 | 入库明细接口不回仓库 / 创建时间 / 到仓时间 / 箱号 | 仓库用 OMS 配置;时间与箱明细为 null | 拿不到完整单据,需要 entryInfo 单头查询接口 | | 35 | 入库明细接口不回仓库 / 创建时间 / 到仓时间 / 箱号 | 仓库用 OMS 配置;时间与箱明细为 null | 拿不到完整单据,需要 entryInfo 单头查询接口 |
| 36 | 是否有入库单列表 / 时间窗查询 | `query()` 的 cursor 当 entryCode 用 | 无法做增量同步,只能按单号轮询 | | 36 | 是否有入库单列表 / 时间窗查询 | `query()` 的 cursor 当 entryCode 用 | 无法做增量同步,只能按单号轮询 |
| 37 | `forecastWeight` / `weight` 是克、`firstWeight` 是千克 | 未映射(统一模型没有行级重量) | 想按箱对账重量时需要 | | 37 | `forecastWeight` / `weight` 是克、`firstWeight` 是千克 | 未映射(统一模型没有行级重量) | 想按箱对账重量时需要 |
| 38 | 退货单**没有列表查询** | `queryReturns` 显式拒绝 | 无法批量同步退货单 | | 38 | ~~退货单没有列表查询~~ ✅ 已对接 `selectRmaInfoList` | `queryReturns(ReturnQuery)` | 无 |
| 39 | 退货 `skus[].command` 码表(文档只写「1 上架 / 2 销毁」) | 只确定 DESTROY→2,其余都归 1 | 非销毁类处理方式可能与仓方预期不符 | | 39 | 退货 `skus[].command` 码表(文档只写「1 上架 / 2 销毁」) | 只确定 DESTROY→2,其余都归 1 | 非销毁类处理方式可能与仓方预期不符 |
| 40 | 退货 `valueAddedService` / `shelveSkuCode` / `catalog` / `picUrls` 码值与语义 | 不下发 | 重新包装 / 换标上架等场景发不了 | | 40 | 退货 `valueAddedService` / `shelveSkuCode` / `catalog` / `picUrls` 码值与语义 | 不下发 | 重新包装 / 换标上架等场景发不了 |
| 41 | 未妥投 / 返邮 / FBA 三种退货方式要不要做 | 只实现 `returnType=2` | 买家退货的返邮面单、FBA 退货都得人工 | | 41 | 未妥投 / 返邮 / FBA 三种退货方式要不要做 | 只实现 `returnType=2` | 买家退货的返邮面单、FBA 退货都得人工 |
@ -64,10 +65,10 @@
| 62 | PR 环境查不到任何轨迹(连出库单里的真实跟踪号都「未匹配到轨迹」) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 | | 62 | PR 环境查不到任何轨迹(连出库单里的真实跟踪号都「未匹配到轨迹」) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 |
| 63 | 轨迹接口一次可查多个跟踪号,统一模型只有单号口径 | 逐个查、按单号匹配 | 批量查只能循环调用 | | 63 | 轨迹接口一次可查多个跟踪号,统一模型只有单号口径 | 逐个查、按单号匹配 | 批量查只能循环调用 |
| 64 | 轨迹的 `eventStatus` 取值(文档示例是 `"string"` 占位) | 原样透传 | 宿主无法按事件类型分支 | | 64 | 轨迹的 `eventStatus` 取值(文档示例是 `"string"` 占位) | 原样透传 | 宿主无法按事件类型分支 |
| 65 | 条码打印的纸张尺寸只有 4 档(7×3/10×6/6×4/A4),与入库贴标的 14 种不重叠 | 独立枚举 `BarcodePaperSize` | 宿主换标签纸时要选对枚举 | | 65 | 箱唛纸张尺寸只有 4 档,与入库贴标的 14 种不重叠 | 独立枚举 `CaseMarkPaperSize`(按实测尺寸命名) | 宿主换标签纸时要选对枚举 |
| 66 | 条码文件地址的**有效期**未知(OSS 链接) | 原样返回,不缓存 | 宿主存旧链接可能 403 | | 66 | 条码文件地址的**有效期**未知(OSS 链接) | 原样返回,不缓存 | 宿主存旧链接可能 403 |
| 67 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 | | 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`,按映射表走 | 无(已规避) | | 69 | SKU 标纸张码值 4/2/5 不连续 | 独立枚举 `EdayunSkuLabelPaper`,按映射表走 | 无(已规避) |
| 72 | **`printBarcode` 的 pageSize=2 / pageSize=3 文档标称与实际相反**(文档 2=6×4cm、3=A4;实测 2=100×150mm、3=60×40mm) | 枚举按实测尺寸命名,码值不变 | 按文档标称选纸会打错 | | 72 | **`printBarcode` 的 pageSize=2 / pageSize=3 文档标称与实际相反**(文档 2=6×4cm、3=A4;实测 2=100×150mm、3=60×40mm) | 枚举按实测尺寸命名,码值不变 | 按文档标称选纸会打错 |
| 73 | 两个端点名与实际语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标) | 代码按实际语义命名并在 javadoc 标注 | 无(已规避) | | 73 | 两个端点名与实际语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标) | 代码按实际语义命名并在 javadoc 标注 | 无(已规避) |

31
docs-warehouse/yqn/README.md

@ -206,6 +206,36 @@ WarehouseConnection.of(
**未指定时按 UTC 解释,不猜成北京时间。** **未指定时按 UTC 解释,不猜成北京时间。**
## 9.5 商品查询(API 113)
```
POST /v1/product/findPage → Page<ProductInfo>
```
### 页码从 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. 联调探针 ## 10. 联调探针
两个探针,默认跳过: 两个探针,默认跳过:
@ -235,4 +265,5 @@ mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \
| 库存调整 | 运去哪无此接口 | | 库存调整 | 运去哪无此接口 |
| 换货 / 无头件 / BOL | 仓方无对应接口 | | 换货 / 无头件 / BOL | 仓方无对应接口 |
| 退货查询列表 | 只有按单号查,无列表接口 | | 退货查询列表 | 只有按单号查,无列表接口 |
| 商品查询的条码 / 时间窗过滤 | API 113 只接受 skuList 与分页 |
| 出库列表 / 时间窗查询 | 只有按单号查 | | 出库列表 / 时间窗查询 | 只有按单号查 |

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java

@ -21,7 +21,7 @@ public interface CaseMarkPrintCapable extends WarehouseAdapter {
* *
* @return 已生成的文件(地址或 base64);仓方未返回文件时抛出异常,不返回 null * @return 已生成的文件(地址或 base64);仓方未返回文件时抛出异常,不返回 null
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不声明 {@code BARCODE_PRINT} * 该仓不声明 {@code CASE_MARK_PRINT}
*/ */
WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd); WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd);
} }

18
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java

@ -44,22 +44,18 @@ public interface WarehouseDirectoryCapable extends WarehouseAdapter {
* <p>与 {@link #carriers} 的区别:那个只给一串物流方式码,这个是承运商 → * <p>与 {@link #carriers} 的区别:那个只给一串物流方式码,这个是承运商 →
* 物流服务的两层结构,宿主要做下拉框或按承运商筛选时用这个。</p> * 物流服务的两层结构,宿主要做下拉框或按承运商筛选时用这个。</p>
* *
* <p>默认走 {@link #carriers} 把码包装成没有名称的条目;能给出结构的仓应覆盖。</p> * <p><b>默认不支持</b>,不拿 {@link #carriers} 的码硬凑成两层结构——
* 那样会得到 {@code carrierId == nameEn == "FEDEX-G"} 这种假条目,
* 宿主若按类注释「下单时 carrierName 填 nameEn()」使用,就会把物流方式码
* 当成承运商名发出去。能给出真实结构的仓自己覆盖。</p>
* *
* @return 承运商列表;仓方返回空时为 empty list(不是错误) * @return 承运商列表;仓方返回空时为 empty list(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不声明 {@code DIRECTORY} 或没有承运商接口 * 该仓没有承运商目录接口
*/ */
default List<common.ecommerce.warehouse.model.WarehouseCarrier> carrierDirectory( default List<common.ecommerce.warehouse.model.WarehouseCarrier> carrierDirectory(
WarehouseContext ctx) { WarehouseContext ctx) {
List<common.ecommerce.warehouse.model.WarehouseCarrier> out = throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
new java.util.ArrayList<common.ecommerce.warehouse.model.WarehouseCarrier>(); common.ecommerce.warehouse.enums.WarehouseCapability.DIRECTORY);
for (String code : carriers(ctx)) {
out.add(common.ecommerce.warehouse.model.WarehouseCarrier.builder()
.carrierId(code)
.nameEn(code)
.build());
}
return out;
} }
} }

20
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java

@ -19,6 +19,24 @@ import java.util.Objects;
public final class WarehouseProduct { public final class WarehouseProduct {
private final String omsSku; private final String omsSku;
/**
* 仓侧 SKU——<b>建档时下发给仓方的那串,之后所有查询 / 下单都用它</b>。
*
* <p>各适配器在建档时按「{@code providerSku} 优先,为空才回退 {@link #omsSku}」
* 决定仓方库里存什么,字段名各不相同(易达云 {@code skuCode}、
* 运去哪 {@code sku})。仓方一旦落库,<b>之后按 SKU 查询、下单、查库存都必须传
* 同一串</b>——所以它不一定等于 {@link #omsSku()}:</p>
*
* <ul>
* <li>给了 {@code providerSku}(如 {@code AP0000X9US0010601})→ 仓方存它,
* 后续传入 {@code ProductQuery.providerSkus()} / {@code InventoryQuery.providerSkus()}
* / {@code OutboundLine.providerSku()} 时也必须是它</li>
* <li>没给 → 仓方存的就是 {@code omsSku},两者同名</li>
* </ul>
*
* <p>SDK <b>不做 OMS→仓侧 SKU 的转换</b>:映射表在宿主手里,静默转换会拿回
* 空结果或错商品,比报错更难发现。</p>
*/
private final String providerSku; private final String providerSku;
private final String customItemNo; private final String customItemNo;
private final String barcode; private final String barcode;
@ -233,7 +251,7 @@ public final class WarehouseProduct {
return omsSku; return omsSku;
} }
/** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。 */ /** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。详见字段注释。 */
public String providerSku() { public String providerSku() {
return providerSku; return providerSku;
} }

21
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java

@ -3,12 +3,31 @@ package common.ecommerce.warehouse.capability;
import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
/** 商品建档 / 更新能力。 */ /** 商品建档 / 更新 / 查询能力。 */
public interface WarehouseProductCapable extends WarehouseAdapter { public interface WarehouseProductCapable extends WarehouseAdapter {
/** 在某仓创建或更新一个 SKU。 */ /** 在某仓创建或更新一个 SKU。 */
ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product); ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product);
/**
* 批量 / 分页查询仓侧商品资料。
*
* <p>查询用的 SKU 是<b>仓侧 SKU</b>(建档时下发的那串,通常是
* {@code WarehouseProduct.providerSku()},没给映射时等于 OMS SKU)。
* SDK 不做 OMS→仓侧 SKU 的转换——映射表在宿主手里,静默转换会让结果对不上。</p>
*
* <p>默认不支持:只有提供商品查询接口的仓才覆盖。</p>
*
* @return 分页结果;仓方无数据时为空页(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不提供商品查询
*/
default common.ecommerce.shared.support.Page<common.ecommerce.warehouse.model.ProductInfo> query(
WarehouseContext ctx, common.ecommerce.warehouse.model.ProductQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.PRODUCT);
}
/** 商品建档结果。 */ /** 商品建档结果。 */
final class ProductResult { final class ProductResult {

7
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java

@ -37,6 +37,13 @@ public final class InventoryQuery {
return new Builder(); return new Builder();
} }
/**
* 仓侧 SKU 列表;空表示不按 SKU 过滤。
*
* <p>同 {@link ProductQuery#providerSkus()}:必须是建档时下发的仓侧 SKU
* ({@code WarehouseProduct.providerSku()},未给映射时即 {@code omsSku()}),
* 不一定是 OMS SKU。</p>
*/
public List<String> providerSkus() { public List<String> providerSkus() {
return providerSkus; return providerSkus;
} }

423
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java

@ -0,0 +1,423 @@
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;
/**
* 仓侧商品资料(查询结果)。
*
* <p>与 {@link common.ecommerce.warehouse.capability.WarehouseProduct} 的区别:
* 那个是<b>建档入参</b>(我们下发给仓方),这个是<b>查询结果</b>(仓方存着什么)。
* 两者字段高度重叠但语义不同——入参里没有 id / 状态 / 创建时间,
* 结果里也没有「要求仓方必填」这类约束,所以不复用同一个类。</p>
*
* <p>单位与入参一致:尺寸 cm、重量 g。</p>
*/
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<String> 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;
private final String remark;
/** 该商品来自哪家仓。 */
private final WarehouseProvider sourceProvider;
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<String>(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.remark = b.remark;
this.sourceProvider = b.sourceProvider;
}
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<String> 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;
}
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<String> extraBarcodes = new ArrayList<String>();
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 String remark;
private WarehouseProvider sourceProvider;
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 sourceProvider(WarehouseProvider v) {
this.sourceProvider = v;
return this;
}
public ProductInfo build() {
return new ProductInfo(this);
}
}
}

147
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java

@ -0,0 +1,147 @@
package common.ecommerce.warehouse.model;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 商品查询条件(批量 / 分页)。
*
* <p>与 {@link InventoryQuery} 的口径一致:{@code providerSkus} 是<b>仓侧 SKU</b>,
* 即建档时下发给仓方的那一串(通常等于 {@code WarehouseProduct.providerSku()},
* 没给映射时就是 OMS SKU)。<b>SDK 不做 OMS→仓侧 SKU 的转换</b>——
* 那张映射表在宿主手里,这里静默转换会让查回来的东西对不上。</p>
*
* <p>各仓支持的过滤维度不同,不支持的由适配器<b>显式拒绝</b>,
* 不静默忽略——忽略一个过滤条件会让结果对不上。</p>
*/
public final class ProductQuery {
/** 单次最多查多少个 SKU(各仓不同,由适配器按自己的上限再校验)。 */
public static final int MAX_SKUS = 100;
private final List<String> providerSkus;
/** 条码(UPC / 仓方条码)。 */
private final String barcode;
private final Instant createdAfter;
private final Instant createdBefore;
private final int pageSize;
private final String cursor;
public ProductQuery(Builder b) {
this.providerSkus = Collections.unmodifiableList(
new ArrayList<String>(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;
}
public static Builder builder() {
return new Builder();
}
/**
* 仓侧 SKU 列表;空表示不按 SKU 过滤。
*
* <p>这串必须等于<b>建档时下发给仓方的 SKU</b>({@code WarehouseProduct.providerSku()},
* 未给映射时即 {@code omsSku()})。各仓入库字段不同:易达云 {@code skuCode}
* (逗号拼接,≤50)/ 运去哪 {@code skuList}(JSON 数组,≤100)。
* 传错不会报错,只会查不到——SDK 不做 OMS→仓侧转换。</p>
*/
public List<String> providerSkus() {
return providerSkus;
}
/** 条码;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 表示第一页。 */
public String cursor() {
return cursor;
}
public static final class Builder {
private final List<String> providerSkus = new ArrayList<String>();
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<String> v) {
if (v != null) {
for (String s : v) {
providerSku(s);
}
}
return this;
}
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;
}
public Builder pageSize(int v) {
this.pageSize = v;
return this;
}
public Builder cursor(String v) {
this.cursor = v;
return this;
}
public ProductQuery build() {
return new ProductQuery(this);
}
}
}

19
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.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot; 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.LabelPrintTask;
import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.ReturnCommand; import common.ecommerce.warehouse.model.ReturnCommand;
@ -96,6 +98,23 @@ public final class WarehouseOperations {
} }
/** /**
* 批量 / 分页查询仓侧商品资料。只读,不走幂等。
*
* <p>查询入参的 {@code providerSkus} 是<b>仓侧 SKU</b>(建档时下发的那串)。
* SDK 不做 OMS→仓侧 SKU 转换。</p>
*/
public Page<ProductInfo> queryProducts(ProductQuery query) {
require(WarehouseCapability.PRODUCT, WarehouseProductCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.product.query",
CallSupport.params("skuCount", query.providerSkus().size(),
"barcode", query.barcode(),
"hasCreatedRange", query.hasCreatedRange(),
"cursor", query.cursor()),
p -> p.size(),
() -> ((WarehouseProductCapable) adapter).query(ctx, query));
}
/**
* 创建调拨单。<b>写操作</b>:强制经幂等守卫,幂等键 * 创建调拨单。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + transferRequestNo + create}。 * {@code warehouseCode + transferRequestNo + create}。
* *

7
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})。 */ /** 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。 */
public static final String PATH_PRODUCT_CREATE = "/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})。 */ /** 创建出库单({@code POST /webApi/order/v1/createOrder})。 */
public static final String PATH_ORDER_CREATE = "/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"; 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})。
* *
* <p>端点名是 newPrintCaseMark,实际打的是 SKU 标——已与仓方确认。</p> * <p>端点名是 newPrintCaseMark,实际打的是 SKU 标——已与仓方确认。</p>
*/ */
public static final String PATH_SKU_LABEL_PRINT = public static final String PATH_SKU_LABEL_PRINT =
"/webApi/entryInfo/v1/newPrintCaseMarkContentType"; "/webApi/entryInfo/v1/newPrintCaseMark";
/** 查询客户自有物流服务(承运商)({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。 */ /** 查询客户自有物流服务(承运商)({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。 */
public static final String PATH_CARRIERS = "/webApi/carrier/v1/listCarrierByWarehouse"; public static final String PATH_CARRIERS = "/webApi/carrier/v1/listCarrierByWarehouse";

71
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.EdayunInventoryDtos;
import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos; import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos;
import common.ecommerce.edayun.dto.EdayunOrderCostDtos; import common.ecommerce.edayun.dto.EdayunOrderCostDtos;
import common.ecommerce.edayun.dto.EdayunProductQueryDtos;
import common.ecommerce.edayun.dto.EdayunRentDetailDtos; import common.ecommerce.edayun.dto.EdayunRentDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos; import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDtos; 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.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef; import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.PackageResult; 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.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery; import common.ecommerce.warehouse.model.ReturnQuery;
@ -98,8 +101,8 @@ import java.util.List;
/** /**
* 易达云适配器。 * 易达云适配器。
* *
* <p>已实现:商品建档、创建出库单。其余能力<b>不声明</b>,门面调用会显式抛 * <p>已实现的能力见 {@link #capabilities()};<b>没声明的能力门面会显式抛
* {@code WarehouseUnsupportedCapabilityException},不返回空集合。</p> * {@code WarehouseUnsupportedCapabilityException},不返回空集合</b>。</p>
* *
* <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。</p> * {@code WarehouseConnection} 传入。</p>
@ -213,6 +216,40 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
parsed.data == null ? null : parsed.data.skuId); parsed.data == null ? null : parsed.data.skuId);
} }
/**
* 批量查询仓侧商品资料({@code POST /webApi/skuInfo/v1/listProductPage})。
*
* <p>入参 SKU 是<b>仓侧 SKU</b>,即建档时下发到 {@code skuCode} 字段的那串
* ({@link EdayunProductMapper} 的 {@code skuOf}),不一定等于 OMS SKU。
* 易达云的 {@code skuCode} 是逗号拼接的
* 单个字符串且一次最多 50 个,超了本地拒绝(不截断)。
* 审核时间窗统一模型没有对应字段,不传。</p>
*
* <p>查询条件全空时仓方默认按创建时间查<b>最近一个月</b>——这一点由仓方兜底,
* 本地不补默认值。</p>
*/
@Override
public Page<ProductInfo> 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); // 统一模型不区分业务类型,默认查「店铺订单」(1);
// 不传反而返回全账号的产品,量太大 // 不传反而返回全账号的产品,量太大
EdayunLogisticsProductDtos.ListProductRequest body = EdayunLogisticsProductMapper.toRequest( 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); String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_LOGISTICS_PRODUCTS, bodyJson, 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); HttpResponse resp = send(ctx, EdayunConstants.PATH_TRACK, bodyJson, operation);
EdayunTrackDtos.GetTrackResponse parsed = EdayunTrackDtos.GetTrackResponse parsed =
json.fromJson(resp.body(), EdayunTrackDtos.GetTrackResponse.class); json.fromJson(resp.body(), EdayunTrackDtos.GetTrackResponse.class);
if (parsed != null && isNoTrackFound(parsed.msg)) { if (parsed != null && isNoData(parsed.msg)) {
return null; return null;
} }
requireSuccess(ctx, parsed == null ? null : parsed.code, requireSuccess(ctx, parsed == null ? null : parsed.code,
@ -971,9 +1010,10 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
return EdayunTrackMapper.find(parsed, trackingNumber); return EdayunTrackMapper.find(parsed, trackingNumber);
} }
/** 仓方「没有轨迹」的提示语。 */ /** 仓方「没有数据」的提示语:查不到不等于调用失败。 */
private static boolean isNoTrackFound(String msg) { private static boolean isNoData(String msg) {
return msg != null && (msg.contains("未匹配到轨迹") || msg.contains("跟踪号为空")); return msg != null && (msg.contains("查询无数据") || msg.contains("未匹配到轨迹")
|| msg.contains("跟踪号为空"));
} }
// ------------------------------------------------------------------ 条码打印 // ------------------------------------------------------------------ 条码打印
@ -1023,7 +1063,7 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
// ------------------------------------------------------------------ SKU 标 // ------------------------------------------------------------------ SKU 标
/** /**
* 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。 * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
* *
* <p><b>端点名叫 newPrintCaseMark,但实际打的是 SKU 标</b>——已与仓方确认。 * <p><b>端点名叫 newPrintCaseMark,但实际打的是 SKU 标</b>——已与仓方确认。
* 箱唛走 {@code printCaseMarks}(端点 {@code printBarcode})。</p> * 箱唛走 {@code printCaseMarks}(端点 {@code printBarcode})。</p>
@ -1031,12 +1071,13 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
* <p>统一模型的 {@code BoxLabelCommand} 没有「选哪些箱」的字段, * <p>统一模型的 {@code BoxLabelCommand} 没有「选哪些箱」的字段,
* 所以默认整单打印;要打部分箱用重载。</p> * 所以默认整单打印;要打部分箱用重载。</p>
* *
* <p><b>真机未验证</b>:PR 环境该接口返回「接口不存在或未启用」, * <p><b>刻意不是 public、也没声明 {@code SKU_LABEL} 能力位</b>:该接口在 PR 环境
* 换到 {@code /newPrintCaseMark}(无 ContentType 后缀)能过参数校验 * 参数齐全后一律「内部服务器错误」(路径已确认存在,缺参数有中文校验提示),
* (缺 pageSize 报「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」), * 属于仓方服务端异常。放成 public 会让调用方以为门面够得到,实际门面按
* 但补全后一律「内部服务器错误」。见 docs-warehouse/edayun/TODO.md。</p> * {@code SKU_LABEL} 门控、会直接抛不支持。等仓方修复后再提升可见性并声明能力位。
* 见 docs-warehouse/edayun/TODO.md #68。</p>
*/ */
public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) { WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) {
EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd); EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd);
return sendSkuLabel(ctx, body); return sendSkuLabel(ctx, body);
} }
@ -1046,8 +1087,8 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
* *
* @param selection 选箱条件;四选一,全空时本地拒绝 * @param selection 选箱条件;四选一,全空时本地拒绝
*/ */
public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd, WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd,
EdayunSkuLabelMapper.CaseSelection selection) { EdayunSkuLabelMapper.CaseSelection selection) {
EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelDtos.PrintSkuLabelRequest body =
EdayunSkuLabelMapper.toRequest(cmd, selection); EdayunSkuLabelMapper.toRequest(cmd, selection);
return sendSkuLabel(ctx, body); return sendSkuLabel(ctx, body);

1
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.sdk.WarehouseAdapterFactory;
import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory;
/** /**
* 易达云适配器工厂。 * 易达云适配器工厂。

20
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java

@ -36,6 +36,26 @@ public final class EdayunLogisticsProductMapper {
return req; return req;
} }
/**
* 解析仓方仓 id:显式指定的 {@code warehouseCode} 优先,否则用账户配置的。
*
* <p>两者都必须是易达云的<b>数字仓 id</b>——统一模型叫 {@code warehouseCode}
* 但易达云这个接口只认数字 id。给了非数字就本地拒绝,避免静默退回账户仓
* (那样调用方以为按自己的仓查了,实际不是)。</p>
*/
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} 与无效行。 */ /** 响应 → 统一产品清单;跳过 {@code -998} 与无效行。 */
public static List<LogisticsProduct> toProducts( public static List<LogisticsProduct> toProducts(
List<EdayunLogisticsProductDtos.Product> rows, String warehouseCode) { List<EdayunLogisticsProductDtos.Product> rows, String warehouseCode) {

2
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java

@ -163,6 +163,8 @@ public final class EdayunOrderMapper {
for (OutboundLine line : lines) { for (OutboundLine line : lines) {
EdayunCreateOrderDtos.CreateOrderRequest.ProductItem item = EdayunCreateOrderDtos.CreateOrderRequest.ProductItem item =
new EdayunCreateOrderDtos.CreateOrderRequest.ProductItem(); new EdayunCreateOrderDtos.CreateOrderRequest.ProductItem();
// 必须与建档时下发的 skuCode 一致(providerSku 优先,见 EdayunProductMapper.skuOf)。
// 传 OMS SKU 而建档时用的是 providerSku 的话,仓方会报 SKU 不存在。
item.productSku = firstNonBlank(line.providerSku(), line.omsSku()); item.productSku = firstNonBlank(line.providerSku(), line.omsSku());
item.quantity = line.quantity(); item.quantity = line.quantity();
Money value = line.declareValue(); Money value = line.declareValue();

20
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java

@ -128,6 +128,26 @@ public final class EdayunProductMapper {
return d; return d;
} }
/**
* 下发到易达云 {@code skuCode} 字段的值——<b>整条链路都以这个为准</b>。
*
* <p>规则:{@code providerSku} 优先,为空才回退 {@code omsSku}。</p>
*
* <p><b>为什么这条规则要写在建档这里</b>:易达云把 {@code skuCode} 当唯一键落库,
* 之后<b>查商品({@code listProductPage} 的 {@code skuCode})、建出库单
* (商品行 {@code productSku})、查库存({@code skuCodeList})全都按这串匹配</b>。
* 所以:</p>
* <ul>
* <li>宿主给了 {@code providerSku} → 仓方库里存它,之后所有查询 / 下单都必须传它,
* <b>不等于 OMS SKU</b></li>
* <li>宿主没给(如 {@code ybtest})→ 仓方库里存的就是 OMS SKU,两者同名</li>
* </ul>
*
* <p>SDK <b>不做 OMS→仓侧 SKU 的转换</b>:映射表在宿主手里(供应商编码规则、
* 按仓不同的前缀),SDK 猜不出来;静默转换会拿回空结果或错商品,比报错更难发现。</p>
*
* <p>出库行同理,见 {@code EdayunOrderMapper}({@code firstNonBlank(providerSku, omsSku)})。</p>
*/
private static String skuOf(WarehouseProduct product) { private static String skuOf(WarehouseProduct product) {
String sku = product.providerSku(); String sku = product.providerSku();
return sku != null && !sku.trim().isEmpty() ? sku.trim() : product.omsSku(); return sku != null && !sku.trim().isEmpty() ? sku.trim() : product.omsSku();

153
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})。
*
* <p><b>SKU 过滤用逗号拼接的单个字符串</b>({@code skuCode}),
* 且一次最多 50 个——与统一模型的 {@code providerSkus} 列表不同,这里要拼。</p>
*
* <p>页码从 1 开始,单页最多 200。</p>
*/
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<ProductInfo> toPage(EdayunProductQueryDtos.ListProductResponse response,
int currentPage, int pageSize) {
if (response == null || response.rows == null || response.rows.isEmpty()) {
return Page.empty();
}
List<ProductInfo> out = new ArrayList<ProductInfo>(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;
}
/**
* 一行 → 统一商品资料。
*
* <p>尺寸取<b>实际</b>({@code length/width/height/weight}),缺失才回落
* 预报值({@code forecast*})——查询商品资料的目的就是拿到仓方当前存的值。</p>
*/
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();
}
}

6
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) .returnRequestNo(basic == null ? trimToNull(requestedRmaCode)
: firstNonBlank(basic.relationNo, basic.rmaCode, requestedRmaCode)) : firstNonBlank(basic.relationNo, basic.rmaCode, requestedRmaCode))
.providerReturnId(basic == null ? trimToNull(requestedRmaCode) : basic.rmaCode) .providerReturnId(basic == null ? trimToNull(requestedRmaCode) : basic.rmaCode)
.warehouseCode(firstNonBlank( // 响应只有仓名(美西1仓)与数字 id,没有仓编码。
basic == null ? null : basic.warehouseName, warehouseCode)) // warehouseCode 这一列必须放「编码」,不能退化成展示名——
// 宿主会拿它做 equals / 回传查询,放中文名会全线失效。
.warehouseCode(trimToNull(warehouseCode))
.orderRef(basic == null ? null : basic.relationNo) .orderRef(basic == null ? null : basic.relationNo)
.type(basic == null ? null : basic.returnTypeName) .type(basic == null ? null : basic.returnTypeName)
.status(EdayunRmaStatus.toCore( .status(EdayunRmaStatus.toCore(

35
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, public static EdayunReturnDtos.SaveReturnRequest toRequest(ReturnCommand cmd,
String providerWarehouseId) { String providerWarehouseId) {
requireHonorable(cmd);
EdayunReturnDtos.SaveReturnRequest req = new EdayunReturnDtos.SaveReturnRequest(); EdayunReturnDtos.SaveReturnRequest req = new EdayunReturnDtos.SaveReturnRequest();
req.returnType = RETURN_TYPE_SELF_SHIP; req.returnType = RETURN_TYPE_SELF_SHIP;
@ -62,6 +64,35 @@ public final class EdayunReturnMapper {
} }
/** /**
* 本适配器<b>不支持的命令字段</b>在本地拒绝,不静默丢弃。
*
* <p>静默丢弃的后果是调用方以为条件生效了,实际没有。三个字段的情况:</p>
* <ul>
* <li>{@code lineName}(项目):易达云退货单没有项目概念</li>
* <li>{@code estimatedReceiveDate}:易达云按关联单号推,不接受预计到仓日</li>
* <li>{@code returnReason}:易达云要 Integer 字典码({@code wms_rma_return_reason}),
* 统一模型给的是自由文本,对不上——见 TODO</li>
* </ul>
*/
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} 数字优先,否则 {@code warehouseCode}。
* *
* <p>命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。</p> * <p>命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。</p>
@ -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) { private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) { if (a != null && !a.trim().isEmpty()) {
return a.trim(); return a.trim();

40
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(); req.trackingNos = query.trackingNo().trim();
} }
Long warehouseId = warehouseIdOf(providerWarehouseId); applyWarehouseFilter(req, query, providerWarehouseId);
if (warehouseId != null) {
req.warehouseId = warehouseId;
} else if (hasText(query.warehouseCode())) {
req.warehouseCode = query.warehouseCode().trim();
}
if (hasText(query.providerSku())) { if (hasText(query.providerSku())) {
req.skuCode = query.providerSku().trim(); req.skuCode = query.providerSku().trim();
@ -87,6 +82,32 @@ public final class EdayunRmaListMapper {
} }
/** /**
* 仓过滤:账户仓 id 与调用方给的仓编码只能二选一。
*
* <p>易达云文档写明「{@code warehouseCode}(优先使用仓库 id)」,两者同时给时
* 仓方会忽略编码。若调用方显式指定了<b>另一个</b>仓编码,静默按账户仓查会把
* 过滤条件丢掉、结果反而变宽——这种冲突在本地拒绝,不猜。</p>
*/
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}。 * 单号类型 → 易达云 {@code orderNoSearchType}。
* *
* <p>null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。</p> * <p>null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。</p>
@ -153,9 +174,10 @@ public final class EdayunRmaListMapper {
// 列表没有来源单号字段,用 RMA 号兜底;orderRef 用平台 / 出库单号 // 列表没有来源单号字段,用 RMA 号兜底;orderRef 用平台 / 出库单号
.returnRequestNo(firstNonBlank(row.rmaCode, row.ordOrderCode)) .returnRequestNo(firstNonBlank(row.rmaCode, row.ordOrderCode))
.providerReturnId(row.rmaCode) .providerReturnId(row.rmaCode)
// 文档响应示例没有 warehouseCode,但真机会返回,优先用它 // 列表有 warehouseCode(真机返回,文档示例里没有)就直接用;
.warehouseCode(firstNonBlank(row.warehouseCode, row.warehouseName, // **不能退化成 warehouseName**——那是展示名(美西1仓),
fallbackWarehouseCode)) // 宿主拿 warehouseCode 做 equals / 回传查询会全线失效。
.warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode))
.orderRef(firstNonBlank(row.platformOrderCode, row.ordOrderCode)) .orderRef(firstNonBlank(row.platformOrderCode, row.ordOrderCode))
.type(row.returnTypeName) .type(row.returnTypeName)
.status(EdayunRmaStatus.toCore(row.status, row.statusName)) .status(EdayunRmaStatus.toCore(row.status, row.statusName))

2
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; import java.util.List;
/** /**
* 易达云 SKU 标映射({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。 * 易达云 SKU 标映射({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
* *
* <p><b>统一模型只能表达「整单打印」</b>:{@code BoxLabelCommand} 没有「选哪些箱」 * <p><b>统一模型只能表达「整单打印」</b>:{@code BoxLabelCommand} 没有「选哪些箱」
* 的字段,所以选箱条件(系统箱号列表 / SKU / 箱序号区间 / 客户箱号区间) * 的字段,所以选箱条件(系统箱号列表 / SKU / 箱序号区间 / 客户箱号区间)

4
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java

@ -66,7 +66,9 @@ public final class EdayunTrackMapper {
.carrier(track.carrierName) .carrier(track.carrierName)
// 仓方状态是数字码,码表没给;保留原值而不是猜成某个字符串 // 仓方状态是数字码,码表没给;保留原值而不是猜成某个字符串
.status(track.status == null ? null : String.valueOf(track.status)) .status(track.status == null ? null : String.valueOf(track.status))
.signedBy(track.receiver) // track.receiver 是「收件人」,不是「签收人」——在途就有值。
// signedBy 的约定是「未签收为 null」,映射它会让每个在途包裹都被
// 判成已签收。易达云响应里没有签收人字段,宁可不填。
.firstOnlineAt(parseLocal(track.onlineTime, zone)) .firstOnlineAt(parseLocal(track.onlineTime, zone))
.deliveredAt(parseLocal(track.deliveredTime, zone)); .deliveredAt(parseLocal(track.deliveredTime, zone));

96
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})。
*
* <p>一个文件对应一个接口。查询条件全空时仓方默认按创建时间查<b>最近一个月</b>,
* 页码从 1 开始,单页最多 200 条。</p>
*/
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 编码,多个用英文逗号拼接,<b>一次最多 50 个</b>。 */
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<ProductRow> 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;
/** 带电标志:<b>0 是 / 1 否</b>(同其它接口的反向布尔)。 */
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;
}
}

2
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java

@ -6,7 +6,7 @@ import java.util.List;
/** /**
* 易达云报文结构:打印 SKU 标 * 易达云报文结构:打印 SKU 标
* ({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。 * ({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
* *
* <p>一个文件对应一个接口。响应 {@code data} 是<b>PDF 地址字符串</b>,同步生成。</p> * <p>一个文件对应一个接口。响应 {@code data} 是<b>PDF 地址字符串</b>,同步生成。</p>
* *

8
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.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue; import static org.junit.jupiter.api.Assertions.assertTrue;
/** /**
@ -150,11 +149,4 @@ class EdayunCarrierTest {
assertTrue(transport.lastDataRequest().body().contains("\"warehouseId\":2")); assertTrue(transport.lastDataRequest().body().contains("\"warehouseId\":2"));
} }
/** 仓库列表接口易达云没有,显式拒绝而不是空列表。 */
@Test
void warehousesAreUnsupported() {
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(stub("{}"), new JacksonJsonCodec())
.warehouses(ctx("2")));
}
} }

6
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java

@ -165,7 +165,8 @@ class EdayunInventoryTest {
/** 仓编码缺失时回退 OMS 仓编码,快照必须有 warehouseCode。 */ /** 仓编码缺失时回退 OMS 仓编码,快照必须有 warehouseCode。 */
@Test @Test
void warehouseCodeFallsBack() { EdayunInventoryDtos.InventoryRow r = row(); void warehouseCodeFallsBack() {
EdayunInventoryDtos.InventoryRow r = row();
r.warehouseCode = null; r.warehouseCode = null;
assertEquals("EDY-WH", EdayunInventoryMapper.toPage( assertEquals("EDY-WH", EdayunInventoryMapper.toPage(
@ -173,7 +174,8 @@ class EdayunInventoryTest {
.items().get(0).warehouseCode()); .items().get(0).warehouseCode());
} }
/** 没有 SKU 的行跳过,不应让整页失败。 */ @Test /** 没有 SKU 的行跳过,不应让整页失败。 */
@Test
void rowsWithoutSkuAreSkipped() { void rowsWithoutSkuAreSkipped() {
EdayunInventoryDtos.InventoryRow dirty = row(); EdayunInventoryDtos.InventoryRow dirty = row();
dirty.skuCode = " "; dirty.skuCode = " ";

215
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})映射。
*
* <p>重点:SKU 是逗号拼接的单个字符串、<b>一次最多 50 个</b>、页码从 1 开始、
* 实际尺寸优先于预报尺寸。</p>
*/
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<ProductInfo> 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<ProductInfo> 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);
}
}

35
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java

@ -84,6 +84,41 @@ class EdayunReturnTest {
EdayunReturnMapper.toRequest(cmd, "2").relationNo); 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 @Test
void nonNumericWarehouseGoesToWarehouseCode() { void nonNumericWarehouseGoesToWarehouseCode() {
ReturnCommand noWarehouse = ReturnCommand.builder() ReturnCommand noWarehouse = ReturnCommand.builder()

33
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java

@ -102,6 +102,29 @@ class EdayunRmaListTest {
EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PLATFORM_ORDER_NO)); EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PLATFORM_ORDER_NO));
} }
/**
* 账户绑了数字仓 id 时,调用方再传一个<b>不同</b>的仓编码要本地拒绝——
* 仓方会忽略 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 @Test
void warehouseIdGoesNumeric() { void warehouseIdGoesNumeric() {
EdayunRmaListDtos.SelectRmaListRequest numeric = EdayunRmaListDtos.SelectRmaListRequest numeric =
@ -155,6 +178,7 @@ class EdayunRmaListTest {
row.ordOrderCode = "ORD822935302"; row.ordOrderCode = "ORD822935302";
row.trackingNo = "ORD822935302"; row.trackingNo = "ORD822935302";
row.warehouseName = "美西1仓"; row.warehouseName = "美西1仓";
row.warehouseCode = "USLA";
row.warehouseId = 2L; row.warehouseId = 2L;
row.returnType = 0; row.returnType = 0;
row.returnTypeName = "未妥投退回"; row.returnTypeName = "未妥投退回";
@ -170,7 +194,8 @@ class EdayunRmaListTest {
assertEquals("RMA2411058099", ret.returnRequestNo()); assertEquals("RMA2411058099", ret.returnRequestNo());
assertEquals("RMA2411058099", ret.providerReturnId()); assertEquals("RMA2411058099", ret.providerReturnId());
assertEquals("美西1仓", ret.warehouseCode()); // warehouseCode 必须是仓编码,不能是展示名(美西1仓)
assertEquals("USLA", ret.warehouseCode());
assertEquals("102002", ret.orderRef()); assertEquals("102002", ret.orderRef());
assertEquals("未妥投退回", ret.type()); assertEquals("未妥投退回", ret.type());
// 6 = 处理中-等待指令 → 待收货 // 6 = 处理中-等待指令 → 待收货
@ -191,11 +216,11 @@ class EdayunRmaListTest {
assertEquals("USLA", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode()); assertEquals("USLA", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode());
} }
/** 没有仓编码时回退仓名,再回退 OMS 仓编码。 */ /** 响应没有仓编码时直接回退 OMS 仓编码——**不能**退化成仓名(美西1仓)。 */
@Test @Test
void warehouseCodeFallsBackToOms() { void warehouseCodeFallsBackToOmsNotDisplayName() {
EdayunRmaListDtos.RmaRow r = row(); EdayunRmaListDtos.RmaRow r = row();
r.warehouseName = null; r.warehouseCode = null;
assertEquals("EDY-WH", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode()); assertEquals("EDY-WH", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode());
} }

2
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; import static org.junit.jupiter.api.Assertions.assertTrue;
/** /**
* SKU 标打印({@code newPrintCaseMarkContentType})映射。 * SKU 标打印({@code newPrintCaseMark})映射。
* *
* <p>重点:码值不连续(4/2/5)、统一模型只能表达整单打印、 * <p>重点:码值不连续(4/2/5)、统一模型只能表达整单打印、
* Made in China 与分隔符默认关。</p> * Made in China 与分隔符默认关。</p>

3
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java

@ -102,7 +102,8 @@ class EdayunTrackTest {
assertEquals("LF-1741871641090", info.trackingNumber()); assertEquals("LF-1741871641090", info.trackingNumber());
assertEquals("fedex", info.carrier()); assertEquals("fedex", info.carrier());
assertEquals("1", info.status()); assertEquals("1", info.status());
assertEquals("123", info.signedBy()); // receiver 是收件人,不是签收人;signedBy 必须为空(未签收契约)
assertNull(info.signedBy());
// 上网 / 妥投时间按 GMT-04:00 解释 // 上网 / 妥投时间按 GMT-04:00 解释
assertEquals(Instant.parse("2025-08-19T12:17:00Z"), info.firstOnlineAt()); assertEquals(Instant.parse("2025-08-19T12:17:00Z"), info.firstOnlineAt());
assertEquals(Instant.parse("2025-08-20T14:00:00Z"), info.deliveredAt()); assertEquals(Instant.parse("2025-08-20T14:00:00Z"), info.deliveredAt());

106
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;
/**
* 商品查询联调探针:<b>只读</b>。
*
* <pre>
* # 只看报文(不联网)
* 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]
* </pre>
*/
@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<ProductInfo> 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;
}
}

436
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 装配链路冒烟。
*
* <p><b>不联网</b>:走 {@link WarehouseSdk} 门面 → 工厂 → 适配器 → 假传输层,
* 用真实报文样本验一遍「能不能装起来、能力位对不对、字段有没有搬对」。</p>
*
* <p>覆盖的业务场景:</p>
* <ol>
* <li>主数据:仓库 / 承运商 / 物流产品</li>
* <li>发货:试算 → 建单 → 查单 → 面单 → 取消</li>
* <li>库存:查询</li>
* <li>退货:建单 → 查详情 → 列表 → 取消</li>
* <li>单据 / 轨迹 / 打印</li>
* </ol>
*/
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<WarehouseCapability> 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<WarehouseFacility> warehouses = sdk.warehouses(WH, conn()).warehouses();
assertEquals(1, warehouses.size());
assertEquals("USLA", warehouses.get(0).warehouseCode());
assertEquals("2", warehouses.get(0).providerWarehouseId());
List<WarehouseCarrier> carriers = sdk.warehouses(WH, conn()).carrierDirectory();
assertEquals(1, carriers.size());
assertEquals("FedEx", carriers.get(0).nameEn());
assertEquals(1, carriers.get(0).logists().size());
List<LogisticsProduct> 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<FeeEstimateResult> 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<InventorySnapshot> 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<BolDocument> bols = sdk.warehouses(WH, conn()).orderBols("FBA1");
assertEquals(1, bols.size());
assertEquals("cp005", bols.get(0).bolCode());
// 轨迹:节点
List<TrackEvent> 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()));
}
}

3
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -26,6 +26,9 @@ public final class YqnConstants {
/** 商品创建 / 编辑(V1 推荐版)。 */ /** 商品创建 / 编辑(V1 推荐版)。 */
public static final String PATH_PRODUCT_SAVE = "/v1/product/save"; 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)。 */ /** 创建销售订单(API 123)。 */
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create"; public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/** 订单详情(API 128):按来源单号查完整订单。 */ /** 订单详情(API 128):按来源单号查完整订单。 */

30
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.YqnLogisticsProductDtos;
import common.ecommerce.yqn.dto.YqnOrderDetailDtos; import common.ecommerce.yqn.dto.YqnOrderDetailDtos;
import common.ecommerce.yqn.dto.YqnProductDtos; import common.ecommerce.yqn.dto.YqnProductDtos;
import common.ecommerce.yqn.dto.YqnProductQueryDtos;
import common.ecommerce.yqn.dto.YqnReturnProcessDtos; import common.ecommerce.yqn.dto.YqnReturnProcessDtos;
import common.ecommerce.yqn.dto.YqnSaleReturnPlanDtos; import common.ecommerce.yqn.dto.YqnSaleReturnPlanDtos;
import common.ecommerce.yqn.dto.YqnSkuLabelDtos; import common.ecommerce.yqn.dto.YqnSkuLabelDtos;
@ -170,6 +171,35 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
json.stringAt(raw, "message")); json.stringAt(raw, "message"));
} }
/**
* 批量查询仓侧商品资料(API 113,{@code /v1/product/findPage})。
*
* <p>入参 SKU 是<b>仓侧 SKU</b>,即建档时下发到 {@code sku} 字段的那串
* ({@link YqnProductMapper#skuOf}),不一定等于 OMS SKU。
* 运去哪这个接口没有条码 / 时间窗过滤,传了要本地拒绝而不是静默忽略。</p>
*
* <p>页码从 0 开始——游标就是页码字符串,不做 ±1 换算。</p>
*/
@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 @Override

2
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java

@ -140,6 +140,8 @@ public final class YqnOutboundMapper {
new ArrayList<YqnCreateOrderDtos.CreateOrderRequest.ProductItem>(lines.size()); new ArrayList<YqnCreateOrderDtos.CreateOrderRequest.ProductItem>(lines.size());
for (OutboundLine line : lines) { for (OutboundLine line : lines) {
YqnCreateOrderDtos.CreateOrderRequest.ProductItem item = new YqnCreateOrderDtos.CreateOrderRequest.ProductItem(); 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.sku = line.providerSku() != null ? line.providerSku() : line.omsSku();
item.quantity = line.quantity(); item.quantity = line.quantity();
item.lineNo = line.lineNo(); item.lineNo = line.lineNo();

20
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java

@ -85,7 +85,25 @@ public final class YqnProductMapper {
return req; return req;
} }
/** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */ /**
* 下发到运去哪 {@code sku} 字段的值——<b>整条链路都以这个为准</b>。
*
* <p>规则:{@code providerSku} 优先,为空才回退 {@code omsSku}。</p>
*
* <p><b>为什么这条规则要写在建档这里</b>:运去哪把 {@code sku} 当唯一键落库,
* 之后<b>查商品(API 113 {@code skuList})、建出库单(商品行 {@code sku})、
* 查库存({@code skuList})全都按这串匹配</b>。所以:</p>
* <ul>
* <li>宿主给了 {@code providerSku}(如 {@code AP0000X9US0010601})→ 仓方库里存它,
* 之后所有查询 / 下单都必须传它,<b>不等于 OMS SKU</b></li>
* <li>宿主没给(如 {@code ybtest})→ 仓方库里存的就是 OMS SKU,两者同名</li>
* </ul>
*
* <p>SDK <b>不做 OMS→仓侧 SKU 的转换</b>:映射表在宿主手里(供应商编码规则、
* 按仓不同的前缀),SDK 猜不出来;静默转换会拿回空结果或错商品,比报错更难发现。</p>
*
* <p>出库行同理,见 {@code YqnOutboundMapper}({@code providerSku} 优先)。</p>
*/
public static String skuOf(WarehouseProduct product) { public static String skuOf(WarehouseProduct product) {
String providerSku = product.providerSku(); String providerSku = product.providerSku();
if (providerSku != null && !providerSku.trim().isEmpty()) { if (providerSku != null && !providerSku.trim().isEmpty()) {

175
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})。
*
* <p><b>页码从 0 开始</b>——统一模型的游标语义是「下一页页码」,
* 这里用字符串页码原样透传,不做 ±1 换算,免得调用方和仓方口径对不上。</p>
*/
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<String>(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);
}
/** 游标 → 页码;<b>从 0 开始</b>,空游标即第 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<ProductInfo> toPage(YqnProductQueryDtos.FindPageResponse response) {
if (response == null || response.data == null
|| response.data.content == null || response.data.content.isEmpty()) {
return Page.empty();
}
List<ProductInfo> out = new ArrayList<ProductInfo>(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));
}
/**
* 下一页游标。
*
* <p>优先用 {@code last}(仓方明确给了是否末页);缺失时用
* {@code number+1 < totalPages} 推断。两者都给不出时按「本页是否满页」兜底。</p>
*/
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();
}
}

112
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})。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。</p>
*
* <p><b>页码从 0 开始</b>(文档:「起始页为从0开始」),与其它分页接口不同。
* {@code pageSize} 默认 100、最大 100。</p>
*/
public final class YqnProductQueryDtos {
private YqnProductQueryDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class FindPageRequest {
/** 仓侧 SKU 列表,最大 100 个。 */
public List<String> skuList;
/** 每页大小,默认 100、最大 100。 */
public Integer pageSize;
/** 页码,<b>从 0 开始</b>。 */
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<ProductRow> 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;
}
}

190
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})映射。
*
* <p>重点:<b>页码从 0 开始</b>、单页上限 100、{@code last} 优先判断翻页。</p>
*/
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<ProductInfo> 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<ProductInfo> 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);
}
}

33
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java

@ -75,6 +75,39 @@ class YqnReadOnlyProbeTest {
}); });
} }
/**
* 商品查询(API 113)。
*
* <p>不传 {@code skuList} 时仓方返回全量第一页——正好用来验「页码从 0 开始」。
* 用 {@code -Dyqn.probe.skuList=A,B} 可以顺带验按 SKU 过滤。</p>
*/
@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」这条路是否被仓方接受。 */ /** 物流产品:验证「GET 但参数写在 query」这条路是否被仓方接受。 */
@Test @Test
void probeLogisticsProducts() { void probeLogisticsProducts() {

Loading…
Cancel
Save