Browse Source

docs(edayun): 补退货 / BOL / 物流产品 / 轨迹 / 条码的实测结论

README 新增五节,每节都包含「真机验证」小节与实际返回:
- 退货四接口:状态码表(来自列表文档)、时间窗是字符串、checkList 优先、
  data=false 是仓方拒绝、详情三处文档类型不符
- BOL:与入库 BOL 的区别、11=已妥投、PR 无数据
- 物流产品:-998 是哨兵值、applicableBusiness 只能固定 1、各口径条数
- 物流轨迹:请求体是纯数组、「未匹配到轨迹」不是错误、上网/妥投时间口径
- 条码打印:与入库贴标的区别、本地提前挡的两条、四种纸张

库存一节补了真机结论:pageSize 静默截断到 500、页码越界重复返回最后一页、
safeStock 大量为 null、数字字段全是字符串。

TODO 从 37 条增到 67 条,主要新增:退货状态码表 / 行 id 缺失、BOL 状态码表、
物流产品码表与哨兵值、轨迹 eventStatus、条码 OSS 链接有效期。

Co-Authored-By: Claude <noreply@anthropic.com>
master
chenchuchuan 4 days ago
parent
commit
5124ff85d1
  1. 381
      docs-warehouse/edayun/README.md
  2. 34
      docs-warehouse/edayun/TODO.md

381
docs-warehouse/edayun/README.md

