From 5124ff85d12fdb5412bdbc5352a24e6cf0eba3dd Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Mon, 16 Nov 2026 16:20:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(edayun):=20=E8=A1=A5=E9=80=80=E8=B4=A7=20/?= =?UTF-8?q?=20BOL=20/=20=E7=89=A9=E6=B5=81=E4=BA=A7=E5=93=81=20/=20?= =?UTF-8?q?=E8=BD=A8=E8=BF=B9=20/=20=E6=9D=A1=E7=A0=81=E7=9A=84=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=E7=BB=93=E8=AE=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs-warehouse/edayun/README.md | 381 +++++++++++++++++++++++++++++++++++++++- docs-warehouse/edayun/TODO.md | 34 +++- 2 files changed, 411 insertions(+), 4 deletions(-) diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md index 3a96829..7e1c55e 100644 --- a/docs-warehouse/edayun/README.md +++ b/docs-warehouse/edayun/README.md @@ -20,6 +20,14 @@ | 库存查询 | ✅ 已对接(`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`) | | 其它业务接口 | ⬜ 等文档 | | 回调 | ⬜ 等文档 | | 真机验证 | ⬜ 等测试环境 | @@ -193,7 +201,8 @@ POST /webApi/order/v1/createOrder |---|---| | `signatureRequired = true` | `is_signature` | -保价(`is_insurance`)标准模型没有对应字段,暂不下发。 +保价:任意商品行带 `insuredAmount` 就整单下发 `is_insurance`——`addService` +是订单级开关,易达云没有行级保价。 ## 查询出库单 / 面单 @@ -799,9 +808,39 @@ POST /webApi/userSkuStock/v1/queryInventory → Page | `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 +859,344 @@ 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 +``` + +店铺订单 / 平台仓订单共用,`orderNo` 传 EDA 的平台仓订单号(如 `FBA473182144`)。 + +### 与入库 BOL 不是一回事 + +| | `inbound().bols()` | `orderBols()` | +|---|---|---| +| 对象 | 头程入库计划单 | 平台仓 / 店铺订单 | +| 返回 | `List` 文件地址 | 带提货状态、约定/实际提货量、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 +``` + +### `-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 / 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`。 + ## 待确认(问易达云) | # | 要确认 | diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index b2378b2..3c231e8 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -5,7 +5,6 @@ ## 待仓方确认 | # | 问题 | 当前处理 | 影响 | -|---|---|---|---| | 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 | | 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 | | 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 | @@ -38,6 +37,37 @@ | 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 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 | +|---|---|---|---| ## 待业务确认 @@ -45,7 +75,7 @@ |---|---|---|---| | 6 | **派送地址的州要全称(California)还是二字码(CA)** | 原样透传 | 所有出库单地址 | | 7 | 统一模型缺的字段:带电 / 包材 / 物流包装 | 创建产品里硬编码为「不带」 | 带电商品无法正确申报 | -| 8 | 保价服务(`is_insurance`) | 未下发,标准模型无字段 | 保价订单 | +| 8 | 保价服务(`is_insurance`) | 任意商品行有 `insuredAmount` 即整单下发 `is_insurance` | 混合保价单会整单保价 | | 9 | `OutboundCommand` 没有 `carrierProductId`(易达云物流产品 id) | 未下发,走仓方默认分物流规则 | 指定物流产品 | | 10 | `channelName` 从 `Platform` 枚举推(AMAZON_SC → Amazon) | 首段大写 | 非标准平台名可能对不上 |