Compare commits

...

12 Commits

Author SHA1 Message Date
chenchuchuan c8f471352b Merge branch 'master' of common-ecommerce 6 days ago
chenchuchuan f66720f6be feat(edayun): 对接仓库清单(权限内 / 全量激活) 6 days ago
chenchuchuan 17ef1c574a feat(edayun): 对接客户自有物流服务(承运商)清单 6 days ago
chenchuchuan b675dd67e0 refactor(edayun): 修正 printBarcode / newPrintCaseMark 的语义归属 6 days ago
chenchuchuan fed2c0d4fc feat(edayun): 对接打印箱唛(真机未启用) 6 days ago
chenchuchuan 5124ff85d1 docs(edayun): 补退货 / BOL / 物流产品 / 轨迹 / 条码的实测结论 6 days ago
chenchuchuan d8b3bdec55 feat(edayun): 对接商品条码打印 6 days ago
chenchuchuan 6ba1cb408a feat(edayun): 对接物流轨迹查询 6 days ago
chenchuchuan 3c7ff77488 feat(edayun): 对接物流产品清单 6 days ago
chenchuchuan 59aec58ffa feat(edayun): 对接 BOL 查询(平台仓订单) 6 days ago
chenchuchuan 9e06b5873e feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 6 days ago
chenchuchuan 8b3fa466af fix(edayun): 库存 safeStock 缺失记 -1、出库单补保价映射 6 days ago
  1. 501
      docs-warehouse/edayun/README.md
  2. 46
      docs-warehouse/edayun/TODO.md
  3. 33
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/BolCapable.java
  4. 27
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java
  5. 25
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java
  6. 17
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
  7. 47
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CaseMarkPaperSize.java
  8. 6
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelSizeType.java
  9. 38
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnQueryNoType.java
  10. 4
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
  11. 217
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BolDocument.java
  12. 126
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CaseMarkPrintCommand.java
  13. 173
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java
  14. 40
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java
  15. 116
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCarrier.java
  16. 119
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  17. 45
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  18. 479
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  19. 70
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunBolMapper.java
  20. 83
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunCarrierMapper.java
  21. 71
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunCaseMarkMapper.java
  22. 11
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunInventoryMapper.java
  23. 90
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java
  24. 24
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java
  25. 175
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java
  26. 143
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java
  27. 249
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java
  28. 127
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java
  29. 177
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java
  30. 112
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunWarehouseMapper.java
  31. 82
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunBolDtos.java
  32. 38
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCancelReturnDtos.java
  33. 60
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCarrierDtos.java
  34. 55
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCaseMarkDtos.java
  35. 79
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunLogisticsProductDtos.java
  36. 223
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDetailDtos.java
  37. 122
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDtos.java
  38. 138
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunRmaListDtos.java
  39. 69
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java
  40. 73
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunTrackDtos.java
  41. 95
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunWarehouseDtos.java
  42. 74
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunBolStatus.java
  43. 103
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunRmaStatus.java
  44. 61
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunSkuLabelPaper.java
  45. 18
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java
  46. 169
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunBolTest.java
  47. 109
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCancelReturnTest.java
  48. 160
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java
  49. 166
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCaseMarkTest.java
  50. 33
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java
  51. 110
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductTest.java
  52. 65
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderTest.java
  53. 227
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnDetailTest.java
  54. 205
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java
  55. 249
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java
  56. 158
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java
  57. 217
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java
  58. 184
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunWarehouseTest.java
  59. 121
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunBolProbeTest.java
  60. 117
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCarrierProbeTest.java
  61. 104
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCaseMarkProbeTest.java
  62. 163
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCreateOrderProbeTest.java
  63. 141
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunReturnProbeTest.java
  64. 141
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunRmaListProbeTest.java
  65. 115
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunTrackProbeTest.java
  66. 102
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunWarehouseProbeTest.java
  67. 16
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  68. 5
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java
  69. 3
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

501
docs-warehouse/edayun/README.md

