Browse Source

merge: 合入远端商品查询,统一改用 ProductInfo

手动合并的检查结论:编译与测试都过,但语义上两边各做了一套,
恒健 / 信仓还在产出 WarehouseProduct(建档入参),与远端的
ProductInfo(查询结果)重复。按远端方案统一。

- ProductInfo 作为唯一的商品查询结果模型:补恒健 / 信仓特有的
  实测尺寸、申报价值、保价、保质期、体积、状态原值等字段
- WarehouseProduct 回退到远端版本:去掉为「查询结果复用建档入参」
  加的 allowUnknownDimensions / providerProductId / measured* 等
- 恒健 / 信仓 mapper 改为产出 ProductInfo,适配器方法名对齐为 query()

顺带修两个操作日志漏点(都是门面方法没走 CallSupport.observe):
- OutboundOutbounds.create:写操作只记了幂等层的 writes.create,
  没有门面级记录,日志里看不到「下发」这个动作
- 退货 create / cancel、入库 create、入库 bols、inventorySyncStrategy

并把恒健两个绕开日志的适配器方法收进门面:
- queryReturnHandles -> WarehouseReturnCapable.queryHandles
  返回统一模型 ReturnHandle(新增),不再暴露仓方 DTO
- queryReturnsAdvanced 保留在适配器(统一模型无对应维度),
  文档里标注「不走门面日志」

新增 WarehouseCallObserverTest(7 个用例)覆盖:
成功 / 失败 / 只读 / 一次调用一条 / 未注入 observer / observer 抛异常
不影响业务 / params 不含密钥。门面 45 -> 51 个 operation 全部有记录。

mvn test 全量通过。
feature/Walmart
lml 3 days ago
parent
commit
590162eefc
  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. 235
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  8. 16
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java
  9. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
  10. 7
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
  11. 632
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java
  12. 117
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java
  13. 336
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnHandle.java
  14. 118
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  15. 28
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java
  16. 7
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  17. 71
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  18. 1
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java
  19. 20
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java
  20. 2
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java
  21. 20
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java
  22. 153
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java
  23. 6
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java
  24. 35
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java
  25. 40
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java
  26. 2
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java
  27. 4
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
  28. 96
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java
  29. 2
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java
  30. 8
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java
  31. 6
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java
  32. 215
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java
  33. 35
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java
  34. 33
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java
  35. 2
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java
  36. 3
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java
  37. 106
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java
  38. 436
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java
  39. 34
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  40. 34
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java
  41. 100
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java
  42. 48
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java
  43. 20
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java
  44. 213
      warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseCallObserverTest.java
  45. 3
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  46. 25
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java
  47. 44
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java
  48. 3
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  49. 30
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  50. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
  51. 20
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
  52. 175
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java
  53. 112
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java
  54. 190
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java
  55. 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 { @@ -85,7 +85,7 @@ public enum YqnOutboundStatus {
`sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略,
调用方不应假定排序一定生效。
`WarehouseCapability`(26 个):
`WarehouseCapability`(27 个):
| 能力 | 说明 | 运去哪 | 信仓 |
|---|---|:---:|:---:|
@ -99,7 +99,7 @@ public enum YqnOutboundStatus { @@ -99,7 +99,7 @@ public enum YqnOutboundStatus {
| `BOX_LABEL` | 入库箱标(异步) | ✅ | — |
| `SKU_LABEL` | SKU 标(异步) | ✅ | — |
| `LOGISTICS_PRODUCT` | 物流产品清单 | ✅ | ✅ |
| `WAREHOUSE_DIRECTORY` | 仓库目录 | ✅ | — |
| `DIRECTORY` | 仓库 / 承运商目录 | ✅ | — |
| `WEBHOOK` | 状态回调 | ✅ | — |
| `TRANSFER` | 仓间调拨 | ✅ | ✅ |
| `RETURN` | 退货发起 / 查询 | ✅ | — |
@ -107,6 +107,7 @@ public enum YqnOutboundStatus { @@ -107,6 +107,7 @@ public enum YqnOutboundStatus {
| `TRACKING` | 物流轨迹 | ✅ | — |
| `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — |
| `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — |
| `CASE_MARK_PRINT` | 箱唛打印(同步 PDF) | — | — |
| `DESTRUCTION` | 销毁 / 报废 | ✅ | — |
| `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — |
| `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — |

79
docs-warehouse/edayun/README.md

@ -8,6 +8,7 @@ @@ -8,6 +8,7 @@
| 适配器 / 工厂 | ✅ 类型就绪,能力位为空 |
| 获取 token | ✅ 已对接(`POST /oauth/token`) |
| 创建产品 | ✅ 已对接(`POST /webApi/skuInfo/v1/createProduct`) |
| 商品查询 | ✅ 已对接(`POST /webApi/skuInfo/v1/listProductPage`) |
| 创建出库单 | ✅ 已对接(`POST /webApi/order/v1/createOrder`) |
| 查询出库单 | ✅ 已对接(`POST /webApi/order/v1/getOrderInfo`) |
| 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) |
@ -28,7 +29,7 @@ @@ -28,7 +29,7 @@
| 物流产品清单 | ✅ 已对接(`POST /webApi/order/listByLogisticProductHasPerm`) |
| 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) |
| 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) |
| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** |
| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMark`),**真机未启用** |
| 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) |
| 仓库清单 | ✅ 已对接(`warehouse/listWarehouseHasPerm` + `warehouse/listActive`) |
| 其它业务接口 | ⬜ 等文档 |
@ -156,6 +157,55 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false -Dedayun.probe.product=tr @@ -156,6 +157,55 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false -Dedayun.probe.product=tr
... -Dedayun.probe.write=true -Dedayun.probe.token=... -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=...
```
## 商品查询
```
POST /webApi/skuInfo/v1/listProductPage → Page<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 @@ -913,10 +963,10 @@ POST /webApi/rma/info/v1/saveAndPublish → WarehouseReturn
| 方法 | 状态 |
|---|---|
| `queryReturns(ctx, cursor)` | ❌ 文档只给了按单号查,没有列表接口 |
| `queryReturns(ReturnQuery)` | ✅ 已实现(`selectRmaInfoList`) |
| `process(ctx, cmd)` | ❌ 要仓侧明细行 id,而详情响应里**没有行 id**(`checkList` / `skuList` / `shelfList` 都没有) |
`queryReturns` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。
`process` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。
### 探针
@ -1154,7 +1204,7 @@ POST /webApi/track/getTrackInfoList → List<TrackEvent> / TrackingInfo @@ -1154,7 +1204,7 @@ POST /webApi/track/getTrackInfoList → List<TrackEvent> / TrackingInfo
| 端点 | 实际打印 | 我们的方法 | 能力位 |
|---|---|---|---|
| `/webApi/skuInfo/v2/printBarcode` | **箱唛**(外箱标) | `printCaseMarks(...)` | `CASE_MARK_PRINT` |
| `/webApi/entryInfo/v1/newPrintCaseMarkContentType` | **SKU 标** | `printSkuLabel(...)` | 走入库 `SKU_LABEL` 语义 |
| `/webApi/entryInfo/v1/newPrintCaseMark` | **SKU 标** | `printSkuLabel(...)` | 走入库 `SKU_LABEL` 语义 |
**不要被路径名误导**。代码里两个方法的 javadoc 都写了这条提醒。
@ -1192,10 +1242,10 @@ POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel @@ -1192,10 +1242,10 @@ POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel
仓方其它校验:缺 `productInfos` →「产品信息不能为空」、缺 `pageSize` →
「纸张尺寸不能为空」、SKU 不存在 →「sku=XXX信息不存在」。
### SKU 标(newPrintCaseMarkContentType)
### SKU 标(newPrintCaseMark)
```
POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel
POST /webApi/entryInfo/v1/newPrintCaseMark → WarehouseLabel
```
**真机未启用**:PR 环境该路径报「接口不存在或未启用」,去掉
@ -1317,6 +1367,23 @@ DTO 按 `List` 收。 @@ -1317,6 +1367,23 @@ DTO 按 `List` 收。
`listWarehouseHasPerm` 只有 17 个。DTO 只声明统一模型用得上的十几个——
Jackson 会忽略未知字段。
## SKU 口径:传的是 OMS SKU 还是仓侧 SKU?
**结论:两边都必须是仓侧 SKU(建档时下发的那串)。**
代码依据:
- 建档:`YqnProductMapper.skuOf()` / `EdayunProductMapper.skuOf()` 都是
**`providerSku` 优先,为空才回退 `omsSku`**
- 出库行:`OutboundLine` 同时有 `omsSku` 与 `providerSku`,映射时同样 providerSku 优先
- 商品查询:`ProductQuery.providerSkus()` 是仓侧 SKU,**SDK 不做 OMS→仓侧转换**
所以仓方库里存的永远是「我们建档时下发的那串」。如果宿主给 `providerSku`
建了档,那么查询也必须用它;只有两者相同时(如 `ybtest`)才能混用。
**SDK 不会静默转换的原因**:OMS→仓侧 SKU 的映射表在宿主手里(供应商编码规则、
按仓不同的前缀等),SDK 猜不出来。查错了会拿到空结果或错的商品,比报错更难发现。
## 待确认(问易达云)
| # | 要确认 |

7
docs-warehouse/edayun/TODO.md

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

31
docs-warehouse/yqn/README.md