@ -20,6 +20,14 @@
| 库存查询 | ✅ 已对接(`POST /webApi/userSkuStock/v1/queryInventory`) | | 库存查询 | ✅ 已对接(`POST /webApi/userSkuStock/v1/queryInventory`) |
| 创建 / 编辑自发入库单 | ✅ 已对接(`POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder`) | | 创建 / 编辑自发入库单 | ✅ 已对接(`POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder`) |
| 查询入库单 / 入库状态 | ✅ 已对接(`POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail`) | | 查询入库单 / 入库状态 | ✅ 已对接(`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`) |
| 其它业务接口 | ⬜ 等文档 | | 其它业务接口 | ⬜ 等文档 |
| 回调 | ⬜ 等文档 | | 回调 | ⬜ 等文档 |
| 真机验证 | ⬜ 等测试环境 | | 真机验证 | ⬜ 等测试环境 |
@ -193,7 +201,8 @@ POST /webApi/order/v1/createOrder
|---|---| |---|---|
| `signatureRequired = true` | `is_signature` | | `signatureRequired = true` | `is_signature` |
保价(`is_insurance`)标准模型没有对应字段,暂不下发。 保价:任意商品行带 `insuredAmount` 就整单下发 `is_insurance`——`addService`
是订单级开关,易达云没有行级保价。
## 查询出库单 / 面单 ## 查询出库单 / 面单
@ -799,9 +808,39 @@ POST /webApi/userSkuStock/v1/queryInventory → Page<InventorySnapshot>
| `warehouseIdList` 是数字 id | 非数字本地拒绝(同仓租明细) | | `warehouseIdList` 是数字 id | 非数字本地拒绝(同仓租明细) |
| 分页 | 游标是页码字符串;`total` 按文档当总行数用,缺失时按满页判断 | | 分页 | 游标是页码字符串;`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`(可售)落,**不可售数量被丢弃**—— 不在统一模型里。整行按 `inventoryType = 0`(可售)落,**不可售数量被丢弃**——
需要对账不可售库存时要扩展模型,见 TODO。 需要对账不可售库存时要扩展模型,见 TODO。
@ -820,6 +859,344 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
[-Dedayun.probe.zeroStock=true] [-Dedayun.probe.page=1] [-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 环境没有任何可查到的轨迹**,映射只被单测覆盖。
## 打印条码
```
POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel
```
### 与入库 SKU 贴标不是一回事
| | `inbound().printSkuLabel()` | `printBarcodes()` |
|---|---|---|
| 对象 | 入库计划单 | **任意 SKU** |
| 绑定 | 必填入库单号 | 不绑单据 |
| 纸张 | 14 种小尺寸 | **4 档** |
| 返回 | 异步任务号 | **同步 PDF 地址** |
因为纸张集合完全不同,新增了独立枚举 `BarcodePaperSize`(7×3cm / 10×6cm / 6×4cm / A4),
没有复用 `SkuLabelSizeType`——那可是 14 个取值,混用会误导调用方。
### 响应 `data` 是文件地址字符串
```json
{"code":200,"msg":"操作成功","data":"https://.../barcode123.pdf","traceId":null}
```
不是对象、也不是任务号——仓方同步生成 PDF。映射到 `WarehouseLabel.url()`。
### 本地提前挡住的两条
| 约束 | 仓方提示 | 我们 |
|---|---|---|
| SKU 数 > 50 | `最多打印50个SKU` | `BarcodePrintCommand` 构造期就拒 |
| 份数 ≤ 0 | `内部服务器错误` | 同上 |
仓方对非法 `num` 回的是「内部服务器错误」,看不出原因,所以本地先挡。
### 其它实测校验
| 场景 | 仓方返回 |
|---|---|
| 缺 `productInfos` / 空数组 | `产品信息不能为空` |
| 缺 `pageSize` | `纸张尺寸不能为空` |
| `pageSize=9`(非法) | `内部服务器错误` |
| SKU 不存在 | `sku=NO-SUCH-SKU信息不存在` |
### `isPrintSkuName` 只在 true 时下发
`false` 是仓方默认值,不下发,省得干扰它自己的默认。
### 真机验证(2026-11-16)
`ybtest` + A4 + `isPrintSkuName=true` → 拿到真实 PDF:
`https://oss.edayun.com/test/2026/11/16/02/.../barcode7640824581948387426.pdf`
四种纸张尺寸都返回 `code=200`。
## 待确认(问易达云) ## 待确认(问易达云)
| # | 要确认 | | # | 要确认 |

34
docs-warehouse/edayun/TODO.md

@ -5,7 +5,6 @@
## 待仓方确认 ## 待仓方确认
| # | 问题 | 当前处理 | 影响 | | # | 问题 | 当前处理 | 影响 |
|---|---|---|---|
| 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 | | 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 |
| 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 | | 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 |
| 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 | | 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 |
@ -38,6 +37,37 @@
| 35 | 入库明细接口不回仓库 / 创建时间 / 到仓时间 / 箱号 | 仓库用 OMS 配置;时间与箱明细为 null | 拿不到完整单据,需要 entryInfo 单头查询接口 | | 35 | 入库明细接口不回仓库 / 创建时间 / 到仓时间 / 箱号 | 仓库用 OMS 配置;时间与箱明细为 null | 拿不到完整单据,需要 entryInfo 单头查询接口 |
| 36 | 是否有入库单列表 / 时间窗查询 | `query()` 的 cursor 当 entryCode 用 | 无法做增量同步,只能按单号轮询 | | 36 | 是否有入库单列表 / 时间窗查询 | `query()` 的 cursor 当 entryCode 用 | 无法做增量同步,只能按单号轮询 |
| 37 | `forecastWeight` / `weight` 是克、`firstWeight` 是千克 | 未映射(统一模型没有行级重量) | 想按箱对账重量时需要 | | 37 | `forecastWeight` / `weight` 是克、`firstWeight` 是千克 | 未映射(统一模型没有行级重量) | 想按箱对账重量时需要 |
| 38 | 退货单**没有列表查询** | `queryReturns` 显式拒绝 | 无法批量同步退货单 |
| 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 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 |
|---|---|---|---|
## 待业务确认 ## 待业务确认
@ -45,7 +75,7 @@
|---|---|---|---| |---|---|---|---|
| 6 | **派送地址的州要全称(California)还是二字码(CA)** | 原样透传 | 所有出库单地址 | | 6 | **派送地址的州要全称(California)还是二字码(CA)** | 原样透传 | 所有出库单地址 |
| 7 | 统一模型缺的字段:带电 / 包材 / 物流包装 | 创建产品里硬编码为「不带」 | 带电商品无法正确申报 | | 7 | 统一模型缺的字段:带电 / 包材 / 物流包装 | 创建产品里硬编码为「不带」 | 带电商品无法正确申报 |
| 8 | 保价服务(`is_insurance`) | 未下发,标准模型无字段 | 保价订单 | | 8 | 保价服务(`is_insurance`) | 任意商品行有 `insuredAmount` 即整单下发 `is_insurance` | 混合保价单会整单保价 |
| 9 | `OutboundCommand` 没有 `carrierProductId`(易达云物流产品 id) | 未下发,走仓方默认分物流规则 | 指定物流产品 | | 9 | `OutboundCommand` 没有 `carrierProductId`(易达云物流产品 id) | 未下发,走仓方默认分物流规则 | 指定物流产品 |
| 10 | `channelName` 从 `Platform` 枚举推(AMAZON_SC → Amazon) | 首段大写 | 非标准平台名可能对不上 | | 10 | `channelName` 从 `Platform` 枚举推(AMAZON_SC → Amazon) | 首段大写 | 非标准平台名可能对不上 |

Loading…
Cancel
Save