@ -20,6 +20,17 @@ @@ -20,6 +20,17 @@
| 库存查询 | ✅ 已对接(`POST /webApi/userSkuStock/v1/queryInventory`) |
| 创建 / 编辑自发入库单 | ✅ 已对接(`POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder`) |
| 查询入库单 / 入库状态 | ✅ 已对接(`POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail`) |
| 创建退货单 | ✅ 已对接(`POST /webApi/rma/info/v1/saveAndPublish`),仅「自行退回」 |
| 退货单详情 | ✅ 已对接(`POST /webApi/rma/info/v1/getOrderDetail`) |
| 取消退货单 | ✅ 已对接(`POST /webApi/rma/info/v1/cancel`) |
| 退货检验后处理 | ⬜ 等文档(缺行 id) |
| BOL 查询(平台仓订单) | ✅ 已对接(`POST /webApi/fbaOrder/v1/getOrderBolList`) |
| 物流产品清单 | ✅ 已对接(`POST /webApi/order/listByLogisticProductHasPerm`) |
| 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) |
| 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) |
| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** |
| 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) |
| 仓库清单 | ✅ 已对接(`warehouse/listWarehouseHasPerm` + `warehouse/listActive`) |
| 其它业务接口 | ⬜ 等文档 |
| 回调 | ⬜ 等文档 |
| 真机验证 | ⬜ 等测试环境 |
@ -193,7 +204,8 @@ POST /webApi/order/v1/createOrder @@ -193,7 +204,8 @@ POST /webApi/order/v1/createOrder
|---|---|
| `signatureRequired = true` | `is_signature` |
保价(`is_insurance`)标准模型没有对应字段,暂不下发。
保价:任意商品行带 `insuredAmount` 就整单下发 `is_insurance`——`addService`
是订单级开关,易达云没有行级保价。
## 查询出库单 / 面单
@ -799,9 +811,39 @@ POST /webApi/userSkuStock/v1/queryInventory → Page<InventorySnapshot> @@ -799,9 +811,39 @@ POST /webApi/userSkuStock/v1/queryInventory → Page<InventorySnapshot>
| `warehouseIdList` 是数字 id | 非数字本地拒绝(同仓租明细) |
| 分页 | 游标是页码字符串;`total` 按文档当总行数用,缺失时按满页判断 |
### 真机验证(2026-11-13,PR 环境)
| 场景 | 结果 |
|---|---|
| `warehouseIdList:[2]`,pageSize 100 | `total=339`,本页 100 条,翻页正常 |
| 不传仓库过滤 | `total=436` |
| `totalStockGreaterThanZero:false` | `total=2436` |
| `pageSize` 传 501 / 2000 | **不报错,静默截断到 500** |
| `pageSize` 传 0 / -1 | `total=0`、`rows` 为空(不是报错) |
| 不传 `pageSize` | 服务端默认返回 **200** 条 |
| 不传 `pageNum`,或传 0 | 按第 1 页返回 |
| **页码超过最后一页** | **重复返回最后一页**,不是空列表 |
| `skuCodeList` 101 个 | `code=500`「skuCode列表最大支持100」 |
| `warehouseIdList:["USLA"]` | `code=500`「参数不符合文档规范…parseLong error」 |
**页码越界重复返回最后一页**这点最坑:不能拿「本页为空」当循环终止条件,
必须用 `total` 判断。实现里 `nextCursor` 就是这么做的。
### 字段类型:数字全是字符串
真机返回的 `totalStock` / `stock` / `frozenStock` / `toDeliverStock` /
`inTransitStock` / `safeStock` / `nonSaleStock` 全是 **字符串**(`"15499"`),
`warehouseId` 也是字符串。DTO 用 `Integer` 由 Jackson 自动转换,没问题。
### `safeStock` 经常为 null
采样 500 行:**430 行的 `safeStock` 是 null**(`toDeliverStock` 则都有值)。
统一模型约定「仓方未给时为 -1」,所以这里映射成 **-1 而不是 0**,
否则真实的「安全库存 0」和「没配安全库存」分不出来。
### 未映射的字段
`nonSaleStock`(不可售库存)、`snInStock`、`barCode`、`goodsType`、`countryName`
`nonSaleStock`(不可售库存)、`snInStock`、`barcode`、`goodsType`、`countryName`
不在统一模型里。整行按 `inventoryType = 0`(可售)落,**不可售数量被丢弃**——
需要对账不可售库存时要扩展模型,见 TODO。
@ -820,6 +862,461 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \ @@ -820,6 +862,461 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
[-Dedayun.probe.zeroStock=true] [-Dedayun.probe.page=1]
```
## 创建退货单
```
POST /webApi/rma/info/v1/saveAndPublish → WarehouseReturn
```
### 四种退货方式,我们只做「自行退回」
| `returnType` | 含义 | 必填 | 我们的实现 |
|---|---|---|---|
| 0 | 未妥投退回(派送失败 / 拒收 / 拦截) | 关联单号 | ❌ |
| 1 | 返邮退回(EDA 提供返邮面单) | 关联单号 + 退货人姓名/城市/地址/邮编 + 返邮标签 | ❌ |
| **2** | **自行退回(买家自己寄回)** | **关联单号 + 跟踪号** | ✅ **唯一路径** |
| 3 | FBA 退回 | 亚马逊单号 + 退货仓 + 承运商 + 跟踪号 + 标签数 | ❌ |
`ReturnCommand` 强制要求 `returnTrackingNo`,正好对上「自行退回」;
另外三种要退货人地址或亚马逊单号,标准模型没有对应字段。见 TODO。
### 响应 `data` 就是退货单号
```json
{"code":200,"msg":"操作成功","data":"RMA2411053149","traceId":"..."}
```
和运去哪不同(那个只回 code/message,拿不到仓单号),这里能直接落
`providerReturnId`,后续查询 / 取消有单号可用。
接口不回状态,所以 `status` 固定 `UNKNOWN`——**不要当成「已受理」**。
### 仓:数字优先
`warehouseId`(数字)优先级高于 `warehouseCode`。取命令上的 `warehouseId`,
没有再取账户配置的 `providerWarehouseId`;数字进 `warehouseId`,非数字进
`warehouseCode`(如 `USLA`)。两者都没有时不下发,由仓方按关联单号的仓处理。
### 处理指令只有「销毁」能确定
`skus[].command` 文档说是「1 上架 / 2 销毁」,但没有给码表。统一模型的
`ReturnDealMethod` 是另一套码(客户自提 / 拍照确认 / 销毁 / 仓库确认),映射:
| `ReturnDealMethod` | `command` |
|---|---|
| `DESTROY` | **2 销毁** |
| 其余三种 | 1 上架(都要先入库再处理) |
见 TODO。
### 未实现的退货能力
| 方法 | 状态 |
|---|---|
| `queryReturns(ctx, cursor)` | ❌ 文档只给了按单号查,没有列表接口 |
| `process(ctx, cmd)` | ❌ 要仓侧明细行 id,而详情响应里**没有行 id**(`checkList` / `skuList` / `shelfList` 都没有) |
`queryReturns` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。
### 探针
```bash
# dry-run:只打印报文(不联网)
mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
-Dedayun.probe.return=true -Dtest=EdayunReturnProbeTest test
# 真发一次(会在测试仓建 RMA 单,relationNo 必须是真实出库单号)
... -Dedayun.probe.return=true -Dedayun.probe.write=true \
-Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
-Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
-Dedayun.probe.warehouseId=2 -Dedayun.probe.sku=ybtest \
-Dedayun.probe.relationNo=ORD599493019 \
-Dedayun.probe.trackingNo=1Z84V7X00397803717
```
报文示例(dry-run 产出):
```json
{"returnType":2,"relationNo":"ORD599493019","carrierName":"Fedex","customerRemark":"probe",
"skus":[{"skuCode":"ybtest","command":1,"skuNum":1}],
"trackingNo":"1Z84V7X00397803717","warehouseId":2}
```
## 退货单详情
```
POST /webApi/rma/info/v1/getOrderDetail → WarehouseReturn
```
请求只有一个 `rmaCode`(**仓侧 RMA 号**,不是 OMS 单号)。响应七块,统一模型只承载
单头与明细行:
| 响应块 | 用途 | 进统一模型 |
|---|---|---|
| `basicInfo` | 状态、关联单号、仓库、退货方式、创建时间 | ✅ 单头 |
| `skuList` | 预报要退的 SKU | ✅ 明细(兜底) |
| `checkList` | 仓实际收货检验结果 | ✅ **明细(优先)** |
| `logisticsInfo` | 退货人地址、返邮信息 | ❌ 标准模型无字段 |
| `shipmentParcelList` | 预报包裹尺寸重量 | ❌ |
| `packageList` | 跟踪号与包裹状态 | ❌ |
| `shelfList` | 实际上架数量 | ❌ |
### 明细行:检验优先,预报兜底
`skuList` 是买家预报要退什么,`checkList` 是仓实际收到的(带异常原因与照片)。
对账以**实际收到**为准,所以 `checkList` 优先;没有检验记录(还没收货)才退回预报。
两边字段类型还不一致:`skuNum` 在 `skuList` 是 **string**,在 `checkList` 是 **number**,
所以分开映射,不合并成一个循环。
### 状态:码表缺失,只能按中文名推断
文档只给 `status: 1` 这类示例,**没有码表**。`EdayunRmaStatus` 因此只按
`statusName` 中文名兜底,码值一个都没映射:
| 中文名关键字 | 归一化 |
|---|---|
| 驳回 / 拒绝 / 不通过 | `REJECTED` |
| 关闭 / 取消 / 作废 | `CLOSED` |
| 完成 / 已上架 / 结案 | `COMPLETED` |
| 审核 | `PENDING_REVIEW` |
| 收货 / 检验 / 清点 | `PENDING_RECEIPT` |
| 在途 / 退货中 / 运输 / 已发出 / 待收 | `RETURNING` |
| 草稿 / 预报 | `DRAFT` |
| 认不出 | `UNKNOWN`(原文进 `rawStatus`) |
**否定语义先判**:「审核不通过」不能被「审核」命中成待审核。
### 响应只有仓名,没有仓编码
`basicInfo` 给的是 `warehouseId`(数字)+ `warehouseName`,没有仓编码。
`warehouseCode` 回退 OMS 仓编码。
### `data: null` 当作查不到
单号不存在时仓方回 `code=200` + `data: null`,适配器返回 `null`——
这是「接口通、单不存在」,不是失败,不当异常抛。
## 取消退货单
```
POST /webApi/rma/info/v1/cancel → boolean
```
请求同样只有 `rmaCode`。响应 `data` 是**布尔值**,不是单号:
```json
{"code":200,"msg":"操作成功","data":true}
```
### `data=false` 是仓方拒绝,要抛异常
`code=200` 只说明请求被接受,`data=false` 表示仓方拒绝(如已收货)。
取消是状态变更,**不能静默返回 false** 让调用方以为没事——适配器抛
`WarehouseException`,`msg` 里的原因原样带出。
`data` 缺失同样按失败处理。
### 只认仓侧 RMA 号
幂等键 `warehouseCode + providerReturnNo + "cancel"`。传 OMS 单号仓方查不到,
所以宿主必须先用创建 / 详情拿到 `providerReturnId`。
## BOL 查询(平台仓订单)
```
POST /webApi/fbaOrder/v1/getOrderBolList → List<BolDocument>
```
店铺订单 / 平台仓订单共用,`orderNo` 传 EDA 的平台仓订单号(如 `FBA473182144`)。
### 与入库 BOL 不是一回事
| | `inbound().bols()` | `orderBols()` |
|---|---|---|
| 对象 | 头程入库计划单 | 平台仓 / 店铺订单 |
| 返回 | `List<String>` 文件地址 | 带提货状态、约定/实际提货量、POD |
方法名带 `order` 前缀是因为 `InboundCapable.bols` 已有同签名同参数、
返回值不同的方法,同一适配器实现两者时擦除后无法区分。
### 状态码表只有一个确认
`status = 11 → 已妥投` 是文档响应示例确认的。其余状态 `EdayunBolStatus`
按 `statusName` 中文名兜底,认不出归 `UNKNOWN`,原值留在 `BolDocument.rawStatus()`。
### 真机验证(2026-11-16)
`orderNo = FBA473182144` → `code=200, data.totalNum=null, bolList=null`。
**PR 环境没有 BOL 数据**,映射只被单测覆盖。
## 物流产品清单
```
POST /webApi/order/listByLogisticProductHasPerm → List<LogisticsProduct>
```
### `-998` 是哨兵值,要跳过
最后一条常是 `productId = -998`、`productName = 使用分物流规则`,
其余字段全 null。它不是可选的物流产品,映射时**跳过**,
否则宿主的渠道清单里会多一个查不到的 id。
### 入参
| 字段 | 我们的值 |
|---|---|
| `warehouseId` | 账户配置的 `providerWarehouseId`(数字);非数字时不传 |
| `applicableBusiness` | 固定 **1 店铺订单**——统一模型不区分业务类型 |
文档说 `warehouseId` 必填,**实测不传会返回全部仓的产品**(162 条 vs 仓 2 的 36 条)。
### 统一模型只有 3 个字段
`LogisticsProduct` 只有编码 / 名称 / 是否跨国;**易达云不回跨国标记**,恒 `false`。
承运商类型、派单方式、面单获取方式、增值服务选项、适用业务都在 DTO 里。
### 真机验证(2026-11-16)
| 场景 | 结果 |
|---|---|
| 仓 2 + 店铺订单 | 36 条 |
| 仓 2 + 平台仓订单 | 23 条 |
| 仓 2 + 退货单 | 35 条 |
| 仓 2 不传业务类型 | 37 条(含 -998) |
| 仓 98 + 店铺订单 | 22 条 |
| 不传仓 | 162 条(全账号) |
`-998` 每条都出现,确认是哨兵值。
## 物流轨迹
```
POST /webApi/track/getTrackInfoList → List<TrackEvent> / TrackingInfo
```
### 请求体是**纯字符串数组**
```json
["1Z84V7X00397803717"]
```
文档把字段名留空了,示例写成 `[{"": ["aa","bb"]}]` 是自动生成的占位。
真机实测只有纯数组能通:嵌套对象会被静默忽略,返回空 body。
### 「未匹配到轨迹」不是错误
查不到时仓方回 `code=500, msg=未匹配到轨迹`。但对调用方来说,
这和「运单刚生成、还没揽收」是同一件事——适配器把它当**空结果**处理
(`track` 返回空列表,`trackShipment` 返回 `null`),不抛异常。
其它 500(如「系统异常」)仍然抛。
`msg=跟踪号为空` 同理按空结果处理。
### 上网时间 / 妥投时间是**带时区的字符串**
文档说明「主要关注上网时间跟妥投时间」,所以统一模型的 `TrackingInfo`
新增两个字段直接承载:
| 易达云 | 统一模型 |
|---|---|
| `onlineTime`(`2025-08-19 08:17:00`) | `firstOnlineAt()`(Instant) |
| `deliveredTime` | `deliveredAt()`(Instant) |
| `timeZone`(`GMT-04:00`) | 解释上面两个时间用 |
**同一个响应里时间口径混杂**:`onlineTime` / `deliveredTime` 是字符串,
而节点时间 `recentDescribeTime` 是毫秒。字符串按 `timeZone` 解析,解析失败留 null。
时区解析认 `GMT±HH:mm` / `UTC±HH:mm` / `±HH:mm`;认不出按 UTC,
**不猜成仓所在时区**(那是另一个概念)。
### 节点状态优先 eventStatus
节点上的 `status` 是数字码(码表未给),`eventStatus` 是字符串。
映射时 `eventStatus` 优先,缺失才退回数字码的字符串形式。
### 真机验证(2026-11-16)
| 跟踪号 | 结果 |
|---|---|
| 文档示例 `LF-1741871641090` | `code=500 未匹配到轨迹` |
| 出库单里的真实 `889542071709` | `code=500 未匹配到轨迹` |
| `1Z84V7X00397803717` | 同上 |
**PR 环境没有任何可查到的轨迹**,映射只被单测覆盖。
## 打印箱唛 / SKU 标
### 两个端点名与实际语义是反的
已与仓方确认:
| 端点 | 实际打印 | 我们的方法 | 能力位 |
|---|---|---|---|
| `/webApi/skuInfo/v2/printBarcode` | **箱唛**(外箱标) | `printCaseMarks(...)` | `CASE_MARK_PRINT` |
| `/webApi/entryInfo/v1/newPrintCaseMarkContentType` | **SKU 标** | `printSkuLabel(...)` | 走入库 `SKU_LABEL` 语义 |
**不要被路径名误导**。代码里两个方法的 javadoc 都写了这条提醒。
### 箱唛(printBarcode)
```
POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel
```
请求体按 SKU 列表打,服务端把每个 SKU 的条码排版成箱唛 PDF。
**四种纸张尺寸实测(MediaBox,单位 pt):**
| `pageSize` | 文档标称 | 实测 MediaBox | 折算 |
|---|---|---|---|
| 0 | 7×3cm | `198 × 85` | 69.9 × 30.0 mm |
| 1 | 10×6cm | `284 × 170` | 100.2 × 60.0 mm |
| 2 | 6×4cm | `283 × 425` | **99.9 × 150.0 mm** |
| 3 | A4 | `170 × 113` | **60.0 × 39.9 mm** |
**`pageSize=2` 和 `pageSize=3` 的文档标称与实际相反**:文档说 2 是「6×4cm」、
3 是「A4」,实际 2 打出来是 100×150mm、3 打出来是 60×40mm。
枚举按**实测尺寸**命名(`SIZE_60_40` / `SIZE_100_150`),码值原样保留。
**本地提前挡的两条**(仓方都回「内部服务器错误」,看不出原因):
| 约束 | 本地行为 |
|---|---|
| SKU 数 > 50 | 构造期拒绝(仓方提示「最多打印50个SKU」) |
| 份数 ≤ 0 | 构造期拒绝 |
`isPrintSkuName` 只在 `true` 时下发,`false` 交给仓方默认。
**真机(2026-11-16)**:`ybtest` 拿到真实 PDF,四种纸张都 `code=200`。
仓方其它校验:缺 `productInfos` →「产品信息不能为空」、缺 `pageSize` →
「纸张尺寸不能为空」、SKU 不存在 →「sku=XXX信息不存在」。
### SKU 标(newPrintCaseMarkContentType)
```
POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel
```
**真机未启用**:PR 环境该路径报「接口不存在或未启用」,去掉
`ContentType` 后缀的 `newPrintCaseMark` 能过参数校验(缺 `pageSize` 报
「纸张不能为空」、缺 `madeInChina` 报「产地标签不能为空」),但补全后一律
「内部服务器错误」。所以本接口实现是**按文档写的**,映射只有单测覆盖。
纸张码值不连续:`100×100=4` / `100×150=2` / `A4=5`。统一枚举
`LabelSizeType` 为此补了 `A4`。
统一模型的 `BoxLabelCommand` 没有「选哪些箱」,默认整单打印;部分箱用
`printSkuLabel(ctx, cmd, CaseSelection)` 重载(系统箱号 / SKU / 箱序号区间 /
客户箱号区间四选一,全空本地拒)。
`madeInChina` 与 `separation` 是易达云特有语义,统一模型没有对应概念 → 默认关。
## 承运商清单(客户自有物流服务)
```
POST /webApi/carrier/v1/listCarrierByWarehouse → List<WarehouseCarrier>
```
客户自有物流(自有物流 + 客户上传面单)下单时要用:`carrierName` 可以填承运商名,
也可以用某个下属物流服务的名字。
### 两层结构
```
承运商(carrierId / carrierNameEn / carrierNameCn)
└── 物流服务(logisticId / logisticName)
```
统一模型新增 `WarehouseCarrier`(带 `logists()`),挂到
`WarehouseDirectoryCapable.carrierDirectory(ctx)`,门面 `carrierDirectory()`。
原有的 `carriers()` 返回 `List<String>`(只有码),保留不动;
`carrierDirectory()` 的默认实现会把 `carriers()` 的码包装成无名条目,
能给出结构的仓覆盖它。
### `ownLogisticList` 文档写成对象、真机是数组
```json
"ownLogisticList": [ {"logisticId":"583","logisticName":"..."}, ... ]
```
DTO 按 `List` 收。
### 入参
| 字段 | 我们的值 |
|---|---|
| `warehouseId` | 账户配置的 `providerWarehouseId`(数字);非数字/为空时不传 |
| `countryCode` | 本地不传(统一模型没有对应字段) |
### 真机验证(2026-11-16)
| 场景 | 结果 |
|---|---|
| 仓 2 | **11 个承运商**,FedEx 下有 12 个物流服务 |
| 不传仓 | 22 个承运商 |
| `countryCode=US` | 10 个承运商 |
### 仓库清单
见下面的「仓库清单」一节——`warehouses()` 现在有实现了。
## 仓库清单
两个接口用途完全不同,**不要混用**:
| 接口 | 含义 | 实测条数 | 我们的方法 |
|---|---|---|---|
| `warehouse/listWarehouseHasPerm` | 当前客户**有权限**的仓 | 69(跳过 -999 后 68) | `warehouses(ctx)` |
| `warehouse/listActive` | 平台**全量**激活仓 | 118 | `activeWarehouses(ctx, inbound)` |
`listActive` 含当前客户**没授权**的仓(68 个有权限的仓里,有 50 个不在里面),
所以**给客户选仓必须用 `warehouses()`**。
### `-999` 是「智能分仓」哨兵值
`listWarehouseHasPerm` 最后一条固定是:
```json
{"warehouseId":"-999","warehouseName":"使用分仓规则","warehouseNameEn":"divideWarehouse",
"warehouseCode":"USMC", ...其余全 null}
```
不是真实仓,映射时跳过——和物流产品接口的 `-998` 是同一套路。
### `listActive` 的 `warehouseOperationType`
| 值 | 含义 | 实测 |
|---|---|---|
| 0 | 尾程仓 | 111 条 |
| 1 | 头程仓 | 7 条 |
| 不传 | 两者之和 | 118 条 |
文档说必填,实测不传也能通。`activeWarehouses(ctx, inboundWarehouse)` 会明确传 0 或 1。
### 统一模型的口径
`WarehouseFacility.warehouseCode()` 放的是**仓编码**(`USLA` / `USALA-Q031`),
数字 id(`2` / `40269`)进 `providerWarehouseId()`——两者不能互换。
字段映射:
| 易达云 | 统一模型 | 备注 |
|---|---|---|
| `warehouseCode` | `warehouseCode` | 下单用 |
| `warehouseId` | `providerWarehouseId` | 数字,字符串形式 |
| `warehouseName` | `name` | 缺失回退英文名 |
| `address` | `address1` | 仓方只给单行地址 |
| `provinceCode` | `province` / `state` | 两个字段都填 |
| `warehouseManagerName` / `Tel` | `contactName` / `mobilePhone` | 仅 `listActive` 有 |
### 两个接口的字段数差很多
`listActive` 返回 47 个字段(容量、营业时间、负责人邮箱、地图链接等),
`listWarehouseHasPerm` 只有 17 个。DTO 只声明统一模型用得上的十几个——
Jackson 会忽略未知字段。
## 待确认(问易达云)
| # | 要确认 |

46
docs-warehouse/edayun/TODO.md

@ -5,7 +5,6 @@ @@ -5,7 +5,6 @@
## 待仓方确认
| # | 问题 | 当前处理 | 影响 |
|---|---|---|---|
| 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 |
| 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 |
| 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 |
@ -38,6 +37,49 @@ @@ -38,6 +37,49 @@
| 35 | 入库明细接口不回仓库 / 创建时间 / 到仓时间 / 箱号 | 仓库用 OMS 配置;时间与箱明细为 null | 拿不到完整单据,需要 entryInfo 单头查询接口 |
| 36 | 是否有入库单列表 / 时间窗查询 | `query()` 的 cursor 当 entryCode 用 | 无法做增量同步,只能按单号轮询 |
| 37 | `forecastWeight` / `weight` 是克、`firstWeight` 是千克 | 未映射(统一模型没有行级重量) | 想按箱对账重量时需要 |
| 38 | 退货单**没有列表查询** | `queryReturns` 显式拒绝 | 无法批量同步退货单 |
| 39 | 退货 `skus[].command` 码表(文档只写「1 上架 / 2 销毁」) | 只确定 DESTROY→2,其余都归 1 | 非销毁类处理方式可能与仓方预期不符 |
| 40 | 退货 `valueAddedService` / `shelveSkuCode` / `catalog` / `picUrls` 码值与语义 | 不下发 | 重新包装 / 换标上架等场景发不了 |
| 41 | 未妥投 / 返邮 / FBA 三种退货方式要不要做 | 只实现 `returnType=2` | 买家退货的返邮面单、FBA 退货都得人工 |
| 42 | 退货创建是否需要「同一关联单号分次退」的幂等键 | 用 `returnRequestNo`(OMS 单号) | 同一单多次退要各自生成新 OMS 单号 |
| 43 | 退货 `warehouseId` 缺省时仓方是否真按关联单号的仓走 | 不下发 | 可能落到错误仓 |
| 44 | 库存 `pageNum` 超过最后一页会**重复返回最后一页** | 用 `total` 判断终止,不看空页 | 无(已规避) |
| 45 | 库存 `pageSize` 超过 500 被**静默截断** | 本地也截到 500 | 无(已规避) |
| 46 | 库存 `safeStock` 大量为 null(采样 500 行有 430 行) | 映射成 -1(统一模型约定) | 宿主展示时要区分 -1 与 0 |
| 47 | 创建出库单的 eBay `ebayTransactionId` / `ebayItemId`、亚马逊 `salesPlatformOrderNo` / `sellerId` | 不下发(标准模型无字段) | 拿不到平台政策保护(OTDR 等) |
| 48 | 创建出库单的 `carrierProductId` / `pickUpType` / `customerLogisticsAccountId` / `orderTag` | 不下发 | 指定物流产品、自有物流自提单发不了 |
| 49 | 创建出库单的 `meteringResultList` / `truckAppointment` / `addServiceAttachFiles` | 不下发 | 定制打包、卡车约车、增值服务附件都不支持 |
| 50 | **退货状态码表**(`basicInfo.status`)完全没给 | 只按 `statusName` 中文名推断,码值不映射 | 中文名变化会让状态判错 |
| 51 | 退货详情**没有明细行 id**(`checkList` / `skuList` / `shelfList` 都没有) | `process()` 显式拒绝 | 检验后处理(上架 / 销毁)做不了 |
| 52 | 退货详情的退货人地址、预报包裹、包裹状态、实际上架数量 | 只在 DTO,不进统一模型 | 宿主要这些数据得自己解析原报 |
| 53 | `skuList[].command` 标 number、`shelfList[].command` 标 string | 两边分别声明 | 无(已兼容) |
| 54 | 取消退货 `data=false` 的拒绝原因只有 `msg` 文本 | 抛异常并带出 msg | 宿主只能靠文本判断原因 |
| 55 | **BOL 状态码表**(`bolList[].status`)只有 `11=已妥投` 确认 | 其余按 `statusName` 中文名兜底 | 状态判错 |
| 56 | PR 环境没有 BOL 数据(`bolList=null`) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 |
| 57 | BOL 接口属「平台仓订单(FBA)」,统一模型没有平台仓订单概念 | 挂 `BolCapable.orderBols(providerOrderNo)` | 宿主需自行持有 EDA 的平台仓单号 |
| 58 | 物流产品的 `carrierType` / `deliveryType` / `labelGetMethod` / `serviceAttribute` / `valueAddedOptions` 码表 | 不进统一模型,只在 DTO | 宿主想按业务类型筛渠道时缺依据 |
| 59 | `LogisticsProduct.crossCountry` 易达云不回 | 恒 false | 跨国渠道无法识别 |
| 60 | 物流产品接口的 `applicableBusiness` 只能固定 1(店铺订单) | 统一模型不区分业务类型 | 平台仓订单 / 退货单的专属渠道看不到 |
| 61 | **轨迹 `status` / 节点 `status` 码表**完全没给 | 节点优先 `eventStatus` 字符串,汇总只透数字 | 状态判错 |
| 62 | PR 环境查不到任何轨迹(连出库单里的真实跟踪号都「未匹配到轨迹」) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 |
| 63 | 轨迹接口一次可查多个跟踪号,统一模型只有单号口径 | 逐个查、按单号匹配 | 批量查只能循环调用 |
| 64 | 轨迹的 `eventStatus` 取值(文档示例是 `"string"` 占位) | 原样透传 | 宿主无法按事件类型分支 |
| 65 | 条码打印的纸张尺寸只有 4 档(7×3/10×6/6×4/A4),与入库贴标的 14 种不重叠 | 独立枚举 `BarcodePaperSize` | 宿主换标签纸时要选对枚举 |
| 66 | 条码文件地址的**有效期**未知(OSS 链接) | 原样返回,不缓存 | 宿主存旧链接可能 403 |
| 67 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 |
| 68 | **箱唛接口在 PR 环境未启用**(`newPrintCaseMarkContentType` 报「接口不存在或未启用」;去掉后缀的 `newPrintCaseMark` 能过参数校验但一律「内部服务器错误」) | 按文档实现,映射只有单测 | 上线前必须真机验证 |
| 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 标注 | 无(已规避) |
| 74 | 仓库清单有两个接口,`listActive` 含未授权仓 | `warehouses()` 只走 `listWarehouseHasPerm` | 用错会给出客户没权限的仓 |
| 77 | `listWarehouseHasPerm` 末条固定是 `-999`(智能分仓) | 映射时跳过 | 无(已规避) |
| 78 | `warehouseRegionType` / `warehouseStatus` / `privateFlag` 码表只部分确认 | 只在 DTO,不进统一模型 | 宿主想按区域类型筛选时缺依据 |
| 79 | `listActive` 比 `listWarehouseHasPerm` 多 30 个字段(容量 / 营业时间 / 负责人邮箱等) | 不声明,Jackson 忽略 | 想用这些字段需扩展 DTO |
| 75 | 承运商接口的 `countryCode` 过滤统一模型没有对应字段 | 不下发 | 宿主想按国家筛承运商得用扩展方法 |
| 76 | `ownLogisticList` 文档写成对象、真机是数组 | DTO 按 List 收 | 无(已兼容) |
| 70 | 箱唛的 `madeInChina` / `separation` 统一模型没有语义 | 默认关 | 需要打「Made in China」时得走扩展重载 |
| 71 | 箱唛选箱条件(系统箱号 / SKU / 箱序号 / 客户箱号)统一模型没有 | 提供 `CaseSelection` 扩展重载 | 宿主想要部分箱打印必须用易达云专有 API |
|---|---|---|---|
## 待业务确认
@ -45,7 +87,7 @@ @@ -45,7 +87,7 @@
|---|---|---|---|
| 6 | **派送地址的州要全称(California)还是二字码(CA)** | 原样透传 | 所有出库单地址 |
| 7 | 统一模型缺的字段:带电 / 包材 / 物流包装 | 创建产品里硬编码为「不带」 | 带电商品无法正确申报 |
| 8 | 保价服务(`is_insurance`) | 未下发,标准模型无字段 | 保价订单 |
| 8 | 保价服务(`is_insurance`) | 任意商品行有 `insuredAmount` 即整单下发 `is_insurance` | 混合保价单会整单保价 |
| 9 | `OutboundCommand` 没有 `carrierProductId`(易达云物流产品 id) | 未下发,走仓方默认分物流规则 | 指定物流产品 |
| 10 | `channelName` 从 `Platform` 枚举推(AMAZON_SC → Amazon) | 首段大写 | 非标准平台名可能对不上 |

33
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/BolCapable.java

@ -0,0 +1,33 @@ @@ -0,0 +1,33 @@
package common.ecommerce.warehouse.capability;
import common.ecommerce.warehouse.model.BolDocument;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import java.util.List;
/**
* BOL(提单 / 提货凭证)查询能力。
*
* <p><b>与 {@link InboundCapable#bols}</b> 不是一回事:那个是头程入库计划单的 BOL
* 文件地址({@code List<String>});本接口针对<b>平台仓订单 / 店铺订单</b>,
* 返回带提货状态、约定 / 实际提货量与 POD 的完整单据。</p>
*
* <p>只读能力,不声明 {@code WarehouseCapability.BOL} 的仓默认拒绝。</p>
*/
public interface BolCapable extends WarehouseAdapter {
/**
* 查某张订单的 BOL 清单。
*
* <p>方法名带 {@code order} 前缀:{@link InboundCapable} 已有同签名的
* {@code bols(ctx, String)}(返回 {@code List<String>}),同一适配器实现两者时
* 返回值类型冲突、擦除后无法区分。</p>
*
* @param providerOrderNo 仓方(或平台仓)订单号
* @return BOL 清单;没有 BOL 时为空列表(不是错误)
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不支持
*/
List<BolDocument> orderBols(WarehouseContext ctx, String providerOrderNo);
}

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

@ -0,0 +1,27 @@ @@ -0,0 +1,27 @@
package common.ecommerce.warehouse.capability;
import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
import common.ecommerce.warehouse.model.WarehouseLabel;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
/**
* 箱唛打印能力:按 SKU 打外箱标(箱唛)。
*
* <p>与 {@link InboundCapable#printSkuLabel} 不是一回事:那个是<b>入库计划单</b>的贴标
* (绑定入库单号、有 14 种小纸尺寸、仓方异步生成);这个是<b>按 SKU 打条码</b>,
* 仓库 / 门店自己贴标用,仓方同步返回文件地址。</p>
*
* <p>只读语义(不改业务状态),但会生成文件;重复调用只是再生成一份。</p>
*/
public interface CaseMarkPrintCapable extends WarehouseAdapter {
/**
* 打印 SKU 条码。
*
* @return 已生成的文件(地址或 base64);仓方未返回文件时抛出异常,不返回 null
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不声明 {@code BARCODE_PRINT}
*/
WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd);
}

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

@ -37,4 +37,29 @@ public interface WarehouseDirectoryCapable extends WarehouseAdapter { @@ -37,4 +37,29 @@ public interface WarehouseDirectoryCapable extends WarehouseAdapter {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.DIRECTORY);
}
/**
* 客户自有的承运商及其下属物流服务(带名称与 id 的完整结构)。
*
* <p>与 {@link #carriers} 的区别:那个只给一串物流方式码,这个是承运商 →
* 物流服务的两层结构,宿主要做下拉框或按承运商筛选时用这个。</p>
*
* <p>默认走 {@link #carriers} 把码包装成没有名称的条目;能给出结构的仓应覆盖。</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;
}
}

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

@ -4,6 +4,7 @@ import common.ecommerce.shared.support.Page; @@ -4,6 +4,7 @@ import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.ReturnDealMethod;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
@ -36,7 +37,7 @@ public interface WarehouseReturnCapable extends WarehouseAdapter { @@ -36,7 +37,7 @@ public interface WarehouseReturnCapable extends WarehouseAdapter {
WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo);
/** 分页查退货单;命名原因同 {@link #getReturn}。 */
Page<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor);
Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query);
/**
* 按明细行设置检验后处理方式。<b>写操作</b>,幂等键
@ -44,8 +45,18 @@ public interface WarehouseReturnCapable extends WarehouseAdapter { @@ -44,8 +45,18 @@ public interface WarehouseReturnCapable extends WarehouseAdapter {
*/
void process(WarehouseContext ctx, ReturnProcessCommand cmd);
/** 取消退货单;仅部分仓支持。 */
default void cancel(WarehouseContext ctx, String returnRequestNo) {
/**
* 取消退货单;仅部分仓支持。
*
* <p>与 {@link #create} 的区别:这个只需要仓侧退货单号({@code providerReturnId}),
* 因为多数仓的取消接口只认自己的 RMA 号。</p>
*
* @param providerReturnNo 仓侧退货单号(创建时返回的 {@code providerReturnId})
* @return {@code true} 取消成功;返回 {@code false} 表示仓方接受请求但拒绝取消
* (如已收货),具体原因在 {@code msg} 里——由适配器抛异常还是返回 false
* 由各仓决定,不统一的调用方应同时处理两种情况
*/
default boolean cancel(WarehouseContext ctx, String providerReturnNo) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.RETURN);
}

47
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CaseMarkPaperSize.java

@ -0,0 +1,47 @@ @@ -0,0 +1,47 @@
package common.ecommerce.warehouse.enums;
/**
* 箱唛打印的纸张尺寸(易达云 {@code printBarcode} 的 {@code pageSize})。
*
* <p><b>名称按真机实测尺寸取,不是按文档标称</b>——文档的 2 / 3 两档与实测相反。
* 实测是 PDF MediaBox 折算的毫米数(1pt = 25.4/72 mm):</p>
*
* <table>
* <tr><th>码值</th><th>文档标称</th><th>实测</th><th>枚举</th></tr>
* <tr><td>0</td><td>7×3cm</td><td>69.9 × 30.0 mm</td><td>{@link #SIZE_70_30}</td></tr>
* <tr><td>1</td><td>10×6cm</td><td>100.2 × 60.0 mm</td><td>{@link #SIZE_100_60}</td></tr>
* <tr><td>2</td><td>6×4cm</td><td><b>99.9 × 150.0 mm</b></td><td>{@link #SIZE_100_150}</td></tr>
* <tr><td>3</td><td>A4</td><td><b>60.0 × 39.9 mm</b></td><td>{@link #SIZE_60_40}</td></tr>
* </table>
*
* <p>与入库贴标用的 {@link SkuLabelSizeType}(14 种小尺寸)不是一套,不能互换。</p>
*/
public enum CaseMarkPaperSize {
/** 0:约 70mm × 30mm(文档 7×3cm,实测一致)。 */
SIZE_70_30(0, "70×30mm"),
/** 1:约 100mm × 60mm(文档 10×6cm,实测一致)。 */
SIZE_100_60(1, "100×60mm"),
/** 2:约 100mm × 150mm(<b>文档标 6×4cm,实测不符</b>)。 */
SIZE_100_150(2, "100×150mm"),
/** 3:约 60mm × 40mm(<b>文档标 A4,实测不符</b>)。 */
SIZE_60_40(3, "60×40mm");
private final int code;
private final String label;
CaseMarkPaperSize(int code, String label) {
this.code = code;
this.label = label;
}
/** 仓方码值。 */
public int code() {
return code;
}
/** 实测尺寸的显示名。 */
public String label() {
return label;
}
}

6
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelSizeType.java

@ -13,7 +13,9 @@ public enum LabelSizeType { @@ -13,7 +13,9 @@ public enum LabelSizeType {
/** 100mm × 150mm。 */
SIZE_100_150(20, "100×150"),
/** 104mm × 98mm(美国信纸)。 */
SIZE_104_98(30, "104×98(美国信纸)");
SIZE_104_98(30, "104×98(美国信纸)"),
/** A4(210mm × 297mm);易达云箱唛支持,运去哪不支持。 */
A4(40, "A4");
private final int code;
private final String label;
@ -45,7 +47,7 @@ public enum LabelSizeType { @@ -45,7 +47,7 @@ public enum LabelSizeType {
/** 是否可用于每页 1 个的排版。 */
public boolean singlePerPage() {
return this == SIZE_100_100 || this == SIZE_100_150;
return this == SIZE_100_100 || this == SIZE_100_150 || this == A4;
}
/** 是否可用于每页 6 个的排版。 */

38
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnQueryNoType.java

@ -0,0 +1,38 @@ @@ -0,0 +1,38 @@
package common.ecommerce.warehouse.enums;
/**
* 退货单查询时「单号」的类型。
*
* <p>易达云列表接口的 {@code orderNoSearchType}:1 退货单号 / 2 出库单号 / 3 平台订单号。
* 用统一枚举表达,适配器不支持的类型要<b>显式拒绝</b>——静默按别的口径查会让结果对不上。</p>
*
* <p>与 {@link FeeQueryNoType} 不是一套:那边是费用查询的「仓侧订单号 / 平台单号 / 追踪号」,
* 这里有「退货单号」,语义不同,不复用。</p>
*/
public enum ReturnQueryNoType {
/** 退货单号(仓侧 RMA 号)。 */
PROVIDER_RETURN_NO(10, "退货单号"),
/** 出库单号(原始发货单号)。 */
OUTBOUND_ORDER_NO(20, "出库单号"),
/** 平台订单号。 */
PLATFORM_ORDER_NO(30, "平台订单号");
private final int code;
private final String label;
ReturnQueryNoType(int code, String label) {
this.code = code;
this.label = label;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
}

4
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java

@ -59,7 +59,9 @@ public enum WarehouseCapability { @@ -59,7 +59,9 @@ public enum WarehouseCapability {
/** 物流异动单:召回 / 换址 / 在途异常(对已交运的运单发起处理) */
TRACKING_CHANGE(250, "物流异动单"),
/** 地址属性识别:判定收件地址是商业 / 住宅(影响附加费) */
ADDRESS_CLASSIFICATION(260, "地址属性识别");
ADDRESS_CLASSIFICATION(260, "地址属性识别"),
/** 箱唛打印(不依赖单据,按 SKU 打外箱标) */
CASE_MARK_PRINT(270, "箱唛打印");
private final int code;
private final String label;

217
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BolDocument.java

@ -0,0 +1,217 @@ @@ -0,0 +1,217 @@
package common.ecommerce.warehouse.model;
import java.time.Instant;
import java.util.Objects;
/**
* BOL(提单 / 提货凭证)单据。
*
* <p>与 {@link WarehouseAttachment} 的区别:附件只是「名字 + 类型 + URL」,
* BOL 还带<b>提货状态、约定 / 实际提货量、POD 签收凭证</b>,是独立的业务单据。</p>
*
* <p>SDK 不落文件、不访问对象存储:所有 URL 原样给出,下载由宿主负责。</p>
*/
public final class BolDocument {
/** 仓方 BOL 编号。 */
private final String bolCode;
/** BOL 文件地址。 */
private final String fileUrl;
/** 签收后的 BOL(带签章)地址;未签收为 null。 */
private final String signedFileUrl;
/** POD(签收凭证)地址;未妥投为 null。 */
private final String podFileUrl;
/** POD 上传时间(UTC)。 */
private final Instant podUploadedAt;
/** 仓方状态码原值;语义由适配器解释。 */
private final Integer rawStatus;
/** 状态中文名原值。 */
private final String statusName;
/** 约定提货日期(仓方原值,可能是日期字符串或时间戳)。 */
private final String scheduledPickupDate;
/** 实际提货日期(仓方原值)。 */
private final String actualPickupDate;
/** 约定提货件数。 */
private final Integer scheduledPickupQuantity;
/** 实际提货件数。 */
private final Integer actualPickupQuantity;
/** 卡车公司。 */
private final String truckCompany;
/** 跟踪号;卡车单可能是 BOL 号。 */
private final String trackingNo;
private BolDocument(Builder b) {
this.bolCode = require(b.bolCode, "bolCode");
this.fileUrl = b.fileUrl;
this.signedFileUrl = b.signedFileUrl;
this.podFileUrl = b.podFileUrl;
this.podUploadedAt = b.podUploadedAt;
this.rawStatus = b.rawStatus;
this.statusName = b.statusName;
this.scheduledPickupDate = b.scheduledPickupDate;
this.actualPickupDate = b.actualPickupDate;
this.scheduledPickupQuantity = b.scheduledPickupQuantity;
this.actualPickupQuantity = b.actualPickupQuantity;
this.truckCompany = b.truckCompany;
this.trackingNo = b.trackingNo;
}
public static Builder builder() {
return new Builder();
}
/** 仓方 BOL 编号。 */
public String bolCode() {
return bolCode;
}
public String fileUrl() {
return fileUrl;
}
/** 签收后的 BOL 地址;未签收为 null。 */
public String signedFileUrl() {
return signedFileUrl;
}
/** POD 签收凭证地址;未妥投为 null。 */
public String podFileUrl() {
return podFileUrl;
}
public Instant podUploadedAt() {
return podUploadedAt;
}
/** 仓方状态码原值。 */
public Integer rawStatus() {
return rawStatus;
}
/** 仓方状态名原值。 */
public String statusName() {
return statusName;
}
/** 约定提货日期(仓方原值)。 */
public String scheduledPickupDate() {
return scheduledPickupDate;
}
/** 实际提货日期(仓方原值)。 */
public String actualPickupDate() {
return actualPickupDate;
}
public Integer scheduledPickupQuantity() {
return scheduledPickupQuantity;
}
public Integer actualPickupQuantity() {
return actualPickupQuantity;
}
public String truckCompany() {
return truckCompany;
}
public String trackingNo() {
return trackingNo;
}
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 bolCode;
private String fileUrl;
private String signedFileUrl;
private String podFileUrl;
private Instant podUploadedAt;
private Integer rawStatus;
private String statusName;
private String scheduledPickupDate;
private String actualPickupDate;
private Integer scheduledPickupQuantity;
private Integer actualPickupQuantity;
private String truckCompany;
private String trackingNo;
public Builder bolCode(String v) {
this.bolCode = v;
return this;
}
public Builder fileUrl(String v) {
this.fileUrl = v;
return this;
}
public Builder signedFileUrl(String v) {
this.signedFileUrl = v;
return this;
}
public Builder podFileUrl(String v) {
this.podFileUrl = v;
return this;
}
public Builder podUploadedAt(Instant v) {
this.podUploadedAt = v;
return this;
}
public Builder rawStatus(Integer v) {
this.rawStatus = v;
return this;
}
public Builder statusName(String v) {
this.statusName = v;
return this;
}
public Builder scheduledPickupDate(String v) {
this.scheduledPickupDate = v;
return this;
}
public Builder actualPickupDate(String v) {
this.actualPickupDate = v;
return this;
}
public Builder scheduledPickupQuantity(Integer v) {
this.scheduledPickupQuantity = v;
return this;
}
public Builder actualPickupQuantity(Integer v) {
this.actualPickupQuantity = v;
return this;
}
public Builder truckCompany(String v) {
this.truckCompany = v;
return this;
}
public Builder trackingNo(String v) {
this.trackingNo = v;
return this;
}
public BolDocument build() {
Objects.requireNonNull(bolCode, "bolCode");
return new BolDocument(this);
}
}
}

126
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CaseMarkPrintCommand.java

@ -0,0 +1,126 @@ @@ -0,0 +1,126 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.CaseMarkPaperSize;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 箱唛打印命令(打外箱标,不是入库单的 SKU 贴标)。
*
* <p>与 {@link SkuLabelCommand} 的区别:那个是<b>入库计划单</b>的贴标(绑定
* 入库单号、14 种小纸尺寸);这个是<b>按 SKU 打条码</b>,不依赖任何单据,
* 仓库 / 门店自己贴标用。</p>
*
* <p>仓方<b>同步</b>返回文件地址(不是异步任务),所以返回的是
* {@link WarehouseLabel} 而不是 {@link LabelPrintTask}。</p>
*/
public final class CaseMarkPrintCommand {
/** 一次最多打多少种 SKU。 */
public static final int MAX_SKUS = 50;
private final CaseMarkPaperSize paperSize;
/** 备注,如 {@code Made in China}。 */
private final String remark;
/** 是否打印 SKU 名称。 */
private final boolean printSkuName;
private final List<CaseMarkItem> items;
private CaseMarkPrintCommand(Builder b) {
if (b.paperSize == null) {
throw new IllegalArgumentException("paperSize is required");
}
this.paperSize = b.paperSize;
this.remark = b.remark;
this.printSkuName = b.printSkuName;
if (b.items.isEmpty()) {
throw new IllegalArgumentException("items must not be empty");
}
if (b.items.size() > MAX_SKUS) {
throw new IllegalArgumentException(
"at most " + MAX_SKUS + " skus per print, got " + b.items.size());
}
this.items = Collections.unmodifiableList(new ArrayList<CaseMarkItem>(b.items));
}
public static Builder builder() {
return new Builder();
}
public CaseMarkPaperSize paperSize() {
return paperSize;
}
/** 备注;null 表示不打印。 */
public String remark() {
return remark;
}
/** 是否打印 SKU 名称。 */
public boolean printSkuName() {
return printSkuName;
}
public List<CaseMarkItem> items() {
return items;
}
/** 一个 SKU 及其打印份数。 */
public static final class CaseMarkItem {
private final String providerSku;
private final int copies;
public CaseMarkItem(String providerSku, int copies) {
if (providerSku == null || providerSku.trim().isEmpty()) {
throw new IllegalArgumentException("providerSku must not be blank");
}
if (copies <= 0) {
throw new IllegalArgumentException("copies must be positive");
}
this.providerSku = providerSku.trim();
this.copies = copies;
}
public String providerSku() {
return providerSku;
}
public int copies() {
return copies;
}
}
public static final class Builder {
private CaseMarkPaperSize paperSize;
private String remark;
private boolean printSkuName;
private final List<CaseMarkItem> items = new ArrayList<CaseMarkItem>();
public Builder paperSize(CaseMarkPaperSize v) {
this.paperSize = v;
return this;
}
public Builder remark(String v) {
this.remark = v;
return this;
}
public Builder printSkuName(boolean v) {
this.printSkuName = v;
return this;
}
public Builder item(String providerSku, int copies) {
this.items.add(new CaseMarkItem(providerSku, copies));
return this;
}
public CaseMarkPrintCommand build() {
return new CaseMarkPrintCommand(this);
}
}
}

173
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnQuery.java

@ -0,0 +1,173 @@ @@ -0,0 +1,173 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.ReturnQueryNoType;
import common.ecommerce.warehouse.enums.ReturnStatus;
import java.time.Instant;
import java.util.Collections;
import java.util.List;
/**
* 退货单查询条件(单次查询,不推进水位线)。
*
* <p>各仓支持的维度不同:易达云支持时间窗 + 单号 + 仓库 + 状态 + SKU,
* 不支持的维度由适配器<b>显式拒绝</b>,不静默忽略——忽略一个过滤条件会让结果对不上。</p>
*/
public final class ReturnQuery {
private final Instant createdAfter;
private final Instant createdBefore;
private final String orderNo;
private final ReturnQueryNoType orderNoType;
private final String trackingNo;
private final String warehouseCode;
private final List<ReturnStatus> statuses;
private final String providerSku;
private final int pageSize;
private final String cursor;
private ReturnQuery(Builder b) {
if (b.createdAfter != null && b.createdBefore != null
&& !b.createdAfter.isBefore(b.createdBefore)) {
throw new IllegalArgumentException("createdAfter must be before createdBefore");
}
this.createdAfter = b.createdAfter;
this.createdBefore = b.createdBefore;
this.orderNo = b.orderNo;
this.orderNoType = b.orderNoType;
this.trackingNo = b.trackingNo;
this.warehouseCode = b.warehouseCode;
this.statuses = Collections.unmodifiableList(new java.util.ArrayList<ReturnStatus>(b.statuses));
this.providerSku = b.providerSku;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
public static Builder builder() {
return new Builder();
}
/** 创建时间窗起点(UTC);null 表示不限。 */
public Instant createdAfter() {
return createdAfter;
}
/** 创建时间窗终点(UTC)。 */
public Instant createdBefore() {
return createdBefore;
}
public boolean hasCreatedRange() {
return createdAfter != null && createdBefore != null;
}
/** 单号;配合 {@link #orderNoType()}。 */
public String orderNo() {
return orderNo;
}
/** 单号类型;null 由适配器按自己的默认口径解释。 */
public ReturnQueryNoType orderNoType() {
return orderNoType;
}
/** 跟踪号。 */
public String trackingNo() {
return trackingNo;
}
/** 仓编码;适配器优先用账户配置的仓方 id。 */
public String warehouseCode() {
return warehouseCode;
}
/** 状态过滤;空表示不过滤。 */
public List<ReturnStatus> statuses() {
return statuses;
}
/** 仓侧 SKU。 */
public String providerSku() {
return providerSku;
}
public int pageSize() {
return pageSize;
}
/** 分页游标;null 表示第一页。 */
public String cursor() {
return cursor;
}
public static final class Builder {
private Instant createdAfter;
private Instant createdBefore;
private String orderNo;
private ReturnQueryNoType orderNoType;
private String trackingNo;
private String warehouseCode;
private final List<ReturnStatus> statuses = new java.util.ArrayList<ReturnStatus>();
private String providerSku;
private int pageSize = 100;
private String cursor;
public Builder createdAfter(Instant v) {
this.createdAfter = v;
return this;
}
public Builder createdBefore(Instant v) {
this.createdBefore = v;
return this;
}
/** 单号;配合 {@link #orderNoType}。 */
public Builder orderNo(String v) {
this.orderNo = v;
return this;
}
public Builder orderNoType(ReturnQueryNoType v) {
this.orderNoType = v;
return this;
}
public Builder trackingNo(String v) {
this.trackingNo = v;
return this;
}
public Builder warehouseCode(String v) {
this.warehouseCode = v;
return this;
}
public Builder status(ReturnStatus v) {
if (v != null) {
this.statuses.add(v);
}
return this;
}
public Builder providerSku(String v) {
this.providerSku = v;
return this;
}
public Builder pageSize(int v) {
this.pageSize = v;
return this;
}
public Builder cursor(String v) {
this.cursor = v;
return this;
}
public ReturnQuery build() {
return new ReturnQuery(this);
}
}
}

40
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java

@ -28,6 +28,20 @@ public final class TrackingInfo { @@ -28,6 +28,20 @@ public final class TrackingInfo {
private final Instant estimatedDeliveryAt;
/** 签收人;未签收为 null。 */
private final String signedBy;
/**
* 上网时间(= 承运商首次揽收扫描);仓方未给为 null。
*
* <p>易达云字段:{@code onlineTime}({@code getTrackInfoList})。
* 对客服场景意义在于「包裹到底有没有真的交给承运商」——
* 有上网时间才说明物流真的启动了。</p>
*/
private final Instant firstOnlineAt;
/**
* 妥投时间(= 已签收);未妥投为 null。
*
* <p>易达云字段:{@code deliveredTime}({@code getTrackInfoList})。</p>
*/
private final Instant deliveredAt;
/** 承运商侧可公开查询的轨迹页地址。 */
private final String publicUrl;
private final List<TrackEvent> events;
@ -74,6 +88,8 @@ public final class TrackingInfo { @@ -74,6 +88,8 @@ public final class TrackingInfo {
this.statusDetail = b.statusDetail;
this.estimatedDeliveryAt = b.estimatedDeliveryAt;
this.signedBy = b.signedBy;
this.firstOnlineAt = b.firstOnlineAt;
this.deliveredAt = b.deliveredAt;
this.publicUrl = b.publicUrl;
this.events = Collections.unmodifiableList(new ArrayList<TrackEvent>(b.events));
this.parcelWeightGrams = b.parcelWeightGrams;
@ -118,6 +134,16 @@ public final class TrackingInfo { @@ -118,6 +134,16 @@ public final class TrackingInfo {
return signedBy;
}
/** 上网时间(首次揽收扫描);仓方未给为 null。 */
public Instant firstOnlineAt() {
return firstOnlineAt;
}
/** 妥投时间;未妥投为 null。 */
public Instant deliveredAt() {
return deliveredAt;
}
public String publicUrl() {
return publicUrl;
}
@ -177,6 +203,8 @@ public final class TrackingInfo { @@ -177,6 +203,8 @@ public final class TrackingInfo {
private String statusDetail;
private Instant estimatedDeliveryAt;
private String signedBy;
private Instant firstOnlineAt;
private Instant deliveredAt;
private String publicUrl;
private final List<TrackEvent> events = new ArrayList<TrackEvent>();
private Double parcelWeightGrams;
@ -222,6 +250,18 @@ public final class TrackingInfo { @@ -222,6 +250,18 @@ public final class TrackingInfo {
return this;
}
/** 上网时间(首次揽收扫描)。 */
public Builder firstOnlineAt(Instant v) {
this.firstOnlineAt = v;
return this;
}
/** 妥投时间。 */
public Builder deliveredAt(Instant v) {
this.deliveredAt = v;
return this;
}
public Builder publicUrl(String v) {
this.publicUrl = v;
return this;

116
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCarrier.java

@ -0,0 +1,116 @@ @@ -0,0 +1,116 @@
package common.ecommerce.warehouse.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 客户自有的承运商(物流服务商)及其下属物流服务。
*
* <p>用于「客户自有物流 + 客户上传面单」的自提单场景:下单时
* {@code carrierName} 填 {@link #nameEn()} 或某个 {@link OwnLogistic#name()}。</p>
*
* <p>这是<b>主数据</b>,不是状态:同一仓的承运商清单很少变,适合宿主缓存。</p>
*/
public final class WarehouseCarrier {
/** 承运商 id(仓方码)。 */
private final String carrierId;
/** 承运商英文名,如 {@code FedEx}。 */
private final String nameEn;
/** 承运商中文名。 */
private final String nameCn;
/** 该承运商下的物流服务;仓方未给时为空列表。 */
private final List<OwnLogistic> logists;
private WarehouseCarrier(Builder b) {
this.carrierId = require(b.carrierId, "carrierId");
this.nameEn = b.nameEn;
this.nameCn = b.nameCn;
this.logists = Collections.unmodifiableList(new ArrayList<OwnLogistic>(b.logists));
}
public static Builder builder() {
return new Builder();
}
public String carrierId() {
return carrierId;
}
public String nameEn() {
return nameEn;
}
public String nameCn() {
return nameCn;
}
/** 下属物流服务;可能为空。 */
public List<OwnLogistic> logists() {
return logists;
}
/** 展示名:优先中文名,没有再用英文名。 */
public String displayName() {
return nameCn != null && !nameCn.trim().isEmpty() ? nameCn : nameEn;
}
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 OwnLogistic {
private final String logisticId;
private final String name;
public OwnLogistic(String logisticId, String name) {
this.logisticId = require(logisticId, "logisticId");
this.name = name;
}
public String logisticId() {
return logisticId;
}
public String name() {
return name;
}
}
public static final class Builder {
private String carrierId;
private String nameEn;
private String nameCn;
private final List<OwnLogistic> logists = new ArrayList<OwnLogistic>();
public Builder carrierId(String v) {
this.carrierId = v;
return this;
}
public Builder nameEn(String v) {
this.nameEn = v;
return this;
}
public Builder nameCn(String v) {
this.nameCn = v;
return this;
}
public Builder logistic(OwnLogistic v) {
this.logists.add(v);
return this;
}
public WarehouseCarrier build() {
return new WarehouseCarrier(this);
}
}
}

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

@ -4,55 +4,57 @@ import common.ecommerce.shared.audit.CallObserver; @@ -4,55 +4,57 @@ import common.ecommerce.shared.audit.CallObserver;
import common.ecommerce.shared.audit.CallSupport;
import common.ecommerce.shared.idempotency.IdempotencyGuard;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.capability.CaseMarkPrintCapable;
import common.ecommerce.warehouse.capability.BolCapable;
import common.ecommerce.warehouse.capability.DestructionCapable;
import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.AddressClassificationCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.TrackingChangeCapable;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.ChannelRecommendQuery;
import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.model.DestructionCommand;
import common.ecommerce.warehouse.model.DestructionOrder;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.LabelPrintTask;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.SkuLabelCommand;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.WarehouseLabel;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.spi.WarehouseAccount;
import java.time.Instant;
import java.util.List;
import java.util.Map;
/**
* 单个仓的操作入口:{@code sdk.warehouses(code, conn).outbound()} 等。
@ -331,6 +333,20 @@ public final class WarehouseOperations { @@ -331,6 +333,20 @@ public final class WarehouseOperations {
}
/**
* 仓方基础资料:客户自有的承运商及其下属物流服务。
*
* <p>只读主数据。与 {@link #carriers()} 的区别是带名称与两层结构,
* 宿主可直接渲染成「承运商 → 物流服务」两级下拉。</p>
*/
public List<common.ecommerce.warehouse.model.WarehouseCarrier> carrierDirectory() {
require(WarehouseCapability.DIRECTORY, WarehouseDirectoryCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.directory.carriers.detail",
CallSupport.params(),
List::size,
() -> ((WarehouseDirectoryCapable) adapter).carrierDirectory(ctx));
}
/**
* 查物流产品(承运商渠道)清单。只读主数据,不走幂等。
*
* @param warehouseCode 仓 code;null 时用账户配置的仓
@ -343,6 +359,38 @@ public final class WarehouseOperations { @@ -343,6 +359,38 @@ public final class WarehouseOperations {
() -> ((LogisticsProductCapable) adapter).products(ctx, warehouseCode));
}
/**
* 查平台仓订单 / 店铺订单的 BOL(提单 / 提货凭证)。
*
* <p>与 {@code inbound().bols()} 不同:那个是入库计划单的 BOL 文件地址,
* 这个带提货状态与 POD。只读,不走幂等。</p>
*
* @param providerOrderNo 仓方(或平台仓)订单号
*/
public List<common.ecommerce.warehouse.model.BolDocument> orderBols(String providerOrderNo) {
require(WarehouseCapability.BOL, BolCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.bol.order",
CallSupport.params("providerOrderNo", providerOrderNo),
List::size,
() -> ((BolCapable) adapter).orderBols(ctx, providerOrderNo));
}
/**
* 打印箱唛(外箱标,不依赖入库单)。
*
* <p>与 {@code inbound().printSkuLabel()} 不同:那个是入库计划单的 SKU 贴标,
* 这个只按 SKU 打外箱标。仓方同步返回文件地址,所以不走幂等守卫——
* 重复调用只是再生成一份,不改业务状态。</p>
*/
public WarehouseLabel printCaseMarks(CaseMarkPrintCommand cmd) {
require(WarehouseCapability.CASE_MARK_PRINT, CaseMarkPrintCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.caseMark.print",
CallSupport.params("paperSize", cmd.paperSize(),
"skuCount", cmd.items().size()),
r -> CallSupport.NO_COUNT,
() -> ((CaseMarkPrintCapable) adapter).printCaseMarks(ctx, cmd));
}
/** 费用视图。 */
public FeeView fees() {
return new FeeView();
@ -643,12 +691,21 @@ public final class WarehouseOperations { @@ -643,12 +691,21 @@ public final class WarehouseOperations {
() -> ((WarehouseReturnCapable) adapter).getReturn(ctx, returnRequestNo));
}
public Page<WarehouseReturn> query(String cursor) {
/**
* 分页查退货单。
*
* <p>各仓支持的过滤维度不同,不支持的由适配器显式拒绝;传空条件时
* 适配器要么用自己的默认窗口(如易达云默认近一个月),要么拒绝。</p>
*/
public Page<WarehouseReturn> query(ReturnQuery query) {
require(WarehouseCapability.RETURN, WarehouseReturnCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.return.query",
CallSupport.params("cursor", cursor),
CallSupport.params("cursor", query.cursor(),
"orderNo", query.orderNo(),
"warehouseCode", query.warehouseCode(),
"statusCount", query.statuses().size()),
p -> p.size(),
() -> ((WarehouseReturnCapable) adapter).queryReturns(ctx, cursor));
() -> ((WarehouseReturnCapable) adapter).queryReturns(ctx, query));
}
/**
@ -677,6 +734,28 @@ public final class WarehouseOperations { @@ -677,6 +734,28 @@ public final class WarehouseOperations {
},
c -> null));
}
/**
* 取消退货单。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + providerReturnNo + "cancel"}。
*
* <p>只传仓侧退货单号——多数仓的取消接口只认自己的 RMA 号。</p>
*
* @return {@code true} 取消成功
*/
public boolean cancel(final String providerReturnNo) {
require(WarehouseCapability.RETURN, WarehouseReturnCapable.class);
if (guard == null) {
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());
}
}
/** 费用视图。 */

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

@ -79,6 +79,51 @@ public final class EdayunConstants { @@ -79,6 +79,51 @@ public final class EdayunConstants {
/** 费用试算 / 预估({@code POST /webApi/estimate/v1/trial})。 */
public static final String PATH_FEE_ESTIMATE = "/webApi/estimate/v1/trial";
/** 创建退货单 / 退货预报({@code POST /webApi/rma/info/v1/saveAndPublish})。 */
public static final String PATH_RETURN_CREATE = "/webApi/rma/info/v1/saveAndPublish";
/** 获取退货单详情({@code POST /webApi/rma/info/v1/getOrderDetail})。 */
public static final String PATH_RETURN_DETAIL = "/webApi/rma/info/v1/getOrderDetail";
/** 取消退货单({@code POST /webApi/rma/info/v1/cancel})。 */
public static final String PATH_RETURN_CANCEL = "/webApi/rma/info/v1/cancel";
/** 查询退货单列表({@code POST /webApi/rma/info/v1/selectRmaInfoList})。 */
public static final String PATH_RETURN_LIST = "/webApi/rma/info/v1/selectRmaInfoList";
/** 查询 BOL 信息({@code POST /webApi/fbaOrder/v1/getOrderBolList})。 */
public static final String PATH_BOL_LIST = "/webApi/fbaOrder/v1/getOrderBolList";
/** 根据仓库查询物流产品列表({@code POST /webApi/order/listByLogisticProductHasPerm})。 */
public static final String PATH_LOGISTICS_PRODUCTS = "/webApi/order/listByLogisticProductHasPerm";
/** 查询订单物流轨迹({@code POST /webApi/track/getTrackInfoList})。 */
public static final String PATH_TRACK = "/webApi/track/getTrackInfoList";
/**
* 打印箱唛({@code POST /webApi/skuInfo/v2/printBarcode})。
*
* <p>端点名是 printBarcode,实际打的是箱唛——已与仓方确认。</p>
*/
public static final String PATH_CASE_MARK_PRINT = "/webApi/skuInfo/v2/printBarcode";
/**
* 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
*
* <p>端点名是 newPrintCaseMark,实际打的是 SKU 标——已与仓方确认。</p>
*/
public static final String PATH_SKU_LABEL_PRINT =
"/webApi/entryInfo/v1/newPrintCaseMarkContentType";
/** 查询客户自有物流服务(承运商)({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。 */
public static final String PATH_CARRIERS = "/webApi/carrier/v1/listCarrierByWarehouse";
/** 获取激活仓库列表({@code POST /webApi/warehouse/listActive})。 */
public static final String PATH_WAREHOUSE_ACTIVE = "/webApi/warehouse/listActive";
/** 获取权限内仓库({@code POST /webApi/warehouse/listWarehouseHasPerm})。 */
public static final String PATH_WAREHOUSE_PERMITTED = "/webApi/warehouse/listWarehouseHasPerm";
/** 物流增值:签收服务。 */
public static final String ADD_SERVICE_SIGNATURE = "is_signature";

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

@ -2,9 +2,13 @@ package common.ecommerce.edayun.adapter; @@ -2,9 +2,13 @@ package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.auth.EdayunTokenClient;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.edayun.dto.EdayunAccountFlowDtos;
import common.ecommerce.edayun.dto.EdayunBolDtos;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
import common.ecommerce.edayun.dto.EdayunCancelDtos;
import common.ecommerce.edayun.dto.EdayunCancelReturnDtos;
import common.ecommerce.edayun.dto.EdayunCaseMarkDtos;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.edayun.dto.EdayunCreateProductDtos;
import common.ecommerce.edayun.dto.EdayunFeeEstimateDtos;
import common.ecommerce.edayun.dto.EdayunGetOrderDtos;
@ -12,8 +16,15 @@ import common.ecommerce.edayun.dto.EdayunGetOrderLabelDtos; @@ -12,8 +16,15 @@ import common.ecommerce.edayun.dto.EdayunGetOrderLabelDtos;
import common.ecommerce.edayun.dto.EdayunInboundDtos;
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.EdayunRentDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
import common.ecommerce.edayun.dto.EdayunSkuLabelDtos;
import common.ecommerce.edayun.dto.EdayunTrackDtos;
import common.ecommerce.edayun.dto.EdayunWarehouseDtos;
import common.ecommerce.edayun.enums.EdayunCancelStatus;
import common.ecommerce.edayun.http.EdayunRequestFactory;
import common.ecommerce.http.HttpRequest;
@ -26,13 +37,18 @@ import common.ecommerce.shared.spi.ChannelSecret; @@ -26,13 +37,18 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.BolCapable;
import common.ecommerce.warehouse.capability.CaseMarkPrintCapable;
import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
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.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
import common.ecommerce.warehouse.enums.LabelMode;
@ -40,9 +56,12 @@ import common.ecommerce.warehouse.enums.WarehouseCapability; @@ -40,9 +56,12 @@ import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.BolDocument;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.model.FeeQuery;
@ -51,12 +70,23 @@ import common.ecommerce.warehouse.model.InboundOrder; @@ -51,12 +70,23 @@ 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.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
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.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
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.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -76,7 +106,11 @@ import java.util.List; @@ -76,7 +106,11 @@ import java.util.List;
*/
public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable,
OutboundCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable,
InboundCapable {
InboundCapable, WarehouseReturnCapable, BolCapable, LogisticsProductCapable,
TrackingCapable, CaseMarkPrintCapable, WarehouseDirectoryCapable {
/** 物流产品查询的适用业务:1 店铺订单(默认口径)。 */
private static final int APPLICABLE_BUSINESS_STORE_ORDER = 1;
private final HttpTransport transport;
private final JacksonJsonCodec json;
@ -128,7 +162,10 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -128,7 +162,10 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE,
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND);
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND,
WarehouseCapability.RETURN, WarehouseCapability.BOL,
WarehouseCapability.LOGISTICS_PRODUCT, WarehouseCapability.TRACKING,
WarehouseCapability.CASE_MARK_PRINT, WarehouseCapability.DIRECTORY);
}
/**
@ -686,6 +723,440 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -686,6 +723,440 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
EdayunFeeEstimateMapper.toResult(parsed, ctx.warehouseCode()));
}
// ------------------------------------------------------------------ 退货
/**
* 创建退货单 / 退货预报({@code POST /webApi/rma/info/v1/saveAndPublish})。
*
* <p>统一模型只对应「自行退回」({@code returnType=2}):它要求退货运单号,
* 正好是买家自己寄回的场景。未妥投 / 返邮 / FBA 退回要退货人地址或亚马逊单号,
* 标准模型没有——见 TODO。</p>
*
* <p>与运去哪不同,<b>响应 {@code data} 就是仓侧退货单号</b>,可直接落
* {@code providerReturnId};状态不回,只能后续人工或回调补。</p>
*/
@Override
public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) {
EdayunReturnDtos.SaveReturnRequest body =
EdayunReturnMapper.toRequest(cmd, ctx.providerWarehouseId());
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_CREATE, bodyJson,
"warehouse.return.create");
EdayunReturnDtos.SaveReturnResponse parsed =
json.fromJson(resp.body(), EdayunReturnDtos.SaveReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.create");
if (parsed.data == null || parsed.data.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun return create returned no return order no")
.operation("warehouse.return.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return EdayunReturnMapper.toCreated(cmd, parsed.data.trim(), ctx.warehouseCode());
}
/**
* 获取退货单详情({@code POST /webApi/rma/info/v1/getOrderDetail})。
*
* <p>{@code returnRequestNo} 可以是 OMS 退货单号,也可以是仓方 RMA 号——
* 仓方只认 {@code rmaCode},所以<b>非 RMA 号要先有创建时拿到的
* {@code providerReturnId}</b>。这里原样传,查不到由仓方报错。</p>
*
* <p>明细行优先取仓的检验结果({@code checkList}),没有才退回预报
* ({@code skuList})——对账以实际收到为准。</p>
*/
@Override
public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) {
EdayunReturnDetailDtos.GetReturnRequest body =
EdayunReturnDetailMapper.toRequest(returnRequestNo);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_DETAIL, bodyJson,
"warehouse.return.get");
EdayunReturnDetailDtos.GetReturnResponse parsed =
json.fromJson(resp.body(), EdayunReturnDetailDtos.GetReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.get");
if (parsed.data == null) {
// 单号不存在时仓方可能回 code=200 + data=null,按「查不到」返回 null
return null;
}
return EdayunReturnDetailMapper.toReturn(parsed.data, ctx.warehouseCode(),
body.rmaCode);
}
/**
* 取消退货单({@code POST /webApi/rma/info/v1/cancel})。
*
* <p>只认仓方 {@code rmaCode},所以传的必须是创建时拿到的
* {@code providerReturnId}——用 OMS 单号会被仓方查不到。</p>
*
* <p>响应 {@code data=true} 才算成功。{@code code=200} + {@code data=false}
* 是仓方拒绝(如已收货),这里抛异常而不是静默返回 false——
* 取消退货是状态变更,调用方必须知道没成功。</p>
*/
@Override
public boolean cancel(WarehouseContext ctx, String providerReturnNo) {
if (!hasText(providerReturnNo)) {
throw new IllegalArgumentException(
"edayun return cancel needs the provider return no (rmaCode)");
}
EdayunCancelReturnDtos.CancelReturnRequest body =
new EdayunCancelReturnDtos.CancelReturnRequest();
body.rmaCode = providerReturnNo.trim();
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_CANCEL, bodyJson,
"warehouse.return.cancel");
EdayunCancelReturnDtos.CancelReturnResponse parsed =
json.fromJson(resp.body(), EdayunCancelReturnDtos.CancelReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.cancel");
if (parsed.data == null || !parsed.data) {
throw WarehouseException.builder()
.message("edayun return cancel rejected: " + parsed.msg)
.operation("warehouse.return.cancel")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return true;
}
/**
* 查询退货单列表({@code POST /webApi/rma/info/v1/selectRmaInfoList})。
*
* <p>只回单头,没有明细行与退货人地址;要明细请用 {@link #getReturn}。</p>
*
* <p>时间窗不传时仓方默认近一个月——这一点由仓方兜底,本地不补默认值,
* 免得「没给时间窗」和「显式要近一个月」两种情况被混掉。</p>
*/
@Override
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query) {
int pageNum = EdayunRmaListMapper.pageNumber(query.cursor());
EdayunRmaListDtos.SelectRmaListRequest body = EdayunRmaListMapper.toRequest(
query, ctx.providerWarehouseId(), ctx.zone(), pageNum);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_LIST, bodyJson,
"warehouse.return.query");
EdayunRmaListDtos.SelectRmaListResponse parsed =
json.fromJson(resp.body(), EdayunRmaListDtos.SelectRmaListResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.query");
return EdayunRmaListMapper.toPage(parsed, ctx.warehouseCode(), pageNum, body.pageSize);
}
/**
* 按明细行设置检验后处理方式。
*
* <p>需要仓侧明细行 id,而查退货单的接口还没有——无法构造,显式拒绝。</p>
*/
@Override
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN_DISPOSITION);
}
// ------------------------------------------------------------------ BOL / 物流产品
/**
* 查询 BOL(提单 / 提货凭证)
* ({@code POST /webApi/fbaOrder/v1/getOrderBolList})。
*
* <p>店铺订单与平台仓订单共用,{@code orderNo} 传 EDA 的平台仓订单号
* (如 {@code FBA473182144})。没有 BOL 时返回空列表,不是错误。</p>
*/
@Override
public List<BolDocument> orderBols(WarehouseContext ctx, String providerOrderNo) {
EdayunBolDtos.GetBolRequest body = EdayunBolMapper.toRequest(providerOrderNo);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_BOL_LIST, bodyJson,
"warehouse.bol.order");
EdayunBolDtos.GetBolResponse parsed =
json.fromJson(resp.body(), EdayunBolDtos.GetBolResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.bol.order");
return EdayunBolMapper.toDocuments(parsed);
}
/**
* 查物流产品清单
* ({@code POST /webApi/order/listByLogisticProductHasPerm})。
*
* <p>{@code productId = -998}(使用分物流规则)不是真实产品,映射时跳过。</p>
*/
@Override
public List<LogisticsProduct> products(WarehouseContext ctx, String warehouseCode) {
// 统一模型不区分业务类型,默认查「店铺订单」(1);
// 不传反而返回全账号的产品,量太大
EdayunLogisticsProductDtos.ListProductRequest body = EdayunLogisticsProductMapper.toRequest(
ctx.providerWarehouseId(), APPLICABLE_BUSINESS_STORE_ORDER);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_LOGISTICS_PRODUCTS, bodyJson,
"warehouse.logistics.products");
EdayunLogisticsProductDtos.ListProductResponse parsed =
json.fromJson(resp.body(), EdayunLogisticsProductDtos.ListProductResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.logistics.products");
return EdayunLogisticsProductMapper.toProducts(
parsed == null ? null : parsed.data, ctx.warehouseCode());
}
// ------------------------------------------------------------------ 物流轨迹
/**
* 按跟踪号查轨迹节点({@code POST /webApi/track/getTrackInfoList})。
*
* <p>请求体是<b>纯字符串数组</b>,文档示例的嵌套对象是错的。
* 仓方无轨迹时返回<b>空列表</b>——真机对查不到的跟踪号回
* {@code code=500, msg=未匹配到轨迹},那是「没轨迹」不是「调用失败」。</p>
*/
@Override
public List<TrackEvent> track(WarehouseContext ctx, String trackingNumber) {
EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track");
return EdayunTrackMapper.toTrackEvents(parsed);
}
/**
* 按跟踪号查运单级轨迹;除节点外带上网时间与妥投时间。
*
* <p>文档说明「主要关注上网时间跟妥投时间」,这两个在
* {@link TrackingInfo#firstOnlineAt()} / {@link TrackingInfo#deliveredAt()}。</p>
*/
@Override
public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) {
EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track.shipment");
return EdayunTrackMapper.toTrackingInfo(parsed);
}
/**
* 查一条轨迹;查不到返回 null。
*
* <p><b>「未匹配到轨迹」按空结果处理</b>:仓方把这个当业务失败(code=500),
* 但对调用方来说和「运单还没揽收」是同一件事——两者都不该抛异常,
* 否则宿主无法区分「真失败」和「还没轨迹」。</p>
*/
private EdayunTrackDtos.Track fetchTrack(WarehouseContext ctx, String trackingNumber,
String operation) {
List<String> body = EdayunTrackMapper.toRequest(
java.util.Collections.singletonList(trackingNumber));
String bodyJson = json.toJson(body);
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)) {
return null;
}
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, operation);
return EdayunTrackMapper.find(parsed, trackingNumber);
}
/** 仓方「没有轨迹」的提示语。 */
private static boolean isNoTrackFound(String msg) {
return msg != null && (msg.contains("未匹配到轨迹") || msg.contains("跟踪号为空"));
}
// ------------------------------------------------------------------ 条码打印
// ------------------------------------------------------------------ 箱唛
/**
* 打印箱唛({@code POST /webApi/skuInfo/v2/printBarcode})。
*
* <p><b>端点名叫 printBarcode,但实际打的是箱唛(外箱标)</b>——已与仓方确认。
* 真正的 SKU 标走 {@code printSkuLabel}(端点 {@code newPrintCaseMark})。</p>
*
* <p>与入库箱标({@code inbound().printBoxLabel})不同:那个是运去哪风格的
* 异步任务(只回任务号),易达云这个<b>同步返回 PDF 地址</b>。</p>
*
* <p>真机实测的仓方校验:{@code productInfos} 为空报「产品信息不能为空」,
* 缺 {@code pageSize} 报「纸张尺寸不能为空」,{@code pageSize} 非 0~3 报
* 「内部服务器错误」,{@code num=0} 同样「内部服务器错误」,超过 50 个 SKU
* 报「最多打印50个SKU」。本地已提前挡住后两者。</p>
*/
@Override
public WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd) {
EdayunCaseMarkDtos.PrintCaseMarkRequest body = EdayunCaseMarkMapper.toRequest(cmd);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_CASE_MARK_PRINT, bodyJson,
"warehouse.caseMark.print");
EdayunCaseMarkDtos.PrintCaseMarkResponse parsed =
json.fromJson(resp.body(), EdayunCaseMarkDtos.PrintCaseMarkResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.caseMark.print");
if (parsed.data == null || parsed.data.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun printBarcode returned no file url")
.operation("warehouse.caseMark.print")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return EdayunCaseMarkMapper.toLabel(parsed.data.trim(), cmd);
}
// ------------------------------------------------------------------ SKU 标
/**
* 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
*
* <p><b>端点名叫 newPrintCaseMark,但实际打的是 SKU 标</b>——已与仓方确认。
* 箱唛走 {@code printCaseMarks}(端点 {@code printBarcode})。</p>
*
* <p>统一模型的 {@code BoxLabelCommand} 没有「选哪些箱」的字段,
* 所以默认整单打印;要打部分箱用重载。</p>
*
* <p><b>真机未验证</b>:PR 环境该接口返回「接口不存在或未启用」,
* 换到 {@code /newPrintCaseMark}(无 ContentType 后缀)能过参数校验
* (缺 pageSize 报「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」),
* 但补全后一律「内部服务器错误」。见 docs-warehouse/edayun/TODO.md。</p>
*/
public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) {
EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd);
return sendSkuLabel(ctx, body);
}
/**
* 打印 SKU 标(可选箱)。
*
* @param selection 选箱条件;四选一,全空时本地拒绝
*/
public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd,
EdayunSkuLabelMapper.CaseSelection selection) {
EdayunSkuLabelDtos.PrintSkuLabelRequest body =
EdayunSkuLabelMapper.toRequest(cmd, selection);
return sendSkuLabel(ctx, body);
}
private WarehouseLabel sendSkuLabel(WarehouseContext ctx,
EdayunSkuLabelDtos.PrintSkuLabelRequest body) {
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_SKU_LABEL_PRINT, bodyJson,
"warehouse.skuLabel.print");
EdayunSkuLabelDtos.PrintSkuLabelResponse parsed =
json.fromJson(resp.body(), EdayunSkuLabelDtos.PrintSkuLabelResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.skuLabel.print");
if (parsed.data == null || parsed.data.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun newPrintCaseMark returned no file url")
.operation("warehouse.skuLabel.print")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return EdayunSkuLabelMapper.toLabel(parsed.data.trim());
}
// ------------------------------------------------------------------ 承运商
/**
* 客户名下有权限的仓库列表
* ({@code POST /webApi/warehouse/listWarehouseHasPerm})。
*
* <p><b>用这个,不要用 listActive</b>:listActive 是平台全量激活仓(118 条),
* 含当前客户没授权的;这个只返回有权限的(69 条)。</p>
*
* <p>{@code -999}(智能分仓)是哨兵值,映射时已跳过。</p>
*/
@Override
public List<WarehouseFacility> warehouses(WarehouseContext ctx) {
EdayunWarehouseDtos.ListPermittedRequest body =
EdayunWarehouseMapper.toListPermittedRequest();
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_WAREHOUSE_PERMITTED, bodyJson,
"warehouse.directory.warehouses");
EdayunWarehouseDtos.ListWarehouseResponse parsed =
json.fromJson(resp.body(), EdayunWarehouseDtos.ListWarehouseResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.directory.warehouses");
return EdayunWarehouseMapper.toFacilities(parsed == null ? null : parsed.data);
}
/**
* 平台侧全量激活仓({@code POST /webApi/warehouse/listActive})。
*
* <p>与 {@link #warehouses} 的区别:那个只返回<b>有权限</b>的仓;这个是平台
* 全量(实测 118 条 vs 69 条),<b>含当前客户没授权的</b>——不要用它给客户选仓。</p>
*
* <p>实测:{@code warehouseOperationType=0} 尾程仓 111 条、{@code =1} 头程仓 7 条、
* 不传则两者之和 118 条(文档说必填,实际不传也通)。</p>
*/
public List<WarehouseFacility> activeWarehouses(WarehouseContext ctx,
boolean inboundWarehouse) {
EdayunWarehouseDtos.ListActiveRequest body =
EdayunWarehouseMapper.toListActiveRequest(inboundWarehouse);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_WAREHOUSE_ACTIVE, bodyJson,
"warehouse.directory.warehouses.active");
EdayunWarehouseDtos.ListWarehouseResponse parsed =
json.fromJson(resp.body(), EdayunWarehouseDtos.ListWarehouseResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.directory.warehouses.active");
return EdayunWarehouseMapper.toFacilities(parsed == null ? null : parsed.data);
}
/**
* 客户自有物流服务(承运商)清单
* ({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>返回「承运商 → 物流服务」两层。{@code warehouseId} 只认数字;
* 非数字或为空时不下发,仓方会返回所有服务商。</p>
*
* <p>真机(2026-11-16):仓 2 → 11 个承运商;不传仓 → 22 个;
* 只按国家 US → 10 个。{@code ownLogisticList} 实测是数组(文档写成对象)。</p>
*/
@Override
public List<WarehouseCarrier> carrierDirectory(WarehouseContext ctx) {
EdayunCarrierDtos.ListCarrierRequest body =
EdayunCarrierMapper.toRequest(ctx.providerWarehouseId(), null);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_CARRIERS, bodyJson,
"warehouse.directory.carriers.detail");
EdayunCarrierDtos.ListCarrierResponse parsed =
json.fromJson(resp.body(), EdayunCarrierDtos.ListCarrierResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.directory.carriers.detail");
return EdayunCarrierMapper.toCarriers(parsed == null ? null : parsed.data);
}
// ------------------------------------------------------------------ internals
/** 发业务请求(自动取 token、算签名)。 */
private HttpResponse send(WarehouseContext ctx, String path, String bodyJson, String operation) {

70
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunBolMapper.java

@ -0,0 +1,70 @@ @@ -0,0 +1,70 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunBolDtos;
import common.ecommerce.warehouse.model.BolDocument;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 易达云 BOL 映射({@code POST /webApi/fbaOrder/v1/getOrderBolList})。
*
* <p>只是字段搬运 + 时间戳转换;状态码表只有 {@code 11=已妥投} 确认,
* 其余靠 {@code statusName} 中文名兜底。</p>
*/
public final class EdayunBolMapper {
private EdayunBolMapper() {
}
/** 查询请求。 */
public static EdayunBolDtos.GetBolRequest toRequest(String orderNo) {
if (orderNo == null || orderNo.trim().isEmpty()) {
throw new IllegalArgumentException("edayun needs an orderNo to query BOL list");
}
EdayunBolDtos.GetBolRequest req = new EdayunBolDtos.GetBolRequest();
req.orderNo = orderNo.trim();
return req;
}
/** 响应 → BOL 列表;没有 BOL 时返回空列表。 */
public static List<BolDocument> toDocuments(EdayunBolDtos.GetBolResponse response) {
if (response == null || response.data == null
|| response.data.bolList == null || response.data.bolList.isEmpty()) {
return Collections.emptyList();
}
List<BolDocument> out = new ArrayList<BolDocument>(response.data.bolList.size());
for (EdayunBolDtos.Bol bol : response.data.bolList) {
if (bol != null && bol.bolCode != null && !bol.bolCode.trim().isEmpty()) {
out.add(toDocument(bol));
}
}
return out;
}
/** 一张 BOL → 统一单据。 */
static BolDocument toDocument(EdayunBolDtos.Bol bol) {
return BolDocument.builder()
.bolCode(bol.bolCode.trim())
.fileUrl(bol.bolFileUrl)
.signedFileUrl(bol.signBolFileUrl)
.podFileUrl(bol.podFileUrl)
.podUploadedAt(instantOf(bol.podFileTime))
.rawStatus(bol.status)
.statusName(bol.statusName)
.scheduledPickupDate(bol.pickupTime)
.actualPickupDate(bol.actualPickupTime)
.scheduledPickupQuantity(bol.orderPickupNum)
.actualPickupQuantity(bol.actualPickupNum)
.truckCompany(bol.truckCompany)
.trackingNo(bol.trackingNo)
.build();
}
/** 毫秒时间戳 → Instant;0 与 null 都当未给。 */
static Instant instantOf(Long millis) {
return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis);
}
}

83
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunCarrierMapper.java

@ -0,0 +1,83 @@ @@ -0,0 +1,83 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
import common.ecommerce.warehouse.model.WarehouseCarrier;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 易达云承运商映射({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>响应 {@code ownLogisticList} 文档写成对象、真机返回数组,DTO 按 List 收。</p>
*/
public final class EdayunCarrierMapper {
private EdayunCarrierMapper() {
}
/** 查询请求。 */
public static EdayunCarrierDtos.ListCarrierRequest toRequest(String providerWarehouseId,
String countryCode) {
EdayunCarrierDtos.ListCarrierRequest req = new EdayunCarrierDtos.ListCarrierRequest();
req.warehouseId = warehouseIdOf(providerWarehouseId);
req.countryCode = hasText(countryCode) ? countryCode.trim() : null;
return req;
}
/** 响应 → 统一模型;{@code carrierId} 缺失的行跳过(模型要求非空)。 */
public static List<WarehouseCarrier> toCarriers(
List<EdayunCarrierDtos.Carrier> rows) {
if (rows == null || rows.isEmpty()) {
return Collections.emptyList();
}
List<WarehouseCarrier> out = new ArrayList<WarehouseCarrier>(rows.size());
for (EdayunCarrierDtos.Carrier row : rows) {
WarehouseCarrier carrier = toCarrier(row);
if (carrier != null) {
out.add(carrier);
}
}
return out;
}
static WarehouseCarrier toCarrier(EdayunCarrierDtos.Carrier row) {
if (row == null || !hasText(row.carrierId)) {
return null;
}
WarehouseCarrier.Builder b = WarehouseCarrier.builder()
.carrierId(row.carrierId.trim())
.nameEn(trimToNull(row.carrierNameEn))
.nameCn(trimToNull(row.carrierNameCn));
if (row.ownLogisticList != null) {
for (EdayunCarrierDtos.OwnLogistic l : row.ownLogisticList) {
if (l != null && hasText(l.logisticId)) {
b.logistic(new WarehouseCarrier.OwnLogistic(l.logisticId.trim(),
trimToNull(l.logisticName)));
}
}
}
return b.build();
}
/** 仓方仓 id 是数字;非数字/为空返回 null(不传 = 查所有服务商)。 */
static Long warehouseIdOf(String providerWarehouseId) {
if (!hasText(providerWarehouseId)) {
return null;
}
try {
return Long.valueOf(providerWarehouseId.trim());
} catch (NumberFormatException e) {
return null;
}
}
private static String trimToNull(String v) {
return hasText(v) ? v.trim() : null;
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
}

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

@ -0,0 +1,71 @@ @@ -0,0 +1,71 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCaseMarkDtos;
import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
import common.ecommerce.warehouse.model.WarehouseLabel;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云箱唛映射({@code POST /webApi/skuInfo/v2/printBarcode})。
*
* <p>端点名叫 printBarcode,但实际打的是<b>箱唛</b>(外箱标)——已与仓方确认。
* 响应 {@code data} 是 PDF 地址字符串,同步生成。</p>
*/
public final class EdayunCaseMarkMapper {
/** 单次最多打印的 SKU 数(文档:最大 50 个)。 */
static final int MAX_SKUS = 50;
private EdayunCaseMarkMapper() {
}
/**
* 统一命令 → 打印请求。
*
* @throws IllegalArgumentException SKU 数超限(本地先挡,省一次失败请求)
*/
public static EdayunCaseMarkDtos.PrintCaseMarkRequest toRequest(CaseMarkPrintCommand cmd) {
EdayunCaseMarkDtos.PrintCaseMarkRequest req = new EdayunCaseMarkDtos.PrintCaseMarkRequest();
req.pageSize = cmd.paperSize().code();
req.remark = cmd.remark();
// 只有 true 才下发:false 是仓方默认,不下发省得干扰它自己的默认值
req.isPrintSkuName = cmd.printSkuName() ? Boolean.TRUE : null;
req.productInfos = toItems(cmd.items());
return req;
}
private static List<EdayunCaseMarkDtos.ProductInfo> toItems(
List<CaseMarkPrintCommand.CaseMarkItem> items) {
if (items.size() > MAX_SKUS) {
throw new IllegalArgumentException(
"edayun prints at most " + MAX_SKUS + " skus at once, got " + items.size()
+ "; split into multiple calls");
}
List<EdayunCaseMarkDtos.ProductInfo> out =
new ArrayList<EdayunCaseMarkDtos.ProductInfo>(items.size());
for (CaseMarkPrintCommand.CaseMarkItem item : items) {
EdayunCaseMarkDtos.ProductInfo info = new EdayunCaseMarkDtos.ProductInfo();
info.skuCode = item.providerSku();
info.num = item.copies();
out.add(info);
}
return out;
}
/**
* 响应 → 面单对象。
*
* <p>文件地址可能为空——仓方生成失败时仍可能回 {@code code=200}。调用方应在
* 调用前确认 {@code data} 非空,适配器已做该检查。</p>
*/
public static WarehouseLabel toLabel(String fileUrl, CaseMarkPrintCommand cmd) {
return WarehouseLabel.builder()
// 仓库不返回文件 id,用 SKU 数 + 纸张尺寸拼一个可追溯的编号
.labelId("barcode-" + cmd.paperSize().name() + "-" + cmd.items().size())
.format("PDF")
.url(fileUrl)
.build();
}
}

11
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunInventoryMapper.java

@ -82,8 +82,10 @@ public final class EdayunInventoryMapper { @@ -82,8 +82,10 @@ public final class EdayunInventoryMapper {
.inventoryType(0)
.asOfUtc(asOf)
.productName(blankToNull(row.skuName))
.pendingOutbound(intOf(row.toDeliverStock))
.alertQuantity(intOf(row.safeStock))
// 这两个字段仓方会缺:真机 500 行里 430 行 safeStock 为 null。
// 统一模型的约定是「仓方未给时为 -1」,不能和真实的 0 混为一谈
.pendingOutbound(intOfUnknown(row.toDeliverStock))
.alertQuantity(intOfUnknown(row.safeStock))
.build());
}
return Page.of(out, nextCursor(response.total, currentPage, pageSize, out.size()));
@ -141,6 +143,11 @@ public final class EdayunInventoryMapper { @@ -141,6 +143,11 @@ public final class EdayunInventoryMapper {
return v == null ? 0 : v;
}
/** 可缺省的数量:null 记 -1(统一模型对「仓方未给」的约定)。 */
private static int intOfUnknown(Integer v) {
return v == null ? -1 : v;
}
private static String firstNonBlank(String a, String b) {
if (hasText(a)) {
return a.trim();

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

@ -0,0 +1,90 @@ @@ -0,0 +1,90 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.LogisticsProduct;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 易达云物流产品映射
* ({@code POST /webApi/order/listByLogisticProductHasPerm})。
*
* <p>统一模型 {@link LogisticsProduct} 只有「编码 / 名称 / 是否跨国」三个可填字段;
* 承运商类型、派单方式、增值服务选项这些只在 DTO 里。</p>
*
* <p>{@code productId = -998} 是「使用分物流规则」的哨兵值,不是真实产品——
* <b>映射时跳过</b>,否则宿主的渠道清单里会多一个查不到的产品。</p>
*/
public final class EdayunLogisticsProductMapper {
/** 「智能分物流」哨兵值。 */
static final String ID_AUTO_ROUTE = "-998";
private EdayunLogisticsProductMapper() {
}
/** 查询请求。 */
public static EdayunLogisticsProductDtos.ListProductRequest toRequest(
String providerWarehouseId, Integer applicableBusiness) {
EdayunLogisticsProductDtos.ListProductRequest req =
new EdayunLogisticsProductDtos.ListProductRequest();
req.warehouseId = warehouseIdOf(providerWarehouseId);
req.applicableBusiness = applicableBusiness;
return req;
}
/** 响应 → 统一产品清单;跳过 {@code -998} 与无效行。 */
public static List<LogisticsProduct> toProducts(
List<EdayunLogisticsProductDtos.Product> rows, String warehouseCode) {
if (rows == null || rows.isEmpty()) {
return Collections.emptyList();
}
List<LogisticsProduct> out = new ArrayList<LogisticsProduct>(rows.size());
for (EdayunLogisticsProductDtos.Product row : rows) {
LogisticsProduct product = toProduct(row, warehouseCode);
if (product != null) {
out.add(product);
}
}
return out;
}
/**
* 一个产品 → 统一模型。
*
* <p>编码用 {@code productId}(字符串化的数字),名称用 {@code productName}。
* {@code crossCountry} 易达云不回,恒 false。</p>
*/
static LogisticsProduct toProduct(EdayunLogisticsProductDtos.Product row, String warehouseCode) {
if (row == null || row.productId == null || row.productId.trim().isEmpty()) {
return null;
}
String id = row.productId.trim();
if (ID_AUTO_ROUTE.equals(id)) {
// 「使用分物流规则」不是可选的物流产品
return null;
}
return LogisticsProduct.builder()
.sourceProvider(WarehouseProvider.EDAYUN)
.warehouseCode(warehouseCode)
.logisticsProductCode(id)
.logisticsProductName(row.productName)
.crossCountry(false)
.build();
}
/** 仓方仓 id 是数字;非数字/为空返回 null(不传,仓方返回全部仓)。 */
static Long warehouseIdOf(String providerWarehouseId) {
if (providerWarehouseId == null || providerWarehouseId.trim().isEmpty()) {
return null;
}
try {
return Long.valueOf(providerWarehouseId.trim());
} catch (NumberFormatException e) {
return null;
}
}
}

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

@ -104,15 +104,37 @@ public final class EdayunOrderMapper { @@ -104,15 +104,37 @@ public final class EdayunOrderMapper {
req.carrierName = firstNonBlank(cmd.carrier(), cmd.carrierCode());
}
/** 物流增值:签收 / 保价。 */
/**
* 物流增值:签收 / 保价。
*
* <p>签收取命令级的 {@code signatureRequired};保价取<b>任意商品行</b>的
* {@code insuredAmount}——易达云的 {@code addService} 是订单级开关,
* 只要有一行保价就整单开保价。</p>
*/
private static List<String> addServicesOf(OutboundCommand cmd) {
List<String> services = new ArrayList<String>(2);
if (Boolean.TRUE.equals(cmd.signatureRequired())) {
services.add(EdayunConstants.ADD_SERVICE_SIGNATURE);
}
if (hasInsuredLine(cmd)) {
services.add(EdayunConstants.ADD_SERVICE_INSURANCE);
}
return services.isEmpty() ? null : services;
}
/** 任意商品行带保价金额即为保价单。 */
private static boolean hasInsuredLine(OutboundCommand cmd) {
if (cmd.lines() == null) {
return false;
}
for (OutboundLine line : cmd.lines()) {
if (line != null && line.insuredAmount() != null) {
return true;
}
}
return false;
}
/** 地址:注意运去哪用州二字码,易达云要州全称。 */
private static EdayunCreateOrderDtos.CreateOrderRequest.OrderAddress toAddress(ShipTo shipTo) {
EdayunCreateOrderDtos.CreateOrderRequest.OrderAddress addr =

175
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java

@ -0,0 +1,175 @@ @@ -0,0 +1,175 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.edayun.enums.EdayunRmaStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseReturn;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云退货单详情映射({@code POST /webApi/rma/info/v1/getOrderDetail})。
*
* <p>响应七块,统一模型只承载前面几块:单头、明细行、检验 / 上架数量。
* 退货人地址、预报包裹尺寸、包裹状态这些只在 DTO 里——标准模型没有对应字段。</p>
*
* <p><b>明细行取 {@code checkList} 优先,回落 {@code skuList}</b>:
* {@code skuList} 是预报(买家要退什么),{@code checkList} 是仓实际收到的
* (含检验数量与异常原因)。对账要用实际收到的,没有检验记录才退回预报。</p>
*/
public final class EdayunReturnDetailMapper {
private EdayunReturnDetailMapper() {
}
/** 查询请求。 */
public static EdayunReturnDetailDtos.GetReturnRequest toRequest(String rmaCode) {
if (rmaCode == null || rmaCode.trim().isEmpty()) {
throw new IllegalArgumentException("edayun needs a rmaCode to query the return detail");
}
EdayunReturnDetailDtos.GetReturnRequest req =
new EdayunReturnDetailDtos.GetReturnRequest();
req.rmaCode = rmaCode.trim();
return req;
}
/** 详情 → 统一退货单;没有请求单号可兜底时用响应里的 RMA 号。 */
public static WarehouseReturn toReturn(EdayunReturnDetailDtos.ReturnDetail detail,
String warehouseCode) {
return toReturn(detail, warehouseCode, null);
}
/**
* 详情 → 统一退货单。
*
* @param warehouseCode 回退用的 OMS 仓编码(响应只有仓名与数字 id)
* @param requestedRmaCode 请求时用的退货单号;详情为空时用它兜底,
* 保证 {@code returnRequestNo} 不为空
*/
public static WarehouseReturn toReturn(EdayunReturnDetailDtos.ReturnDetail detail,
String warehouseCode, String requestedRmaCode) {
EdayunReturnDetailDtos.BasicInfo basic = detail == null ? null : detail.basicInfo;
WarehouseReturn.Builder builder = WarehouseReturn.builder()
// 没有预报单号时用 RMA 号兜底,returnRequestNo 不能为空
.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))
.orderRef(basic == null ? null : basic.relationNo)
.type(basic == null ? null : basic.returnTypeName)
.status(EdayunRmaStatus.toCore(
basic == null ? null : basic.status,
basic == null ? null : basic.statusName))
// rawStatus 保留中文名:码表没给,码值单独进 type 之外没地方放
.rawStatus(basic == null ? null
: firstNonBlank(basic.statusName, basic.status == null ? null
: String.valueOf(basic.status)))
.createdAt(basic == null ? null : instantOf(basic.createTime))
.sourceProvider(WarehouseProvider.EDAYUN);
builder.lines(toLines(detail));
return builder.build();
}
/**
* 明细行:检验结果优先,没有检验记录时退回预报 SKU。
*
* <p>两边的字段名不同({@code skuNum} 在 skuList 是 string、在 checkList 是 number),
* 分开映射,不要合并成一个循环。</p>
*/
static List<WarehouseReturn.ReturnLine> toLines(EdayunReturnDetailDtos.ReturnDetail detail) {
List<WarehouseReturn.ReturnLine> out = new ArrayList<WarehouseReturn.ReturnLine>();
if (detail == null) {
return out;
}
if (detail.checkList != null && !detail.checkList.isEmpty()) {
for (EdayunReturnDetailDtos.CheckLine line : detail.checkList) {
if (line == null) {
continue;
}
WarehouseReturn.ReturnLine.Builder rb = WarehouseReturn.ReturnLine.builder()
.providerSku(trimToNull(line.skuCode))
.quantity(line.skuNum == null ? 0 : line.skuNum)
.suggestedDisposition(line.commandName)
.remark(joinNonBlank(line.exceptionReasonName, line.remark));
addPictures(rb, line.picUrls);
out.add(rb.build());
}
return out;
}
if (detail.skuList != null) {
for (EdayunReturnDetailDtos.SkuLine line : detail.skuList) {
if (line == null) {
continue;
}
WarehouseReturn.ReturnLine.Builder rb = WarehouseReturn.ReturnLine.builder()
.providerSku(trimToNull(line.skuCode))
.quantity(line.skuNum == null ? 0 : line.skuNum)
.suggestedDisposition(line.commandName)
.newSku(trimToNull(line.shelveSkuCode))
.remark(trimToNull(line.exceptionReasonName));
addPictures(rb, line.picUrls);
out.add(rb.build());
}
}
return out;
}
private static void addPictures(WarehouseReturn.ReturnLine.Builder builder,
List<String> urls) {
if (urls == null) {
return;
}
for (String raw : urls) {
for (String url : splitUrls(raw)) {
builder.pictureUrl(url);
}
}
}
/** 毫秒时间戳 → Instant;0 与 null 都当未给。 */
static Instant instantOf(Long millis) {
return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis);
}
/** 图片地址可能是逗号拼接的多个 URL。 */
static List<String> splitUrls(String raw) {
List<String> out = new ArrayList<String>();
if (raw == null || raw.trim().isEmpty()) {
return out;
}
for (String part : raw.split(",")) {
String v = part.trim();
if (!v.isEmpty()) {
out.add(v);
}
}
return out;
}
private static String joinNonBlank(String a, String b) {
String first = trimToNull(a);
String second = trimToNull(b);
if (first == null) {
return second;
}
return second == null ? first : first + " " + second;
}
private static String trimToNull(String v) {
return v == null || v.trim().isEmpty() ? null : v.trim();
}
private static String firstNonBlank(String... values) {
for (String v : values) {
String t = trimToNull(v);
if (t != null) {
return t;
}
}
return null;
}
}

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

@ -0,0 +1,143 @@ @@ -0,0 +1,143 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
import common.ecommerce.warehouse.enums.ReturnDealMethod;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云退货单映射({@code POST /webApi/rma/info/v1/saveAndPublish})。
*
* <p>统一模型只能表达「自行退回」这一种退货方式({@link ReturnCommand} 强制要求
* 退货运单号),所以 {@code returnType} 固定 2。未妥投退回 / 返邮退回 / FBA 退回
* 需要退货人地址或亚马逊单号,标准模型没有对应字段——见 docs-warehouse/edayun/TODO.md。</p>
*
* <p><b>响应 {@code data} 就是退货单号</b>(如 {@code RMA2411053149}),
* 与运去哪不同,这里能直接拿到仓侧单号。</p>
*/
public final class EdayunReturnMapper {
/**
* 退货方式:自行退回。
*
* <p>0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。统一模型有退货运单号,
* 正好对应「买家自己寄回」。</p>
*/
static final int RETURN_TYPE_SELF_SHIP = 2;
/** 处理指令:上架。 */
static final int COMMAND_PUT_AWAY = 1;
/** 处理指令:销毁。 */
static final int COMMAND_DESTROY = 2;
private EdayunReturnMapper() {
}
/**
* 统一命令 → 创建退货单请求。
*
* @param providerWarehouseId 仓方仓 id;数字进 {@code warehouseId},
* 非数字进 {@code warehouseCode}
*/
public static EdayunReturnDtos.SaveReturnRequest toRequest(ReturnCommand cmd,
String providerWarehouseId) {
EdayunReturnDtos.SaveReturnRequest req = new EdayunReturnDtos.SaveReturnRequest();
req.returnType = RETURN_TYPE_SELF_SHIP;
// 关联单号:仓方按它找原出库单,优先用销售订单号
req.relationNo = firstNonBlank(cmd.saleOrderNo(), cmd.returnRequestNo());
req.carrierName = cmd.carrierCode();
req.trackingNo = cmd.returnTrackingNo();
req.customerRemark = cmd.remark();
applyWarehouse(req, providerWarehouseId, cmd.warehouseId());
req.skus = toSkus(cmd.lines());
return req;
}
/**
* 仓:{@code warehouseId} 数字优先,否则 {@code warehouseCode}。
*
* <p>命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。</p>
*/
private static void applyWarehouse(EdayunReturnDtos.SaveReturnRequest req,
String providerWarehouseId, String cmdWarehouseId) {
String raw = firstNonBlank(cmdWarehouseId, providerWarehouseId);
if (raw == null) {
// 两者都不给时仓方会用关联单号的仓库,允许为空
return;
}
Long id = numericOrNull(raw);
if (id != null) {
req.warehouseId = id;
} else {
req.warehouseCode = raw;
}
}
private static List<EdayunReturnDtos.SkuItem> toSkus(
List<ReturnCommand.ReturnCommandLine> lines) {
List<EdayunReturnDtos.SkuItem> out =
new ArrayList<EdayunReturnDtos.SkuItem>(lines.size());
for (ReturnCommand.ReturnCommandLine line : lines) {
EdayunReturnDtos.SkuItem item = new EdayunReturnDtos.SkuItem();
item.skuCode = line.providerSku();
item.skuNum = line.quantity();
item.command = commandOf(line.dealMethod());
out.add(item);
}
return out;
}
/**
* 统一处理方式 → 易达云处理指令。
*
* <p><b>只有「销毁」能确定</b>({@code 2})。其余三种统一取值在易达云都归「上架」——
* 客户自提 / 拍照确认 / 仓库确认都要先入库再处理,所以下发上架。
* 易达云的完整码表未拿到,见 TODO。</p>
*/
static Integer commandOf(ReturnDealMethod method) {
if (method == null) {
return null;
}
return method == ReturnDealMethod.DESTROY ? COMMAND_DESTROY : COMMAND_PUT_AWAY;
}
/**
* 创建成功 → 统一退货单。
*
* <p>仓侧单号直接来自响应 {@code data};接口不回状态,所以 {@link ReturnStatus#UNKNOWN}。</p>
*/
public static WarehouseReturn toCreated(ReturnCommand cmd, String providerReturnNo,
String warehouseCode) {
return WarehouseReturn.builder()
.returnRequestNo(cmd.returnRequestNo())
.providerReturnId(providerReturnNo)
.warehouseCode(warehouseCode)
.orderRef(cmd.saleOrderNo())
.status(ReturnStatus.UNKNOWN)
.sourceProvider(WarehouseProvider.EDAYUN)
.build();
}
private static Long numericOrNull(String v) {
try {
return Long.valueOf(v.trim());
} catch (NumberFormatException e) {
return null;
}
}
private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) {
return a.trim();
}
return b != null && !b.trim().isEmpty() ? b.trim() : null;
}
}

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

@ -0,0 +1,249 @@ @@ -0,0 +1,249 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
import common.ecommerce.edayun.enums.EdayunRmaStatus;
import common.ecommerce.warehouse.enums.ReturnQueryNoType;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.shared.support.Page;
import java.time.Instant;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云退货单列表映射
* ({@code POST /webApi/rma/info/v1/selectRmaInfoList})。
*
* <p>与详情接口的区别:列表只回单头,没有明细行、没有退货人地址。
* 需要明细要走 {@code getOrderDetail}。</p>
*
* <p>时间参数是<b>字符串</b> {@code yyyy-MM-dd HH:mm:ss},且按仓方时区解释
* ({@code WarehouseContext.zone()}),不是毫秒时间戳。</p>
*/
public final class EdayunRmaListMapper {
/** 单页上限。 */
static final int MAX_PAGE_SIZE = 200;
private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private EdayunRmaListMapper() {
}
/**
* 统一查询条件 → 列表请求。
*
* @param providerWarehouseId 仓方数字仓 id;数字进 {@code warehouseId}
* @param zone 解释时间窗的时区(仓方时区)
* @param pageNum 页码,从 1 开始
*/
public static EdayunRmaListDtos.SelectRmaListRequest toRequest(ReturnQuery query,
String providerWarehouseId,
ZoneId zone, int pageNum) {
EdayunRmaListDtos.SelectRmaListRequest req = new EdayunRmaListDtos.SelectRmaListRequest();
req.pageNum = pageNum;
req.pageSize = pageSize(query.pageSize());
if (query.hasCreatedRange()) {
ZoneId z = zone == null ? java.time.ZoneOffset.UTC : zone;
req.createTimeStart = TIME.format(query.createdAfter().atZone(z));
req.createTimeEnd = TIME.format(query.createdBefore().atZone(z));
}
if (hasText(query.orderNo())) {
// orderNos 必须配合 orderNoSearchType;不传类型时默认按退货单号查
req.orderNos = query.orderNo().trim();
req.orderNoSearchType = orderNoSearchTypeOf(query.orderNoType());
}
if (hasText(query.trackingNo())) {
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();
}
if (hasText(query.providerSku())) {
req.skuCode = query.providerSku().trim();
}
// 接口只支持单个状态值,多状态由调用方拆成多次查询
if (query.statuses().size() > 1) {
throw new IllegalArgumentException(
"edayun return list accepts at most one status, got " + query.statuses().size()
+ "; split into multiple queries");
}
if (query.statuses().size() == 1) {
req.status = statusOf(query.statuses().get(0));
}
return req;
}
/**
* 单号类型 → 易达云 {@code orderNoSearchType}。
*
* <p>null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。</p>
*
* @throws IllegalArgumentException 不支持的类型
*/
static Integer orderNoSearchTypeOf(ReturnQueryNoType type) {
if (type == null) {
return 1;
}
switch (type) {
case PROVIDER_RETURN_NO:
return 1;
case OUTBOUND_ORDER_NO:
return 2;
case PLATFORM_ORDER_NO:
return 3;
default:
throw new IllegalArgumentException(
"edayun return list does not support orderNoType: " + type);
}
}
/**
* 统一状态 → 易达云 {@code status}。
*
* <p>码表来自文档原文:{@code 0 待发布 / 1 待仓库签收 / 2 搁置中 / 3 仓库签收 /
* 4 处理中-仓库处理 / 5 已处理 / 6 处理中-等待指令 / 7 物流签收 / -1 已取消}。</p>
*
* <p>统一枚举里没有「搁置中」「等待指令」这类细分,所以查询时<b>只能按大类取一个代表值</b>;
* 认不出的返回 null(不过滤),由调用方承担后果——见 TODO。</p>
*/
static Integer statusOf(ReturnStatus status) {
if (status == null) {
return null;
}
switch (status) {
case DRAFT:
return 0;
case PENDING_REVIEW:
// 仓方没有「待审核」,最接近的是「待发布」
return 0;
case RETURNING:
// 退货中:还没到仓,取「待仓库签收」
return 1;
case PENDING_RECEIPT:
return 1;
case COMPLETED:
// 已处理(含已上架)
return 5;
case CLOSED:
return -1;
default:
return null;
}
}
/** 一行 → 统一退货单(只有单头,没有明细)。 */
public static WarehouseReturn toReturn(EdayunRmaListDtos.RmaRow row, String fallbackWarehouseCode) {
if (row == null) {
return null;
}
return WarehouseReturn.builder()
// 列表没有来源单号字段,用 RMA 号兜底;orderRef 用平台 / 出库单号
.returnRequestNo(firstNonBlank(row.rmaCode, row.ordOrderCode))
.providerReturnId(row.rmaCode)
// 文档响应示例没有 warehouseCode,但真机会返回,优先用它
.warehouseCode(firstNonBlank(row.warehouseCode, row.warehouseName,
fallbackWarehouseCode))
.orderRef(firstNonBlank(row.platformOrderCode, row.ordOrderCode))
.type(row.returnTypeName)
.status(EdayunRmaStatus.toCore(row.status, row.statusName))
.rawStatus(firstNonBlank(row.statusName,
row.status == null ? null : String.valueOf(row.status)))
// 列表里签收时间比创建时间更能反映「退货进度」,但统一模型只留创建时间
.createdAt(instantOf(row.createTime))
.sourceProvider(WarehouseProvider.EDAYUN)
.build();
}
/** 响应 → 分页。 */
public static Page<WarehouseReturn> toPage(EdayunRmaListDtos.SelectRmaListResponse response,
String fallbackWarehouseCode,
int currentPage, int pageSize) {
if (response == null || response.rows == null || response.rows.isEmpty()) {
return Page.empty();
}
List<WarehouseReturn> out = new ArrayList<WarehouseReturn>(response.rows.size());
for (EdayunRmaListDtos.RmaRow row : response.rows) {
WarehouseReturn ret = toReturn(row, fallbackWarehouseCode);
if (ret != null) {
out.add(ret);
}
}
return Page.of(out, nextCursor(response.total, currentPage, pageSize, out.size()));
}
/**
* 有下一页时返回下一页页码。
*
* <p>文档写明 {@code total} 是总数据量(行数),优先用它判断;
* 缺失时退回「本页是否满页」。</p>
*/
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;
}
/** 游标是字符串化的页码。 */
static int pageNumber(String cursor) {
if (!hasText(cursor)) {
return 1;
}
try {
int v = Integer.parseInt(cursor.trim());
return v > 0 ? v : 1;
} catch (NumberFormatException e) {
return 1;
}
}
/** 每页条数:默认 100,上限 200。 */
static int pageSize(int requested) {
if (requested <= 0) {
return 100;
}
return Math.min(requested, MAX_PAGE_SIZE);
}
/** 仓方仓 id 是数字;非数字返回 null(退回用仓编码)。 */
static Long warehouseIdOf(String providerWarehouseId) {
if (!hasText(providerWarehouseId)) {
return null;
}
try {
return Long.valueOf(providerWarehouseId.trim());
} catch (NumberFormatException e) {
return null;
}
}
private static Instant instantOf(Long millis) {
return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis);
}
private static String firstNonBlank(String... values) {
for (String v : values) {
if (hasText(v)) {
return v.trim();
}
}
return null;
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
}

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

@ -0,0 +1,127 @@ @@ -0,0 +1,127 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunSkuLabelDtos;
import common.ecommerce.edayun.enums.EdayunSkuLabelPaper;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.WarehouseLabel;
import java.util.List;
/**
* 易达云 SKU 标映射({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
*
* <p><b>统一模型只能表达「整单打印」</b>:{@code BoxLabelCommand} 没有「选哪些箱」
* 的字段,所以选箱条件(系统箱号列表 / SKU / 箱序号区间 / 客户箱号区间)
* 一律不下发——仓方默认整单。要打部分箱请走 {@code printSkuLabel} 的扩展重载。</p>
*
* <p>响应 {@code data} 是 PDF 地址,同步生成;而统一模型的
* {@code LabelPrintTask} 是异步任务语义(只有任务号)。所以这里返回
* {@link WarehouseLabel},把地址放在 {@code url()}。</p>
*/
public final class EdayunSkuLabelMapper {
/** 是否需要 Made in China:是。 */
static final int MADE_IN_CHINA_YES = 1;
/** 是否需要 Made in China:否。 */
static final int MADE_IN_CHINA_NO = 0;
private EdayunSkuLabelMapper() {
}
/**
* 统一命令 → SKU 标请求(整单打印)。
*
* @throws IllegalArgumentException 尺寸不在易达云支持的三档内
*/
public static EdayunSkuLabelDtos.PrintSkuLabelRequest toRequest(BoxLabelCommand cmd) {
EdayunSkuLabelDtos.PrintSkuLabelRequest req =
new EdayunSkuLabelDtos.PrintSkuLabelRequest();
// 统一模型里 providerInboundNo 就是仓侧 REV 单号
req.entryCode = cmd.providerInboundNo();
EdayunSkuLabelPaper paper = EdayunSkuLabelPaper.of(cmd.sizeType());
req.pageSize = paper.code();
// 统一模型没有「原产地标注」,默认不打 Made in China——猜「打」会让每箱多一行
req.madeInChina = MADE_IN_CHINA_NO;
// 分隔符是易达云特有的分页提示,统一模型没有对应语义,默认关
req.separation = Boolean.FALSE;
req.twoPrint = cmd.twoCopies() ? 1 : 0;
return req;
}
/**
* 带选箱条件的请求(易达云专有能力)。
*
* <p>选箱条件四选一,全部为空时仓方会报错,这里本地先拒。</p>
*/
public static EdayunSkuLabelDtos.PrintSkuLabelRequest toRequest(BoxLabelCommand cmd,
CaseSelection selection) {
EdayunSkuLabelDtos.PrintSkuLabelRequest req = toRequest(cmd);
if (selection == null || selection.isEmpty()) {
throw new IllegalArgumentException(
"edayun sku label needs at least one box selector"
+ " (case codes / sku / serial range / seller case range)");
}
req.caseCodeList = selection.caseCodes;
req.skuCode = selection.skuCode;
req.startCaseSerialNo = selection.startCaseSerialNo;
req.endCaseSerialNo = selection.endCaseSerialNo;
req.startSellerCaseNo = selection.startSellerCaseNo;
req.endSellerCaseNo = selection.endSellerCaseNo;
return req;
}
/** 响应 → 面单对象;地址为空视为失败。 */
public static WarehouseLabel toLabel(String fileUrl) {
return WarehouseLabel.builder()
// 仓方不回文件 id
.labelId("case-mark")
.format("PDF")
.url(fileUrl)
.build();
}
/** 选箱条件:四个维度都是「有就用」。 */
public static final class CaseSelection {
private List<String> caseCodes;
private String skuCode;
private String startCaseSerialNo;
private String endCaseSerialNo;
private String startSellerCaseNo;
private String endSellerCaseNo;
public CaseSelection caseCodes(List<String> v) {
this.caseCodes = v;
return this;
}
public CaseSelection skuCode(String v) {
this.skuCode = v;
return this;
}
public CaseSelection caseSerialRange(String start, String end) {
this.startCaseSerialNo = start;
this.endCaseSerialNo = end;
return this;
}
public CaseSelection sellerCaseRange(String start, String end) {
this.startSellerCaseNo = start;
this.endSellerCaseNo = end;
return this;
}
boolean isEmpty() {
return (caseCodes == null || caseCodes.isEmpty())
&& isBlank(skuCode)
&& isBlank(startCaseSerialNo) && isBlank(endCaseSerialNo)
&& isBlank(startSellerCaseNo) && isBlank(endSellerCaseNo);
}
private static boolean isBlank(String v) {
return v == null || v.trim().isEmpty();
}
}
}

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

@ -0,0 +1,177 @@ @@ -0,0 +1,177 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunTrackDtos;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云物流轨迹映射({@code POST /webApi/track/getTrackInfoList})。
*
* <p><b>请求体是纯字符串数组</b>,没有包装对象。文档示例
* {@code [{"": ["aa","bb"]}]} 是自动生成的占位,真机只有纯数组能通。</p>
*
* <p>时间字段口径混杂:{@code onlineTime} / {@code deliveredTime} 是
* <b>带时区偏移的字符串</b>,而节点时间 {@code recentDescribeTime} 是毫秒。
* 字符串时间要按响应里的 {@code timeZone}(如 {@code GMT-04:00})解释。</p>
*/
public final class EdayunTrackMapper {
private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private EdayunTrackMapper() {
}
/** 跟踪号 → 请求体(纯字符串数组)。 */
public static List<String> toRequest(List<String> trackingNumbers) {
if (trackingNumbers == null || trackingNumbers.isEmpty()) {
throw new IllegalArgumentException(
"edayun track query needs at least one tracking number");
}
List<String> out = new ArrayList<String>(trackingNumbers.size());
for (String tn : trackingNumbers) {
if (tn != null && !tn.trim().isEmpty()) {
out.add(tn.trim());
}
}
if (out.isEmpty()) {
throw new IllegalArgumentException(
"edayun track query needs at least one non-blank tracking number");
}
return out;
}
/**
* 一条轨迹 → {@link TrackingInfo}。
*
* <p>文档说「主要关注上网时间跟妥投时间」,所以这两个单独落到
* {@link TrackingInfo#firstOnlineAt()} / {@link TrackingInfo#deliveredAt()},
* 而不是混在节点里。字符串时间按响应里的 {@code timeZone} 解释,解析失败留 null。</p>
*/
public static TrackingInfo toTrackingInfo(EdayunTrackDtos.Track track) {
if (track == null || track.trackingNo == null || track.trackingNo.trim().isEmpty()) {
return null;
}
ZoneId zone = zoneOf(track.timeZone);
TrackingInfo.Builder builder = TrackingInfo.builder()
.trackingNumber(track.trackingNo.trim())
.carrier(track.carrierName)
// 仓方状态是数字码,码表没给;保留原值而不是猜成某个字符串
.status(track.status == null ? null : String.valueOf(track.status))
.signedBy(track.receiver)
.firstOnlineAt(parseLocal(track.onlineTime, zone))
.deliveredAt(parseLocal(track.deliveredTime, zone));
if (track.trackDetaillVoList != null) {
for (EdayunTrackDtos.TrackDetail detail : track.trackDetaillVoList) {
if (detail == null) {
continue;
}
builder.event(TrackEvent.builder()
.trackingNumber(track.trackingNo.trim())
.carrier(track.carrierName)
.status(detail.eventStatus != null ? detail.eventStatus
: (detail.status == null ? null : String.valueOf(detail.status)))
.description(detail.recentDescribe)
.occurredAt(instantOf(detail.recentDescribeTime))
.build());
}
}
return builder.build();
}
/**
* 节点列表:{@code track} 只要节点,不含上网 / 妥投这两条汇总时间。
*
* <p>与 {@link #toTrackingInfo} 分开,是因为统一模型把节点列表和运单汇总
* 视为两个层次;上网 / 妥投是汇总信息,不塞进节点里。</p>
*/
public static List<TrackEvent> toTrackEvents(EdayunTrackDtos.Track track) {
if (track == null || track.trackDetaillVoList == null) {
return java.util.Collections.emptyList();
}
List<TrackEvent> out = new ArrayList<TrackEvent>(track.trackDetaillVoList.size());
for (EdayunTrackDtos.TrackDetail detail : track.trackDetaillVoList) {
if (detail == null) {
continue;
}
out.add(TrackEvent.builder()
.trackingNumber(track.trackingNo)
.carrier(track.carrierName)
.status(detail.eventStatus != null ? detail.eventStatus
: (detail.status == null ? null : String.valueOf(detail.status)))
.description(detail.recentDescribe)
.occurredAt(instantOf(detail.recentDescribeTime))
.build());
}
return out;
}
/**
* 从响应里按跟踪号取一条轨迹。
*
* <p>接口一次可查多个跟踪号;{@code track} / {@code trackShipment} 都是单个口径,
* 所以按跟踪号精确匹配。找不到返回 null,不抛异常——运单可能刚生成还没轨迹。</p>
*/
public static EdayunTrackDtos.Track find(EdayunTrackDtos.GetTrackResponse response,
String trackingNumber) {
if (response == null || response.data == null || trackingNumber == null) {
return null;
}
String target = trackingNumber.trim();
for (EdayunTrackDtos.Track track : response.data) {
if (track != null && track.trackingNo != null
&& target.equalsIgnoreCase(track.trackingNo.trim())) {
return track;
}
}
return null;
}
/**
* 解析时区偏移,如 {@code GMT-04:00} / {@code GMT+08:00}。
*
* <p>认不出返回 UTC——不猜成仓所在时区(那是另一个概念)。</p>
*/
static ZoneId zoneOf(String gmtOffset) {
if (gmtOffset == null || gmtOffset.trim().isEmpty()) {
return ZoneOffset.UTC;
}
String v = gmtOffset.trim().toUpperCase(java.util.Locale.ROOT);
if (v.startsWith("GMT")) {
v = v.substring(3);
} else if (v.startsWith("UTC")) {
v = v.substring(3);
}
try {
return ZoneOffset.of(v.isEmpty() ? "Z" : v);
} catch (java.time.DateTimeException e) {
return ZoneOffset.UTC;
}
}
/** 字符串时间({@code yyyy-MM-dd HH:mm:ss})→ Instant;解析失败返回 null。 */
static Instant parseLocal(String value, ZoneId zone) {
if (value == null || value.trim().isEmpty()) {
return null;
}
try {
return LocalDateTime.parse(value.trim(), TIME)
.atZone(zone == null ? ZoneOffset.UTC : zone).toInstant();
} catch (DateTimeParseException e) {
return null;
}
}
private static Instant instantOf(Long millis) {
return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis);
}
}

112
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunWarehouseMapper.java

@ -0,0 +1,112 @@ @@ -0,0 +1,112 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunWarehouseDtos;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseFacility;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 易达云仓库清单映射
* ({@code warehouse/listActive} 与 {@code warehouse/listWarehouseHasPerm})。
*
* <p><b>两个接口用途不同</b>:</p>
* <ul>
* <li>{@code listWarehouseHasPerm} = 当前客户<b>有权限</b>的仓(69 条)——下单用这个</li>
* <li>{@code listActive} = 平台侧<b>全量</b>激活仓(118 条)——含未授权的仓</li>
* </ul>
*
* <p>{@code -999} 是「智能分仓」的哨兵值(名称 {@code divideWarehouse}),
* 不是真实仓,映射时跳过。</p>
*/
public final class EdayunWarehouseMapper {
/** 「智能分仓」哨兵值。 */
static final String ID_SMART_SPLIT = "-999";
/** 仓库类型:头程仓。 */
static final int OPERATION_TYPE_INBOUND = 1;
/** 仓库类型:尾程仓。 */
static final int OPERATION_TYPE_OUTBOUND = 0;
private EdayunWarehouseMapper() {
}
/** 激活仓库请求。 */
public static EdayunWarehouseDtos.ListActiveRequest toListActiveRequest(
boolean inboundWarehouse) {
EdayunWarehouseDtos.ListActiveRequest req =
new EdayunWarehouseDtos.ListActiveRequest();
req.warehouseOperationType = inboundWarehouse
? OPERATION_TYPE_INBOUND : OPERATION_TYPE_OUTBOUND;
return req;
}
/** 权限内仓库请求(接口无参数)。 */
public static EdayunWarehouseDtos.ListPermittedRequest toListPermittedRequest() {
return new EdayunWarehouseDtos.ListPermittedRequest();
}
/** 响应 → 统一模型;跳过 {@code -999} 与缺 code 的行。 */
public static List<WarehouseFacility> toFacilities(
List<EdayunWarehouseDtos.WarehouseRow> rows) {
if (rows == null || rows.isEmpty()) {
return Collections.emptyList();
}
List<WarehouseFacility> out = new ArrayList<WarehouseFacility>(rows.size());
for (EdayunWarehouseDtos.WarehouseRow row : rows) {
WarehouseFacility facility = toFacility(row);
if (facility != null) {
out.add(facility);
}
}
return out;
}
/**
* 一行 → 统一仓资料。
*
* <p>统一模型的口径:{@code warehouseCode} 用<b>仓编码</b>(如 {@code USLA}),
* 不是数字 id——那个进 {@code providerWarehouseId}。</p>
*/
static WarehouseFacility toFacility(EdayunWarehouseDtos.WarehouseRow row) {
if (row == null || !hasText(row.warehouseCode)) {
return null;
}
if (ID_SMART_SPLIT.equals(trim(row.warehouseId))) {
return null;
}
return WarehouseFacility.builder()
.sourceProvider(WarehouseProvider.EDAYUN)
.providerWarehouseId(trim(row.warehouseId))
.warehouseCode(row.warehouseCode.trim())
.name(firstNonBlank(row.warehouseName, row.warehouseNameEn))
.country(row.countryCode)
.province(row.provinceCode)
.city(row.cityName)
.state(row.provinceCode)
// 仓方只给单行地址,落在 address1
.address1(row.address)
.postcode(row.zipCode)
.contactName(row.warehouseManagerName)
.mobilePhone(row.warehouseManagerTel)
.build();
}
private static String firstNonBlank(String a, String b) {
if (hasText(a)) {
return a.trim();
}
return hasText(b) ? b.trim() : null;
}
private static String trim(String v) {
return v == null ? null : v.trim();
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
}

82
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunBolDtos.java

@ -0,0 +1,82 @@ @@ -0,0 +1,82 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:查询 BOL 信息
* ({@code POST /webApi/fbaOrder/v1/getOrderBolList})。
*
* <p>一个文件对应一个接口,只放该请求 / 响应与内嵌子结构。</p>
*
* <p>店铺订单 / 平台仓订单共用本接口,{@code orderNo} 传 EDA 的平台仓订单号。</p>
*/
public final class EdayunBolDtos {
private EdayunBolDtos() {
}
/** 查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetBolRequest {
/** EDA 的平台仓订单号,如 {@code FBA473182144}。必填。 */
public String orderNo;
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetBolResponse {
public Integer code;
public String msg;
public BolData data;
public String traceId;
}
/** BOL 数据。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BolData {
/** BOL 总数。 */
public Integer totalNum;
/** 未提货数。 */
public Integer unPickupNum;
public List<Bol> bolList;
}
/** 一张 BOL。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Bol {
/** BOL 文件地址。 */
public String bolFileUrl;
/** BOL 编号。 */
public String bolCode;
/** 约定提货件数。 */
public Integer orderPickupNum;
/** 约定提货日期,如 {@code 2025-03-02}。 */
public String pickupTime;
/** 卡车公司。 */
public String truckCompany;
/** POD 上传时间(毫秒)。 */
public Long podFileTime;
/** 状态码;码表未给,见 {@code EdayunBolStatus}。 */
public Integer status;
public String statusName;
/** 实际提货件数。 */
public Integer actualPickupNum;
/** 实际提货日期。 */
public String actualPickupTime;
/** 签收后的 BOL(带签章)地址。 */
public String signBolFileUrl;
/** POD(签收凭证)地址。 */
public String podFileUrl;
/** 跟踪号;卡车单可能是 BOL 号。 */
public String trackingNo;
}
}

38
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCancelReturnDtos.java

@ -0,0 +1,38 @@ @@ -0,0 +1,38 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
/**
* 易达云报文结构:取消退货单
* ({@code POST /webApi/rma/info/v1/cancel})。
*
* <p>一个文件对应一个接口。请求只有一个 {@code rmaCode};响应 {@code data}
* 是<b>布尔值</b>({@code true} 成功),不是单号——与创建接口不同。</p>
*/
public final class EdayunCancelReturnDtos {
private EdayunCancelReturnDtos() {
}
/** 取消请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CancelReturnRequest {
/** 退货单号(易达云的 RMA 号)。必填。 */
public String rmaCode;
}
/** 取消响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CancelReturnResponse {
public Integer code;
public String msg;
/**
* 结果,{@code true} 表示取消成功。
*
* <p><b>注意</b>:仓方可能回 {@code code=200} + {@code data=false}
* (业务拒绝),所以两个都要判。</p>
*/
public Boolean data;
public String traceId;
}
}

60
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCarrierDtos.java

@ -0,0 +1,60 @@ @@ -0,0 +1,60 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:查询客户自有物流服务(承运商)
* ({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>一个文件对应一个接口。响应是「承运商 → 物流服务」两层:
* {@code carrierId / carrierNameEn / carrierNameCn} + 下属 {@code ownLogisticList}。</p>
*/
public final class EdayunCarrierDtos {
private EdayunCarrierDtos() {
}
/** 查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListCarrierRequest {
/** 仓库 id;不传则查所有服务商。 */
public Long warehouseId;
/** 国家编码,如 {@code US}。 */
public String countryCode;
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListCarrierResponse {
public Integer code;
public String msg;
public List<Carrier> data;
public String traceId;
}
/** 一个承运商。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Carrier {
/** 承运商 id。 */
public String carrierId;
/** 英文名,如 {@code FedEx}。 */
public String carrierNameEn;
/** 中文名。 */
public String carrierNameCn;
/**
* 下属物流服务。
*
* <p><b>文档写成对象,真机返回数组</b>——按 List 收,避免解析失败。</p>
*/
public List<OwnLogistic> ownLogisticList;
}
/** 承运商下的一个物流服务。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class OwnLogistic {
public String logisticId;
public String logisticName;
}
}

55
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCaseMarkDtos.java

@ -0,0 +1,55 @@ @@ -0,0 +1,55 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:打印箱唛({@code POST /webApi/skuInfo/v2/printBarcode})。
*
* <p>一个文件对应一个接口。响应 {@code data} 是<b>箱唛 PDF 地址字符串</b>,
* 同步生成,不是任务号。</p>
*
* <p><b>接口名与语义不一致</b>:端点叫 {@code printBarcode},但实际打的是
* 箱唛(外箱标)。已与仓方确认,不要被路径名误导。</p>
*/
public final class EdayunCaseMarkDtos {
private EdayunCaseMarkDtos() {
}
/** 打印请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PrintCaseMarkRequest {
/** 备注,如 {@code Made in China};≤64。 */
public String remark;
/** 是否打印 SKU 名称。 */
public Boolean isPrintSkuName;
/** 纸张尺寸:0 7×3cm / 1 10×6cm / 2 6×4cm / 3 A4。<b>必填</b>。 */
public Integer pageSize;
/** 产品信息,最大 50 个 SKU。<b>必填</b>。 */
public List<ProductInfo> productInfos;
}
/** 一个 SKU。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ProductInfo {
public String skuCode;
/** 打印份数;必须 > 0。 */
public Integer num;
}
/** 打印响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PrintCaseMarkResponse {
public Integer code;
public String msg;
/** 条码文件地址(PDF)。 */
public String data;
/** 文档标为 object,实际是字符串 {@code "null"};保留 Object 避免解析失败。 */
public Object traceId;
}
}

79
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunLogisticsProductDtos.java

@ -0,0 +1,79 @@ @@ -0,0 +1,79 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:根据仓库查询物流产品列表
* ({@code POST /webApi/order/listByLogisticProductHasPerm})。
*
* <p>一个文件对应一个接口。用于「出库单 / 退货单能选哪些物流产品」。
* 最后一条可能是 {@code productId = -998}(智能分物流),此时其余字段全是 null。</p>
*/
public final class EdayunLogisticsProductDtos {
private EdayunLogisticsProductDtos() {
}
/** 查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListProductRequest {
/** 适用业务:1 店铺订单 / 2 平台仓订单 / 3 退货单。 */
public Integer applicableBusiness;
/** 仓库 id。文档标必填,实测不传返回全部仓的产品。 */
public Long warehouseId;
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListProductResponse {
public Integer code;
public String msg;
public List<Product> data;
public String traceId;
}
/** 一个物流产品。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Product {
/** 物流产品 id(字符串化的数字)。 */
public String productId;
public String productName;
/** 承运商类型,码表未给。 */
public Integer carrierType;
/** 派送类型,码表未给。 */
public Integer deliveryType;
/** 服务属性列表,码表未给。 */
public List<Integer> serviceAttribute;
/** 是否校验跟踪号。 */
public Boolean tackingNoCheckFlag;
/** 适用业务:1 店铺订单 / 2 平台仓订单 / 3 退货单。 */
public List<Integer> applicableBusiness;
/** 面单获取方式,码表未给(实测 0 / 1 / 2)。 */
public Integer labelGetMethod;
/** 增值服务选项(名称 + 可取值说明)。 */
public List<ValueAddedOption> valueAddedOptions;
/** 固定价格标记。 */
public Integer fixedPrice;
/** 退货是否回传提货时间标记。 */
public Integer returnPickupTimeFlage;
/** 是否对公众开放。 */
public Boolean supportPublic;
/** 客户编码列表;null 表示不限。 */
public List<String> customerCodes;
}
/** 增值服务选项。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ValueAddedOption {
public String name;
/** 取值说明,如 {@code is_signature};文档示例还写过逗号拼接的多值。 */
public String value;
}
}

223
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDetailDtos.java

@ -0,0 +1,223 @@ @@ -0,0 +1,223 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonFormat;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:获取退货单详情
* ({@code POST /webApi/rma/info/v1/getOrderDetail})。
*
* <p>一个文件对应一个接口,只放该请求 / 响应与内嵌子结构。</p>
*
* <p>响应按业务分组,七块内容:</p>
* <ul>
* <li>{@code basicInfo} —— 单头(状态、关联单号、仓库、退货方式、创建时间)</li>
* <li>{@code logisticsInfo} —— 退货人地址与返邮信息</li>
* <li>{@code shipmentParcelList} —— 预报的包裹尺寸重量</li>
* <li>{@code skuList} —— 预报的退货 SKU</li>
* <li>{@code packageList} —— 包裹 / 跟踪号及状态</li>
* <li>{@code checkList} —— 仓收货检验结果</li>
* <li>{@code shelfList} —— 实际上架结果</li>
* </ul>
*/
public final class EdayunReturnDetailDtos {
private EdayunReturnDetailDtos() {
}
/** 查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetReturnRequest {
/** 退货单号(易达云的 RMA 号)。必填。 */
public String rmaCode;
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetReturnResponse {
public Integer code;
public String msg;
public ReturnDetail data;
public String traceId;
}
/** 退货单详情。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ReturnDetail {
public BasicInfo basicInfo;
public LogisticsInfo logisticsInfo;
public List<ShipmentParcel> shipmentParcelList;
public List<SkuLine> skuList;
public List<PackageLine> packageList;
public List<CheckLine> checkList;
public List<ShelfLine> shelfList;
}
/** 单头。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BasicInfo {
/** 退货单号。 */
public String rmaCode;
/** 状态码;码表见 {@code EdayunRmaStatus}。 */
public Integer status;
/** 状态中文名。 */
public String statusName;
/** 关联单号(EDA 单号或客户单号)。 */
public String relationNo;
/** 预报品类数 / 实际品类数 / 预报商品数 / 实际商品数。 */
public Integer forecastCategoryNum;
public Integer productCategoryNum;
public Integer forecastProductNum;
public Integer productNum;
public Long warehouseId;
public String warehouseName;
/** 退货方式:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。 */
public Integer returnType;
public String returnTypeName;
/** 退货原因,字典 {@code wms_rma_return_reason}。 */
public Integer returnReason;
public String returnReasonName;
/** 创建时间(毫秒)。 */
public Long createTime;
public String carrierName;
/** 包裹状态,字典 {@code wms_rma_claim_package_status}。 */
public Integer packageStatus;
public String packageStatusName;
public String customerRemark;
}
/** 退货人 / 返邮信息。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class LogisticsInfo {
/** 是否返邮。 */
public Integer returnMailFlag;
/** 是否需要签收。 */
public Integer signatureFlag;
public Long logisticsProductId;
public String logisticsProduct;
public Integer returnLabelNum;
public String returnUserName;
public String returnCountryCode;
public String returnCountryName;
public String returnProvinceCode;
public String returnProvinceName;
public String returnCity;
public String returnAddress;
public String returnAddress2;
public String returnHouseNum;
public String returnZipCode;
public String returnPhone;
/** 返邮说明。 */
public String returnMailStr;
}
/** 预报包裹。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ShipmentParcel {
public String rmaParcelId;
public Double length;
public Double width;
public Double height;
/** 重量;单位文档未标。 */
public Double weight;
}
/** 预报退货 SKU。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SkuLine {
public String tempBarcode;
public String skuCode;
public String barcode;
public String extraBarcode;
/** 处理指令:1 上架 / 2 销毁(码表未给全)。 */
public Integer command;
public String commandName;
/**
* 增值服务。
*
* <p><b>文档标 number,真机返回字符串 {@code "0"}</b>——按 String 收,避免解析失败。</p>
*/
public String valueAddedServices;
/** 上架后的 SKU。 */
public String shelveSkuCode;
public String shelveSkuBarcode;
/** 数量;<b>文档标 string,真机返回 number</b>,用 Integer 两种都能收。 */
public Integer skuNum;
public String exceptionReason;
public String exceptionReasonName;
public Integer catalog;
public String catalogName;
/**
* 图片地址。
*
* <p>文档标 string(逗号拼接),真机返回 JSON 数组或 null。
* 用 {@code ACCEPT_SINGLE_VALUE_AS_ARRAY} 同时兼容两种。</p>
*/
@JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
public List<String> picUrls;
}
/** 包裹 / 跟踪号。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PackageLine {
public String trackingNo;
public Integer status;
public String statusName;
}
/** 收货检验结果。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CheckLine {
public String skuCode;
public String barcode;
public String tempBarcode;
public Integer skuNum;
public Double length;
public Double width;
public Double height;
public Double weight;
public Integer command;
public String commandName;
public Integer valueAddedService;
public Integer exceptionReason;
public String exceptionReasonName;
public String remark;
/**
* 图片地址。
*
* <p><b>文档标 string,真机返回 JSON 数组</b>(如 {@code []})。按 List 收。</p>
*/
@JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
public List<String> picUrls;
}
/** 实际上架结果。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ShelfLine {
public String skuCode;
public String barcode;
public String extraBarcode;
public String tempBarcode;
/** 文档标 string,真机返回 number——用 Integer 收。 */
public Integer command;
public String commandName;
public String valueAddedService;
public String shelveSkuCode;
public String shelveSkuBarcode;
/** 收货数量。 */
public Integer receiptQuantity;
/** 上架数量。 */
public Integer shelfQuantity;
/** 更新时间(毫秒)。 */
public Long updateTime;
/** 序列号集合。 */
public String snCodeList;
}
}

122
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunReturnDtos.java

@ -0,0 +1,122 @@ @@ -0,0 +1,122 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:创建退货单 / 退货预报
* ({@code POST /webApi/rma/info/v1/saveAndPublish})。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。</p>
*
* <p>四种退货方式({@code returnType})的必填项各不相同:</p>
* <ul>
* <li>0 未妥投退回:{@code relationNo} 必填</li>
* <li>1 返邮退回:{@code relationNo} + 返邮标签 + 退货人姓名 / 城市 / 详细地址 / 邮编 必填;
* 物流产品不填则沿用关联单号的</li>
* <li>2 自行退回:{@code relationNo} + {@code trackingNo} 必填</li>
* <li>3 FBA 退回:{@code channelOrderNo}、退货仓库、承运商、物流信息、{@code trackingNo}、
* {@code returnLabelNum} 必填;{@code truckFlag=1}(卡车)时 {@code trackingNo} 传 BOL 号</li>
* </ul>
*
* <p>{@code warehouseId} 与 {@code warehouseCode} 传一个即可,<b>id 优先</b>。</p>
*/
public final class EdayunReturnDtos {
private EdayunReturnDtos() {
}
/** 创建退货单请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaveReturnRequest {
/** 退货方式:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。<b>必填</b>。 */
public Integer returnType;
/** 关联单号(EDA 单号或客户单号)。 */
public String relationNo;
/** 退货原因,字典 {@code wms_rma_return_reason}(0 派送失败 / 1 客户退货)。 */
public Integer returnReason;
/** 包裹状态,字典 {@code wms_rma_claim_package_status}(0 已拆箱 / 1 未拆包 / 2 未知)。 */
public Integer packageStatus;
/** 承运商。 */
public String carrierName;
/** 客户内部备注。 */
public String customerRemark;
/** 退货单 SKU 列表。<b>必填</b>。 */
public List<SkuItem> skus;
/** 物流产品 id。 */
public Long logisticsProductId;
/** 退货人国家。 */
public String returnCountryCode;
/** 退货人省 / 州:支持英文全称 / 二字码 / EDA 区域编码(California / CA / US01)。 */
public String returnProvinceCode;
public String returnEmailAddress;
public String returnUserName;
public String returnCity;
public String returnAddress;
public String returnAddress2;
public String returnHouseNum;
public String returnZipCode;
public String returnPhone;
/** 发件人区县。 */
public String district;
/** 发件人街道。 */
public String subDistrict;
/** 退货标签数。 */
public Integer returnLabelNum;
/** 提货日期。 */
public String pickUpDate;
/** 跟踪号,多个用逗号分隔;默认用关联单号的。 */
public String trackingNo;
/** 物流方式:1 卡车 / 0 快递。 */
public Integer truckFlag;
/** 亚马逊单号(FBA 退货必填)。 */
public String channelOrderNo;
/** 仓库 id,优先级高于仓库编码。 */
public Long warehouseId;
/** 仓库编码;默认用关联单号的,FBA 退货必填。 */
public String warehouseCode;
}
/** 一条退货 SKU。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SkuItem {
/** SKU 编码。 */
public String skuCode;
/**
* 处理指令:1 上架 / 2 销毁(由 EDA 字典定义)。
*
* <p>文档未给码表,统一模型的 {@code ReturnDealMethod} 与它<b>不是一套码</b>,
* 映射关系待确认——见 TODO。</p>
*/
public Integer command;
/** 增值服务,逗号分隔({@code REPACKAGE} 重新包装 / {@code RELABEL} 重新贴标 等)。 */
public String valueAddedService;
/** 上架后的 SKU(换标上架时用)。 */
public String shelveSkuCode;
/** 数量。 */
public Integer skuNum;
/** 分类编码,由仓方字典定义。 */
public Integer catalog;
/** 图片地址。 */
public String picUrls;
}
/** 创建退货单响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaveReturnResponse {
public Integer code;
public String msg;
/** 退货单号(如 {@code RMA2411053149})。 */
public String data;
public String traceId;
}
}

138
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunRmaListDtos.java

@ -0,0 +1,138 @@ @@ -0,0 +1,138 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:查询退货单列表
* ({@code POST /webApi/rma/info/v1/selectRmaInfoList})。
*
* <p>一个文件对应一个接口,只放该请求 / 响应与内嵌子结构。</p>
*
* <p>时间参数是<b>字符串</b>({@code yyyy-MM-dd HH:mm:ss}),不是毫秒时间戳——
* 与其它接口不一致,注意别按毫秒传。</p>
*/
public final class EdayunRmaListDtos {
private EdayunRmaListDtos() {
}
/** 列表查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SelectRmaListRequest {
/** 页码,从 1 开始。必填。 */
public Integer pageNum;
/** 每页条数,最大 200。必填。 */
public Integer pageSize;
/** 创建时间-开始,格式 {@code yyyy-MM-dd HH:mm:ss};缺省为近一个月。 */
public String createTimeStart;
/** 创建时间-结束,同上。 */
public String createTimeEnd;
/** 查询类型:1 退货单号 / 2 出库单号 / 3 平台订单号。配合 {@link #orderNos}。 */
public Integer orderNoSearchType;
/** 单号,多个用英文逗号分隔;配合 {@link #orderNoSearchType}。 */
public String orderNos;
/** 跟踪号,多个用英文逗号分隔。 */
public String trackingNos;
/** 仓库编码;{@link #warehouseId} 优先。 */
public String warehouseCode;
/** 仓库 id,优先级高于仓库编码。 */
public Long warehouseId;
/** 退货类型:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。 */
public Integer returnType;
/** SKU 编码。 */
public String skuCode;
/** 返邮标记:0 否 / 1 是。 */
public Integer returnMailFlag;
/** 是否上网:0 否 / 1 是。 */
public Integer onlineFlag;
/** 状态码,字典 {@code wms_rma_status}。 */
public Integer status;
/** 查询时间类型:0 创建 / 1 签收 / 2 查验 / 3 处理。 */
public Integer searchTimeType;
}
/** 列表查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SelectRmaListResponse {
/** 总行数。 */
public Long total;
public List<RmaRow> rows;
public Integer code;
public String msg;
public String traceId;
}
/** 列表里的一条退货单(只有单头,没有明细)。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class RmaRow {
/** 退货单号。 */
public String rmaCode;
/** 平台订单号。 */
public String platformOrderCode;
/** 索赔单号。 */
public String claimOrderCode;
/** 出库单号(原始发货单)。 */
public String ordOrderCode;
/** 跟踪号。 */
public String trackingNo;
/** 预报品类数 / 实际品类数 / 预报商品数 / 实际商品数。 */
public Integer forecastCategoryNum;
public Integer productCategoryNum;
public Integer forecastProductNum;
public Integer productNum;
/** 增值服务标记。 */
public Integer valueAddedService;
public String warehouseName;
/** 仓名英文。 */
public String warehouseNameEn;
/**
* 仓编码。
*
* <p><b>文档响应示例里没有</b>,但真机(2026-11-13)会返回,如 {@code USLA}。
* 优先用它,而不是仓名。</p>
*/
public String warehouseCode;
public Long warehouseId;
/** 退货类型:0 未妥投 / 1 返邮 / 2 自行退回 / 3 FBA 退回。 */
public Integer returnType;
public String returnTypeName;
/** 退货原因,字典 {@code wms_rma_return_reason}。 */
public Integer returnReason;
public String returnReasonName;
/** 状态码,字典 {@code wms_rma_status}。 */
public Integer status;
public String statusName;
/** 创建时间(毫秒)。 */
public Long createTime;
/** 创建时间(仓方时区的文本,如 {@code 2024-11-04 22:34:14})。 */
public String createTimeLocal;
/** 签收时间(毫秒)。 */
public Long signTime;
public String signTimeLocal;
/** 查验时间(毫秒)。 */
public Long checkTime;
public String checkTimeLocal;
/** 处理时间(毫秒)。 */
public Long handleTime;
public String handleTimeLocal;
/** 创建人。 */
public String createOperator;
}
}

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

@ -0,0 +1,69 @@ @@ -0,0 +1,69 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:打印 SKU 标
* ({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。
*
* <p>一个文件对应一个接口。响应 {@code data} 是<b>PDF 地址字符串</b>,同步生成。</p>
*
* <p><b>接口名与语义不一致</b>:端点叫 {@code newPrintCaseMark}(箱唛),
* 但实际打的是 SKU 标。已与仓方确认,不要被路径名误导。</p>
*
* <p><b>选箱条件四选一</b>(文档原文:箱序号 / 客户箱号 / sku 编码 / 系统箱号
* 必须有一个不为空):</p>
* <ul>
* <li>系统箱号:{@code caseCodeList}</li>
* <li>SKU:{@code skuCode}</li>
* <li>箱序号区间:{@code startCaseSerialNo} ~ {@code endCaseSerialNo}</li>
* <li>客户箱号区间:{@code startSellerCaseNo} ~ {@code endSellerCaseNo}</li>
* </ul>
*/
public final class EdayunSkuLabelDtos {
private EdayunSkuLabelDtos() {
}
/** 打印 SKU 标请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PrintSkuLabelRequest {
/** EDA 入库单号(REV 单号)。必填。 */
public String entryCode;
/** 系统箱号列表(如 {@code B00231164777837})。 */
public List<String> caseCodeList;
/** SKU 编码。 */
public String skuCode;
/** 箱序号开始。 */
public String startCaseSerialNo;
/** 箱序号结束。 */
public String endCaseSerialNo;
/** 开始打印的客户箱号。 */
public String startSellerCaseNo;
/** 结束打印的客户箱号。 */
public String endSellerCaseNo;
/** 纸张尺寸:2 100×150 / 4 100×100 / 5 A4。<b>必填</b>。 */
public Integer pageSize;
/** 是否需要 Made in China:0 否 / 1 是。<b>必填</b>。 */
public Integer madeInChina;
/** 是否打印分隔符(第一页与下一页不一致时插提示页)。<b>必填</b>。 */
public Boolean separation;
/** 每箱打印两份:0 否 / 1 是。 */
public Integer twoPrint;
}
/** 打印响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PrintSkuLabelResponse {
public Integer code;
public String msg;
/** 箱唛 PDF 地址。 */
public String data;
public String traceId;
}
}

73
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunTrackDtos.java

@ -0,0 +1,73 @@ @@ -0,0 +1,73 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:查询订单的物流轨迹
* ({@code POST /webApi/track/getTrackInfoList})。
*
* <p><b>请求体就是一个字符串数组</b>:{@code ["1Z111","1Z222"]},没有包装对象。
* 文档把字段名留空了,示例写成 {@code [{"": ["aa","bb"]}]} 是错的——
* 真机实测只有纯数组能通。</p>
*/
public final class EdayunTrackDtos {
private EdayunTrackDtos() {
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class GetTrackResponse {
public Integer code;
public String msg;
public List<Track> data;
public String traceId;
}
/** 一个跟踪号的轨迹。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Track {
public Long trackId;
public String trackingNo;
/** 轨迹状态;码表未给。 */
public Integer status;
/** 承运商,如 {@code fedex}。 */
public String carrierName;
/** 始发国。 */
public String startCountryName;
/** 目的国。 */
public String endCountryName;
/** 收件人。 */
public String receiver;
/** 轨迹明细节点。 */
public List<TrackDetail> trackDetaillVoList;
/** 上网时间;<b>字符串</b>,如 {@code 2025-08-19 08:17:00}。 */
public String onlineTime;
/** 妥投时间;字符串,同上。 */
public String deliveredTime;
/** 时区偏移,如 {@code GMT-04:00}——解释上面两个时间要用它。 */
public String timeZone;
}
/** 一个轨迹节点。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class TrackDetail {
public String trackingNo;
/** 节点状态;码表未给。 */
public Integer status;
/** 节点描述,如「上网」。 */
public String recentDescribe;
/** 节点时间(毫秒)。 */
public Long recentDescribeTime;
/** 创建时间(毫秒)。 */
public Long createTime;
/** 事件状态原值。 */
public String eventStatus;
}
}

95
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunWarehouseDtos.java

@ -0,0 +1,95 @@ @@ -0,0 +1,95 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:获取激活仓库列表
* ({@code POST /webApi/warehouse/listActive})。
*
* <p>返回的是<b>平台侧全量仓库</b>(含未授权给当前客户的),字段比
* 「权限内仓库」多得多(47 个 vs 17 个)。下单要用的是
* {@code listWarehouseHasPerm}——那个才是当前客户可用的仓。</p>
*/
public final class EdayunWarehouseDtos {
private EdayunWarehouseDtos() {
}
/** 激活仓库查询请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListActiveRequest {
/**
* 仓库类型:0 尾程仓 / 1 头程仓。
*
* <p>文档标必填,实测不传会返回两者之和(118 条 vs 0 类型 111 条 + 1 类型 7 条)。</p>
*/
public Integer warehouseOperationType;
}
/** 权限内仓库查询请求:无参数。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListPermittedRequest {
// 接口不收参数,保留空类是为了和「一个接口一个 DTO」的约定一致
}
/** 两个接口共用同一个响应结构。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListWarehouseResponse {
public Integer code;
public String msg;
public List<WarehouseRow> data;
public String traceId;
}
/**
* 一个仓库。
*
* <p>只声明两个接口都会返回的字段;{@code listActive} 多出来的 30 个字段
* (容量、营业时间、负责人邮箱等)统一模型用不到,不声明——Jackson 会忽略未知字段。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class WarehouseRow {
/** 仓 id(字符串形式,如 {@code "40269"})。 */
public String warehouseId;
/** 仓名称(中文)。 */
public String warehouseName;
/** 仓名称(英文)。 */
public String warehouseNameEn;
/** 仓编码,如 {@code USALA-Q031}。 */
public String warehouseCode;
/** 仓库位置编码(权限内接口给 {@code WH-<id>})。 */
public String warehouseLocationCode;
public String countryCode;
/** 地址原文(单行)。 */
public String address;
/** 仓库区域类型:0 普通 / 1 分区(码表未给全)。 */
public Integer warehouseRegionType;
/** 当前时间(毫秒);权限内接口实测恒为 null。 */
public Long currentTime;
/** 时区,如 {@code America/Los_Angeles}。 */
public String timeZone;
// ---- 仅 listActive 返回,权限内接口没有 ----
/** 州 / 省编码,如 {@code US01}。 */
public String provinceCode;
/** 城市编码 / 名称。 */
public String cityCode;
public String cityName;
public String zipCode;
/** 仓库类型:0 尾程仓 / 1 头程仓。 */
public Integer warehouseOperationType;
/** 仓状态;实测全是 0。 */
public Integer warehouseStatus;
/** 父仓 id(子仓才有)。 */
public String parentWarehouseId;
/** 是否私有仓。 */
public Integer privateFlag;
/** 仓库负责人。 */
public String warehouseManagerName;
public String warehouseManagerTel;
}
}

74
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunBolStatus.java

@ -0,0 +1,74 @@ @@ -0,0 +1,74 @@
package common.ecommerce.edayun.enums;
/**
* 易达云 BOL 状态({@code getOrderBolList} 的 {@code bolList[].status})。
*
* <p><b>只有一个码值是文档确认的</b>:{@code 11 = 已妥投}(文档响应示例)。
* 完整码表易达云没给,所以其余状态只按 {@code statusName} 中文名兜底,
* 认不出就把原值透出({@link BolState#UNKNOWN})——不猜。</p>
*/
public enum EdayunBolStatus {
/** 11 已妥投(文档示例)。 */
DELIVERED(11, BolState.DELIVERED),
/** 无法识别。 */
UNKNOWN(null, BolState.UNKNOWN);
/** 归一化的提货状态;只区分宿主真正会分支处理的几档。 */
public enum BolState {
/** 未提货。 */
PENDING_PICKUP,
/** 已提货 / 运输中。 */
PICKED_UP,
/** 已妥投 / 已签收。 */
DELIVERED,
/** 无法识别。 */
UNKNOWN
}
private final Integer rawCode;
private final BolState state;
EdayunBolStatus(Integer rawCode, BolState state) {
this.rawCode = rawCode;
this.state = state;
}
public Integer rawCode() {
return rawCode;
}
public BolState state() {
return state;
}
/** 状态码 + 中文名 → 归一化状态;码值优先,认不出码再看中文名。 */
public static BolState toState(Integer status, String statusName) {
for (EdayunBolStatus v : values()) {
if (v.rawCode != null && v.rawCode.equals(status)) {
return v.state;
}
}
return byName(statusName);
}
/** 按中文名推断;认不出返回 {@link BolState#UNKNOWN}。 */
static BolState byName(String statusName) {
if (statusName == null || statusName.trim().isEmpty()) {
return BolState.UNKNOWN;
}
String n = statusName.trim();
if (n.contains("妥投") || n.contains("签收") || n.contains("完成")) {
return BolState.DELIVERED;
}
if (n.contains("已提") || n.contains("提货") || n.contains("运输")
|| n.contains("在途") || n.contains("发出")) {
return BolState.PICKED_UP;
}
if (n.contains("未提") || n.contains("待提") || n.contains("待约")
|| n.contains("预约")) {
return BolState.PENDING_PICKUP;
}
return BolState.UNKNOWN;
}
}

103
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunRmaStatus.java

@ -0,0 +1,103 @@ @@ -0,0 +1,103 @@
package common.ecommerce.edayun.enums;
import common.ecommerce.warehouse.enums.ReturnStatus;
/**
* 易达云退货单状态。
*
* <p>码表来自列表接口文档的 {@code status} 参数说明:</p>
* <pre>
* -1 已取消 0 待发布 1 待仓库签收 2 搁置中
* 3 仓库签收 4 处理中-仓库处理 5 已处理 6 处理中-等待指令
* 7 物流签收
* </pre>
*
* <p><b>注意</b>:详情接口({@code getOrderDetail})的 {@code basicInfo.status}
* 是否用同一套码表<b>没有确认</b>——列表文档明确给了字典,
* 详情文档只给了 {@code status: 1} 示例。两者都走本枚举,若日后发现不一致需拆开。</p>
*
* <p>认不出的码走 {@code statusName} 中文名兜底;都认不出归
* {@link ReturnStatus#UNKNOWN},原值保留在 {@code rawStatus}。</p>
*/
public enum EdayunRmaStatus {
/** -1 已取消。 */
CANCELLED(-1, ReturnStatus.CLOSED),
/** 0 待发布。 */
TO_PUBLISH(0, ReturnStatus.DRAFT),
/** 1 待仓库签收。 */
TO_SIGN(1, ReturnStatus.RETURNING),
/** 2 搁置中。 */
SUSPENDED(2, ReturnStatus.UNKNOWN),
/** 3 仓库签收。 */
SIGNED(3, ReturnStatus.PENDING_RECEIPT),
/** 4 处理中-仓库处理。 */
WAREHOUSE_HANDLING(4, ReturnStatus.PENDING_RECEIPT),
/** 5 已处理。 */
HANDLED(5, ReturnStatus.COMPLETED),
/** 6 处理中-等待指令。 */
WAITING_INSTRUCTION(6, ReturnStatus.PENDING_RECEIPT),
/** 7 物流签收。 */
LOGISTICS_SIGNED(7, ReturnStatus.RETURNING),
/** 无法识别。 */
UNKNOWN(null, ReturnStatus.UNKNOWN);
private final Integer rawCode;
private final ReturnStatus core;
EdayunRmaStatus(Integer rawCode, ReturnStatus core) {
this.rawCode = rawCode;
this.core = core;
}
/** 仓方状态码;null 表示无法识别。 */
public Integer rawCode() {
return rawCode;
}
public ReturnStatus toCore() {
return core;
}
/** 状态码 + 中文名 → 底层状态;码值优先,认不出码再看中文名。 */
public static ReturnStatus toCore(Integer status, String statusName) {
for (EdayunRmaStatus v : values()) {
if (v.rawCode != null && v.rawCode.equals(status)) {
return v.core;
}
}
return byName(statusName);
}
/** 按中文名推断;认不出返回 {@code UNKNOWN}。 */
static ReturnStatus byName(String statusName) {
if (statusName == null || statusName.trim().isEmpty()) {
return ReturnStatus.UNKNOWN;
}
String n = statusName.trim();
// 先判否定语义,避免「审核不通过」被「审核」命中
if (n.contains("驳回") || n.contains("拒绝") || n.contains("不通过")) {
return ReturnStatus.REJECTED;
}
if (n.contains("关闭") || n.contains("取消") || n.contains("作废")) {
return ReturnStatus.CLOSED;
}
if (n.contains("完成") || n.contains("已上架") || n.contains("结案")) {
return ReturnStatus.COMPLETED;
}
if (n.contains("审核")) {
return ReturnStatus.PENDING_REVIEW;
}
if (n.contains("收货") || n.contains("检验") || n.contains("清点")) {
return ReturnStatus.PENDING_RECEIPT;
}
if (n.contains("在途") || n.contains("退货中") || n.contains("运输")
|| n.contains("已发出") || n.contains("待收")) {
return ReturnStatus.RETURNING;
}
if (n.contains("草稿") || n.contains("预报")) {
return ReturnStatus.DRAFT;
}
return ReturnStatus.UNKNOWN;
}
}

61
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/enums/EdayunSkuLabelPaper.java

@ -0,0 +1,61 @@ @@ -0,0 +1,61 @@
package common.ecommerce.edayun.enums;
import common.ecommerce.warehouse.enums.LabelSizeType;
/**
* 易达云 SKU 标纸张尺寸({@code newPrintCaseMark} 的 {@code pageSize})。
*
* <p>只有三档,且码值与统一枚举 {@link LabelSizeType} 完全不同:</p>
* <table>
* <tr><th>易达云</th><th>尺寸</th><th>统一枚举</th></tr>
* <tr><td>4</td><td>100×100</td><td>{@link LabelSizeType#SIZE_100_100}</td></tr>
* <tr><td>2</td><td>100×150</td><td>{@link LabelSizeType#SIZE_100_150}</td></tr>
* <tr><td>5</td><td>A4</td><td>{@link LabelSizeType#A4}</td></tr>
* </table>
*
* <p>注意码值不连续(4 / 2 / 5),不要按顺序推。</p>
*/
public enum EdayunSkuLabelPaper {
/** 4:100×100mm。 */
SIZE_100_100(4, "100×100", LabelSizeType.SIZE_100_100),
/** 2:100×150mm。 */
SIZE_100_150(2, "100×150", LabelSizeType.SIZE_100_150),
/** 5:A4。 */
A4(5, "A4", LabelSizeType.A4);
private final int code;
private final String label;
private final LabelSizeType core;
EdayunSkuLabelPaper(int code, String label, LabelSizeType core) {
this.code = code;
this.label = label;
this.core = core;
}
public int code() {
return code;
}
public String label() {
return label;
}
/** 对应的统一尺寸。 */
public LabelSizeType core() {
return core;
}
/** 统一尺寸 → 易达云码值;不支持的尺寸显式拒绝。 */
public static EdayunSkuLabelPaper of(LabelSizeType size) {
for (EdayunSkuLabelPaper v : values()) {
if (v.core == size) {
return v;
}
}
throw new IllegalArgumentException(
"edayun case mark does not support label size: " + size
+ " (only 100x100 / 100x150 / A4)");
}
}

18
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java

@ -17,6 +17,7 @@ import java.time.Instant; @@ -17,6 +17,7 @@ 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.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
@ -58,15 +59,19 @@ class EdayunAdapterTest { @@ -58,15 +59,19 @@ class EdayunAdapterTest {
assertEquals(WarehouseProvider.EDAYUN, adapter.provider());
}
/** 已实现能力:商品建档。声明了就必须有实现。 */
/**
* 已实现能力:商品建档 / 出库。声明了就必须有实现。
*
* <p>只断言「始终存在」与「始终不存在」的能力位,避免每加一个接口就要改这里。</p>
*/
@Test
void declaresOnlyImplementedCapabilities() {
EdayunAdapter adapter = new EdayunAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
// 未实现的仍然不声明
assertTrue(!adapter.capabilities().contains(WarehouseCapability.TRACKING));
// 易达云没有调拨 / 换货,永远不声明
assertFalse(adapter.capabilities().contains(WarehouseCapability.TRANSFER));
}
/** 注册到门面后能按 provider 解析到适配器。 */
@ -93,7 +98,7 @@ class EdayunAdapterTest { @@ -93,7 +98,7 @@ class EdayunAdapterTest {
common.ecommerce.warehouse.model.OutboundRef.ofRequestNo("")));
}
/** 未声明能力(如退货)时门面显式拒绝,不返回空列表。 */
/** 未声明能力时门面显式拒绝,不返回空列表。 */
@Test
void unimplementedCapabilityIsRejected() {
WarehouseSdk sdk = sdk();
@ -101,8 +106,9 @@ class EdayunAdapterTest { @@ -101,8 +106,9 @@ class EdayunAdapterTest {
EdayunConstants.PR_BASE_URL,
common.ecommerce.shared.spi.ChannelSecret.builder().appSecret("k").build());
// 调拨易达云不声明
assertThrows(WarehouseUnsupportedCapabilityException.class,
() -> sdk.warehouses(WH, conn).returns().query(null));
() -> sdk.warehouses(WH, conn).getTransfer("T-1"));
}
/** 能力矩阵查询本身可用(不触发真实 API)。 */
@ -111,6 +117,6 @@ class EdayunAdapterTest { @@ -111,6 +117,6 @@ class EdayunAdapterTest {
EdayunAdapter adapter = new EdayunAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertTrue(adapter.capabilities().contains(WarehouseCapability.INBOUND));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.TRACKING));
assertFalse(adapter.capabilities().contains(WarehouseCapability.TRANSFER));
}
}

169
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunBolTest.java

@ -0,0 +1,169 @@ @@ -0,0 +1,169 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunBolDtos;
import common.ecommerce.edayun.enums.EdayunBolStatus;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.BolDocument;
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 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;
/**
* BOL 信息({@code /webApi/fbaOrder/v1/getOrderBolList})映射。
*
* <p>重点:只有 11=已妥投 确认,其余按中文名兜底;空 bolList 返回空列表不是错误。</p>
*/
class EdayunBolTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00: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-bol", 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_BOL_LIST,
req -> Responses.ok(body));
}
// ------------------------------------------------------------ 请求
@Test
void requiresOrderNo() {
assertThrows(IllegalArgumentException.class,
() -> EdayunBolMapper.toRequest(" "));
assertEquals("FBA473182144", EdayunBolMapper.toRequest(" FBA473182144 ").orderNo);
}
// ------------------------------------------------------------ 响应
private static EdayunBolDtos.Bol bol() {
EdayunBolDtos.Bol bol = new EdayunBolDtos.Bol();
bol.bolCode = "cp005";
bol.bolFileUrl = "https://oss/FBA0012958017-BOL.pdf";
bol.signBolFileUrl = "https://oss/signed.pdf";
bol.podFileUrl = "https://oss/pod.pdf";
bol.podFileTime = 1740910561000L;
bol.status = 11;
bol.statusName = "已妥投";
bol.pickupTime = "2025-03-02";
bol.actualPickupTime = "2025-03-02";
bol.orderPickupNum = 1;
bol.actualPickupNum = 1;
bol.truckCompany = "123";
bol.trackingNo = "123123";
return bol;
}
@Test
void mapsBolFields() {
BolDocument doc = EdayunBolMapper.toDocument(bol());
assertEquals("cp005", doc.bolCode());
assertEquals("https://oss/FBA0012958017-BOL.pdf", doc.fileUrl());
assertEquals("https://oss/signed.pdf", doc.signedFileUrl());
assertEquals("https://oss/pod.pdf", doc.podFileUrl());
assertEquals(Instant.ofEpochMilli(1740910561000L), doc.podUploadedAt());
assertEquals(Integer.valueOf(11), doc.rawStatus());
assertEquals("已妥投", doc.statusName());
assertEquals("2025-03-02", doc.scheduledPickupDate());
assertEquals("2025-03-02", doc.actualPickupDate());
assertEquals(Integer.valueOf(1), doc.scheduledPickupQuantity());
assertEquals(Integer.valueOf(1), doc.actualPickupQuantity());
assertEquals("123", doc.truckCompany());
assertEquals("123123", doc.trackingNo());
}
/** 只有 11 确认;其余码按中文名兜底。 */
@Test
void statusOnly11IsConfirmed() {
assertEquals(EdayunBolStatus.BolState.DELIVERED,
EdayunBolStatus.toState(11, null));
// 未知码 + 中文名能认 → 按名字
assertEquals(EdayunBolStatus.BolState.PICKED_UP,
EdayunBolStatus.toState(99, "已提货"));
// 都认不出 → UNKNOWN
assertEquals(EdayunBolStatus.BolState.UNKNOWN,
EdayunBolStatus.toState(99, "某个新状态"));
assertEquals(EdayunBolStatus.BolState.UNKNOWN,
EdayunBolStatus.toState(null, null));
}
/** podFileTime 为 0 时不造 1970 年。 */
@Test
void zeroPodTimeIsNull() {
EdayunBolDtos.Bol b = bol();
b.podFileTime = 0L;
assertNull(EdayunBolMapper.toDocument(b).podUploadedAt());
}
/** 没有 bolList 时返回空列表,不是错误。 */
@Test
void emptyBolListYieldsEmptyResult() {
EdayunBolDtos.GetBolResponse resp = new EdayunBolDtos.GetBolResponse();
resp.code = 200;
resp.data = new EdayunBolDtos.BolData();
assertTrue(EdayunBolMapper.toDocuments(resp).isEmpty());
assertTrue(EdayunBolMapper.toDocuments(null).isEmpty());
}
/** 没有 bolCode 的行跳过——BolDocument 要求 bolCode 非空。 */
@Test
void rowsWithoutBolCodeAreSkipped() {
EdayunBolDtos.Bol bad = bol();
bad.bolCode = " ";
EdayunBolDtos.BolData data = new EdayunBolDtos.BolData();
data.bolList = java.util.Arrays.asList(bad, bol());
EdayunBolDtos.GetBolResponse resp = new EdayunBolDtos.GetBolResponse();
resp.data = data;
assertEquals(1, EdayunBolMapper.toDocuments(resp).size());
}
@Test
void adapterQueriesBolList() {
RecordingTransport transport = stub("{\"code\":200,\"msg\":\"操作成功\",\"data\":{"
+ "\"totalNum\":1,\"unPickupNum\":0,\"bolList\":[{\"bolCode\":\"cp005\","
+ "\"status\":11,\"statusName\":\"已妥投\",\"pickupTime\":\"2025-03-02\","
+ "\"orderPickupNum\":1,\"bolFileUrl\":\"https://oss/b.pdf\"}]}}");
List<BolDocument> docs = new EdayunAdapter(transport, new JacksonJsonCodec())
.orderBols(ctx(), "FBA473182144");
assertEquals(1, docs.size());
assertEquals("cp005", docs.get(0).bolCode());
assertTrue(transport.lastDataRequest().body().contains("\"orderNo\":\"FBA473182144\""));
}
/** 业务码失败要抛异常。 */
@Test
void businessErrorFails() {
RecordingTransport transport = stub("{\"code\":500,\"msg\":\"订单不存在\"}");
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec())
.orderBols(ctx(), "FBA-NOT-EXIST"));
}
}

109
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCancelReturnTest.java

@ -0,0 +1,109 @@ @@ -0,0 +1,109 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCancelReturnDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseException;
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.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 取消退货单({@code /webApi/rma/info/v1/cancel})。
*
* <p>重点:响应 data 是布尔;{@code code=200 + data=false} 是仓方拒绝,要抛异常;
* 传的必须是仓侧 RMA 号。</p>
*/
class EdayunCancelReturnTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00: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-return-cancel", 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_RETURN_CANCEL,
req -> Responses.ok(body));
}
@Test
void cancelSucceedsWhenDataIsTrue() {
RecordingTransport transport = stub(
"{\"code\":200,\"msg\":\"操作成功\",\"data\":true}");
boolean ok = new EdayunAdapter(transport, new JacksonJsonCodec())
.cancel(ctx(), "RMA2411053149");
assertTrue(ok);
assertTrue(transport.lastDataRequest().body().contains("\"rmaCode\":\"RMA2411053149\""),
transport.lastDataRequest().body());
}
/**
* {@code code=200} 但 {@code data=false} 是仓方拒绝(如已收货)——
* 取消是状态变更,不能静默返回 false 让调用方以为没事。
*/
@Test
void dataFalseIsRejected() {
RecordingTransport transport = stub(
"{\"code\":200,\"msg\":\"退货单已收货,不允许取消\",\"data\":false}");
WarehouseException ex = assertThrows(WarehouseException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec())
.cancel(ctx(), "RMA1"));
assertTrue(ex.getMessage().contains("已收货"), ex.getMessage());
}
/** data 缺失同样视为失败——不能把「没返回结果」当成功。 */
@Test
void missingDataIsRejected() {
RecordingTransport transport = stub("{\"code\":200,\"msg\":\"操作成功\"}");
assertThrows(WarehouseException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec())
.cancel(ctx(), "RMA1"));
}
/** 业务码非 200 走 requireSuccess 的异常路径。 */
@Test
void businessErrorFails() {
RecordingTransport transport = stub("{\"code\":500,\"msg\":\"退货单不存在\"}");
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec())
.cancel(ctx(), "RMA-NOT-EXIST"));
}
/** 空单号本地拒绝,不发请求。 */
@Test
void blankRmaCodeIsRejected() {
RecordingTransport transport = stub("{\"code\":200,\"data\":true}");
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec()).cancel(ctx(), " "));
assertTrue(ex.getMessage().contains("rmaCode"), ex.getMessage());
assertTrue(transport.dataRequests().isEmpty());
assertEquals(0, transport.dataRequests().size());
}
}

160
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java

@ -0,0 +1,160 @@ @@ -0,0 +1,160 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseCarrier;
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 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;
/**
* 承运商清单({@code /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>重点:ownLogisticList 文档写成对象、真机是数组;carrierId 缺失的行跳过。</p>
*/
class EdayunCarrierTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx(String providerWarehouseId) {
return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, providerWarehouseId,
WarehouseConnection.of("https://test.example/openapi",
ChannelSecret.builder().appKey("k").appSecret("s")
.clientId("c").clientSecret("cs").build()),
"req-carrier", 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_CARRIERS,
req -> Responses.ok(body));
}
// ------------------------------------------------------------ 请求
@Test
void numericWarehouseIdIsSent() {
EdayunCarrierDtos.ListCarrierRequest req =
EdayunCarrierMapper.toRequest("2", null);
assertEquals(Long.valueOf(2L), req.warehouseId);
assertNull(req.countryCode);
}
/** 非数字仓 id 不下发——仓方会返回所有服务商。 */
@Test
void nonNumericWarehouseIdIsOmitted() {
assertNull(EdayunCarrierMapper.toRequest("USLA", null).warehouseId);
assertNull(EdayunCarrierMapper.toRequest(null, null).warehouseId);
}
@Test
void countryCodeIsTrimmed() {
assertEquals("US", EdayunCarrierMapper.toRequest("2", " US ").countryCode);
assertNull(EdayunCarrierMapper.toRequest("2", " ").countryCode);
}
// ------------------------------------------------------------ 响应
private static EdayunCarrierDtos.Carrier carrier() {
EdayunCarrierDtos.OwnLogistic l1 = new EdayunCarrierDtos.OwnLogistic();
l1.logisticId = "583";
l1.logisticName = "Collections by Tiktok - FedEx";
EdayunCarrierDtos.OwnLogistic l2 = new EdayunCarrierDtos.OwnLogistic();
l2.logisticId = "250";
l2.logisticName = "FedEx-express";
EdayunCarrierDtos.Carrier c = new EdayunCarrierDtos.Carrier();
c.carrierId = "1";
c.carrierNameEn = "FedEx";
c.carrierNameCn = "联邦快递";
c.ownLogisticList = java.util.Arrays.asList(l1, l2);
return c;
}
@Test
void mapsCarrierWithLogistics() {
WarehouseCarrier c = EdayunCarrierMapper.toCarrier(carrier());
assertEquals("1", c.carrierId());
assertEquals("FedEx", c.nameEn());
assertEquals("联邦快递", c.nameCn());
assertEquals("联邦快递", c.displayName());
assertEquals(2, c.logists().size());
assertEquals("583", c.logists().get(0).logisticId());
assertEquals("FedEx-express", c.logists().get(1).name());
}
/** 没有中文名时 displayName 退回英文名。 */
@Test
void displayNameFallsBackToEnglish() {
EdayunCarrierDtos.Carrier c = carrier();
c.carrierNameCn = null;
assertEquals("FedEx", EdayunCarrierMapper.toCarrier(c).displayName());
}
/** carrierId 缺失的行跳过——模型要求非空。 */
@Test
void carrierWithoutIdIsSkipped() {
EdayunCarrierDtos.Carrier bad = carrier();
bad.carrierId = " ";
List<WarehouseCarrier> list = EdayunCarrierMapper.toCarriers(
java.util.Arrays.asList(bad, carrier()));
assertEquals(1, list.size());
}
/** ownLogisticList 缺失或为空不抛异常。 */
@Test
void missingLogisticListYieldsEmpty() {
EdayunCarrierDtos.Carrier c = carrier();
c.ownLogisticList = null;
assertTrue(EdayunCarrierMapper.toCarrier(c).logists().isEmpty());
assertTrue(EdayunCarrierMapper.toCarriers(null).isEmpty());
assertTrue(EdayunCarrierMapper.toCarriers(
java.util.Collections.<EdayunCarrierDtos.Carrier>emptyList()).isEmpty());
}
@Test
void adapterQueriesCarriers() {
RecordingTransport transport = stub("{\"code\":200,\"msg\":\"操作成功\",\"data\":[{"
+ "\"carrierId\":\"1\",\"carrierNameEn\":\"FedEx\",\"carrierNameCn\":\"FedEx\","
+ "\"ownLogisticList\":[{\"logisticId\":\"250\",\"logisticName\":\"FedEx-express\"}]}]}");
List<WarehouseCarrier> list = new EdayunAdapter(transport, new JacksonJsonCodec())
.carrierDirectory(ctx("2"));
assertEquals(1, list.size());
assertEquals("FedEx", list.get(0).nameEn());
assertEquals(1, list.get(0).logists().size());
assertTrue(transport.lastDataRequest().body().contains("\"warehouseId\":2"));
}
/** 仓库列表接口易达云没有,显式拒绝而不是空列表。 */
@Test
void warehousesAreUnsupported() {
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(stub("{}"), new JacksonJsonCodec())
.warehouses(ctx("2")));
}
}

166
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCaseMarkTest.java

@ -0,0 +1,166 @@ @@ -0,0 +1,166 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCaseMarkDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.CaseMarkPaperSize;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
import common.ecommerce.warehouse.model.WarehouseLabel;
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/v2/printBarcode})映射。
*
* <p>重点:响应 data 是文件地址、同步返回(不是任务号)、50 个 SKU 上限。</p>
*/
class EdayunCaseMarkTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00: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-barcode", 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_CASE_MARK_PRINT,
req -> Responses.ok(body));
}
private static CaseMarkPrintCommand command() {
return CaseMarkPrintCommand.builder()
.paperSize(CaseMarkPaperSize.SIZE_70_30)
.remark("Made in China")
.printSkuName(false)
.item("ybtest", 2)
.build();
}
// ------------------------------------------------------------ 请求
@Test
void mapsRequest() {
EdayunCaseMarkDtos.PrintCaseMarkRequest req = EdayunCaseMarkMapper.toRequest(command());
assertEquals(Integer.valueOf(0), req.pageSize);
assertEquals("Made in China", req.remark);
assertEquals(1, req.productInfos.size());
assertEquals("ybtest", req.productInfos.get(0).skuCode);
assertEquals(Integer.valueOf(2), req.productInfos.get(0).num);
}
/** isPrintSkuName 只在 true 时下发,false 交给仓方默认。 */
@Test
void printSkuNameOnlySentWhenTrue() {
assertNull(EdayunCaseMarkMapper.toRequest(command()).isPrintSkuName);
CaseMarkPrintCommand withName = CaseMarkPrintCommand.builder()
.paperSize(CaseMarkPaperSize.SIZE_60_40)
.printSkuName(true)
.item("sku", 1)
.build();
assertEquals(Boolean.TRUE, EdayunCaseMarkMapper.toRequest(withName).isPrintSkuName);
}
@Test
void paperSizesMap() {
assertEquals(0, CaseMarkPaperSize.SIZE_70_30.code());
assertEquals(1, CaseMarkPaperSize.SIZE_100_60.code());
assertEquals(2, CaseMarkPaperSize.SIZE_100_150.code());
assertEquals(3, CaseMarkPaperSize.SIZE_60_40.code());
}
/** 超过 50 个 SKU 本地就挡,不发请求(仓方也会报「最多打印50个SKU」)。 */
@Test
void moreThan50SkusRejectedLocally() {
CaseMarkPrintCommand.Builder b = CaseMarkPrintCommand.builder()
.paperSize(CaseMarkPaperSize.SIZE_60_40);
for (int i = 0; i < 51; i++) {
b.item("SKU-" + i, 1);
}
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> EdayunCaseMarkMapper.toRequest(b.build()));
assertTrue(ex.getMessage().contains("at most 50"), ex.getMessage());
}
/** 空 SKU 列表与非法份数在命令构造期就被拒。 */
@Test
void invalidCommandRejectedAtConstruction() {
assertThrows(IllegalArgumentException.class,
() -> CaseMarkPrintCommand.builder().paperSize(CaseMarkPaperSize.SIZE_60_40).build());
assertThrows(IllegalArgumentException.class,
() -> CaseMarkPrintCommand.builder().paperSize(CaseMarkPaperSize.SIZE_60_40)
.item("sku", 0));
assertThrows(IllegalArgumentException.class,
() -> CaseMarkPrintCommand.builder().paperSize(CaseMarkPaperSize.SIZE_60_40)
.item(" ", 1));
// 缺纸张尺寸
assertThrows(IllegalArgumentException.class,
() -> CaseMarkPrintCommand.builder().item("sku", 1).build());
}
// ------------------------------------------------------------ 响应
/** data 是文件地址字符串,直接落 WarehouseLabel.url。 */
@Test
void responseDataIsFileUrl() {
RecordingTransport transport = stub("{\"code\":200,\"msg\":\"操作成功\","
+ "\"data\":\"https://oss.edayun.com/barcode1.pdf\",\"traceId\":null}");
WarehouseLabel label = new EdayunAdapter(transport, new JacksonJsonCodec())
.printCaseMarks(ctx(), command());
assertEquals("https://oss.edayun.com/barcode1.pdf", label.url());
assertEquals("PDF", label.format());
assertNull(label.contentBase64());
assertTrue(transport.lastDataRequest().body().contains("\"skuCode\":\"ybtest\""));
}
/** code=200 但 data 为空 → 抛异常,不能返回没有文件的对象。 */
@Test
void blankDataFails() {
RecordingTransport transport = stub(
"{\"code\":200,\"msg\":\"操作成功\",\"data\":\" \"}");
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec())
.printCaseMarks(ctx(), command()));
}
/** 仓方业务错误(如 SKU 不存在)要抛异常并带出原因。 */
@Test
void businessErrorFails() {
RecordingTransport transport = stub(
"{\"code\":500,\"msg\":\"sku=NO-SUCH信息不存在\",\"data\":null}");
try {
new EdayunAdapter(transport, new JacksonJsonCodec())
.printCaseMarks(ctx(), command());
org.junit.jupiter.api.Assertions.fail("should have thrown");
} catch (RuntimeException e) {
assertTrue(e.getMessage().contains("SKU") || e.getMessage().contains("sku"), e.getMessage());
}
}
}

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

@ -136,10 +136,36 @@ class EdayunInventoryTest { @@ -136,10 +136,36 @@ class EdayunInventoryTest {
assertTrue(s.sellable());
}
/** 仓编码缺失时回退 OMS 仓编码,快照必须有 warehouseCode。 */
/**
* 仓方会缺字段:真机 500 行里 430 行 {@code safeStock} 为 null。
* 统一模型对「仓方未给」的约定是 -1,不能与真实的 0 混为一谈。
*/
@Test
void missingSafeStockIsMinusOne() {
EdayunInventoryDtos.InventoryRow r = row();
r.safeStock = null;
r.toDeliverStock = null;
InventorySnapshot s = EdayunInventoryMapper.toPage(
response(1L, r), "W", AS_OF, 1, 100).items().get(0);
assertEquals(-1, s.alertQuantity());
assertEquals(-1, s.pendingOutbound());
}
/** 真实值为 0 时仍然是 0,不能被当成「未给」。 */
@Test
void warehouseCodeFallsBack() {
void zeroSafeStockStaysZero() {
EdayunInventoryDtos.InventoryRow r = row();
r.safeStock = 0;
assertEquals(0, EdayunInventoryMapper.toPage(
response(1L, r), "W", AS_OF, 1, 100).items().get(0).alertQuantity());
}
/** 仓编码缺失时回退 OMS 仓编码,快照必须有 warehouseCode。 */
@Test
void warehouseCodeFallsBack() { EdayunInventoryDtos.InventoryRow r = row();
r.warehouseCode = null;
assertEquals("EDY-WH", EdayunInventoryMapper.toPage(
@ -147,8 +173,7 @@ class EdayunInventoryTest { @@ -147,8 +173,7 @@ class EdayunInventoryTest {
.items().get(0).warehouseCode());
}
/** 没有 SKU 的行跳过,不应让整页失败。 */
@Test
/** 没有 SKU 的行跳过,不应让整页失败。 */ @Test
void rowsWithoutSkuAreSkipped() {
EdayunInventoryDtos.InventoryRow dirty = row();
dirty.skuCode = " ";

110
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductTest.java

@ -0,0 +1,110 @@ @@ -0,0 +1,110 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.LogisticsProduct;
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 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.assertTrue;
/**
* 物流产品清单({@code /webApi/order/listByLogisticProductHasPerm})。
*
* <p>重点:{@code -998}(使用分物流规则)不是真实产品,要跳过。</p>
*/
class EdayunLogisticsProductTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00: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-lp", CLOCK);
}
private static EdayunLogisticsProductDtos.Product product(String id, String name) {
EdayunLogisticsProductDtos.Product p = new EdayunLogisticsProductDtos.Product();
p.productId = id;
p.productName = name;
return p;
}
@Test
void mapsProduct() {
LogisticsProduct lp = EdayunLogisticsProductMapper.toProduct(
product("133", "美国USPS-Priority Mail"), "USLA");
assertEquals("133", lp.logisticsProductCode());
assertEquals("美国USPS-Priority Mail", lp.logisticsProductName());
assertEquals("USLA", lp.warehouseCode());
assertEquals(WarehouseProvider.EDAYUN, lp.sourceProvider());
// 易达云不回跨国标记,恒 false
assertTrue(!lp.crossCountry());
}
/** -998 是「使用分物流规则」的哨兵值,不是可选产品。 */
@Test
void autoRouteSentinelIsSkipped() {
List<LogisticsProduct> list = EdayunLogisticsProductMapper.toProducts(
java.util.Arrays.asList(product("133", "USPS"), product("-998", "使用分物流规则")),
"USLA");
assertEquals(1, list.size());
assertEquals("133", list.get(0).logisticsProductCode());
}
/** 没有 productId 的行跳过。 */
@Test
void rowsWithoutProductIdAreSkipped() {
assertNull(EdayunLogisticsProductMapper.toProduct(product(" ", "x"), "W"));
assertNull(EdayunLogisticsProductMapper.toProduct(null, "W"));
}
@Test
void emptyRowsYieldEmptyList() {
assertTrue(EdayunLogisticsProductMapper.toProducts(null, "W").isEmpty());
assertTrue(EdayunLogisticsProductMapper.toProducts(
java.util.Collections.<EdayunLogisticsProductDtos.Product>emptyList(), "W").isEmpty());
}
@Test
void warehouseIdOnlyWhenNumeric() {
assertEquals(Long.valueOf(2L), EdayunLogisticsProductMapper.toRequest("2", 1).warehouseId);
assertNull(EdayunLogisticsProductMapper.toRequest("USLA", 1).warehouseId);
assertNull(EdayunLogisticsProductMapper.toRequest(null, 1).warehouseId);
}
@Test
void adapterQueriesProducts() {
RecordingTransport transport = RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_LOGISTICS_PRODUCTS,
req -> Responses.ok("{\"code\":200,\"msg\":\"操作成功\",\"data\":["
+ "{\"productId\":\"133\",\"productName\":\"USPS\"},"
+ "{\"productId\":\"-998\",\"productName\":\"使用分物流规则\"}]}"));
List<LogisticsProduct> list = new EdayunAdapter(transport, new JacksonJsonCodec())
.products(ctx(), null);
assertEquals(1, list.size());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"warehouseId\":2"), body);
assertTrue(body.contains("\"applicableBusiness\":1"), body);
}
}

65
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderTest.java

@ -10,6 +10,7 @@ import common.ecommerce.warehouse.model.ShipTo; @@ -10,6 +10,7 @@ import common.ecommerce.warehouse.model.ShipTo;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
@ -171,4 +172,68 @@ class EdayunOrderTest { @@ -171,4 +172,68 @@ class EdayunOrderTest {
assertNull(EdayunOrderMapper.toCreateRequest(base().build(), "2").addService);
}
/** 任意商品行带保价金额 → 整单开保价(addService 是订单级开关)。 */
@Test
void insuredLineMapsToInsuranceService() {
OutboundCommand insured = OutboundCommand.builder()
.outboundRequestNo("OB-3")
.salesPlatform(Platform.AMAZON_SC)
.shipTo(ShipTo.builder().name("a").phone("p")
.countryCode("US").stateOrProvince("CA").city("c")
.addressLine1("a1").postalCode("1").build())
.line(OutboundLine.builder().lineNo("1").omsSku("S").quantity(1)
.insuredAmount(Money.of("100.00", "USD")).build())
.build();
EdayunCreateOrderDtos.CreateOrderRequest req =
EdayunOrderMapper.toCreateRequest(insured, "2");
assertEquals(1, req.addService.size());
assertEquals("is_insurance", req.addService.get(0));
}
/** 签收 + 保价可同时下发。 */
@Test
void signatureAndInsuranceCanCoexist() {
OutboundCommand both = OutboundCommand.builder()
.outboundRequestNo("OB-4")
.salesPlatform(Platform.AMAZON_SC)
.signatureRequired(true)
.shipTo(ShipTo.builder().name("a").phone("p")
.countryCode("US").stateOrProvince("CA").city("c")
.addressLine1("a1").postalCode("1").build())
.line(OutboundLine.builder().lineNo("1").omsSku("S").quantity(1)
.insuredAmount(Money.of("50.00", "USD")).build())
.build();
List<String> services = EdayunOrderMapper.toCreateRequest(both, "2").addService;
assertEquals(2, services.size());
assertTrue(services.contains("is_signature"));
assertTrue(services.contains("is_insurance"));
}
/** 增补:平台单号同时带 eBay Transaction ID 与商品级 itemId。 */
@Test
void ebayIdsAreNotMappedYet() {
// 标准模型没有 ebayTransactionId / ebayItemId;
// 商品级的 platformOrderItemIds 目前只映射到 platformItemId(亚马逊口径)
OutboundCommand cmd = OutboundCommand.builder()
.outboundRequestNo("OB-5")
.salesPlatform(Platform.EBAY)
.shipTo(ShipTo.builder().name("a").phone("p")
.countryCode("US").stateOrProvince("CA").city("c")
.addressLine1("a1").postalCode("1").build())
.line(OutboundLine.builder().lineNo("1").omsSku("S").quantity(1)
.platformOrderItemId("EBAY-ITEM-1").build())
.build();
EdayunCreateOrderDtos.CreateOrderRequest req =
EdayunOrderMapper.toCreateRequest(cmd, "2");
assertEquals("eBay", req.channelName);
assertNull(req.ebayTransactionId);
assertEquals("EBAY-ITEM-1", req.productItemVOList.get(0).platformItemId);
}
}

227
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnDetailTest.java

@ -0,0 +1,227 @@ @@ -0,0 +1,227 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseReturn;
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/rma/info/v1/getOrderDetail})映射。
*
* <p>重点:明细行检验结果优先于预报、状态码表缺失只能按中文名推断、
* 响应只有仓名没有仓编码。</p>
*/
class EdayunReturnDetailTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00: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-return-detail", CLOCK);
}
// ------------------------------------------------------------ 请求
@Test
void requiresRmaCode() {
assertThrows(IllegalArgumentException.class,
() -> EdayunReturnDetailMapper.toRequest(" "));
assertEquals("RMA1", EdayunReturnDetailMapper.toRequest(" RMA1 ").rmaCode);
}
// ------------------------------------------------------------ 响应
private static EdayunReturnDetailDtos.ReturnDetail detail() {
EdayunReturnDetailDtos.BasicInfo basic = new EdayunReturnDetailDtos.BasicInfo();
basic.rmaCode = "RMA2411053149";
basic.status = 3;
basic.statusName = "仓库签收";
basic.relationNo = "ORD599493019";
basic.warehouseId = 2L;
basic.warehouseName = "美西1仓";
basic.returnType = 2;
basic.returnTypeName = "自行退回";
basic.createTime = 1790568000000L;
EdayunReturnDetailDtos.SkuLine sku = new EdayunReturnDetailDtos.SkuLine();
sku.skuCode = "ybtest";
sku.skuNum = 2;
sku.command = 1;
sku.commandName = "上架";
sku.shelveSkuCode = "ybtest-NEW";
sku.picUrls = java.util.Arrays.asList("https://img/1.jpg", "https://img/2.jpg");
EdayunReturnDetailDtos.ReturnDetail detail = new EdayunReturnDetailDtos.ReturnDetail();
detail.basicInfo = basic;
detail.skuList = java.util.Collections.singletonList(sku);
return detail;
}
private static EdayunReturnDetailDtos.ReturnDetail checked() {
EdayunReturnDetailDtos.ReturnDetail detail = detail();
EdayunReturnDetailDtos.CheckLine check = new EdayunReturnDetailDtos.CheckLine();
check.skuCode = "ybtest";
check.skuNum = 1;
check.commandName = "上架";
check.exceptionReasonName = "外箱破损";
check.remark = "已拍照";
detail.checkList = java.util.Collections.singletonList(check);
return detail;
}
@Test
void mapsBasicInfo() {
WarehouseReturn ret = EdayunReturnDetailMapper.toReturn(detail(), "EDY-WH");
assertEquals("ORD599493019", ret.returnRequestNo());
assertEquals("RMA2411053149", ret.providerReturnId());
assertEquals("ORD599493019", ret.orderRef());
// 3 = 仓库签收 → 待收货
assertEquals("PENDING_RECEIPT", ret.status().name());
assertEquals("仓库签收", ret.rawStatus());
assertEquals(Instant.ofEpochMilli(1790568000000L), ret.createdAt());
assertEquals(WarehouseProvider.EDAYUN, ret.sourceProvider());
assertEquals("自行退回", ret.type());
}
/** 响应只有仓名与数字 id;warehouseCode 回退 OMS 仓编码。 */
@Test
void warehouseCodeFallsBackToOms() {
EdayunReturnDetailDtos.ReturnDetail noName = detail();
noName.basicInfo.warehouseName = null;
assertEquals("EDY-WH",
EdayunReturnDetailMapper.toReturn(noName, "EDY-WH").warehouseCode());
}
/** 明细优先取检验结果——对账以实际收到为准。 */
@Test
void checkListWinsOverSkuList() {
WarehouseReturn ret = EdayunReturnDetailMapper.toReturn(checked(), "W");
assertEquals(1, ret.lines().size());
WarehouseReturn.ReturnLine line = ret.lines().get(0);
assertEquals("ybtest", line.providerSku());
// 预报是 2,实际只收到 1
assertEquals(1, line.quantity());
assertEquals("外箱破损 已拍照", line.remark());
}
/** 没有检验记录时退回预报 SKU,skuNum 是 string 要解析。 */
@Test
void fallsBackToSkuList() {
WarehouseReturn ret = EdayunReturnDetailMapper.toReturn(detail(), "W");
assertEquals(1, ret.lines().size());
WarehouseReturn.ReturnLine line = ret.lines().get(0);
assertEquals(2, line.quantity());
assertEquals("ybtest-NEW", line.newSku());
assertEquals(2, line.pictureUrls().size());
assertEquals("https://img/2.jpg", line.pictureUrls().get(1));
}
/** 状态码表没给,只能按中文名推断;认不出归 UNKNOWN 并保留原文。 */
@Test
void statusInferredFromName() {
assertEquals(ReturnStatus.PENDING_RECEIPT, EdayunReturnDetailMapper.toReturn(
withStatus(9, "待收货"), "W").status());
assertEquals(ReturnStatus.REJECTED, EdayunReturnDetailMapper.toReturn(
withStatus(9, "审核驳回"), "W").status());
assertEquals(ReturnStatus.COMPLETED, EdayunReturnDetailMapper.toReturn(
withStatus(9, "已完成"), "W").status());
assertEquals(ReturnStatus.CLOSED, EdayunReturnDetailMapper.toReturn(
withStatus(9, "已关闭"), "W").status());
WarehouseReturn unknown = EdayunReturnDetailMapper.toReturn(
withStatus(9, "某个新状态"), "W");
assertEquals(ReturnStatus.UNKNOWN, unknown.status());
assertEquals("某个新状态", unknown.rawStatus());
}
/** 「审核不通过」不能被「审核」命中成待审核。 */
@Test
void rejectedBeatsPendingReview() {
assertEquals(ReturnStatus.REJECTED, EdayunReturnDetailMapper.toReturn(
withStatus(9, "审核不通过"), "W").status());
}
private static EdayunReturnDetailDtos.ReturnDetail withStatus(int code, String name) {
EdayunReturnDetailDtos.ReturnDetail d = detail();
d.basicInfo.status = code;
d.basicInfo.statusName = name;
return d;
}
/** createTime 为 0 或 null 时忽略,不要造出 1970 年。 */
@Test
void zeroCreateTimeIsNull() {
EdayunReturnDetailDtos.ReturnDetail d = detail();
d.basicInfo.createTime = 0L;
assertNull(EdayunReturnDetailMapper.toReturn(d, "W").createdAt());
}
/** 空/缺详情不抛异常:用请求单号兜底,返回空明细。 */
@Test
void nullDetailIsTolerated() {
WarehouseReturn ret = EdayunReturnDetailMapper.toReturn(null, "W", "RMA-X");
assertEquals("RMA-X", ret.returnRequestNo());
assertEquals("RMA-X", ret.providerReturnId());
assertTrue(ret.lines().isEmpty());
}
// ------------------------------------------------------------ 门面
@Test
void adapterQueriesReturnDetail() {
RecordingTransport transport = RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_RETURN_DETAIL,
req -> Responses.ok("{\"code\":200,\"msg\":\"操作成功\",\"data\":{"
+ "\"basicInfo\":{\"rmaCode\":\"RMA1\",\"status\":1,"
+ "\"statusName\":\"待收货\",\"relationNo\":\"ORD-1\","
+ "\"warehouseName\":\"美西1仓\",\"createTime\":1790568000000},"
+ "\"skuList\":[{\"skuCode\":\"ybtest\",\"skuNum\":\"2\"}]}}"));
WarehouseReturn ret = new EdayunAdapter(transport, new JacksonJsonCodec())
.getReturn(ctx(), "RMA1");
assertEquals("RMA1", ret.providerReturnId());
assertEquals("ORD-1", ret.returnRequestNo());
assertEquals(1, ret.lines().size());
assertTrue(transport.lastDataRequest().body().contains("\"rmaCode\":\"RMA1\""));
}
/** data=null 表示单号查不到,返回 null 而不是抛异常。 */
@Test
void missingDataReturnsNull() {
RecordingTransport transport = RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_RETURN_DETAIL,
req -> Responses.ok("{\"code\":200,\"msg\":\"操作成功\",\"data\":null}"));
assertNull(new EdayunAdapter(transport, new JacksonJsonCodec())
.getReturn(ctx(), "RMA-NOT-EXIST"));
}
}

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

@ -0,0 +1,205 @@ @@ -0,0 +1,205 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.ReturnDealMethod;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
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.assertTrue;
/**
* 创建退货单({@code /webApi/rma/info/v1/saveAndPublish})映射。
*
* <p>重点:统一模型只对应「自行退回」(returnType=2)、响应 data 就是退货单号、
* warehouseId 数字优先、只有「销毁」能确定码值。</p>
*/
class EdayunReturnTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx(String providerWarehouseId) {
return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, providerWarehouseId,
WarehouseConnection.of("https://test.example/openapi",
ChannelSecret.builder().appKey("k").appSecret("s")
.clientId("c").clientSecret("cs").build()),
"req-return", CLOCK);
}
private static ReturnCommand command(ReturnDealMethod method) {
return ReturnCommand.builder()
.returnRequestNo("RT-001")
.saleOrderNo("ORD599493019")
.returnTrackingNo("1Z84V7X00397803717")
.carrierCode("Fedex")
.warehouseId("2")
.remark("客户寄回")
.line("ybtest", 2, method)
.build();
}
// ------------------------------------------------------------ 请求
@Test
void mapsSelfShipReturn() {
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(command(ReturnDealMethod.WAREHOUSE_CONFIRM), "2");
// 统一模型有退货运单号,只对得上「自行退回」
assertEquals(Integer.valueOf(2), req.returnType);
assertEquals("ORD599493019", req.relationNo);
assertEquals("1Z84V7X00397803717", req.trackingNo);
assertEquals("Fedex", req.carrierName);
assertEquals("客户寄回", req.customerRemark);
assertEquals(Long.valueOf(2L), req.warehouseId);
assertNull(req.warehouseCode);
}
/** 没有销售订单号时退回我们的退货单号,relationNo 不能为空。 */
@Test
void relationNoFallsBackToReturnRequestNo() {
ReturnCommand cmd = ReturnCommand.builder()
.returnRequestNo("RT-002")
.saleOrderNo("ORD-X")
.returnTrackingNo("1Z1")
.carrierCode("UPS")
.line("sku", 1, ReturnDealMethod.DESTROY)
.build();
assertEquals("ORD-X",
EdayunReturnMapper.toRequest(cmd, "2").relationNo);
}
@Test
void nonNumericWarehouseGoesToWarehouseCode() {
ReturnCommand noWarehouse = ReturnCommand.builder()
.returnRequestNo("RT-003")
.saleOrderNo("ORD-X")
.returnTrackingNo("1Z1")
.carrierCode("UPS")
.line("sku", 1, ReturnDealMethod.DESTROY)
.build();
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(noWarehouse, "USLA");
assertEquals("USLA", req.warehouseCode);
assertNull(req.warehouseId);
}
/** 命令上的仓优先于账户配置。 */
@Test
void commandWarehouseWins() {
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(command(ReturnDealMethod.DESTROY), "99");
assertEquals(Long.valueOf(2L), req.warehouseId);
}
@Test
void mapsSkuLines() {
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(command(ReturnDealMethod.DESTROY), "2");
assertEquals(1, req.skus.size());
EdayunReturnDtos.SkuItem sku = req.skus.get(0);
assertEquals("ybtest", sku.skuCode);
assertEquals(Integer.valueOf(2), sku.skuNum);
assertEquals(Integer.valueOf(EdayunReturnMapper.COMMAND_DESTROY), sku.command);
}
/** 只有「销毁」能确定;其余三种统一取值都归「上架」。 */
@Test
void commandMappingOnlyDestroysOnDestroy() {
assertEquals(Integer.valueOf(2),
EdayunReturnMapper.commandOf(ReturnDealMethod.DESTROY));
assertEquals(Integer.valueOf(1),
EdayunReturnMapper.commandOf(ReturnDealMethod.CUSTOMER_PICKUP));
assertEquals(Integer.valueOf(1),
EdayunReturnMapper.commandOf(ReturnDealMethod.PHOTO_CONFIRM));
assertEquals(Integer.valueOf(1),
EdayunReturnMapper.commandOf(ReturnDealMethod.WAREHOUSE_CONFIRM));
assertNull(EdayunReturnMapper.commandOf(null));
}
// ------------------------------------------------------------ 响应
/** 每次业务调用前会先取 token,桩里要同时路由 /oauth/token。 */
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(EdayunConstants_path(), req -> Responses.ok(body));
}
private static String okBody(String rma) {
return "{\"code\":200,\"msg\":\"操作成功\",\"data\":\"" + rma + "\","
+ "\"traceId\":\"11d8888e0c7e4827\"}";
}
/** 响应 data 是字符串(退货单号),不是对象——直接落 providerReturnId。 */
@Test
void responseDataIsReturnOrderNo() {
RecordingTransport transport = stub(okBody("RMA2411053149"));
WarehouseReturn result = new EdayunAdapter(transport, new JacksonJsonCodec())
.create(ctx("2"), command(ReturnDealMethod.DESTROY));
assertEquals("RT-001", result.returnRequestNo());
assertEquals("RMA2411053149", result.providerReturnId());
assertEquals("ORD599493019", result.orderRef());
assertEquals("EDY-WH", result.warehouseCode());
assertEquals(ReturnStatus.UNKNOWN, result.status());
assertEquals(WarehouseProvider.EDAYUN, result.sourceProvider());
}
/** 请求体按 poNumber 之外的字段落地:确认发出去的是退货报文。 */
@Test
void sendsReturnRequest() {
RecordingTransport transport = stub(okBody("RMA1"));
new EdayunAdapter(transport, new JacksonJsonCodec())
.create(ctx("2"), command(ReturnDealMethod.DESTROY));
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"returnType\":2"), body);
assertTrue(body.contains("\"relationNo\":\"ORD599493019\""), body);
assertTrue(body.contains("\"trackingNo\":\"1Z84V7X00397803717\""), body);
assertTrue(body.contains("\"warehouseId\":2"), body);
assertTrue(body.contains("\"command\":2"), body);
}
/** 业务码失败要抛异常,不能当成建单成功。 */
@Test
void businessErrorFails() {
RecordingTransport transport = stub(
"{\"code\":500,\"msg\":\"自行退回[关联单号|跟踪号]不能为空!\",\"data\":null}");
try {
new EdayunAdapter(transport, new JacksonJsonCodec())
.create(ctx("2"), command(ReturnDealMethod.DESTROY));
org.junit.jupiter.api.Assertions.fail("should have thrown");
} catch (RuntimeException e) {
assertTrue(e.getMessage().contains("关联单号"), e.getMessage());
}
}
/** 文档里的路径常量集中在一处,测试直接引用。 */
private static String EdayunConstants_path() {
return common.ecommerce.edayun.EdayunConstants.PATH_RETURN_CREATE;
}
}

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

@ -0,0 +1,249 @@ @@ -0,0 +1,249 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
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.ReturnQueryNoType;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
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/rma/info/v1/selectRmaInfoList})映射。
*
* <p>重点:时间是字符串不是毫秒、orderNos 要配 orderNoSearchType、只能传一个状态、
* total 判断翻页。</p>
*/
class EdayunRmaListTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-13T00: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-return-list", CLOCK);
}
private static ReturnQuery.Builder base() {
return ReturnQuery.builder();
}
// ------------------------------------------------------------ 请求
/** 时间是 {@code yyyy-MM-dd HH:mm:ss} 字符串,不是毫秒。 */
@Test
void timeWindowIsFormattedString() {
EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
base().createdAfter(Instant.parse("2026-11-05T11:00:00Z"))
.createdBefore(Instant.parse("2026-11-06T11:00:00Z"))
.build(), "2", ZoneOffset.UTC, 1);
assertEquals("2026-11-05 11:00:00", req.createTimeStart);
assertEquals("2026-11-06 11:00:00", req.createTimeEnd);
}
/** 时间窗按仓方时区解释。 */
@Test
void timeWindowUsesWarehouseZone() {
EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
base().createdAfter(Instant.parse("2026-11-05T11:00:00Z"))
.createdBefore(Instant.parse("2026-11-05T12:00:00Z"))
.build(), null, java.time.ZoneId.of("America/Los_Angeles"), 1);
// 2026-11-01 夏令时结束,11/05 洛杉矶是 PST(UTC-8):UTC 11:00 → 03:00
assertEquals("2026-11-05 03:00:00", req.createTimeStart);
}
/** 不传时间窗时不下发,由仓方默认近一个月。 */
@Test
void noTimeWindowIsOmitted() {
EdayunRmaListDtos.SelectRmaListRequest req =
EdayunRmaListMapper.toRequest(base().build(), "2", ZoneOffset.UTC, 1);
assertNull(req.createTimeStart);
assertNull(req.createTimeEnd);
}
/** orderNos 必须配 orderNoSearchType;不传类型默认按退货单号。 */
@Test
void orderNoDefaultsToRmaCodeSearch() {
EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
base().orderNo("RMA1").build(), null, ZoneOffset.UTC, 1);
assertEquals("RMA1", req.orderNos);
assertEquals(Integer.valueOf(1), req.orderNoSearchType);
}
@Test
void orderNoTypesMap() {
assertEquals(Integer.valueOf(1),
EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PROVIDER_RETURN_NO));
assertEquals(Integer.valueOf(2),
EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.OUTBOUND_ORDER_NO));
assertEquals(Integer.valueOf(3),
EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PLATFORM_ORDER_NO));
}
@Test
void warehouseIdGoesNumeric() {
EdayunRmaListDtos.SelectRmaListRequest numeric =
EdayunRmaListMapper.toRequest(base().build(), "2", ZoneOffset.UTC, 1);
assertEquals(Long.valueOf(2L), numeric.warehouseId);
assertNull(numeric.warehouseCode);
EdayunRmaListDtos.SelectRmaListRequest byCode = EdayunRmaListMapper.toRequest(
base().warehouseCode("USLA").build(), null, ZoneOffset.UTC, 1);
assertEquals("USLA", byCode.warehouseCode);
assertNull(byCode.warehouseId);
}
/** 接口只支持单个状态;多状态要拆查询。 */
@Test
void multipleStatusesAreRejected() {
ReturnQuery two = base().status(ReturnStatus.RETURNING).status(ReturnStatus.COMPLETED).build();
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> EdayunRmaListMapper.toRequest(two, "2", ZoneOffset.UTC, 1));
assertTrue(ex.getMessage().contains("at most one status"), ex.getMessage());
}
@Test
void statusMapsToRawCode() {
assertEquals(Integer.valueOf(0), EdayunRmaListMapper.statusOf(ReturnStatus.DRAFT));
assertEquals(Integer.valueOf(1), EdayunRmaListMapper.statusOf(ReturnStatus.RETURNING));
assertEquals(Integer.valueOf(1), EdayunRmaListMapper.statusOf(ReturnStatus.PENDING_RECEIPT));
assertEquals(Integer.valueOf(5), EdayunRmaListMapper.statusOf(ReturnStatus.COMPLETED));
assertEquals(Integer.valueOf(-1), EdayunRmaListMapper.statusOf(ReturnStatus.CLOSED));
assertNull(EdayunRmaListMapper.statusOf(ReturnStatus.UNKNOWN));
}
/** 每页上限 200。 */
@Test
void pageSizeCappedAt200() {
assertEquals(Integer.valueOf(200), EdayunRmaListMapper.toRequest(
base().pageSize(1000).build(), null, ZoneOffset.UTC, 1).pageSize);
assertEquals(Integer.valueOf(100), EdayunRmaListMapper.toRequest(
base().build(), null, ZoneOffset.UTC, 1).pageSize);
}
// ------------------------------------------------------------ 响应
private static EdayunRmaListDtos.RmaRow row() {
EdayunRmaListDtos.RmaRow row = new EdayunRmaListDtos.RmaRow();
row.rmaCode = "RMA2411058099";
row.platformOrderCode = "102002";
row.ordOrderCode = "ORD822935302";
row.trackingNo = "ORD822935302";
row.warehouseName = "美西1仓";
row.warehouseId = 2L;
row.returnType = 0;
row.returnTypeName = "未妥投退回";
row.status = 6;
row.statusName = "处理中-等待指令";
row.createTime = 1730788454000L;
return row;
}
@Test
void mapsRowToReturn() {
WarehouseReturn ret = EdayunRmaListMapper.toReturn(row(), "EDY-WH");
assertEquals("RMA2411058099", ret.returnRequestNo());
assertEquals("RMA2411058099", ret.providerReturnId());
assertEquals("美西1仓", ret.warehouseCode());
assertEquals("102002", ret.orderRef());
assertEquals("未妥投退回", ret.type());
// 6 = 处理中-等待指令 → 待收货
assertEquals(ReturnStatus.PENDING_RECEIPT, ret.status());
assertEquals("处理中-等待指令", ret.rawStatus());
assertEquals(Instant.ofEpochMilli(1730788454000L), ret.createdAt());
assertEquals(WarehouseProvider.EDAYUN, ret.sourceProvider());
// 列表没有明细
assertTrue(ret.lines().isEmpty());
}
/** 真机会返回 warehouseCode,优先用它而不是仓名。 */
@Test
void prefersWarehouseCodeFromResponse() {
EdayunRmaListDtos.RmaRow r = row();
r.warehouseCode = "USLA";
assertEquals("USLA", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode());
}
/** 没有仓编码时回退仓名,再回退 OMS 仓编码。 */
@Test
void warehouseCodeFallsBackToOms() {
EdayunRmaListDtos.RmaRow r = row();
r.warehouseName = null;
assertEquals("EDY-WH", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode());
}
/** 没有平台单号时 orderRef 用出库单号。 */
@Test
void orderRefFallsBackToOutboundOrderNo() {
EdayunRmaListDtos.RmaRow r = row();
r.platformOrderCode = null;
assertEquals("ORD822935302", EdayunRmaListMapper.toReturn(r, "W").orderRef());
}
@Test
void nextCursorUsesTotal() {
assertEquals("2", EdayunRmaListMapper.nextCursor(250L, 1, 100, 100));
assertNull(EdayunRmaListMapper.nextCursor(250L, 3, 100, 50));
// total 缺失时按满页判断
assertEquals("2", EdayunRmaListMapper.nextCursor(null, 1, 100, 100));
}
@Test
void emptyRowsYieldEmptyPage() {
EdayunRmaListDtos.SelectRmaListResponse resp = new EdayunRmaListDtos.SelectRmaListResponse();
resp.total = 0L;
resp.rows = java.util.Collections.emptyList();
assertTrue(EdayunRmaListMapper.toPage(resp, "W", 1, 100).items().isEmpty());
}
// ------------------------------------------------------------ 门面
@Test
void adapterQueriesList() {
RecordingTransport transport = RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(common.ecommerce.edayun.EdayunConstants.PATH_RETURN_LIST,
req -> Responses.ok("{\"total\":1,\"code\":200,\"msg\":\"success\","
+ "\"rows\":[{\"rmaCode\":\"RMA1\",\"status\":5,"
+ "\"statusName\":\"已处理\",\"warehouseName\":\"美西1仓\","
+ "\"createTime\":1730788454000}]}"));
Page<WarehouseReturn> page = new EdayunAdapter(transport, new JacksonJsonCodec())
.queryReturns(ctx(), ReturnQuery.builder().pageSize(100).build());
assertEquals(1, page.size());
assertEquals("RMA1", page.items().get(0).providerReturnId());
assertTrue(transport.lastDataRequest().body().contains("\"pageNum\":1"));
}
}

158
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java

@ -0,0 +1,158 @@ @@ -0,0 +1,158 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunSkuLabelDtos;
import common.ecommerce.edayun.enums.EdayunSkuLabelPaper;
import common.ecommerce.warehouse.enums.LabelDownloadMode;
import common.ecommerce.warehouse.enums.LabelSizeType;
import common.ecommerce.warehouse.enums.LabelsPerPage;
import common.ecommerce.warehouse.model.BoxLabelCommand;
import common.ecommerce.warehouse.model.WarehouseLabel;
import org.junit.jupiter.api.Test;
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;
/**
* SKU 标打印({@code newPrintCaseMarkContentType})映射。
*
* <p>重点:码值不连续(4/2/5)、统一模型只能表达整单打印、
* Made in China 与分隔符默认关。</p>
*/
class EdayunSkuLabelTest {
private static BoxLabelCommand command(LabelSizeType size) {
return BoxLabelCommand.builder()
.providerInboundNo("REV0023116477")
.inboundRequestNo("IB-001")
.sizeType(size)
.labelsPerPage(LabelsPerPage.ONE)
.downloadMode(LabelDownloadMode.PDF)
.twoCopies(true)
.build();
}
// ------------------------------------------------------------ 纸张映射
/** 易达云码值不连续:100×100=4、100×150=2、A4=5。 */
@Test
void paperCodesAreNotSequential() {
assertEquals(4, EdayunSkuLabelPaper.SIZE_100_100.code());
assertEquals(2, EdayunSkuLabelPaper.SIZE_100_150.code());
assertEquals(5, EdayunSkuLabelPaper.A4.code());
}
@Test
void mapsCoreSizes() {
assertEquals(EdayunSkuLabelPaper.SIZE_100_100,
EdayunSkuLabelPaper.of(LabelSizeType.SIZE_100_100));
assertEquals(EdayunSkuLabelPaper.SIZE_100_150,
EdayunSkuLabelPaper.of(LabelSizeType.SIZE_100_150));
assertEquals(LabelSizeType.SIZE_100_100,
EdayunSkuLabelPaper.SIZE_100_100.core());
assertEquals(LabelSizeType.A4, EdayunSkuLabelPaper.A4.core());
}
/** 统一模型的 104×98(美国信纸)易达云不支持,要显式拒绝。 */
@Test
void unsupportedSizeIsRejected() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> EdayunSkuLabelPaper.of(LabelSizeType.SIZE_104_98));
assertTrue(ex.getMessage().contains("only 100x100 / 100x150 / A4"), ex.getMessage());
}
// ------------------------------------------------------------ 请求
@Test
void mapsWholeOrderPrint() {
EdayunSkuLabelDtos.PrintSkuLabelRequest req =
EdayunSkuLabelMapper.toRequest(command(LabelSizeType.SIZE_100_100));
assertEquals("REV0023116477", req.entryCode);
assertEquals(Integer.valueOf(4), req.pageSize);
assertEquals(Integer.valueOf(EdayunSkuLabelMapper.MADE_IN_CHINA_NO), req.madeInChina);
assertEquals(Boolean.FALSE, req.separation);
assertEquals(Integer.valueOf(1), req.twoPrint);
// 统一模型没有选箱字段,默认整单
assertNull(req.caseCodeList);
assertNull(req.skuCode);
assertNull(req.startCaseSerialNo);
}
/** 一箱一份时 twoPrint=0。 */
@Test
void singleCopyMapsZero() {
BoxLabelCommand one = BoxLabelCommand.builder()
.providerInboundNo("REV1").inboundRequestNo("IB-1")
.sizeType(LabelSizeType.SIZE_100_150)
.labelsPerPage(LabelsPerPage.ONE)
.build();
assertEquals(Integer.valueOf(0), EdayunSkuLabelMapper.toRequest(one).twoPrint);
}
/** Made in China 与分隔符是易达云特有语义,统一模型没有 → 默认关。 */
@Test
void madeInChinaAndSeparationDefaultOff() {
EdayunSkuLabelDtos.PrintSkuLabelRequest req =
EdayunSkuLabelMapper.toRequest(command(LabelSizeType.SIZE_100_150));
assertEquals(Integer.valueOf(0), req.madeInChina);
assertEquals(Boolean.FALSE, req.separation);
}
// ------------------------------------------------------------ 选箱
@Test
void mapsCaseCodes() {
EdayunSkuLabelMapper.CaseSelection sel = new EdayunSkuLabelMapper.CaseSelection()
.caseCodes(java.util.Arrays.asList("B001", "B002"));
EdayunSkuLabelDtos.PrintSkuLabelRequest req = EdayunSkuLabelMapper.toRequest(
command(LabelSizeType.SIZE_100_100), sel);
assertEquals(java.util.Arrays.asList("B001", "B002"), req.caseCodeList);
}
@Test
void mapsRangesAndSku() {
EdayunSkuLabelMapper.CaseSelection sel = new EdayunSkuLabelMapper.CaseSelection()
.skuCode("SKU-1")
.caseSerialRange("1", "2")
.sellerCaseRange("S1", "S2");
EdayunSkuLabelDtos.PrintSkuLabelRequest req = EdayunSkuLabelMapper.toRequest(
command(LabelSizeType.A4), sel);
assertEquals("SKU-1", req.skuCode);
assertEquals("1", req.startCaseSerialNo);
assertEquals("2", req.endCaseSerialNo);
assertEquals("S1", req.startSellerCaseNo);
assertEquals("S2", req.endSellerCaseNo);
// A4 码值是 5
assertEquals(Integer.valueOf(5), req.pageSize);
}
/** 选箱条件全空时本地拒——仓方要求四选一。 */
@Test
void emptySelectionIsRejected() {
assertThrows(IllegalArgumentException.class,
() -> EdayunSkuLabelMapper.toRequest(command(LabelSizeType.SIZE_100_100),
new EdayunSkuLabelMapper.CaseSelection()));
assertThrows(IllegalArgumentException.class,
() -> EdayunSkuLabelMapper.toRequest(command(LabelSizeType.SIZE_100_100), null));
}
// ------------------------------------------------------------ 响应
/** 响应 data 是 PDF 地址,同步返回(不是任务号)。 */
@Test
void labelCarriesUrl() {
WarehouseLabel label = EdayunSkuLabelMapper.toLabel("https://oss/case.pdf");
assertEquals("https://oss/case.pdf", label.url());
assertEquals("PDF", label.format());
assertNull(label.contentBase64());
}
}

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

@ -0,0 +1,217 @@ @@ -0,0 +1,217 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunTrackDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
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 java.util.Arrays;
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;
/**
* 物流轨迹({@code /webApi/track/getTrackInfoList})映射。
*
* <p>重点:请求体是纯字符串数组、上网/妥投时间是带时区的字符串、
* 「未匹配到轨迹」按空结果处理。</p>
*/
class EdayunTrackTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00: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-track", 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_TRACK,
req -> Responses.ok(body));
}
// ------------------------------------------------------------ 请求
/** 请求体是纯字符串数组,不是包装对象。 */
@Test
void requestBodyIsPlainArray() {
List<String> body = EdayunTrackMapper.toRequest(Arrays.asList("1Z111", " 1Z222 "));
assertEquals(Arrays.asList("1Z111", "1Z222"), body);
assertTrue(new JacksonJsonCodec().toJson(body).startsWith("["));
}
@Test
void blankTrackingNumbersRejected() {
assertThrows(IllegalArgumentException.class,
() -> EdayunTrackMapper.toRequest(null));
assertThrows(IllegalArgumentException.class,
() -> EdayunTrackMapper.toRequest(java.util.Collections.<String>emptyList()));
assertThrows(IllegalArgumentException.class,
() -> EdayunTrackMapper.toRequest(Arrays.asList(" ", "")));
}
// ------------------------------------------------------------ 响应
private static EdayunTrackDtos.Track track() {
EdayunTrackDtos.TrackDetail detail = new EdayunTrackDtos.TrackDetail();
detail.trackingNo = "LF-1741871641090";
detail.status = 1;
detail.recentDescribe = "上网";
detail.recentDescribeTime = 1741145821000L;
detail.eventStatus = "IN_TRANSIT";
EdayunTrackDtos.Track track = new EdayunTrackDtos.Track();
track.trackId = 123L;
track.trackingNo = "LF-1741871641090";
track.status = 1;
track.carrierName = "fedex";
track.startCountryName = "中国";
track.endCountryName = "美国";
track.receiver = "123";
track.trackDetaillVoList = java.util.Collections.singletonList(detail);
track.onlineTime = "2025-08-19 08:17:00";
track.deliveredTime = "2025-08-20 10:00:00";
track.timeZone = "GMT-04:00";
return track;
}
@Test
void mapsTrackingInfo() {
TrackingInfo info = EdayunTrackMapper.toTrackingInfo(track());
assertEquals("LF-1741871641090", info.trackingNumber());
assertEquals("fedex", info.carrier());
assertEquals("1", info.status());
assertEquals("123", 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());
assertEquals(1, info.events().size());
}
/** 节点状态优先用 eventStatus,缺失才退回数字码。 */
@Test
void eventStatusFallsBackToCode() {
EdayunTrackDtos.Track t = track();
t.trackDetaillVoList.get(0).eventStatus = null;
assertEquals("1", EdayunTrackMapper.toTrackEvents(t).get(0).status());
t.trackDetaillVoList.get(0).eventStatus = "DELIVERED";
assertEquals("DELIVERED", EdayunTrackMapper.toTrackEvents(t).get(0).status());
}
@Test
void mapsEvents() {
List<TrackEvent> events = EdayunTrackMapper.toTrackEvents(track());
assertEquals(1, events.size());
TrackEvent e = events.get(0);
assertEquals("LF-1741871641090", e.trackingNumber());
assertEquals("fedex", e.carrier());
assertEquals("上网", e.description());
assertEquals(Instant.ofEpochMilli(1741145821000L), e.occurredAt());
}
/** 时间字符串解析失败留 null,不抛异常。 */
@Test
void unparsableTimesStayNull() {
EdayunTrackDtos.Track t = track();
t.onlineTime = "not-a-time";
t.deliveredTime = null;
TrackingInfo info = EdayunTrackMapper.toTrackingInfo(t);
assertNull(info.firstOnlineAt());
assertNull(info.deliveredAt());
}
/** 时区偏移解析:GMT±HH:mm、UTC±HH:mm、空值。 */
@Test
void zoneParsing() {
assertEquals(ZoneOffset.of("-04:00"), EdayunTrackMapper.zoneOf("GMT-04:00"));
assertEquals(ZoneOffset.of("+08:00"), EdayunTrackMapper.zoneOf("UTC+08:00"));
assertEquals(ZoneOffset.of("+08:00"), EdayunTrackMapper.zoneOf("+08:00"));
assertEquals(ZoneOffset.UTC, EdayunTrackMapper.zoneOf(null));
assertEquals(ZoneOffset.UTC, EdayunTrackMapper.zoneOf("bogus"));
}
/** 一次查多个跟踪号时按单号精确匹配。 */
@Test
void findMatchesByTrackingNumber() {
EdayunTrackDtos.Track other = track();
other.trackingNo = "OTHER-1";
EdayunTrackDtos.GetTrackResponse resp = new EdayunTrackDtos.GetTrackResponse();
resp.code = 200;
resp.data = Arrays.asList(other, track());
assertEquals("LF-1741871641090",
EdayunTrackMapper.find(resp, "lf-1741871641090").trackingNo);
assertNull(EdayunTrackMapper.find(resp, "NOPE"));
assertNull(EdayunTrackMapper.find(null, "X"));
}
// ------------------------------------------------------------ 门面
@Test
void adapterTracksShipment() {
RecordingTransport transport = stub("{\"code\":200,\"msg\":\"ok\",\"data\":[{"
+ "\"trackingNo\":\"LF-1\",\"status\":1,\"carrierName\":\"fedex\","
+ "\"onlineTime\":\"2025-08-19 08:17:00\",\"deliveredTime\":null,"
+ "\"timeZone\":\"GMT+08:00\",\"trackDetaillVoList\":["
+ "{\"recentDescribe\":\"上网\",\"recentDescribeTime\":1741145821000}]}]}");
TrackingInfo info = new EdayunAdapter(transport, new JacksonJsonCodec())
.trackShipment(ctx(), "LF-1");
assertEquals("LF-1", info.trackingNumber());
assertEquals(Instant.parse("2025-08-19T00:17:00Z"), info.firstOnlineAt());
assertNull(info.deliveredAt());
// 请求体是纯数组
assertEquals("[\"LF-1\"]", transport.lastDataRequest().body());
}
/**
* 「未匹配到轨迹」是「还没轨迹」,不是调用失败:返回空列表 / null,不抛异常。
*/
@Test
void noTrackFoundYieldsEmpty() {
RecordingTransport transport = stub(
"{\"code\":500,\"msg\":\"未匹配到轨迹\",\"data\":null}");
assertTrue(new EdayunAdapter(transport, new JacksonJsonCodec())
.track(ctx(), "NOPE").isEmpty());
assertNull(new EdayunAdapter(transport, new JacksonJsonCodec())
.trackShipment(ctx(), "NOPE"));
}
/** 其它业务错误仍要抛异常。 */
@Test
void otherErrorsStillThrow() {
RecordingTransport transport = stub("{\"code\":500,\"msg\":\"系统异常\"}");
assertThrows(RuntimeException.class,
() -> new EdayunAdapter(transport, new JacksonJsonCodec()).track(ctx(), "X"));
}
}

184
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunWarehouseTest.java

@ -0,0 +1,184 @@ @@ -0,0 +1,184 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunWarehouseDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Test;
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.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 仓库清单({@code listActive} / {@code listWarehouseHasPerm})。
*
* <p>重点:-999(智能分仓)要跳过、warehouseCode 用仓编码不是数字 id、
* listActive 与 listWarehouseHasPerm 用途不同。</p>
*/
class EdayunWarehouseTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00: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-wh", CLOCK);
}
private static RecordingTransport stub(String path, String body) {
return RecordingTransport.create()
.route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok(
"{\"access_token\":\"T1\",\"token_type\":\"bearer\"}"))
.route(path, req -> Responses.ok(body));
}
// ------------------------------------------------------------ 请求
/** 头程 / 尾程映射到 1 / 0。 */
@Test
void operationTypeMaps() {
assertEquals(Integer.valueOf(1),
EdayunWarehouseMapper.toListActiveRequest(true).warehouseOperationType);
assertEquals(Integer.valueOf(0),
EdayunWarehouseMapper.toListActiveRequest(false).warehouseOperationType);
}
// ------------------------------------------------------------ 响应
private static EdayunWarehouseDtos.WarehouseRow row() {
EdayunWarehouseDtos.WarehouseRow r = new EdayunWarehouseDtos.WarehouseRow();
r.warehouseId = "2";
r.warehouseName = "美西1仓";
r.warehouseNameEn = "Los Angeles Warehouse";
r.warehouseCode = "USLA";
r.warehouseLocationCode = "WH-2";
r.countryCode = "US";
r.address = "1251 S Rockefeller Ave, Unit B";
r.warehouseRegionType = 0;
r.timeZone = "America/Los_Angeles";
return r;
}
private static EdayunWarehouseDtos.WarehouseRow sentinel() {
EdayunWarehouseDtos.WarehouseRow r = new EdayunWarehouseDtos.WarehouseRow();
r.warehouseId = "-999";
r.warehouseName = "使用分仓规则";
r.warehouseNameEn = "divideWarehouse";
r.warehouseCode = "USMC";
return r;
}
@Test
void mapsFacility() {
WarehouseFacility f = EdayunWarehouseMapper.toFacility(row());
// 统一模型的口径:warehouseCode 是仓编码,数字 id 进 providerWarehouseId
assertEquals("USLA", f.warehouseCode());
assertEquals("2", f.providerWarehouseId());
assertEquals("美西1仓", f.name());
assertEquals("US", f.country());
assertEquals("1251 S Rockefeller Ave, Unit B", f.address1());
assertEquals(WarehouseProvider.EDAYUN, f.sourceProvider());
// 权限内接口没有 zipCode / 负责人
assertNull(f.postcode());
assertNull(f.contactName());
}
/** listActive 多给的字段也要能映射。 */
@Test
void mapsExtraFieldsFromListActive() {
EdayunWarehouseDtos.WarehouseRow r = row();
r.provinceCode = "US01";
r.cityName = "Los Angeles";
r.zipCode = "91761";
r.warehouseManagerName = "Bo-LA6";
r.warehouseManagerTel = "1234567";
WarehouseFacility f = EdayunWarehouseMapper.toFacility(r);
assertEquals("US01", f.province());
assertEquals("US01", f.state());
assertEquals("Los Angeles", f.city());
assertEquals("91761", f.postcode());
assertEquals("Bo-LA6", f.contactName());
assertEquals("1234567", f.mobilePhone());
}
/** -999 是「使用分仓规则」的哨兵值,不是真实仓。 */
@Test
void smartSplitSentinelIsSkipped() {
List<WarehouseFacility> list = EdayunWarehouseMapper.toFacilities(
java.util.Arrays.asList(row(), sentinel()));
assertEquals(1, list.size());
assertEquals("USLA", list.get(0).warehouseCode());
}
/** 没有仓编码的行跳过——统一模型要求 warehouseCode 非空。 */
@Test
void rowsWithoutCodeAreSkipped() {
EdayunWarehouseDtos.WarehouseRow bad = row();
bad.warehouseCode = " ";
assertEquals(1, EdayunWarehouseMapper.toFacilities(
java.util.Arrays.asList(bad, row())).size());
assertNull(EdayunWarehouseMapper.toFacility(null));
}
@Test
void emptyRowsYieldEmptyList() {
assertTrue(EdayunWarehouseMapper.toFacilities(null).isEmpty());
assertTrue(EdayunWarehouseMapper.toFacilities(
java.util.Collections.<EdayunWarehouseDtos.WarehouseRow>emptyList()).isEmpty());
}
// ------------------------------------------------------------ 门面
@Test
void adapterQueriesPermittedWarehouses() {
RecordingTransport transport = stub(
common.ecommerce.edayun.EdayunConstants.PATH_WAREHOUSE_PERMITTED,
"{\"code\":200,\"msg\":\"操作成功\",\"data\":["
+ "{\"warehouseId\":\"2\",\"warehouseName\":\"美西1仓\","
+ "\"warehouseCode\":\"USLA\",\"countryCode\":\"US\"},"
+ "{\"warehouseId\":\"-999\",\"warehouseName\":\"使用分仓规则\","
+ "\"warehouseCode\":\"USMC\"}]}");
List<WarehouseFacility> list = new EdayunAdapter(transport, new JacksonJsonCodec())
.warehouses(ctx());
assertEquals(1, list.size());
assertEquals("USLA", list.get(0).warehouseCode());
}
/** listActive 要带 warehouseOperationType,且同样跳过 -999。 */
@Test
void adapterQueriesActiveWarehouses() {
RecordingTransport transport = stub(
common.ecommerce.edayun.EdayunConstants.PATH_WAREHOUSE_ACTIVE,
"{\"code\":200,\"msg\":\"操作成功\",\"data\":["
+ "{\"warehouseId\":\"40222\",\"warehouseName\":\"上海浦东新区实体仓\","
+ "\"warehouseCode\":\"LS1130\",\"warehouseOperationType\":1}]}");
List<WarehouseFacility> list = new EdayunAdapter(transport, new JacksonJsonCodec())
.activeWarehouses(ctx(), true);
assertEquals(1, list.size());
assertEquals("LS1130", list.get(0).warehouseCode());
assertTrue(transport.lastDataRequest().body()
.contains("\"warehouseOperationType\":1"));
}
}

121
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunBolProbeTest.java

@ -0,0 +1,121 @@ @@ -0,0 +1,121 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunBolMapper;
import common.ecommerce.edayun.adapter.EdayunLogisticsProductMapper;
import common.ecommerce.edayun.dto.EdayunBolDtos;
import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos;
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.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.BolDocument;
import common.ecommerce.warehouse.model.LogisticsProduct;
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.List;
import java.util.UUID;
/**
* BOL + 物流产品联调探针:<b>只读</b>,不会在仓侧产生任何数据。
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.bol=true -Dtest=EdayunBolProbeTest test
*
* # 真查(只读)
* ... -Dedayun.probe.bol=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* [-Dedayun.probe.warehouseId=2] [-Dedayun.probe.orderNo=FBA473182144]
* </pre>
*/
@EnabledIfSystemProperty(named = "edayun.probe.bol", matches = "true")
class EdayunBolProbeTest {
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 WAREHOUSE_ID = System.getProperty("edayun.probe.warehouseId", "");
private static final String ORDER_NO = opt("edayun.probe.orderNo", "FBA473182144");
private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probeBolAndProducts() {
EdayunBolDtos.GetBolRequest bolBody = EdayunBolMapper.toRequest(ORDER_NO);
EdayunLogisticsProductDtos.ListProductRequest lpBody =
EdayunLogisticsProductMapper.toRequest(emptyToNull(WAREHOUSE_ID), 1);
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_BOL_LIST + " ================");
System.out.println("[request] " + new JacksonJsonCodec().toJson(bolBody));
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_LOGISTICS_PRODUCTS + " ================");
System.out.println("[request] " + new JacksonJsonCodec().toJson(lpBody));
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,
emptyToNull(WAREHOUSE_ID),
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());
List<BolDocument> bols = adapter.orderBols(ctx, ORDER_NO);
System.out.println("[OK] bols=" + bols.size());
for (BolDocument b : bols) {
System.out.println(" " + b.bolCode() + " status=" + b.rawStatus()
+ "/" + b.statusName() + " pickup=" + b.scheduledPickupDate()
+ " qty=" + b.scheduledPickupQuantity()
+ " tracking=" + b.trackingNo());
System.out.println(" file=" + b.fileUrl());
}
List<LogisticsProduct> products = adapter.products(ctx, null);
System.out.println("[OK] logisticsProducts=" + products.size());
for (int i = 0; i < Math.min(5, products.size()); i++) {
LogisticsProduct p = products.get(i);
System.out.println(" " + p.logisticsProductCode() + " " + p.logisticsProductName());
}
} 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;
}
private static String emptyToNull(String v) {
return v == null || v.trim().isEmpty() ? null : v.trim();
}
}

117
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCarrierProbeTest.java

@ -0,0 +1,117 @@ @@ -0,0 +1,117 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunCarrierMapper;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
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.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseCarrier;
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.List;
import java.util.UUID;
/**
* 承运商清单联调探针:<b>只读</b>。
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.carrier=true -Dtest=EdayunCarrierProbeTest test
*
* # 真查(只读)
* ... -Dedayun.probe.carrier=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* [-Dedayun.probe.warehouseId=2] [-Dedayun.probe.country=US]
* </pre>
*/
@EnabledIfSystemProperty(named = "edayun.probe.carrier", matches = "true")
class EdayunCarrierProbeTest {
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 WAREHOUSE_ID = System.getProperty("edayun.probe.warehouseId", "");
private static final String COUNTRY = System.getProperty("edayun.probe.country", "");
private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probeCarriers() {
EdayunCarrierDtos.ListCarrierRequest req = EdayunCarrierMapper.toRequest(
emptyToNull(WAREHOUSE_ID), emptyToNull(COUNTRY));
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_CARRIERS + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL
+ " warehouseId=" + mask(WAREHOUSE_ID) + " country=" + COUNTRY);
System.out.println("[request] " + new JacksonJsonCodec().toJson(req));
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,
emptyToNull(WAREHOUSE_ID),
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());
List<WarehouseCarrier> carriers = adapter.carrierDirectory(ctx);
System.out.println("[OK] carriers=" + carriers.size());
for (WarehouseCarrier c : carriers) {
System.out.println(" " + c.carrierId() + " " + c.displayName()
+ " logistics=" + c.logists().size());
for (WarehouseCarrier.OwnLogistic l : c.logists()) {
System.out.println(" - " + l.logisticId() + " " + l.name());
}
}
} 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;
}
private static String emptyToNull(String v) {
return v == null || v.trim().isEmpty() ? null : v.trim();
}
private static String mask(String v) {
if (v == null || v.trim().isEmpty()) {
return "(empty)";
}
String t = v.trim();
return t.length() <= 6 ? "***" : t.substring(0, 3) + "***" + t.substring(t.length() - 2);
}
}

104
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCaseMarkProbeTest.java

@ -0,0 +1,104 @@ @@ -0,0 +1,104 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunCaseMarkMapper;
import common.ecommerce.edayun.dto.EdayunCaseMarkDtos;
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.warehouse.enums.CaseMarkPaperSize;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
import common.ecommerce.warehouse.model.WarehouseLabel;
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.UUID;
/**
* 箱唛打印联调探针:<b>只读</b>(生成 PDF,不改仓侧业务数据)。
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.barcode=true -Dtest=EdayunBarcodeProbeTest test
*
* # 真跑
* ... -Dedayun.probe.barcode=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* [-Dedayun.probe.sku=ybtest]
* </pre>
*/
@EnabledIfSystemProperty(named = "edayun.probe.barcode", matches = "true")
class EdayunCaseMarkProbeTest {
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 = opt("edayun.probe.sku", "ybtest");
private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probePrintBarcode() {
CaseMarkPrintCommand cmd = CaseMarkPrintCommand.builder()
.paperSize(CaseMarkPaperSize.SIZE_60_40)
.remark("PROBE")
.printSkuName(true)
.item(SKU, 1)
.build();
EdayunCaseMarkDtos.PrintCaseMarkRequest req = EdayunCaseMarkMapper.toRequest(cmd);
String bodyJson = new JacksonJsonCodec().toJson(req);
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_CASE_MARK_PRINT + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL + " sku=" + SKU);
System.out.println("[request] " + bodyJson);
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, null,
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());
WarehouseLabel label = adapter.printCaseMarks(ctx, cmd);
System.out.println("[OK] labelId=" + label.labelId() + " format=" + label.format()
+ " url=" + label.url());
} 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;
}
}

163
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunCreateOrderProbeTest.java

@ -0,0 +1,163 @@ @@ -0,0 +1,163 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunOrderMapper;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.model.Platform;
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.OutboundReceipt;
import common.ecommerce.warehouse.model.ShipTo;
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.time.Instant;
import java.util.UUID;
/**
* 创建出库单探针:默认只打印报文,<b>不联网</b>。
*
* <p>创建出库单是<b>写操作</b>,会真实建单并向仓方下发发货任务,所以真跑要显式加
* {@code -Dedayun.probe.write=true};平台单号用 {@code PROBE-} 前缀的时间戳避免撞车。</p>
*
* <pre>
* # 只看报文(安全)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.order=true -Dtest=EdayunCreateOrderProbeTest test
*
* # 真发一次(会在测试仓建单)
* ... -Dedayun.probe.order=true -Dedayun.probe.write=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* -Dedayun.probe.warehouseId=2 -Dedayun.probe.sku=ybtest
* </pre>
*
* <p>建单成功后记下响应里的 {@code orderNo},取消时要用它。
* 写操作不可逆,跑之前请确认这是测试仓。</p>
*/
@EnabledIfSystemProperty(named = "edayun.probe.order", matches = "true")
class EdayunCreateOrderProbeTest {
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 WAREHOUSE_ID = System.getProperty("edayun.probe.warehouseId", "");
private static final String SKU = opt("edayun.probe.sku", "ybtest");
private static final boolean WRITE = Boolean.getBoolean("edayun.probe.write");
@Test
void probeCreateOrder() {
String poNumber = "PROBE-"
+ Long.toString(System.currentTimeMillis(), 36).toUpperCase();
OutboundCommand cmd = OutboundCommand.builder()
.outboundRequestNo("OB-" + poNumber)
.orderRef(poNumber)
.warehouseId(emptyToNull(WAREHOUSE_ID))
.labelMode(LabelMode.WAREHOUSE_LABEL)
.carrier("FedEx")
.salesPlatform(Platform.AMAZON_SC)
.currency("USD")
.declaredTotal(Money.of("19.99", "USD"))
.latestShipDate(Instant.now().plusSeconds(7 * 24 * 3600))
// 地址:易达云要州全称
.shipTo(ShipTo.builder()
.name("Probe Buyer")
.phone("+1-555-0100")
.email("probe@example.com")
.countryCode("US")
.stateOrProvince("California")
.city("Escondido")
.addressLine1("1308 E Washington Ave")
.postalCode("92027")
.build())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku(SKU)
.quantity(1)
.declareValue(Money.of("19.99", "USD"))
.insuredAmount(Money.of("19.99", "USD"))
.build())
.signatureRequired(Boolean.TRUE)
.build();
EdayunCreateOrderDtos.CreateOrderRequest req =
EdayunOrderMapper.toCreateRequest(cmd, emptyToNull(WAREHOUSE_ID));
String bodyJson = new JacksonJsonCodec().toJson(req);
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_ORDER_CREATE + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL
+ " warehouseId=" + mask(WAREHOUSE_ID) + " sku=" + mask(SKU)
+ " poNumber=" + poNumber);
System.out.println("[request] " + bodyJson);
if (!APP_SECRET.trim().isEmpty()) {
System.out.println("[sign] " + common.ecommerce.edayun.http.EdayunRequestFactory
.sign(bodyJson, APP_SECRET));
}
Assumptions.assumeTrue(WRITE, "dry-run:未加 -Dedayun.probe.write=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,
emptyToNull(WAREHOUSE_ID),
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)"),
new JacksonJsonCodec());
OutboundReceipt receipt = adapter.create(ctx, cmd);
System.out.println("[OK] outboundRequestNo=" + receipt.outboundRequestNo()
+ " providerOrderId=" + receipt.providerOrderId());
} 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;
}
private static String emptyToNull(String v) {
return v == null || v.trim().isEmpty() ? null : v.trim();
}
private static String mask(String v) {
if (v == null || v.trim().isEmpty()) {
return "(empty)";
}
String t = v.trim();
return t.length() <= 6 ? "***" : t.substring(0, 3) + "***" + t.substring(t.length() - 2);
}
}

141
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunReturnProbeTest.java

@ -0,0 +1,141 @@ @@ -0,0 +1,141 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunReturnMapper;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
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.warehouse.enums.ReturnDealMethod;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
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.UUID;
/**
* 创建退货单探针:默认只打印报文,<b>不联网</b>。
*
* <p>创建退货单是<b>写操作</b>,会真实建 RMA 单,所以真跑要显式加
* {@code -Dedayun.probe.write=true},并且{@code relationNo} 必须是一个真实存在的
* 出库单号(仓方要按它找原单)。</p>
*
* <pre>
* # 只看报文(安全)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.return=true -Dtest=EdayunReturnProbeTest test
*
* # 真发一次(会在测试仓建退货单)
* ... -Dedayun.probe.return=true -Dedayun.probe.write=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* -Dedayun.probe.warehouseId=2 -Dedayun.probe.sku=ybtest \
* -Dedayun.probe.relationNo=ORD599493019 \
* -Dedayun.probe.trackingNo=1Z84V7X00397803717
* </pre>
*/
@EnabledIfSystemProperty(named = "edayun.probe.return", matches = "true")
class EdayunReturnProbeTest {
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 WAREHOUSE_ID = System.getProperty("edayun.probe.warehouseId", "");
private static final String SKU = opt("edayun.probe.sku", "ybtest");
private static final String RELATION_NO = opt("edayun.probe.relationNo", "ORD599493019");
private static final String TRACKING_NO =
opt("edayun.probe.trackingNo", "1Z84V7X00397803717");
private static final boolean WRITE = Boolean.getBoolean("edayun.probe.write");
@Test
void probeCreateReturn() {
String returnRequestNo = "PROBE-RT-"
+ Long.toString(System.currentTimeMillis(), 36).toUpperCase();
ReturnCommand cmd = ReturnCommand.builder()
.returnRequestNo(returnRequestNo)
.saleOrderNo(RELATION_NO)
.returnTrackingNo(TRACKING_NO)
.carrierCode("Fedex")
.warehouseId(emptyToNull(WAREHOUSE_ID))
.remark("probe")
.line(SKU, 1, ReturnDealMethod.WAREHOUSE_CONFIRM)
.build();
EdayunReturnDtos.SaveReturnRequest req =
EdayunReturnMapper.toRequest(cmd, emptyToNull(WAREHOUSE_ID));
String bodyJson = new JacksonJsonCodec().toJson(req);
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_RETURN_CREATE + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL
+ " warehouseId=" + mask(WAREHOUSE_ID)
+ " relationNo=" + RELATION_NO + " trackingNo=" + mask(TRACKING_NO));
System.out.println("[request] " + bodyJson);
if (!APP_SECRET.trim().isEmpty()) {
System.out.println("[sign] " + common.ecommerce.edayun.http.EdayunRequestFactory
.sign(bodyJson, APP_SECRET));
}
Assumptions.assumeTrue(WRITE, "dry-run:未加 -Dedayun.probe.write=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,
emptyToNull(WAREHOUSE_ID),
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)"),
new JacksonJsonCodec());
WarehouseReturn result = adapter.create(ctx, cmd);
System.out.println("[OK] returnRequestNo=" + result.returnRequestNo()
+ " providerReturnId=" + result.providerReturnId()
+ " status=" + result.status());
} 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;
}
private static String emptyToNull(String v) {
return v == null || v.trim().isEmpty() ? null : v.trim();
}
private static String mask(String v) {
if (v == null || v.trim().isEmpty()) {
return "(empty)";
}
String t = v.trim();
return t.length() <= 6 ? "***" : t.substring(0, 3) + "***" + t.substring(t.length() - 2);
}
}

141
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunRmaListProbeTest.java

@ -0,0 +1,141 @@ @@ -0,0 +1,141 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunRmaListMapper;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
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.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
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.time.Duration;
import java.time.Instant;
import java.util.UUID;
/**
* 退货单列表联调探针:<b>只读</b>,不会在仓侧产生任何数据。
*
* <p>默认跳过,用 {@code -Dedayun.probe.rmaList=true} 开启;凭据走系统属性,
* <b>真实值不入库</b>:</p>
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.rmaList=true -Dtest=EdayunRmaListProbeTest test
*
* # 真查(只读)
* ... -Dedayun.probe.rmaList=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* [-Dedayun.probe.warehouseId=2] [-Dedayun.probe.days=30] [-Dedayun.probe.page=1]
* </pre>
*
* <p>异常只打印不抛出,便于一次跑完对照真实报文。</p>
*/
@EnabledIfSystemProperty(named = "edayun.probe.rmaList", matches = "true")
class EdayunRmaListProbeTest {
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 WAREHOUSE_ID = System.getProperty("edayun.probe.warehouseId", "");
private static final int DAYS = Integer.getInteger("edayun.probe.days", 30);
private static final int PAGE = Integer.getInteger("edayun.probe.page", 1);
private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probeRmaList() {
Instant end = Instant.now();
Instant begin = end.minus(Duration.ofDays(DAYS));
ReturnQuery query = ReturnQuery.builder()
.createdAfter(begin)
.createdBefore(end)
.cursor(PAGE <= 1 ? null : String.valueOf(PAGE))
.pageSize(100)
.build();
EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest(
query, emptyToNull(WAREHOUSE_ID), java.time.ZoneOffset.UTC, PAGE);
String bodyJson = new JacksonJsonCodec().toJson(req);
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_RETURN_LIST + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL
+ " warehouseId=" + mask(WAREHOUSE_ID)
+ " days=" + DAYS + " page=" + PAGE);
System.out.println("[request] " + bodyJson);
if (!APP_SECRET.trim().isEmpty()) {
System.out.println("[sign] " + common.ecommerce.edayun.http.EdayunRequestFactory
.sign(bodyJson, APP_SECRET));
}
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,
emptyToNull(WAREHOUSE_ID),
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<WarehouseReturn> page = adapter.queryReturns(ctx, query);
System.out.println("[OK] rows=" + page.size() + " hasMore=" + page.hasMore()
+ " nextCursor=" + page.nextCursor());
for (WarehouseReturn r : page.items()) {
System.out.println(" " + r.providerReturnId() + " " + r.status()
+ " raw=" + r.rawStatus() + " warehouse=" + r.warehouseCode()
+ " orderRef=" + r.orderRef() + " createdAt=" + r.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;
}
private static String emptyToNull(String v) {
return v == null || v.trim().isEmpty() ? null : v.trim();
}
private static String mask(String v) {
if (v == null || v.trim().isEmpty()) {
return "(empty)";
}
String t = v.trim();
return t.length() <= 6 ? "***" : t.substring(0, 3) + "***" + t.substring(t.length() - 2);
}
}

115
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunTrackProbeTest.java

@ -0,0 +1,115 @@ @@ -0,0 +1,115 @@
package common.ecommerce.edayun.probe;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.adapter.EdayunAdapter;
import common.ecommerce.edayun.adapter.EdayunTrackMapper;
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.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
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.Collections;
import java.util.UUID;
/**
* 物流轨迹联调探针:<b>只读</b>,不会在仓侧产生任何数据。
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.track=true -Dtest=EdayunTrackProbeTest test
*
* # 真查(只读)
* ... -Dedayun.probe.track=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
* -Dedayun.probe.trackingNo=1Z84V7X00397803717
* </pre>
*/
@EnabledIfSystemProperty(named = "edayun.probe.track", matches = "true")
class EdayunTrackProbeTest {
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 TRACKING_NO =
opt("edayun.probe.trackingNo", "1Z84V7X00397803717");
private static final boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probeTrack() {
String bodyJson = new JacksonJsonCodec().toJson(
EdayunTrackMapper.toRequest(Collections.singletonList(TRACKING_NO)));
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_TRACK + " ================");
System.out.println("[probe] baseUrl=" + BASE_URL + " trackingNo=" + mask(TRACKING_NO));
System.out.println("[request] " + bodyJson);
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, null,
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());
TrackingInfo info = adapter.trackShipment(ctx, TRACKING_NO);
if (info == null) {
System.out.println("[EMPTY] 仓方未匹配到轨迹");
return;
}
System.out.println("[OK] " + info.trackingNumber() + " carrier=" + info.carrier()
+ " status=" + info.status()
+ " online=" + info.firstOnlineAt() + " delivered=" + info.deliveredAt()
+ " events=" + info.events().size());
for (TrackEvent e : info.events()) {
System.out.println(" " + e.occurredAt() + " [" + e.status() + "] "
+ e.description());
}
} 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;
}
private static String mask(String v) {
if (v == null || v.trim().isEmpty()) {
return "(empty)";
}
String t = v.trim();
return t.length() <= 6 ? "***" : t.substring(0, 3) + "***" + t.substring(t.length() - 2);
}
}

102
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunWarehouseProbeTest.java

@ -0,0 +1,102 @@ @@ -0,0 +1,102 @@
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.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseFacility;
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.List;
import java.util.UUID;
/**
* 仓库清单联调探针:<b>只读</b>。
*
* <pre>
* # 只看报文(不联网)
* mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
* -Dedayun.probe.warehouse=true -Dtest=EdayunWarehouseProbeTest test
*
* # 真查(只读)
* ... -Dedayun.probe.warehouse=true -Dedayun.probe.call=true \
* -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
* -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=...
* </pre>
*
* <p>两个接口都查:权限内(下单用这个)与全量激活仓(含未授权的)。</p>
*/
@EnabledIfSystemProperty(named = "edayun.probe.warehouse", matches = "true")
class EdayunWarehouseProbeTest {
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 boolean CALL = Boolean.getBoolean("edayun.probe.call");
@Test
void probeWarehouses() {
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_WAREHOUSE_PERMITTED + " (权限内) ================");
System.out.println("[request] {}");
System.out.println("\n================ edayun / POST "
+ EdayunConstants.PATH_WAREHOUSE_ACTIVE + " (全量) ================");
System.out.println("[request] {\"warehouseOperationType\":0}");
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, null,
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());
print("权限内", adapter.warehouses(ctx));
print("全量尾程", adapter.activeWarehouses(ctx, false));
print("全量头程", adapter.activeWarehouses(ctx, true));
} 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 void print(String label, List<WarehouseFacility> list) {
System.out.println("[OK] " + label + " warehouses=" + list.size());
for (int i = 0; i < Math.min(5, list.size()); i++) {
WarehouseFacility f = list.get(i);
System.out.println(" " + f.providerWarehouseId() + " " + f.warehouseCode()
+ " " + f.name() + " " + f.country());
}
}
private static String opt(String name, String fallback) {
String value = System.getProperty(name, "");
String trimmed = value == null ? "" : value.trim();
return trimmed.isEmpty() ? fallback : trimmed;
}
}

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

@ -77,6 +77,7 @@ import common.ecommerce.warehouse.model.TransferCommand; @@ -77,6 +77,7 @@ import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.TransferQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.model.LogisticsProduct;
@ -259,8 +260,19 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -259,8 +260,19 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
* 其余条件为空——需要按状态 / 时间窗筛时用 {@link #queryReturnsAdvanced}。</p>
*/
@Override
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor) {
return queryReturnsAdvanced(ctx, null, null, null, null, null, null, cursor);
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query) {
// 统一入口只带游标 / 每页条数与仓库;其余条件为空——需要按状态 / 时间窗筛时
// 用 queryReturnsAdvanced。ReturnQuery 里给了这里不支持的维度时显式拒绝,
// 静默忽略会让调用方以为筛过。
if (query != null && (query.hasCreatedRange() || query.orderNo() != null
|| query.trackingNo() != null || query.providerSku() != null
|| !query.statuses().isEmpty())) {
throw validation(ctx, OP_RETURN_QUERY,
"hengjian return list does not take these filters through the unified entry;"
+ " use queryReturnsAdvanced (statuses / time window / order no / sku)");
}
return queryReturnsAdvanced(ctx, null, null, null, null, null, null,
query == null ? null : query.cursor());
}
/**

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

@ -10,6 +10,7 @@ import common.ecommerce.shared.testkit.Responses; @@ -10,6 +10,7 @@ import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.ReturnStatus;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -146,7 +147,7 @@ class HengjianReturnQueryTest { @@ -146,7 +147,7 @@ class HengjianReturnQueryTest {
@Test
void listPostsWrappedStringPaging() {
RecordingTransport transport = listing();
adapter(transport).queryReturns(CTX, null);
adapter(transport).queryReturns(CTX, ReturnQuery.builder().build());
String body = transport.lastDataRequest().body();
assertTrue(body.startsWith("{\"params\":{"), body);
@ -185,7 +186,7 @@ class HengjianReturnQueryTest { @@ -185,7 +186,7 @@ class HengjianReturnQueryTest {
@Test
void listMapsRows() {
Page<WarehouseReturn> page = adapter(listing()).queryReturns(CTX, null);
Page<WarehouseReturn> page = adapter(listing()).queryReturns(CTX, ReturnQuery.builder().build());
assertEquals(1, page.size());
assertFalse(page.hasMore());

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

@ -37,6 +37,7 @@ import common.ecommerce.warehouse.model.InboundReceipt; @@ -37,6 +37,7 @@ import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.model.TransferOrder;
@ -569,7 +570,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -569,7 +570,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
}
@Override
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor) {
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
}

Loading…
Cancel
Save