@ -206,6 +206,36 @@ WarehouseConnection.of( @@ -206,6 +206,36 @@ WarehouseConnection.of(
**未指定时按 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. 联调探针
两个探针,默认跳过:
@ -235,4 +265,5 @@ mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \ @@ -235,4 +265,5 @@ mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \
| 库存调整 | 运去哪无此接口 |
| 换货 / 无头件 / 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 { @@ -21,7 +21,7 @@ public interface CaseMarkPrintCapable extends WarehouseAdapter {
*
* @return 已生成的文件(地址或 base64);仓方未返回文件时抛出异常,不返回 null
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不声明 {@code BARCODE_PRINT}
* 该仓不声明 {@code CASE_MARK_PRINT}
*/
WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd);
}

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

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

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

@ -19,6 +19,24 @@ import java.util.Objects; @@ -19,6 +19,24 @@ import java.util.Objects;
public final class WarehouseProduct {
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 customItemNo;
private final String barcode;
@ -161,43 +179,6 @@ public final class WarehouseProduct { @@ -161,43 +179,6 @@ public final class WarehouseProduct {
*/
private final Boolean specialOuterPackaging;
// ==================== 查询结果才有(下发时忽略)====================
/**
* 仓侧商品 id。查询结果里有;建档时忽略。
*
* <p>信仓 {@code id}、恒健无此字段。</p>
*/
private final String providerProductId;
/**
* 仓方实测尺寸 / 重量;null 表示仓方未给。
*
* <p><b>与 {@link #lengthCm()} 等不是一回事</b>:那些是我们申报的尺寸,
* 这些是仓方收货后实测的(恒健 {@code measurement*})。下标成本、抛重都以实测为准。</p>
*/
private final Double measuredLengthCm;
private final Double measuredWidthCm;
private final Double measuredHeightCm;
private final Double measuredWeightGrams;
/** 仓方记录的创建时间(UTC);查询结果才有。 */
private final java.time.Instant createdAt;
/** 仓方记录的更新时间(UTC);查询结果才有。 */
private final java.time.Instant updatedAt;
/**
* 仓方状态原值;查询结果才有,建档时为 null。
*
* <p>信仓 {@code state}:0 临时 / 1 正式;恒健无状态字段。</p>
*/
private final String rawState;
/** 仓方状态中文名(信仓 {@code state_name});无则为 null。 */
private final String stateName;
/**
* 体积(立方厘米);仓方原值。
*
* <p>信仓 {@code volume_cm};恒健无此字段。</p>
*/
private final java.math.BigDecimal volumeCm3;
/**
* 产品图片地址;null 表示不传。
*
@ -220,23 +201,10 @@ public final class WarehouseProduct { @@ -220,23 +201,10 @@ public final class WarehouseProduct {
// 不在构造期强制:这是运去哪的必填项,信仓不需要。必填性由各适配器按自己的
// 协议校验,见 YqnProductMapper;未给时保持 -1 表示「不传」。
this.packingType = b.packingType;
if (b.allowUnknownDimensions) {
// 查询结果:仓方可能没给尺寸 / 重量。用 0 表示「未给」,
// 不伪造一个值——伪造会让计费与抛重计算拿到假数据。
requireNonNegative(b.lengthCm, "lengthCm");
requireNonNegative(b.widthCm, "widthCm");
requireNonNegative(b.heightCm, "heightCm");
requireNonNegative(b.weightGrams, "weightGrams");
this.lengthCm = b.lengthCm;
this.widthCm = b.widthCm;
this.heightCm = b.heightCm;
this.weightGrams = b.weightGrams;
} else {
this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
this.widthCm = requirePositive(b.widthCm, "widthCm");
this.heightCm = requirePositive(b.heightCm, "heightCm");
this.weightGrams = requirePositive(b.weightGrams, "weightGrams");
}
this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
this.widthCm = requirePositive(b.widthCm, "widthCm");
this.heightCm = requirePositive(b.heightCm, "heightCm");
this.weightGrams = requirePositive(b.weightGrams, "weightGrams");
this.itemLengthCm = b.itemLengthCm;
this.itemWidthCm = b.itemWidthCm;
this.itemHeightCm = b.itemHeightCm;
@ -256,16 +224,6 @@ public final class WarehouseProduct { @@ -256,16 +224,6 @@ public final class WarehouseProduct {
new java.util.ArrayList<String>(b.imageUrls));
this.specialOuterPackaging = b.specialOuterPackaging;
this.imageUrl = b.imageUrl;
this.providerProductId = b.providerProductId;
this.measuredLengthCm = b.measuredLengthCm;
this.measuredWidthCm = b.measuredWidthCm;
this.measuredHeightCm = b.measuredHeightCm;
this.measuredWeightGrams = b.measuredWeightGrams;
this.createdAt = b.createdAt;
this.updatedAt = b.updatedAt;
this.rawState = b.rawState;
this.stateName = b.stateName;
this.volumeCm3 = b.volumeCm3;
this.expirationControl = b.expirationControl;
this.expirationDays = b.expirationDays;
this.packedQuantity = b.packedQuantity;
@ -293,7 +251,7 @@ public final class WarehouseProduct { @@ -293,7 +251,7 @@ public final class WarehouseProduct {
return omsSku;
}
/** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。 */
/** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。详见字段注释。 */
public String providerSku() {
return providerSku;
}
@ -492,17 +450,6 @@ public final class WarehouseProduct { @@ -492,17 +450,6 @@ public final class WarehouseProduct {
return v != null && !v.trim().isEmpty();
}
/** 尺寸 / 重量是否为「未给」(0 表示仓方没给,仅查询结果适用)。 */
public boolean hasDimensions() {
return lengthCm > 0 && widthCm > 0 && heightCm > 0 && weightGrams > 0;
}
private static void requireNonNegative(double v, String name) {
if (v < 0) {
throw new IllegalArgumentException(name + " must not be negative");
}
}
private static String require(String v, String n) {
if (!hasText(v)) {
throw new IllegalArgumentException(n + " must not be blank");
@ -517,56 +464,6 @@ public final class WarehouseProduct { @@ -517,56 +464,6 @@ public final class WarehouseProduct {
return v;
}
/** 仓侧商品 id;查询结果才有。 */
public String providerProductId() {
return providerProductId;
}
/** 仓方实测长(cm);未给为 null。 */
public Double measuredLengthCm() {
return measuredLengthCm;
}
/** 仓方实测宽(cm);未给为 null。 */
public Double measuredWidthCm() {
return measuredWidthCm;
}
/** 仓方实测高(cm);未给为 null。 */
public Double measuredHeightCm() {
return measuredHeightCm;
}
/** 仓方实测重量(g);未给为 null。 */
public Double measuredWeightGrams() {
return measuredWeightGrams;
}
/** 仓方记录的创建时间(UTC);未给为 null。 */
public java.time.Instant createdAt() {
return createdAt;
}
/** 仓方记录的更新时间(UTC);未给为 null。 */
public java.time.Instant updatedAt() {
return updatedAt;
}
/** 仓方状态原值;建档时为 null。 */
public String rawState() {
return rawState;
}
/** 仓方状态中文名;无则为 null。 */
public String stateName() {
return stateName;
}
/** 体积(立方厘米);未给为 null。 */
public java.math.BigDecimal volumeCm3() {
return volumeCm3;
}
public static final class Builder {
private String omsSku;
@ -598,22 +495,6 @@ public final class WarehouseProduct { @@ -598,22 +495,6 @@ public final class WarehouseProduct {
private String remark;
private Integer productCategory;
private String imageUrl;
private String providerProductId;
private Double measuredLengthCm;
private Double measuredWidthCm;
private Double measuredHeightCm;
private Double measuredWeightGrams;
private java.time.Instant createdAt;
private java.time.Instant updatedAt;
private String rawState;
private String stateName;
private java.math.BigDecimal volumeCm3;
/**
* 允许尺寸 / 重量为 0(表示仓方未给)。
*
* <p>只给<b>查询结果</b>用:建档时仍然必须给正数。不设这个开关时行为不变。</p>
*/
private boolean allowUnknownDimensions;
private final List<String> imageUrls = new java.util.ArrayList<String>();
private Boolean specialOuterPackaging;
private Boolean expirationControl;
@ -859,76 +740,6 @@ public final class WarehouseProduct { @@ -859,76 +740,6 @@ public final class WarehouseProduct {
/**
* @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐
*/
/**
* 允许尺寸 / 重量为 0(表示仓方未给)。
*
* <p>只在把<b>查询结果</b>映射成模型时使用;建档仍是必填正数。</p>
*/
public Builder allowUnknownDimensions(boolean v) {
this.allowUnknownDimensions = v;
return this;
}
/** 仓侧商品 id(查询结果才有)。 */
public Builder providerProductId(String v) {
this.providerProductId = v;
return this;
}
/** 仓方实测长(cm)。 */
public Builder measuredLengthCm(Double v) {
this.measuredLengthCm = v;
return this;
}
/** 仓方实测宽(cm)。 */
public Builder measuredWidthCm(Double v) {
this.measuredWidthCm = v;
return this;
}
/** 仓方实测高(cm)。 */
public Builder measuredHeightCm(Double v) {
this.measuredHeightCm = v;
return this;
}
/** 仓方实测重量(g)。 */
public Builder measuredWeightGrams(Double v) {
this.measuredWeightGrams = v;
return this;
}
/** 仓方记录的创建时间(UTC)。 */
public Builder createdAt(java.time.Instant v) {
this.createdAt = v;
return this;
}
/** 仓方记录的更新时间(UTC)。 */
public Builder updatedAt(java.time.Instant v) {
this.updatedAt = v;
return this;
}
/** 仓方状态原值。 */
public Builder rawState(String v) {
this.rawState = v;
return this;
}
/** 仓方状态中文名。 */
public Builder stateName(String v) {
this.stateName = v;
return this;
}
/** 体积(立方厘米)。 */
public Builder volumeCm3(java.math.BigDecimal v) {
this.volumeCm3 = v;
return this;
}
public WarehouseProduct build() {
return new WarehouseProduct(this);
}

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

@ -10,17 +10,19 @@ public interface WarehouseProductCapable extends WarehouseAdapter { @@ -10,17 +10,19 @@ public interface WarehouseProductCapable extends WarehouseAdapter {
ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product);
/**
* 分页查商品。<b>只读</b>,不走幂等。
* 批量 / 分页查询仓侧商品资料。
*
* <p>各仓支持的过滤维度不同:不支持的维度由适配器<b>显式拒绝</b>,
* 不静默忽略——忽略一个过滤条件会让调用方以为「仓里就这些商品」。</p>
* <p>查询用的 SKU 是<b>仓侧 SKU</b>(建档时下发的那串,通常是
* {@code WarehouseProduct.providerSku()},没给映射时等于 OMS SKU)。
* SDK 不做 OMS→仓侧 SKU 的转换——映射表在宿主手里,静默转换会让结果对不上。</p>
*
* @param query 查询条件;游标为空表示第一页
* @return 当前页商品;{@code nextCursor} 非空表示还有下一页
* <p>默认不支持:只有提供商品查询接口的仓才覆盖。</p>
*
* @return 分页结果;仓方无数据时为空页(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不支持商品查询
* 该仓不提供商品查询
*/
default common.ecommerce.shared.support.Page<WarehouseProduct> queryProducts(
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);

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

@ -40,6 +40,26 @@ public interface WarehouseReturnCapable extends WarehouseAdapter { @@ -40,6 +40,26 @@ public interface WarehouseReturnCapable extends WarehouseAdapter {
Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query);
/**
* 分页查<b>退货处理单</b>(仓方收货检验后按明细行拆出的处理单元)。
*
* <p>只有提供该接口的仓才覆盖;默认不支持。</p>
*
* <p>与 {@link #queryReturns} 的区别:那个查「一张退货计划」,
* 这个查「计划下每一行 SKU 的待处理记录」。填处理方式要用的四项定位
* (计划单号 + 处理单号 + SKU + tracking)就在返回的
* {@link common.ecommerce.warehouse.model.ReturnHandle} 里。</p>
*
* @return 分页结果;仓方无数据时为空页(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不提供处理单查询
*/
default Page<common.ecommerce.warehouse.model.ReturnHandle> queryHandles(
WarehouseContext ctx, ReturnQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.RETURN);
}
/**
* 按明细行设置检验后处理方式。<b>写操作</b>,幂等键
* {@code warehouseCode + providerReturnNo + lineId + "process"}。
*/

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

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

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

@ -0,0 +1,632 @@ @@ -0,0 +1,632 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 仓侧商品资料(查询结果)。
*
* <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;
/** 更新时间;仓方未给为 null。 */
private final Instant updatedAt;
private final String remark;
/** 该商品来自哪家仓。 */
private final WarehouseProvider sourceProvider;
// ==================== 仓方实测尺寸(恒健 measurement*)====================
/**
* 仓方收货后<b>实测</b>尺寸 / 重量;未给为 null。
*
* <p>与 {@link #lengthCm()} 等不是一回事:那些是我们申报的。
* 下标成本、抛重计算都以实测为准。</p>
*/
private final Double measuredLengthCm;
private final Double measuredWidthCm;
private final Double measuredHeightCm;
private final Double measuredWeightGrams;
// ==================== 申报价值 / 保价(恒健、信仓)====================
/** 申报价值;恒健 {@code cost}+{@code currency}、信仓 {@code amount}(USD);未给为 null。 */
private final Money declaredValue;
/** 是否保价;恒健 {@code isInsuranceFlag}(Y/N);未给为 null。 */
private final Boolean insured;
/** 保价费用;恒健 {@code isInsuranceRate};未给为 null。 */
private final Money insuranceFee;
// ==================== 保质期(恒健)====================
/** 是否开启保质期管理;未给为 null。 */
private final Boolean expirationControl;
/** 保质期天数;未给为 null。 */
private final Integer expirationDays;
// ==================== 体积 / 图片 / 状态名(信仓、恒健)====================
/** 体积(立方厘米);未给为 null。 */
private final java.math.BigDecimal volumeCm3;
/** 商品图片 URL;仓方未给为 null。 */
private final String imageUrl;
/** 仓方状态码的<b>原值文本</b>(信仓 {@code state} 是字符串 0/1);未给为 null。 */
private final String rawState;
private ProductInfo(Builder b) {
this.providerSku = require(b.providerSku, "providerSku");
this.omsSku = b.omsSku;
this.providerProductId = b.providerProductId;
this.customItemNo = b.customItemNo;
this.barcode = b.barcode;
this.extraBarcodes = Collections.unmodifiableList(
new ArrayList<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.updatedAt = b.updatedAt;
this.remark = b.remark;
this.sourceProvider = b.sourceProvider;
this.measuredLengthCm = b.measuredLengthCm;
this.measuredWidthCm = b.measuredWidthCm;
this.measuredHeightCm = b.measuredHeightCm;
this.measuredWeightGrams = b.measuredWeightGrams;
this.declaredValue = b.declaredValue;
this.insured = b.insured;
this.insuranceFee = b.insuranceFee;
this.expirationControl = b.expirationControl;
this.expirationDays = b.expirationDays;
this.volumeCm3 = b.volumeCm3;
this.imageUrl = b.imageUrl;
this.rawState = b.rawState;
}
public static Builder builder() {
return new Builder();
}
public String providerSku() {
return providerSku;
}
/** OMS SKU;仓方不回时为 null。 */
public String omsSku() {
return omsSku;
}
public String providerProductId() {
return providerProductId;
}
public String customItemNo() {
return customItemNo;
}
public String barcode() {
return barcode;
}
/** 额外条码(仓方支持多个时);不可变。 */
public List<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;
}
/** 更新时间;仓方未给为 null。 */
public Instant updatedAt() {
return updatedAt;
}
/** 仓方实测长(cm);未给为 null。 */
public Double measuredLengthCm() {
return measuredLengthCm;
}
/** 仓方实测宽(cm);未给为 null。 */
public Double measuredWidthCm() {
return measuredWidthCm;
}
/** 仓方实测高(cm);未给为 null。 */
public Double measuredHeightCm() {
return measuredHeightCm;
}
/** 仓方实测重量(g);未给为 null。 */
public Double measuredWeightGrams() {
return measuredWeightGrams;
}
/** 申报价值;未给为 null。 */
public Money declaredValue() {
return declaredValue;
}
/** 是否保价;未给为 null。 */
public Boolean insured() {
return insured;
}
/** 保价费用;未给为 null。 */
public Money insuranceFee() {
return insuranceFee;
}
/** 是否开启保质期管理;未给为 null。 */
public Boolean expirationControl() {
return expirationControl;
}
/** 保质期天数;未给为 null。 */
public Integer expirationDays() {
return expirationDays;
}
/** 体积(立方厘米);未给为 null。 */
public java.math.BigDecimal volumeCm3() {
return volumeCm3;
}
/** 商品图片 URL;未给为 null。 */
public String imageUrl() {
return imageUrl;
}
/** 仓方状态码原值文本;未给为 null。 */
public String rawState() {
return rawState;
}
private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return v.trim();
}
public static final class Builder {
private String providerSku;
private String omsSku;
private String providerProductId;
private String customItemNo;
private String barcode;
private final List<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 Instant updatedAt;
private String remark;
private WarehouseProvider sourceProvider;
private Double measuredLengthCm;
private Double measuredWidthCm;
private Double measuredHeightCm;
private Double measuredWeightGrams;
private Money declaredValue;
private Boolean insured;
private Money insuranceFee;
private Boolean expirationControl;
private Integer expirationDays;
private java.math.BigDecimal volumeCm3;
private String imageUrl;
private String rawState;
public Builder providerSku(String v) {
this.providerSku = v;
return this;
}
public Builder omsSku(String v) {
this.omsSku = v;
return this;
}
public Builder providerProductId(String v) {
this.providerProductId = v;
return this;
}
public Builder customItemNo(String v) {
this.customItemNo = v;
return this;
}
public Builder barcode(String v) {
this.barcode = v;
return this;
}
public Builder extraBarcode(String v) {
if (v != null && !v.trim().isEmpty()) {
this.extraBarcodes.add(v.trim());
}
return this;
}
public Builder name(String v) {
this.name = v;
return this;
}
public Builder nameEn(String v) {
this.nameEn = v;
return this;
}
public Builder description(String v) {
this.description = v;
return this;
}
/** 产品类型:1 成品 / 2 配件 / 3 耗材;-1 表示未给。 */
public Builder productType(int v) {
this.productType = v;
return this;
}
public Builder lengthCm(double v) {
this.lengthCm = v;
return this;
}
public Builder widthCm(double v) {
this.widthCm = v;
return this;
}
public Builder heightCm(double v) {
this.heightCm = v;
return this;
}
public Builder weightGrams(double v) {
this.weightGrams = v;
return this;
}
public Builder itemLengthCm(Double v) {
this.itemLengthCm = v;
return this;
}
public Builder itemWidthCm(Double v) {
this.itemWidthCm = v;
return this;
}
public Builder itemHeightCm(Double v) {
this.itemHeightCm = v;
return this;
}
public Builder packedQuantity(Integer v) {
this.packedQuantity = v;
return this;
}
public Builder packedLengthCm(Double v) {
this.packedLengthCm = v;
return this;
}
public Builder packedWidthCm(Double v) {
this.packedWidthCm = v;
return this;
}
public Builder packedHeightCm(Double v) {
this.packedHeightCm = v;
return this;
}
public Builder packedWeightGrams(Double v) {
this.packedWeightGrams = v;
return this;
}
public Builder requireSn(Boolean v) {
this.requireSn = v;
return this;
}
public Builder cost(Money v) {
this.cost = v;
return this;
}
public Builder rawStatus(Integer v) {
this.rawStatus = v;
return this;
}
public Builder rawStatusName(String v) {
this.rawStatusName = v;
return this;
}
public Builder createdAt(Instant v) {
this.createdAt = v;
return this;
}
public Builder remark(String v) {
this.remark = v;
return this;
}
/** 更新时间。 */
public Builder updatedAt(Instant v) {
this.updatedAt = v;
return this;
}
/** 仓方实测长(cm)。 */
public Builder measuredLengthCm(Double v) {
this.measuredLengthCm = v;
return this;
}
/** 仓方实测宽(cm)。 */
public Builder measuredWidthCm(Double v) {
this.measuredWidthCm = v;
return this;
}
/** 仓方实测高(cm)。 */
public Builder measuredHeightCm(Double v) {
this.measuredHeightCm = v;
return this;
}
/** 仓方实测重量(g)。 */
public Builder measuredWeightGrams(Double v) {
this.measuredWeightGrams = v;
return this;
}
/** 申报价值。 */
public Builder declaredValue(Money v) {
this.declaredValue = v;
return this;
}
/** 是否保价。 */
public Builder insured(Boolean v) {
this.insured = v;
return this;
}
/** 保价费用。 */
public Builder insuranceFee(Money v) {
this.insuranceFee = v;
return this;
}
/** 是否开启保质期管理。 */
public Builder expirationControl(Boolean v) {
this.expirationControl = v;
return this;
}
/** 保质期天数。 */
public Builder expirationDays(Integer v) {
this.expirationDays = v;
return this;
}
/** 体积(立方厘米)。 */
public Builder volumeCm3(java.math.BigDecimal v) {
this.volumeCm3 = v;
return this;
}
/** 商品图片 URL。 */
public Builder imageUrl(String v) {
this.imageUrl = v;
return this;
}
/** 仓方状态码原值文本。 */
public Builder rawState(String v) {
this.rawState = v;
return this;
}
public Builder sourceProvider(WarehouseProvider v) {
this.sourceProvider = v;
return this;
}
public ProductInfo build() {
return new ProductInfo(this);
}
}
}

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

@ -1,35 +1,48 @@ @@ -1,35 +1,48 @@
package common.ecommerce.warehouse.model;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 商品查询条件。
* 商品查询条件(批量 / 分页)。
*
* <p>与 {@code WarehouseProductCapable.createOrUpdate} 的区别:那个是写,这个是读。
* 各仓支持的维度不同:不支持的维度由适配器<b>显式拒绝</b>,不静默忽略——
* 忽略一个过滤条件会让调用方以为「仓里就这些商品」。</p>
* <p>与 {@link InventoryQuery} 的口径一致:{@code providerSkus} 是<b>仓侧 SKU</b>,
* 即建档时下发给仓方的那一串(通常等于 {@code WarehouseProduct.providerSku()},
* 没给映射时就是 OMS SKU)。<b>SDK 不做 OMS→仓侧 SKU 的转换</b>——
* 那张映射表在宿主手里,这里静默转换会让查回来的东西对不上。</p>
*
* <p>目前两家仓(恒健 {@code /v2/product/queryPage}、信仓 {@code api.productlist})
* 都只支持按 SKU 过滤 + 分页,所以模型只放这两个维度。</p>
* <p>各仓支持的过滤维度不同,不支持的由适配器<b>显式拒绝</b>,
* 不静默忽略——忽略一个过滤条件会让结果对不上。</p>
*/
public final class ProductQuery {
/**
* 仓方 SKU 列表;空表示不限。
*
* <p>恒健是 {@code skus} 数组(一次可传多个);信仓是 {@code key} 单值(精确匹配)。
* 信仓收到多个 SKU 时由适配器<b>拒绝</b>而不是只取第一个。</p>
*/
/** 单次最多查多少个 SKU(各仓不同,由适配器按自己的上限再校验)。 */
public static final int MAX_SKUS = 100;
private final List<String> providerSkus;
/** 每页条数;0 表示用仓方默认。 */
/** 条码(UPC / 仓方条码)。 */
private final String barcode;
private final Instant createdAfter;
private final Instant createdBefore;
private final int pageSize;
/** 页码游标;null 表示第一页。 */
private final String cursor;
private ProductQuery(Builder b) {
this.providerSkus = Collections.unmodifiableList(new ArrayList<String>(b.providerSkus));
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;
}
@ -38,48 +51,82 @@ public final class ProductQuery { @@ -38,48 +51,82 @@ public final class ProductQuery {
return new Builder();
}
/** 仓方 SKU 列表;空表示不限。不可变。 */
/**
* 仓侧 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;
}
/** 每页条数;0 表示用仓方默认。 */
/** 条码;null 表示不按条码过滤。 */
public String barcode() {
return barcode;
}
public Instant createdAfter() {
return createdAfter;
}
public Instant createdBefore() {
return createdBefore;
}
/** 是否给了完整的创建时间窗。 */
public boolean hasCreatedRange() {
return createdAfter != null && createdBefore != null;
}
public int pageSize() {
return pageSize;
}
/** 页码游标;null 表示第一页。 */
/** 分页游标;null 表示第一页。 */
public String cursor() {
return cursor;
}
public Builder toBuilder() {
Builder b = builder().pageSize(pageSize).cursor(cursor);
b.providerSkus.addAll(providerSkus);
return b;
}
public static final class Builder {
private final List<String> providerSkus = new ArrayList<String>();
private int pageSize;
private String barcode;
private Instant createdAfter;
private Instant createdBefore;
private int pageSize = 100;
private String cursor;
/** 一个仓侧 SKU;空串忽略。 */
public Builder providerSku(String v) {
if (v != null && !v.trim().isEmpty()) {
this.providerSkus.add(v.trim());
}
return this;
}
public Builder providerSkus(List<String> v) {
this.providerSkus.clear();
if (v != null) {
for (String sku : v) {
if (sku != null && !sku.trim().isEmpty()) {
this.providerSkus.add(sku.trim());
}
for (String s : v) {
providerSku(s);
}
}
return this;
}
public Builder providerSku(String v) {
if (v != null && !v.trim().isEmpty()) {
this.providerSkus.add(v.trim());
}
public Builder barcode(String v) {
this.barcode = v;
return this;
}
public Builder createdAfter(Instant v) {
this.createdAfter = v;
return this;
}
public Builder createdBefore(Instant v) {
this.createdBefore = v;
return this;
}

336
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnHandle.java

@ -0,0 +1,336 @@ @@ -0,0 +1,336 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import java.time.Instant;
import java.util.List;
/**
* 退货处理单(仓方收货检验后按明细行拆出的处理单元)。
*
* <p>与 {@link WarehouseReturn} 的区别:那是<b>一张退货计划</b>,
* 这是计划下<b>一行 SKU 的一条待处理记录</b>——一张计划可以有多个处理单,
* 每行可以分别拍照 / 销毁 / 上架。</p>
*
* <p>填写处理方式({@code ReturnProcessCommand})要用的定位字段就在本对象里:
* {@link #returnPlanNo()} + {@link #returnHandleNo()} + {@link #providerSku()}
* + {@link #trackingNumber()}。</p>
*/
public final class ReturnHandle {
private final String returnPlanNo;
private final String returnHandleNo;
private final String returnNo;
private final String trackingNumber;
private final String providerSku;
private final String changeSku;
private final Integer quantity;
private final Integer handledQuantity;
private final Integer photosQuantity;
private final Integer inventoryType;
private final String handlingStatus;
private final String handlingStatusName;
private final String primaryHandlingMethod;
private final String sourceNo;
private final String warehouseCode;
private final String errorStatus;
private final String errorMessage;
private final List<String> photoUrls;
private final List<String> handledPhotoUrls;
private final Instant createdAt;
private final Instant updatedAt;
private final Instant completedAt;
private final WarehouseProvider sourceProvider;
private ReturnHandle(Builder b) {
if (b.returnPlanNo == null || b.returnPlanNo.trim().isEmpty()) {
throw new IllegalArgumentException("returnPlanNo must not be blank");
}
this.returnPlanNo = b.returnPlanNo.trim();
this.returnHandleNo = b.returnHandleNo;
this.returnNo = b.returnNo;
this.trackingNumber = b.trackingNumber;
this.providerSku = b.providerSku;
this.changeSku = b.changeSku;
this.quantity = b.quantity;
this.handledQuantity = b.handledQuantity;
this.photosQuantity = b.photosQuantity;
this.inventoryType = b.inventoryType;
this.handlingStatus = b.handlingStatus;
this.handlingStatusName = b.handlingStatusName;
this.primaryHandlingMethod = b.primaryHandlingMethod;
this.sourceNo = b.sourceNo;
this.warehouseCode = b.warehouseCode;
this.errorStatus = b.errorStatus;
this.errorMessage = b.errorMessage;
this.photoUrls = java.util.Collections.unmodifiableList(
new java.util.ArrayList<String>(b.photoUrls));
this.handledPhotoUrls = java.util.Collections.unmodifiableList(
new java.util.ArrayList<String>(b.handledPhotoUrls));
this.createdAt = b.createdAt;
this.updatedAt = b.updatedAt;
this.completedAt = b.completedAt;
this.sourceProvider = b.sourceProvider;
}
public static Builder builder() {
return new Builder();
}
/** 退货计划单号;必填。 */
public String returnPlanNo() {
return returnPlanNo;
}
/** 仓侧处理单号(恒健 {@code returnPlanHandleItemsNo})。 */
public String returnHandleNo() {
return returnHandleNo;
}
/** 退货编码;部分仓单独给一个(恒健「退货编码」)。 */
public String returnNo() {
return returnNo;
}
/** tracking 号。 */
public String trackingNumber() {
return trackingNumber;
}
/** 仓侧 SKU。 */
public String providerSku() {
return providerSku;
}
/** 换标后的 SKU;非换标为 null。 */
public String changeSku() {
return changeSku;
}
public Integer quantity() {
return quantity;
}
/** 已处理数量;未给为 null。 */
public Integer handledQuantity() {
return handledQuantity;
}
/** 已拍照片数量;未给为 null。 */
public Integer photosQuantity() {
return photosQuantity;
}
/** 库存类型:0 可售 / 1 不可售;未给为 null。 */
public Integer inventoryType() {
return inventoryType;
}
/** 处理状态原值。 */
public String handlingStatus() {
return handlingStatus;
}
/** 处理状态中文名;仓方未给为 null。 */
public String handlingStatusName() {
return handlingStatusName;
}
/** 主要处理方式原值(仓方码,如恒健 101~206)。 */
public String primaryHandlingMethod() {
return primaryHandlingMethod;
}
/** 来源单号。 */
public String sourceNo() {
return sourceNo;
}
public String warehouseCode() {
return warehouseCode;
}
/** 异常码原值;无异常为 null。 */
public String errorStatus() {
return errorStatus;
}
public String errorMessage() {
return errorMessage;
}
/** 照片 URL;不可变。 */
public List<String> photoUrls() {
return photoUrls;
}
/** 处理后照片 URL;不可变。 */
public List<String> handledPhotoUrls() {
return handledPhotoUrls;
}
public Instant createdAt() {
return createdAt;
}
public Instant updatedAt() {
return updatedAt;
}
public Instant completedAt() {
return completedAt;
}
public WarehouseProvider sourceProvider() {
return sourceProvider;
}
public static final class Builder {
private String returnPlanNo;
private String returnHandleNo;
private String returnNo;
private String trackingNumber;
private String providerSku;
private String changeSku;
private Integer quantity;
private Integer handledQuantity;
private Integer photosQuantity;
private Integer inventoryType;
private String handlingStatus;
private String handlingStatusName;
private String primaryHandlingMethod;
private String sourceNo;
private String warehouseCode;
private String errorStatus;
private String errorMessage;
private final List<String> photoUrls = new java.util.ArrayList<String>();
private final List<String> handledPhotoUrls = new java.util.ArrayList<String>();
private Instant createdAt;
private Instant updatedAt;
private Instant completedAt;
private WarehouseProvider sourceProvider;
public Builder returnPlanNo(String v) {
this.returnPlanNo = v;
return this;
}
public Builder returnHandleNo(String v) {
this.returnHandleNo = v;
return this;
}
public Builder returnNo(String v) {
this.returnNo = v;
return this;
}
public Builder trackingNumber(String v) {
this.trackingNumber = v;
return this;
}
public Builder providerSku(String v) {
this.providerSku = v;
return this;
}
public Builder changeSku(String v) {
this.changeSku = v;
return this;
}
public Builder quantity(Integer v) {
this.quantity = v;
return this;
}
public Builder handledQuantity(Integer v) {
this.handledQuantity = v;
return this;
}
public Builder photosQuantity(Integer v) {
this.photosQuantity = v;
return this;
}
public Builder inventoryType(Integer v) {
this.inventoryType = v;
return this;
}
public Builder handlingStatus(String v) {
this.handlingStatus = v;
return this;
}
public Builder handlingStatusName(String v) {
this.handlingStatusName = v;
return this;
}
public Builder primaryHandlingMethod(String v) {
this.primaryHandlingMethod = v;
return this;
}
public Builder sourceNo(String v) {
this.sourceNo = v;
return this;
}
public Builder warehouseCode(String v) {
this.warehouseCode = v;
return this;
}
public Builder errorStatus(String v) {
this.errorStatus = v;
return this;
}
public Builder errorMessage(String v) {
this.errorMessage = v;
return this;
}
public Builder photoUrl(String v) {
if (v != null && !v.trim().isEmpty()) {
this.photoUrls.add(v.trim());
}
return this;
}
public Builder handledPhotoUrl(String v) {
if (v != null && !v.trim().isEmpty()) {
this.handledPhotoUrls.add(v.trim());
}
return this;
}
public Builder createdAt(Instant v) {
this.createdAt = v;
return this;
}
public Builder updatedAt(Instant v) {
this.updatedAt = v;
return this;
}
public Builder completedAt(Instant v) {
this.completedAt = v;
return this;
}
public Builder sourceProvider(WarehouseProvider v) {
this.sourceProvider = v;
return this;
}
public ReturnHandle build() {
return new ReturnHandle(this);
}
}
}

118
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -40,6 +40,8 @@ import common.ecommerce.warehouse.model.InboundOrder; @@ -40,6 +40,8 @@ import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.LabelPrintTask;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.ReturnCommand;
@ -96,19 +98,20 @@ public final class WarehouseOperations { @@ -96,19 +98,20 @@ public final class WarehouseOperations {
}
/**
* 分页查商品。只读,不走幂等。
* 批量 / 分页查询仓侧商品资料。只读,不走幂等。
*
* <p>与 {@link #createProduct} 相对:那个写,这个读。</p>
* <p>查询入参的 {@code providerSkus} 是<b>仓侧 SKU</b>(建档时下发的那串)。
* SDK 不做 OMS→仓侧 SKU 转换。</p>
*/
public common.ecommerce.shared.support.Page<
common.ecommerce.warehouse.capability.WarehouseProduct> queryProducts(
final common.ecommerce.warehouse.model.ProductQuery query) {
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(),
"pageSize", query.pageSize(), "cursor", query.cursor()),
"barcode", query.barcode(),
"hasCreatedRange", query.hasCreatedRange(),
"cursor", query.cursor()),
p -> p.size(),
() -> ((WarehouseProductCapable) adapter).queryProducts(ctx, query));
() -> ((WarehouseProductCapable) adapter).query(ctx, query));
}
/**
@ -460,7 +463,10 @@ public final class WarehouseOperations { @@ -460,7 +463,10 @@ public final class WarehouseOperations {
/** 本仓默认的库存同步策略。 */
public InventorySyncStrategy inventorySyncStrategy() {
require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class);
return ((InventoryCapable) adapter).syncStrategy();
return CallSupport.observe(observer, ctx, "warehouse.inventory.syncStrategy",
CallSupport.params(),
r -> CallSupport.NO_COUNT,
() -> ((InventoryCapable) adapter).syncStrategy());
}
private void require(WarehouseCapability cap, Class<?> type) {
@ -534,16 +540,21 @@ public final class WarehouseOperations { @@ -534,16 +540,21 @@ public final class WarehouseOperations {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final InboundCapable capable = (InboundCapable) adapter;
common.ecommerce.shared.idempotency.WriteResult<InboundReceipt> result =
guard.execute(
WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
cmd.inboundRequestNo(), "create"),
() -> capable.create(ctx, cmd),
receipt -> receipt.providerInboundId());
if (result.alreadyCompleted()) {
return InboundReceipt.of(cmd.inboundRequestNo(), result.resultRef());
}
return result.value();
return CallSupport.observe(observer, ctx, "warehouse.inbound.create",
CallSupport.params("inboundRequestNo", cmd.inboundRequestNo()),
r -> CallSupport.NO_COUNT,
() -> {
common.ecommerce.shared.idempotency.WriteResult<InboundReceipt> result =
guard.execute(
WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
cmd.inboundRequestNo(), "create"),
() -> capable.create(ctx, cmd),
receipt -> receipt.providerInboundId());
if (result.alreadyCompleted()) {
return InboundReceipt.of(cmd.inboundRequestNo(), result.resultRef());
}
return result.value();
});
}
/** 查入库单。 */
@ -631,7 +642,10 @@ public final class WarehouseOperations { @@ -631,7 +642,10 @@ public final class WarehouseOperations {
/** BOL 文档。 */
public List<String> bols(String inboundRef) {
require(WarehouseCapability.INBOUND, InboundCapable.class);
return ((InboundCapable) adapter).bols(ctx, inboundRef);
return CallSupport.observe(observer, ctx, "warehouse.inbound.bols",
CallSupport.params("inboundRef", inboundRef),
List::size,
() -> ((InboundCapable) adapter).bols(ctx, inboundRef));
}
/**
@ -683,20 +697,25 @@ public final class WarehouseOperations { @@ -683,20 +697,25 @@ public final class WarehouseOperations {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final WarehouseReturnCapable capable = (WarehouseReturnCapable) adapter;
common.ecommerce.shared.idempotency.WriteResult<WarehouseReturn> result =
guard.execute(
WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
cmd.returnRequestNo(), "create"),
() -> capable.create(ctx, cmd),
ret -> ret.providerReturnId());
if (result.alreadyCompleted()) {
return WarehouseReturn.builder()
.returnRequestNo(cmd.returnRequestNo())
.providerReturnId(result.resultRef())
.warehouseCode(account.warehouseCode())
.build();
}
return result.value();
return CallSupport.observe(observer, ctx, "warehouse.return.create",
CallSupport.params("returnRequestNo", cmd.returnRequestNo()),
r -> CallSupport.NO_COUNT,
() -> {
common.ecommerce.shared.idempotency.WriteResult<WarehouseReturn> result =
guard.execute(
WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
cmd.returnRequestNo(), "create"),
() -> capable.create(ctx, cmd),
ret -> ret.providerReturnId());
if (result.alreadyCompleted()) {
return WarehouseReturn.builder()
.returnRequestNo(cmd.returnRequestNo())
.providerReturnId(result.resultRef())
.warehouseCode(account.warehouseCode())
.build();
}
return result.value();
});
}
public WarehouseReturn get(String returnRequestNo) {
@ -725,6 +744,22 @@ public final class WarehouseOperations { @@ -725,6 +744,22 @@ public final class WarehouseOperations {
}
/**
* 分页查<b>退货处理单</b>。只读,不走幂等。
*
* <p>与 {@link #query(ReturnQuery)} 的区别:那个查一张退货计划,
* 这个查计划下每一行 SKU 的待处理记录。填处理方式要用的四项定位就在结果里。</p>
*/
public Page<common.ecommerce.warehouse.model.ReturnHandle> queryHandles(ReturnQuery query) {
require(WarehouseCapability.RETURN, WarehouseReturnCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.return.queryHandles",
CallSupport.params("cursor", query.cursor(),
"orderNo", query.orderNo(),
"warehouseCode", query.warehouseCode()),
p -> p.size(),
() -> ((WarehouseReturnCapable) adapter).queryHandles(ctx, query));
}
/**
* 按明细行设置检验后处理方式。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + providerReturnNo + lineId + process}。
*
@ -765,12 +800,17 @@ public final class WarehouseOperations { @@ -765,12 +800,17 @@ public final class WarehouseOperations {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final WarehouseReturnCapable capable = (WarehouseReturnCapable) adapter;
common.ecommerce.shared.idempotency.WriteResult<Boolean> result = guard.execute(
WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
providerReturnNo, "cancel"),
() -> capable.cancel(ctx, providerReturnNo),
ok -> Boolean.TRUE.equals(ok) ? "true" : null);
return result.alreadyCompleted() || Boolean.TRUE.equals(result.value());
return CallSupport.observe(observer, ctx, "warehouse.return.cancel",
CallSupport.params("providerReturnNo", providerReturnNo),
r -> CallSupport.NO_COUNT,
() -> {
common.ecommerce.shared.idempotency.WriteResult<Boolean> result = guard.execute(
WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
providerReturnNo, "cancel"),
() -> capable.cancel(ctx, providerReturnNo),
ok -> Boolean.TRUE.equals(ok) ? "true" : null);
return result.alreadyCompleted() || Boolean.TRUE.equals(result.value());
});
}
}

28
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java

@ -57,16 +57,26 @@ public final class WarehouseOutbounds { @@ -57,16 +57,26 @@ public final class WarehouseOutbounds {
throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
}
final OutboundCapable capable = (OutboundCapable) adapter;
WriteIdentity scope = WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
final WriteIdentity scope = WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
cmd.outboundRequestNo(), "create");
common.ecommerce.shared.idempotency.WriteResult<OutboundReceipt> result =
guard.execute(scope, () -> capable.create(ctx, cmd),
receipt -> receipt.providerOrderId());
if (result.alreadyCompleted()) {
// 回放:本次没有调仓,只有上次记录的结果引用
return OutboundReceipt.of(cmd.outboundRequestNo(), result.resultRef(), "ALREADY_COMPLETED");
}
return result.value();
// 写操作也要有一条门面级记录:幂等层只记 writes.create 的裁决,
// 不记「这次调了仓、成功还是失败」。缺了它,操作日志里就看不到下发动作。
return common.ecommerce.shared.audit.CallSupport.observe(observer, ctx,
"warehouse.outbound.create",
common.ecommerce.shared.audit.CallSupport.params(
"outboundRequestNo", cmd.outboundRequestNo()),
r -> common.ecommerce.shared.audit.CallSupport.NO_COUNT,
() -> {
common.ecommerce.shared.idempotency.WriteResult<OutboundReceipt> result =
guard.execute(scope, () -> capable.create(ctx, cmd),
receipt -> receipt.providerOrderId());
if (result.alreadyCompleted()) {
// 回放:本次没有调仓,只有上次记录的结果引用
return OutboundReceipt.of(cmd.outboundRequestNo(), result.resultRef(),
"ALREADY_COMPLETED");
}
return result.value();
});
}
/** 按仓单号或 OMS 单号查单。 */

7
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java

@ -36,6 +36,9 @@ public final class EdayunConstants { @@ -36,6 +36,9 @@ public final class EdayunConstants {
/** 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。 */
public static final String PATH_PRODUCT_CREATE = "/webApi/skuInfo/v1/createProduct";
/** 批量查询产品分页({@code POST /webApi/skuInfo/v1/listProductPage})。 */
public static final String PATH_PRODUCT_LIST = "/webApi/skuInfo/v1/listProductPage";
/** 创建出库单({@code POST /webApi/order/v1/createOrder})。 */
public static final String PATH_ORDER_CREATE = "/webApi/order/v1/createOrder";
@ -108,12 +111,12 @@ public final class EdayunConstants { @@ -108,12 +111,12 @@ public final class EdayunConstants {
public static final String PATH_CASE_MARK_PRINT = "/webApi/skuInfo/v2/printBarcode";
/**
* 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
* 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
*
* <p>端点名是 newPrintCaseMark,实际打的是 SKU 标——已与仓方确认。</p>
*/
public static final String PATH_SKU_LABEL_PRINT =
"/webApi/entryInfo/v1/newPrintCaseMarkContentType";
"/webApi/entryInfo/v1/newPrintCaseMark";
/** 查询客户自有物流服务(承运商)({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。 */
public static final String PATH_CARRIERS = "/webApi/carrier/v1/listCarrierByWarehouse";

71
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java

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

1
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java

@ -8,7 +8,6 @@ import common.ecommerce.shared.spi.TokenStore; @@ -8,7 +8,6 @@ import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory;
/**
* 易达云适配器工厂。

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

@ -36,6 +36,26 @@ public final class EdayunLogisticsProductMapper { @@ -36,6 +36,26 @@ public final class EdayunLogisticsProductMapper {
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} 与无效行。 */
public static List<LogisticsProduct> toProducts(
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 { @@ -163,6 +163,8 @@ public final class EdayunOrderMapper {
for (OutboundLine line : lines) {
EdayunCreateOrderDtos.CreateOrderRequest.ProductItem item =
new EdayunCreateOrderDtos.CreateOrderRequest.ProductItem();
// 必须与建档时下发的 skuCode 一致(providerSku 优先,见 EdayunProductMapper.skuOf)。
// 传 OMS SKU 而建档时用的是 providerSku 的话,仓方会报 SKU 不存在。
item.productSku = firstNonBlank(line.providerSku(), line.omsSku());
item.quantity = line.quantity();
Money value = line.declareValue();

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

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

35
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java

@ -46,6 +46,8 @@ public final class EdayunReturnMapper { @@ -46,6 +46,8 @@ public final class EdayunReturnMapper {
*/
public static EdayunReturnDtos.SaveReturnRequest toRequest(ReturnCommand cmd,
String providerWarehouseId) {
requireHonorable(cmd);
EdayunReturnDtos.SaveReturnRequest req = new EdayunReturnDtos.SaveReturnRequest();
req.returnType = RETURN_TYPE_SELF_SHIP;
@ -62,6 +64,35 @@ public final class EdayunReturnMapper { @@ -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}。
*
* <p>命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。</p>
@ -134,6 +165,10 @@ public final class EdayunReturnMapper { @@ -134,6 +165,10 @@ public final class EdayunReturnMapper {
}
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) {
return a.trim();

40
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java

@ -64,12 +64,7 @@ public final class EdayunRmaListMapper { @@ -64,12 +64,7 @@ public final class EdayunRmaListMapper {
req.trackingNos = query.trackingNo().trim();
}
Long warehouseId = warehouseIdOf(providerWarehouseId);
if (warehouseId != null) {
req.warehouseId = warehouseId;
} else if (hasText(query.warehouseCode())) {
req.warehouseCode = query.warehouseCode().trim();
}
applyWarehouseFilter(req, query, providerWarehouseId);
if (hasText(query.providerSku())) {
req.skuCode = query.providerSku().trim();
@ -87,6 +82,32 @@ public final class EdayunRmaListMapper { @@ -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}。
*
* <p>null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。</p>
@ -153,9 +174,10 @@ public final class EdayunRmaListMapper { @@ -153,9 +174,10 @@ public final class EdayunRmaListMapper {
// 列表没有来源单号字段,用 RMA 号兜底;orderRef 用平台 / 出库单号
.returnRequestNo(firstNonBlank(row.rmaCode, row.ordOrderCode))
.providerReturnId(row.rmaCode)
// 文档响应示例没有 warehouseCode,但真机会返回,优先用它
.warehouseCode(firstNonBlank(row.warehouseCode, row.warehouseName,
fallbackWarehouseCode))
// 列表有 warehouseCode(真机返回,文档示例里没有)就直接用;
// **不能退化成 warehouseName**——那是展示名(美西1仓),
// 宿主拿 warehouseCode 做 equals / 回传查询会全线失效。
.warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode))
.orderRef(firstNonBlank(row.platformOrderCode, row.ordOrderCode))
.type(row.returnTypeName)
.status(EdayunRmaStatus.toCore(row.status, row.statusName))

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

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

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

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

96
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java

@ -0,0 +1,96 @@ @@ -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; @@ -6,7 +6,7 @@ import java.util.List;
/**
* 易达云报文结构:打印 SKU 标
* ({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
* ({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
*
* <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; @@ -18,7 +18,6 @@ import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
@ -150,11 +149,4 @@ class EdayunCarrierTest { @@ -150,11 +149,4 @@ class EdayunCarrierTest {
assertTrue(transport.lastDataRequest().body().contains("\"warehouseId\":2"));
}
/** 仓库列表接口易达云没有,显式拒绝而不是空列表。 */
@Test
void warehousesAreUnsupported() {
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(stub("{}"), new JacksonJsonCodec())
.warehouses(ctx("2")));
}
}

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

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

215
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java

@ -0,0 +1,215 @@ @@ -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 { @@ -84,6 +84,41 @@ class EdayunReturnTest {
EdayunReturnMapper.toRequest(cmd, "2").relationNo);
}
/** 易达云不接受的命令字段要在本地拒绝,不能静默丢弃。 */
@Test
void unsupportedCommandFieldsAreRejected() {
assertTrue(throwsOn(ReturnCommand.builder()
.returnRequestNo("RT-9").saleOrderNo("SO-1")
.returnTrackingNo("1Z1").carrierCode("UPS")
.lineName("默认项目")
.line("sku", 1, ReturnDealMethod.DESTROY).build())
.contains("lineName"));
assertTrue(throwsOn(ReturnCommand.builder()
.returnRequestNo("RT-9").saleOrderNo("SO-1")
.returnTrackingNo("1Z1").carrierCode("UPS")
.estimatedReceiveDate(java.time.LocalDate.of(2026, 12, 1))
.line("sku", 1, ReturnDealMethod.DESTROY).build())
.contains("estimatedReceiveDate"));
assertTrue(throwsOn(ReturnCommand.builder()
.returnRequestNo("RT-9").saleOrderNo("SO-1")
.returnTrackingNo("1Z1").carrierCode("UPS")
.returnReason("damaged")
.line("sku", 1, ReturnDealMethod.DESTROY).build())
.contains("returnReason"));
}
private static String throwsOn(ReturnCommand cmd) {
try {
EdayunReturnMapper.toRequest(cmd, "2");
org.junit.jupiter.api.Assertions.fail("should have thrown");
return "";
} catch (IllegalArgumentException e) {
return e.getMessage();
}
}
@Test
void nonNumericWarehouseGoesToWarehouseCode() {
ReturnCommand noWarehouse = ReturnCommand.builder()

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

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

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

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

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

106
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java

@ -0,0 +1,106 @@ @@ -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 @@ @@ -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()));
}
}

34
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java

@ -50,7 +50,6 @@ import common.ecommerce.warehouse.capability.TrackingChangeCapable; @@ -50,7 +50,6 @@ import common.ecommerce.warehouse.capability.TrackingChangeCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.AddressType;
import common.ecommerce.warehouse.enums.CancelEligibility;
@ -85,6 +84,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot; @@ -85,6 +84,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnHandle;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.TransferQuery;
@ -94,6 +94,8 @@ import common.ecommerce.warehouse.model.LogisticsProduct; @@ -94,6 +94,8 @@ import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
@ -367,7 +369,33 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -367,7 +369,33 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
*
* <p>恒健没有对应的统一模型:这里返回仓方的处理单行,供宿主填写处理方式与回收照片。</p>
*/
public Page<HengjianReturnHandleDtos.HandleRow> queryReturnHandles(
@Override
public Page<ReturnHandle> queryHandles(WarehouseContext ctx, ReturnQuery query) {
if (query == null) {
query = ReturnQuery.builder().build();
}
// 统一入口只带游标 / 仓库 / 单号;其余维度恒健这里没有对应口径,给了就拒绝
if (query.hasCreatedRange() || query.trackingNo() != null
|| query.providerSku() != null || !query.statuses().isEmpty()
|| query.orderNoType() != null) {
throw validation(ctx, OP_RETURN_HANDLES,
"hengjian return handle list takes returnPlanNo / tracking / warehouse / "
+ "handlingStatus only; use queryHandlesAdvanced for those");
}
List<String> planNos = query.orderNo() == null
? null : java.util.Collections.singletonList(query.orderNo());
List<String> warehouseCodes = query.warehouseCode() == null
? null : java.util.Collections.singletonList(query.warehouseCode());
return queryHandlesAdvanced(ctx, planNos, null, warehouseCodes,
null, null, null, query.cursor());
}
/**
* 多条件分页查退货处理单({@code POST /v1/saleReturn/getReturnPlanHandlePage})。
*
* <p><b>请求是平铺的</b>(无 {@code params} 包裹),与 thirdParty 那两个不同。</p>
*/
public Page<ReturnHandle> queryHandlesAdvanced(
WarehouseContext ctx, List<String> returnPlanNos, List<String> trackingNos,
List<String> warehouseCodes, List<Integer> handlingStatuses,
String createdStart, String createdEnd, String cursor) {
@ -1645,7 +1673,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -1645,7 +1673,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
* <p>响应 {@code data} 是分页对象(不是数组);{@code total} 用来判断是否还有下一页。</p>
*/
@Override
public Page<WarehouseProduct> queryProducts(WarehouseContext ctx, ProductQuery query) {
public Page<ProductInfo> query(WarehouseContext ctx, ProductQuery query) {
HengjianProductQueryDtos.QueryRequest body = HengjianProductQueryMapper.toRequest(query);
String raw = execute(ctx, HengjianConstants.PATH_PRODUCT_QUERY_PAGE, body, OP_PRODUCT_QUERY);
HengjianProductQueryDtos.QueryResponse resp =

34
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java

@ -3,7 +3,7 @@ package common.ecommerce.hengjian.adapter; @@ -3,7 +3,7 @@ package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianProductQueryDtos;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import java.math.BigDecimal;
@ -80,17 +80,17 @@ public final class HengjianProductQueryMapper { @@ -80,17 +80,17 @@ public final class HengjianProductQueryMapper {
// ================================================================ 响应
/** 响应 → 分页商品。 */
public static Page<WarehouseProduct> toPage(HengjianProductQueryDtos.PageData data,
public static Page<ProductInfo> toPage(HengjianProductQueryDtos.PageData data,
String requestedCursor, int requestedPageSize) {
if (data == null || data.data == null || data.data.isEmpty()) {
return Page.last(new ArrayList<WarehouseProduct>());
return Page.last(new ArrayList<ProductInfo>());
}
List<WarehouseProduct> out = new ArrayList<WarehouseProduct>(data.data.size());
List<ProductInfo> out = new ArrayList<ProductInfo>(data.data.size());
for (HengjianProductQueryDtos.ProductRow row : data.data) {
if (row == null) {
continue;
}
WarehouseProduct product = toProduct(row);
ProductInfo product = toProduct(row);
if (product != null) {
out.add(product);
}
@ -99,7 +99,7 @@ public final class HengjianProductQueryMapper { @@ -99,7 +99,7 @@ public final class HengjianProductQueryMapper {
}
/** 按 {@code total} 判断是否还有下一页。 */
static Page<WarehouseProduct> nextPage(List<WarehouseProduct> items, Long totalRaw,
static Page<ProductInfo> nextPage(List<ProductInfo> items, Long totalRaw,
String requestedCursor, int requestedPageSize) {
int page = pageOf(requestedCursor);
if (totalRaw == null) {
@ -112,16 +112,13 @@ public final class HengjianProductQueryMapper { @@ -112,16 +112,13 @@ public final class HengjianProductQueryMapper {
return Page.of(items, String.valueOf(page + 1));
}
/** 一条商品 → 统一模型;{@code sku} 缺失时返回 null(跳过脏数据,不整页失败)。 */
static WarehouseProduct toProduct(HengjianProductQueryDtos.ProductRow row) {
/** 一条商品 → 查询结果模型;{@code sku} 缺失时返回 null(跳过脏数据,不整页失败)。 */
static ProductInfo toProduct(HengjianProductQueryDtos.ProductRow row) {
String sku = trimToNull(row.sku);
if (sku == null) {
return null;
}
WarehouseProduct.Builder b = WarehouseProduct.builder()
// 查询结果允许尺寸 / 重量缺失(用 0 表示),不伪造
.allowUnknownDimensions(true)
.omsSku(sku)
ProductInfo.Builder b = ProductInfo.builder()
.providerSku(sku)
.name(firstNonBlank(row.name, row.nameEn, sku))
.nameEn(trimToNull(row.nameEn))
@ -133,9 +130,9 @@ public final class HengjianProductQueryMapper { @@ -133,9 +130,9 @@ public final class HengjianProductQueryMapper {
.widthCm(doubleOrZero(row.width))
.heightCm(doubleOrZero(row.height))
.weightGrams(doubleOrZero(row.weight))
.itemLengthCm(doubleOrZero(row.itemLength))
.itemWidthCm(doubleOrZero(row.itemWidth))
.itemHeightCm(doubleOrZero(row.itemHeight))
.itemLengthCm(doubleOrNull(row.itemLength))
.itemWidthCm(doubleOrNull(row.itemWidth))
.itemHeightCm(doubleOrNull(row.itemHeight))
// 仓库实测,与申报尺寸分开存
.measuredLengthCm(doubleOrNull(row.measurementLength))
.measuredWidthCm(doubleOrNull(row.measurementWidth))
@ -149,7 +146,8 @@ public final class HengjianProductQueryMapper { @@ -149,7 +146,8 @@ public final class HengjianProductQueryMapper {
.packedWeightGrams(doubleOrNull(row.packedWeight))
// 保质期
.expirationControl(oneZeroToBoolean(row.expirationControl))
.expirationDays(intOrNull(row.expirationDate));
.expirationDays(intOrNull(row.expirationDate))
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.HENGJIAN);
Integer productType = intOrNull(row.productType);
if (productType != null) {
@ -160,11 +158,11 @@ public final class HengjianProductQueryMapper { @@ -160,11 +158,11 @@ public final class HengjianProductQueryMapper {
if (insured != null) {
b.insured("Y".equalsIgnoreCase(insured));
}
// 成本:带币种
// 成本 + 币种
BigDecimal cost = decimalOrNull(row.cost);
String currency = trimToNull(row.currency);
if (cost != null && currency != null) {
b.cost(Money.of(cost, currency));
b.declaredValue(Money.of(cost, currency));
}
BigDecimal rate = decimalOrNull(row.isInsuranceRate);
if (rate != null && currency != null) {

100
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java

@ -8,6 +8,7 @@ import common.ecommerce.shared.support.Page; @@ -8,6 +8,7 @@ import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnHandle;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseAttachment;
import common.ecommerce.warehouse.model.WarehouseReturn;
@ -260,16 +261,16 @@ public final class HengjianReturnQueryMapper { @@ -260,16 +261,16 @@ public final class HengjianReturnQueryMapper {
}
/** 处理单列表 → 统一 Page(每行是一条处理单,不是退货单)。 */
public static Page<HengjianReturnHandleDtos.HandleRow> toHandlePage(
public static Page<ReturnHandle> toHandlePage(
HengjianReturnHandleDtos.HandlePageData data, String cursor, int requestedRows) {
if (data == null) {
return Page.last(new ArrayList<HengjianReturnHandleDtos.HandleRow>());
return Page.last(new ArrayList<ReturnHandle>());
}
List<HengjianReturnHandleDtos.HandleRow> out = new ArrayList<HengjianReturnHandleDtos.HandleRow>();
List<ReturnHandle> out = new ArrayList<ReturnHandle>();
if (data.content != null) {
for (HengjianReturnHandleDtos.HandleRow row : data.content) {
if (row != null) {
out.add(row);
out.add(toHandle(row));
}
}
}
@ -282,6 +283,97 @@ public final class HengjianReturnQueryMapper { @@ -282,6 +283,97 @@ public final class HengjianReturnQueryMapper {
return Page.of(out, String.valueOf(next));
}
/**
* 一条处理单 → 统一模型。
*
* <p>恒健的处理单行<b>没给「退货编码」</b>({@code returnNo}),那个字段只在
* 填写处理方式时必填。所以这里 {@code returnNo} 留 null——不拿处理单号冒充,
* 两者语义不同。调用方填处理方式时需要从别处拿到它。</p>
*/
static ReturnHandle toHandle(HengjianReturnHandleDtos.HandleRow row) {
ReturnHandle.Builder b = ReturnHandle.builder()
.returnPlanNo(row.returnPlanNo)
.returnHandleNo(trimToNull(row.returnPlanHandleItemsNo))
.trackingNumber(trimToNull(row.tracking))
.providerSku(trimToNull(row.erpSku))
.changeSku(trimToNull(row.changeErpsku))
.quantity(row.quantity)
.handledQuantity(row.handlingQuantity)
.photosQuantity(row.photosQuantity)
.inventoryType(parseIntOrNull(row.inventoryType))
.handlingStatus(trimToNull(row.handlingStatus))
.handlingStatusName(handlingStatusName(row.handlingStatus))
.primaryHandlingMethod(trimToNull(row.primaryHandlingMethod))
.sourceNo(firstNonBlank(row.sourceNo, row.openSourceNo))
.warehouseCode(trimToNull(row.orgWarehouseCode))
.errorStatus(trimToNull(row.errorStatus))
.createdAt(parseTime(row.createdAt))
.updatedAt(parseTime(row.updatedAt))
.completedAt(parseTime(row.completeAt))
.sourceProvider(WarehouseProvider.HENGJIAN);
for (String url : urls(row.fileUrlList)) {
b.photoUrl(url);
}
for (String url : urls(row.handleFileUrlList)) {
b.handledPhotoUrl(url);
}
return b.build();
}
/** 处理状态码 → 中文名;认不出的返回 null,不猜。 */
static String handlingStatusName(String raw) {
String v = trimToNull(raw);
if (v == null) {
return null;
}
switch (v) {
case "5":
return "待处理";
case "10":
return "处理中";
case "15":
return "已完成";
case "20":
return "已取消";
default:
return null;
}
}
/** 照片字段文档标 string、实际可能是数组:两种都接。 */
static List<String> urls(Object raw) {
List<String> out = new ArrayList<String>();
if (raw == null) {
return out;
}
if (raw instanceof List) {
for (Object o : (List<?>) raw) {
String v = trimToNull(o == null ? null : String.valueOf(o));
if (v != null) {
out.add(v);
}
}
return out;
}
String v = trimToNull(String.valueOf(raw));
if (v != null) {
out.add(v);
}
return out;
}
static Integer parseIntOrNull(String raw) {
String v = trimToNull(raw);
if (v == null) {
return null;
}
try {
return Integer.valueOf(v);
} catch (NumberFormatException e) {
return null;
}
}
// ================================================================ 处理方式
/**

48
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java

@ -6,7 +6,7 @@ import common.ecommerce.shared.spi.ChannelSecret; @@ -6,7 +6,7 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
@ -69,7 +69,7 @@ class HengjianProductQueryTest { @@ -69,7 +69,7 @@ class HengjianProductQueryTest {
@Test
void sendsPagingAsString() {
RecordingTransport transport = listing(body(ONE_ROW, 1));
adapter(transport).queryProducts(CTX, ProductQuery.builder().pageSize(50).build());
adapter(transport).query(CTX, ProductQuery.builder().pageSize(50).build());
String json = transport.lastDataRequest().body();
assertTrue(json.contains("\"pageSize\":\"50\""), json);
@ -79,11 +79,11 @@ class HengjianProductQueryTest { @@ -79,11 +79,11 @@ class HengjianProductQueryTest {
@Test
void sendsSkusOnlyWhenGiven() {
RecordingTransport absent = listing(body("", 0));
adapter(absent).queryProducts(CTX, ProductQuery.builder().build());
adapter(absent).query(CTX, ProductQuery.builder().build());
assertFalse(absent.lastDataRequest().body().contains("\"skus\""));
RecordingTransport present = listing(body("", 0));
adapter(present).queryProducts(CTX, ProductQuery.builder()
adapter(present).query(CTX, ProductQuery.builder()
.providerSkus(java.util.Arrays.asList("A", "B")).build());
String json = present.lastDataRequest().body();
assertTrue(json.contains("\"skus\":[\"A\",\"B\"]"), json);
@ -92,7 +92,7 @@ class HengjianProductQueryTest { @@ -92,7 +92,7 @@ class HengjianProductQueryTest {
@Test
void cursorBecomesPageNum() {
RecordingTransport transport = listing(body(ONE_ROW, 1000));
adapter(transport).queryProducts(CTX, ProductQuery.builder().cursor("3").pageSize(10).build());
adapter(transport).query(CTX, ProductQuery.builder().cursor("3").pageSize(10).build());
assertTrue(transport.lastDataRequest().body().contains("\"pageNum\":\"3\""));
}
@ -100,7 +100,7 @@ class HengjianProductQueryTest { @@ -100,7 +100,7 @@ class HengjianProductQueryTest {
@Test
void rejectsPageSizeAboveMax() {
assertThrows(IllegalArgumentException.class,
() -> adapter(listing(body("", 0))).queryProducts(CTX,
() -> adapter(listing(body("", 0))).query(CTX,
ProductQuery.builder().pageSize(500).build()));
}
@ -108,12 +108,12 @@ class HengjianProductQueryTest { @@ -108,12 +108,12 @@ class HengjianProductQueryTest {
@Test
void mapsProductFields() {
Page<WarehouseProduct> page = adapter(listing(body(ONE_ROW, 1)))
.queryProducts(CTX, ProductQuery.builder().build());
Page<ProductInfo> page = adapter(listing(body(ONE_ROW, 1)))
.query(CTX, ProductQuery.builder().build());
assertEquals(1, page.size());
WarehouseProduct p = page.items().get(0);
assertEquals("SKU-A", p.omsSku());
ProductInfo p = page.items().get(0);
assertEquals("SKU-A", p.providerSku());
assertEquals("小部件", p.name());
assertEquals("Widget", p.nameEn());
assertEquals("UPC-A", p.barcode());
@ -134,8 +134,8 @@ class HengjianProductQueryTest { @@ -134,8 +134,8 @@ class HengjianProductQueryTest {
/** 仓库实测尺寸与申报尺寸分开存。 */
@Test
void keepsMeasuredDimensionsSeparate() {
WarehouseProduct p = adapter(listing(body(ONE_ROW, 1)))
.queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
ProductInfo p = adapter(listing(body(ONE_ROW, 1)))
.query(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(30.0, p.lengthCm(), 0.001);
assertEquals(30.5, p.measuredLengthCm(), 0.001);
@ -147,8 +147,8 @@ class HengjianProductQueryTest { @@ -147,8 +147,8 @@ class HengjianProductQueryTest {
void fallsBackToItemLengthWhenLengthMissing() {
String row = "{\"sku\":\"SKU-B\",\"width\":20,\"height\":10,\"weight\":100,"
+ "\"itemLength\":29,\"itemWidth\":19,\"itemHeight\":9}";
WarehouseProduct p = adapter(listing(body(row, 1)))
.queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
ProductInfo p = adapter(listing(body(row, 1)))
.query(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(29.0, p.lengthCm(), 0.001, "没有 length 时用 itemLength");
}
@ -156,21 +156,21 @@ class HengjianProductQueryTest { @@ -156,21 +156,21 @@ class HengjianProductQueryTest {
/** total 决定是否还有下一页。 */
@Test
void pagingUsesTotal() {
Page<WarehouseProduct> more = adapter(listing(body(ONE_ROW, 500)))
.queryProducts(CTX, ProductQuery.builder().pageSize(100).build());
Page<ProductInfo> more = adapter(listing(body(ONE_ROW, 500)))
.query(CTX, ProductQuery.builder().pageSize(100).build());
assertTrue(more.hasMore());
assertEquals("2", more.nextCursor());
Page<WarehouseProduct> done = adapter(listing(body(ONE_ROW, 1)))
.queryProducts(CTX, ProductQuery.builder().pageSize(100).build());
Page<ProductInfo> done = adapter(listing(body(ONE_ROW, 1)))
.query(CTX, ProductQuery.builder().pageSize(100).build());
assertFalse(done.hasMore());
assertNull(done.nextCursor());
}
@Test
void emptyPageIsLast() {
Page<WarehouseProduct> page = adapter(listing(body("", 0)))
.queryProducts(CTX, ProductQuery.builder().build());
Page<ProductInfo> page = adapter(listing(body("", 0)))
.query(CTX, ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
assertFalse(page.hasMore());
}
@ -180,17 +180,17 @@ class HengjianProductQueryTest { @@ -180,17 +180,17 @@ class HengjianProductQueryTest {
void skipsRowsWithoutSku() {
String row = "{\"name\":\"无SKU\"}";
assertTrue(adapter(listing(body(row, 1)))
.queryProducts(CTX, ProductQuery.builder().build()).items().isEmpty());
.query(CTX, ProductQuery.builder().build()).items().isEmpty());
}
/** 尺寸缺失用 0 表示「仓方未给」。 */
@Test
void missingDimensionsBecomeZero() {
String row = "{\"sku\":\"SKU-C\"}";
WarehouseProduct p = adapter(listing(body(row, 1)))
.queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
ProductInfo p = adapter(listing(body(row, 1)))
.query(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(0.0, p.lengthCm(), 0.001);
assertFalse(p.hasDimensions());
assertEquals(0.0, p.lengthCm(), 0.001);
}
}

20
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java

@ -9,6 +9,7 @@ import common.ecommerce.shared.testkit.RecordingTransport; @@ -9,6 +9,7 @@ import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.model.ReturnHandle;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
@ -229,7 +230,7 @@ class HengjianReturnQueryTest { @@ -229,7 +230,7 @@ class HengjianReturnQueryTest {
@Test
void handleListPostsFlatBody() {
RecordingTransport transport = handling();
adapter(transport).queryReturnHandles(CTX,
adapter(transport).queryHandlesAdvanced(CTX,
Collections.singletonList("RC1"), null, null,
Collections.singletonList(15), null, null, null);
@ -243,19 +244,18 @@ class HengjianReturnQueryTest { @@ -243,19 +244,18 @@ class HengjianReturnQueryTest {
@Test
void handleListMapsRows() {
Page<HengjianReturnHandleDtos.HandleRow> page =
adapter(handling()).queryReturnHandles(CTX,
Collections.singletonList("RC1"), null, null, null, null, null, null);
Page<ReturnHandle> page =
adapter(handling()).queryHandlesAdvanced(CTX, Collections.singletonList("RC1"), null, null, null, null, null, null);
assertEquals(1, page.size());
assertTrue(page.hasMore(), "last=false 应给出下一页");
assertEquals("2", page.nextCursor());
HengjianReturnHandleDtos.HandleRow row = page.items().get(0);
assertEquals("RC25081300010", row.returnPlanNo);
assertEquals("RP25081400001", row.returnPlanHandleItemsNo);
assertEquals("15", row.handlingStatus);
assertEquals("203", row.primaryHandlingMethod);
assertEquals("C-2077-BU", row.changeErpsku);
ReturnHandle row = page.items().get(0);
assertEquals("RC25081300010", row.returnPlanNo());
assertEquals("RP25081400001", row.returnHandleNo());
assertEquals("15", row.handlingStatus());
assertEquals("203", row.primaryHandlingMethod());
assertEquals("C-2077-BU", row.changeSku());
}
// ================================================================ 处理方式

213
warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseCallObserverTest.java

@ -0,0 +1,213 @@ @@ -0,0 +1,213 @@
package common.ecommerce.warehouse.sdk;
import common.ecommerce.shared.audit.CallObserver;
import common.ecommerce.shared.audit.CallRecord;
import common.ecommerce.shared.testkit.InMemoryIdempotencyStore;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.testkit.FakeWarehouseAdapter;
import common.ecommerce.warehouse.testkit.InMemoryWarehouses;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.ArrayList;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 门面操作日志({@code CallObserver})契约测试。
*
* <p>这里验证的是「<b>新仓接入后操作日志默认就通</b>」这个承诺:
* 适配器只写协议转换、不自己造门面,宿主注入 {@code callObserver} 之后
* 每个门面调用都必然产生一条 {@link CallRecord}。</p>
*/
class WarehouseCallObserverTest {
private static final Instant T0 = Instant.parse("2026-11-09T00:00:00Z");
private static final Clock CLOCK = Clock.fixed(T0, ZoneOffset.UTC);
private static final String WH = "YQN-RF_NY_US";
private RecordingObserver observer;
private WarehouseSdk sdk;
@BeforeEach
void setUp() {
observer = new RecordingObserver();
InMemoryWarehouses repo = new InMemoryWarehouses()
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
sdk = WarehouseSdk.builder()
.warehouseRepository(repo)
.idempotencyStore(new InMemoryIdempotencyStore())
.clock(CLOCK)
.register(new FakeWarehouseAdapter())
.callObserver(observer)
.build();
}
private static OutboundCommand cmd(String requestNo) {
return OutboundCommand.builder()
.outboundRequestNo(requestNo)
.orderRef("SO-1")
.labelMode(LabelMode.WAREHOUSE_LABEL)
.salesPlatform(common.ecommerce.shared.model.Platform.WALMART_SC)
.shipTo(ShipTo.builder()
.name("B") // 测试数据
.countryCode("US")
.city("New York")
.addressLine1("1 Test St")
.build())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku("DM00001")
.quantity(1)
.declareName("Sample")
.declareValue(Money.of("10.00", "USD"))
.build())
.build();
}
/** 成功调用要记一条,operation / provider / 结果都要有。 */
@Test
void recordsSuccessfulCall() {
sdk.warehouses(WH, conn()).outbound().create(cmd("OB-1"));
CallRecord record = observer.lastOf("warehouse.outbound.create");
assertEquals(WarehouseProvider.CUSTOM.name(), record.provider());
assertNotNull(record.outcome());
assertEquals("OB-1", String.valueOf(record.params().get("outboundRequestNo")));
}
/** 失败也要记:异常不能把日志吞掉。 */
@Test
void recordsFailedCall() {
InMemoryWarehouses repo = new InMemoryWarehouses()
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
WarehouseSdk blocking = WarehouseSdk.builder()
.warehouseRepository(repo)
.idempotencyStore(new InMemoryIdempotencyStore())
.clock(CLOCK)
.register(new FakeWarehouseAdapter().blockCancel())
.callObserver(observer)
.build();
assertThrows(RuntimeException.class,
() -> blocking.warehouses(WH, conn()).outbound()
.cancel(common.ecommerce.warehouse.model.CancelCommand.builder()
.outboundRequestNo("OB-X")
.acceptCharge(false)
.build()));
CallRecord record = observer.lastOf("warehouse.outbound.cancel");
assertNotNull(record.errorType(), "失败记录要带异常类型");
}
/** 只读方法同样记。 */
@Test
void recordsReadOnlyCall() {
sdk.warehouses(WH, conn()).outbound().query(
common.ecommerce.warehouse.model.OutboundQuery.builder().build());
assertNotNull(observer.lastOf("warehouse.outbound.query"));
}
/** 同一 SDK 多次调用各记一条,不合并。 */
@Test
void recordsOnePerCall() {
WarehouseOperations ops = sdk.warehouses(WH, conn());
ops.outbound().create(cmd("OB-1"));
ops.outbound().get(common.ecommerce.warehouse.model.OutboundRef.ofRequestNo("OB-1"));
assertNotNull(observer.lastOf("warehouse.outbound.create"));
assertNotNull(observer.lastOf("warehouse.outbound.get"));
assertTrue(observer.records.size() >= 2, "每次门面调用至少一条记录");
}
/** 没注入 observer 时什么都不记,但业务照常跑——不能因为没日志就抛。 */
@Test
void noObserverMeansNoRecordsButStillWorks() {
WarehouseSdk quiet = WarehouseSdk.builder()
.warehouseRepository(new InMemoryWarehouses()
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)))
.idempotencyStore(new InMemoryIdempotencyStore())
.clock(CLOCK)
.register(new FakeWarehouseAdapter())
.build();
assertNotNull(quiet.warehouses(WH, conn()).outbound().create(cmd("OB-1")));
}
/** observer 自己抛异常要被吞掉,不能影响业务返回值。 */
@Test
void observerFailureDoesNotBreakBusinessCall() {
WarehouseSdk broken = WarehouseSdk.builder()
.warehouseRepository(new InMemoryWarehouses()
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)))
.idempotencyStore(new InMemoryIdempotencyStore())
.clock(CLOCK)
.register(new FakeWarehouseAdapter())
.callObserver(record -> {
throw new IllegalStateException("observer boom");
})
.build();
assertNotNull(broken.warehouses(WH, conn()).outbound().create(cmd("OB-1")));
}
/** 参数摘要里不能出现密钥类字段。 */
@Test
void paramsDoNotLeakSecrets() {
sdk.warehouses(WH, conn()).outbound().create(cmd("OB-1"));
for (String key : observer.lastOf("warehouse.outbound.create").params().keySet()) {
assertFalse(key.toLowerCase().contains("secret"), "params 不应含密钥字段: " + key);
assertFalse(key.toLowerCase().contains("token"), "params 不应含 token 字段: " + key);
}
}
private static WarehouseConnection conn() {
return WarehouseConnection.of("https://example.test",
ChannelSecret.builder().appSecret("s").build());
}
/** 记录型观察者。 */
private static final class RecordingObserver implements CallObserver {
private final List<CallRecord> records = new ArrayList<CallRecord>();
@Override
public void onCall(CallRecord record) {
records.add(record);
}
/** 找指定 operation 的记录(写操作前面还会有幂等审计记录,所以不能只看条数)。 */
CallRecord lastOf(String operation) {
CallRecord found = null;
for (CallRecord record : records) {
if (operation.equals(record.operation())) {
found = record;
}
}
assertNotNull(found, "没有 " + operation + " 的记录,实际有 " + operations());
return found;
}
List<String> operations() {
List<String> out = new ArrayList<String>();
for (CallRecord record : records) {
out.add(record.operation());
}
return out;
}
}
}

3
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java

@ -39,6 +39,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot; @@ -39,6 +39,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
@ -228,7 +229,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -228,7 +229,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
* 映射时直接用厘米那套,不做二次换算。</p>
*/
@Override
public Page<WarehouseProduct> queryProducts(WarehouseContext ctx, ProductQuery query) {
public Page<ProductInfo> query(WarehouseContext ctx, ProductQuery query) {
AccessToken token = login(ctx);
Map<String, Object> params = XincangProductQueryMapper.toParams(query);
String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token,

25
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java

@ -2,7 +2,8 @@ package common.ecommerce.xincang.adapter; @@ -2,7 +2,8 @@ package common.ecommerce.xincang.adapter;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangProductListDtos;
@ -97,17 +98,17 @@ public final class XincangProductQueryMapper { @@ -97,17 +98,17 @@ public final class XincangProductQueryMapper {
// ================================================================ 响应
/** 响应 → 分页商品。 */
public static Page<WarehouseProduct> toPage(XincangProductListDtos.ProductListResult rst,
public static Page<ProductInfo> toPage(XincangProductListDtos.ProductListResult rst,
String requestedCursor, int requestedLimit) {
if (rst == null || rst.data == null || rst.data.isEmpty()) {
return Page.last(new ArrayList<WarehouseProduct>());
return Page.last(new ArrayList<ProductInfo>());
}
List<WarehouseProduct> out = new ArrayList<WarehouseProduct>(rst.data.size());
List<ProductInfo> out = new ArrayList<ProductInfo>(rst.data.size());
for (XincangProductListDtos.ProductItem item : rst.data) {
if (item == null) {
continue;
}
WarehouseProduct product = toProduct(item);
ProductInfo product = toProduct(item);
if (product != null) {
out.add(product);
}
@ -121,7 +122,7 @@ public final class XincangProductQueryMapper { @@ -121,7 +122,7 @@ public final class XincangProductQueryMapper {
* <p>按 {@code rst.count}(总数)判断,不按「本页是否满」——服务端可能对
* {@code limit} 做上限收窄,满页不代表还有。</p>
*/
static Page<WarehouseProduct> nextPage(List<WarehouseProduct> items, String totalRaw,
static Page<ProductInfo> nextPage(List<ProductInfo> items, String totalRaw,
String requestedCursor, int requestedLimit) {
int page = pageOf(requestedCursor);
Integer total = intOrNull(totalRaw);
@ -142,15 +143,12 @@ public final class XincangProductQueryMapper { @@ -142,15 +143,12 @@ public final class XincangProductQueryMapper {
* <p>{@code product_no} 缺失时返回 null(无法定位的商品,跳过而不是抛——
* 列表里一条脏数据不该让整页失败)。</p>
*/
static WarehouseProduct toProduct(XincangProductListDtos.ProductItem item) {
static ProductInfo toProduct(XincangProductListDtos.ProductItem item) {
String sku = trimToNull(item.productNo);
if (sku == null) {
return null;
}
WarehouseProduct.Builder b = WarehouseProduct.builder()
// 查询结果允许尺寸 / 重量为 0(仓方没给),不伪造最小值
.allowUnknownDimensions(true)
.omsSku(sku)
ProductInfo.Builder b = ProductInfo.builder()
.providerSku(sku)
.name(firstNonBlank(item.chnName, item.enName, sku))
.nameEn(trimToNull(item.enName))
@ -164,12 +162,12 @@ public final class XincangProductQueryMapper { @@ -164,12 +162,12 @@ public final class XincangProductQueryMapper {
// 查询结果才有
.providerProductId(trimToNull(item.id))
.rawState(trimToNull(item.state))
.stateName(trimToNull(item.stateName))
.rawStatusName(trimToNull(item.stateName))
.volumeCm3(decimalOrNull(item.volumeCm))
.createdAt(XincangOrderDetailMapper.parseTime(item.gmtCreate))
.updatedAt(XincangOrderDetailMapper.parseTime(item.gmtModify))
.imageUrl(trimToNull(item.imageUrl))
.remark(null);
.sourceProvider(WarehouseProvider.XINCANG);
// packing_rate → 装箱数量
Integer packing = intOrNull(item.packingRate);
@ -181,7 +179,6 @@ public final class XincangProductQueryMapper { @@ -181,7 +179,6 @@ public final class XincangProductQueryMapper {
if (amount != null) {
b.declaredValue(Money.of(amount, "USD"));
}
// 统一模型没有「长度/重量单位」以外的差异;外箱尺寸信仓不提供,保持 null
return b.build();
}

44
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java

@ -6,7 +6,7 @@ import common.ecommerce.shared.spi.ChannelSecret; @@ -6,7 +6,7 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.model.ProductInfo;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -94,7 +94,7 @@ class XincangProductQueryTest { @@ -94,7 +94,7 @@ class XincangProductQueryTest {
@Test
void sendsMandatoryQueryParams() {
RecordingTransport transport = productListing(listBody(ONE_ROW, "1"));
adapter(transport).queryProducts(ctx(), ProductQuery.builder().build());
adapter(transport).query(ctx(), ProductQuery.builder().build());
String url = productListUrl(transport);
// 四项必填
@ -108,7 +108,7 @@ class XincangProductQueryTest { @@ -108,7 +108,7 @@ class XincangProductQueryTest {
@Test
void alwaysQueriesFormalState() {
RecordingTransport transport = productListing(listBody("", "0"));
adapter(transport).queryProducts(ctx(), ProductQuery.builder().build());
adapter(transport).query(ctx(), ProductQuery.builder().build());
assertTrue(productListUrl(transport).contains("state=1"));
}
@ -118,7 +118,7 @@ class XincangProductQueryTest { @@ -118,7 +118,7 @@ class XincangProductQueryTest {
void rejectsMultipleSkus() {
RecordingTransport transport = productListing(listBody("", "0"));
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(transport).queryProducts(ctx(), ProductQuery.builder()
() -> adapter(transport).query(ctx(), ProductQuery.builder()
.providerSkus(java.util.Arrays.asList("A", "B")).build()));
assertTrue(ex.getMessage().contains("single sku"), ex.getMessage());
}
@ -126,7 +126,7 @@ class XincangProductQueryTest { @@ -126,7 +126,7 @@ class XincangProductQueryTest {
@Test
void sendsSingleSkuAsKey() {
RecordingTransport transport = productListing(listBody(ONE_ROW, "1"));
adapter(transport).queryProducts(ctx(), ProductQuery.builder().providerSku("SKU-A").build());
adapter(transport).query(ctx(), ProductQuery.builder().providerSku("SKU-A").build());
assertTrue(productListUrl(transport).contains("key=SKU-A"));
}
@ -135,19 +135,19 @@ class XincangProductQueryTest { @@ -135,19 +135,19 @@ class XincangProductQueryTest {
void rejectsLimitAboveMax() {
RecordingTransport transport = productListing(listBody("", "0"));
assertThrows(IllegalArgumentException.class,
() -> adapter(transport).queryProducts(ctx(), ProductQuery.builder().pageSize(500).build()));
() -> adapter(transport).query(ctx(), ProductQuery.builder().pageSize(500).build()));
}
// ---------------------------------------------------------------- 响应
@Test
void mapsProductFields() {
Page<WarehouseProduct> page = adapter(productListing(listBody(ONE_ROW, "1")))
.queryProducts(ctx(), ProductQuery.builder().build());
Page<ProductInfo> page = adapter(productListing(listBody(ONE_ROW, "1")))
.query(ctx(), ProductQuery.builder().build());
assertEquals(1, page.size());
WarehouseProduct p = page.items().get(0);
assertEquals("SKU-A", p.omsSku());
ProductInfo p = page.items().get(0);
assertEquals("SKU-A", p.providerSku());
assertEquals("SKU-A", p.providerSku());
assertEquals("小部件", p.name());
assertEquals("Widget", p.nameEn());
@ -163,7 +163,7 @@ class XincangProductQueryTest { @@ -163,7 +163,7 @@ class XincangProductQueryTest {
assertEquals(0, p.declaredValue().amount().compareTo(new java.math.BigDecimal("12.34")));
assertEquals("9001", p.providerProductId());
assertEquals("1", p.rawState());
assertEquals("正式产品", p.stateName());
assertEquals("正式产品", p.rawStatusName());
assertEquals("https://oss/x.png", p.imageUrl());
// 北京时间 → UTC:10:00 北京 = 02:00 UTC
assertEquals(Instant.parse("2026-11-01T02:00:00Z"), p.createdAt());
@ -172,21 +172,21 @@ class XincangProductQueryTest { @@ -172,21 +172,21 @@ class XincangProductQueryTest {
/** count 决定是否还有下一页,不看本页是否满。 */
@Test
void pagingUsesCount() {
Page<WarehouseProduct> more = adapter(productListing(listBody(ONE_ROW, "50")))
.queryProducts(ctx(), ProductQuery.builder().pageSize(20).build());
Page<ProductInfo> more = adapter(productListing(listBody(ONE_ROW, "50")))
.query(ctx(), ProductQuery.builder().pageSize(20).build());
assertTrue(more.hasMore());
assertEquals("2", more.nextCursor());
Page<WarehouseProduct> done = adapter(productListing(listBody(ONE_ROW, "1")))
.queryProducts(ctx(), ProductQuery.builder().pageSize(20).build());
Page<ProductInfo> done = adapter(productListing(listBody(ONE_ROW, "1")))
.query(ctx(), ProductQuery.builder().pageSize(20).build());
assertFalse(done.hasMore());
assertNull(done.nextCursor());
}
@Test
void emptyDataIsLastPage() {
Page<WarehouseProduct> page = adapter(productListing(listBody("", "0")))
.queryProducts(ctx(), ProductQuery.builder().build());
Page<ProductInfo> page = adapter(productListing(listBody("", "0")))
.query(ctx(), ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
assertFalse(page.hasMore());
}
@ -195,20 +195,20 @@ class XincangProductQueryTest { @@ -195,20 +195,20 @@ class XincangProductQueryTest {
@Test
void missingDimensionsBecomeZero() {
String row = "{\"product_no\":\"SKU-B\",\"state\":\"1\",\"weight_kg\":\"\"}";
WarehouseProduct p = adapter(productListing(listBody(row, "1")))
.queryProducts(ctx(), ProductQuery.builder().build()).items().get(0);
ProductInfo p = adapter(productListing(listBody(row, "1")))
.query(ctx(), ProductQuery.builder().build()).items().get(0);
assertEquals(0.0, p.lengthCm(), 0.001);
assertEquals(0.0, p.weightGrams(), 0.001);
assertFalse(p.hasDimensions());
assertEquals(0.0, p.lengthCm(), 0.001);
}
/** 缺 product_no 的脏数据跳过,不让整页失败。 */
@Test
void skipsRowsWithoutSku() {
String row = "{\"id\":\"1\",\"chn_name\":\"无 SKU\"}";
Page<WarehouseProduct> page = adapter(productListing(listBody(row, "1")))
.queryProducts(ctx(), ProductQuery.builder().build());
Page<ProductInfo> page = adapter(productListing(listBody(row, "1")))
.query(ctx(), ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
}

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

@ -26,6 +26,9 @@ public final class YqnConstants { @@ -26,6 +26,9 @@ public final class YqnConstants {
/** 商品创建 / 编辑(V1 推荐版)。 */
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/** 批量查询 SKU 分页(API 113)。页码从 0 开始。 */
public static final String PATH_PRODUCT_FIND_PAGE = "/v1/product/findPage";
/** 创建销售订单(API 123)。 */
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/** 订单详情(API 128):按来源单号查完整订单。 */

30
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -13,6 +13,7 @@ import common.ecommerce.yqn.dto.YqnInventoryDtos; @@ -13,6 +13,7 @@ import common.ecommerce.yqn.dto.YqnInventoryDtos;
import common.ecommerce.yqn.dto.YqnLogisticsProductDtos;
import common.ecommerce.yqn.dto.YqnOrderDetailDtos;
import common.ecommerce.yqn.dto.YqnProductDtos;
import common.ecommerce.yqn.dto.YqnProductQueryDtos;
import common.ecommerce.yqn.dto.YqnReturnProcessDtos;
import common.ecommerce.yqn.dto.YqnSaleReturnPlanDtos;
import common.ecommerce.yqn.dto.YqnSkuLabelDtos;
@ -170,6 +171,35 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -170,6 +171,35 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
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

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

@ -140,6 +140,8 @@ public final class YqnOutboundMapper { @@ -140,6 +140,8 @@ public final class YqnOutboundMapper {
new ArrayList<YqnCreateOrderDtos.CreateOrderRequest.ProductItem>(lines.size());
for (OutboundLine line : lines) {
YqnCreateOrderDtos.CreateOrderRequest.ProductItem item = new YqnCreateOrderDtos.CreateOrderRequest.ProductItem();
// 必须与建档时下发给仓方的 sku 一致(providerSku 优先,见 YqnProductMapper.skuOf)。
// 传 OMS SKU 而建档时用的是 providerSku 的话,仓方会报 SKU 不存在。
item.sku = line.providerSku() != null ? line.providerSku() : line.omsSku();
item.quantity = line.quantity();
item.lineNo = line.lineNo();

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

@ -85,7 +85,25 @@ public final class YqnProductMapper { @@ -85,7 +85,25 @@ public final class YqnProductMapper {
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) {
String providerSku = product.providerSku();
if (providerSku != null && !providerSku.trim().isEmpty()) {

175
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java

@ -0,0 +1,175 @@ @@ -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 @@ @@ -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 @@ @@ -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 { @@ -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」这条路是否被仓方接受。 */
@Test
void probeLogisticsProducts() {

Loading…
Cancel
Save