From 52a064707b6fb02c4a38c2aa32f26a41971801f2 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Wed, 18 Nov 2026 10:56:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=93=8D=E4=BD=9C=E6=89=8B=E5=86=8C?= =?UTF-8?q?=E6=94=B9=E4=B8=BA=E3=80=8C=E6=BA=90=E7=A0=81=E9=9B=86=E6=88=90?= =?UTF-8?q?=E7=89=88=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 对方面对我们全量源码,不走 Maven 坐标,所以重写: 一、源码怎么集成(新增) - 源码结构图与「必拷/不用拷」清单 - 关键事实:仓库域主代码完全不引用 channel 包(已 grep 核对), 所以只需拷 6 个目录 - 两种放法:合并进 src/main/java(包名不变,不用改 import)/ Gradle 多模块 - 测试代码可选:sdk-testkit 的 FakeDirectAdapter 引用了 channel 包, 只想测仓库域时只拷 5 个类即可 二、必须引入的第三方库(新增) - 全量 grep import 核对后:只有 jackson / slf4j-api / okhttp 三个 - 明确「不需要 Lombok」(仓库域零使用,只有 lingxing 用了) - 给了 Gradle 与 Maven 两种写法 - OkHttp 4.x 是 Kotlin 写的,需要 kotlin-stdlib;给两个规避方案 - 附 HttpTransport 自定义实现说明(不想引 OkHttp 时) 三~七 保持上一版的任务组织: 5 分钟上手 / 能不能做 / 8 个任务 / 全局规则 / 异常处理 只把「引入依赖」的 Maven 坐标换成了源码说明。 Co-Authored-By: Claude --- docs-warehouse/SDK操作手册.md | 789 +++++++++++++++++--------------------- 1 file changed, 348 insertions(+), 441 deletions(-) diff --git a/docs-warehouse/SDK操作手册.md b/docs-warehouse/SDK操作手册.md index 618efd3..02c6688 100644 --- a/docs-warehouse/SDK操作手册.md +++ b/docs-warehouse/SDK操作手册.md @@ -1,9 +1,9 @@ -# 三方仓 SDK 操作手册(业务开发版) +# 三方仓 SDK 使用说明(源码集成版) -> 面向 OMS 业务开发:**你要做的事怎么做**。 -> 不需要了解 SDK 内部分层,照着抄就能跑。 +> 贵方拿到的是一份**完整源码**,直接用源码方式集成,不走 Maven / Gradle 依赖坐标。 +> 本文档说明:**源码怎么放、要引哪些第三方库、每个业务动作怎么写**。 > -> 版本 1.0.0-SNAPSHOT · JDK 1.8 +> JDK 1.8 --- @@ -11,64 +11,197 @@ | 我要… | 看这节 | |---|---| -| 把 SDK 跑起来 | [一、5 分钟上手](#一5-分钟上手) | -| 知道某个仓支不支持我要的功能 | [二、我要做的事能不能做](#二我要做的事能不能做) | -| 发货 / 打面单 | [3.1](#31-发货建出库单--拿面单) | -| 查包裹到哪了 | [3.2](#32-查物流轨迹) | -| 取消订单 | [3.3](#33-取消出库单) | -| 处理买家退货 | [3.4](#34-退货) | -| 同步库存 | [3.5](#35-库存同步) | -| 建商品 / 查商品 | [3.6](#36-商品主数据) | -| 拉费用对账 | [3.7](#37-对账拉费用明细) | -| 打箱唛 / 提货单 | [3.8](#38-打单箱唛--bol) | -| 单位 / SKU / 分页 / 金额怎么传 | [四、贯穿全局的规则](#四几条贯穿全局的规则) | -| 报错了 / 要不要重试 | [五、出错了怎么办](#五出错了怎么办) | +| 把源码放进项目 | [一、源码怎么集成](#一源码怎么集成) | +| 知道要引哪些 jar | [二、必须引入的第三方库](#二必须引入的第三方库) | +| 把 SDK 跑起来 | [三、5 分钟上手](#三5-分钟上手) | +| 知道某仓支不支持某功能 | [四、我要做的事能不能做](#四我要做的事能不能做) | +| 发货 / 面单 | [5.1](#51-发货建出库单--拿面单) | +| 查轨迹 | [5.2](#52-查物流轨迹) | +| 取消订单 | [5.3](#53-取消出库单) | +| 退货 | [5.4](#54-退货) | +| 库存同步 | [5.5](#55-库存同步) | +| 商品建档 / 查询 | [5.6](#56-商品主数据) | +| 对账拉费用 | [5.7](#57-对账拉费用明细) | +| 打箱唛 / BOL | [5.8](#58-打单箱唛--bol) | +| 单位 / SKU / 分页 / 金额 | [六、贯穿全局的规则](#六几条贯穿全局的规则) | +| 报错 / 重试 | [七、出错了怎么办](#七出错了怎么办) | --- -# 一、5 分钟上手 +# 一、源码怎么集成 -## 1.1 引入依赖 +## 1.1 源码结构 -```xml - - ecommerce - warehouse-sdk-core - 1.0.0-SNAPSHOT - +``` +common-ecommerce/ +├── sdk-common/ ← 公共基础(HTTP / JSON / SPI / 审计 / 幂等骨架) +├── warehouse-sdk-core/ ← 三方仓统一模型 + 门面 + 能力接口 +├── warehouse-sdk-edayun/ ← 易达云适配器 +├── warehouse-sdk-yqn/ ← 运去哪适配器 +├── warehouse-sdk-xincang/ ← 信仓适配器 +├── warehouse-sdk-hengjian/ ← 恒健适配器 +├── sdk-testkit/ ← 测试辅助(可选,见 1.4) +├── warehouse-sdk-testkit/ ← 仓域测试辅助(可选) +├── channel-sdk-core/ ← 平台域,本次不用 +└── lingxing/ ← 领星,本次不用 +``` - - - ecommerce - warehouse-sdk-edayun - 1.0.0-SNAPSHOT - +## 1.2 需要拷贝的模块 + +**必拷**(只拷 `src/main/java`): + +| 目录 | 作用 | 文件数 | +|---|---|---| +| `sdk-common/src/main/java` | HTTP、JSON、SPI 定义、日志、幂等骨架 | 47 | +| `warehouse-sdk-core/src/main/java` | 统一模型、门面、能力接口 | 126 | +| `warehouse-sdk-edayun/src/main/java` | 易达云适配器(用哪个仓拷哪个) | 64 | +| `warehouse-sdk-yqn/src/main/java` | 运去哪适配器 | 56 | +| `warehouse-sdk-xincang/src/main/java` | 信仓适配器 | 38 | +| `warehouse-sdk-hengjian/src/main/java` | 恒健适配器 | 58 | + +**不用拷**: + +- `channel-sdk-core/`、`lingxing/` —— 平台商品域 / 领星,与三方仓无关 +- 各模块的 `src/test/java` —— 单测,不影响运行 +- **仓库域主代码完全没有引用 `channel` 包**(已 grep 全量核对),可以只拷上面 6 个 + +## 1.3 放进项目的两种方式 + +### 方式 A:保留包结构,直接加入源码目录(推荐) + +包名一律是 `common.ecommerce.*`,**原样拷进去,不需要改任何 import**。 + +``` +你们的项目/ +└── src/main/java/ + └── common/ecommerce/ + ├── shared/ ← 来自 sdk-common + ├── http/ ← 来自 sdk-common + ├── warehouse/ ← 来自 warehouse-sdk-core + ├── edayun/ ← 来自 warehouse-sdk-edayun + ├── yqn/ ← 来自 warehouse-sdk-yqn + ├── xincang/ ← 来自 warehouse-sdk-xincang + └── hengjian/ ← 来自 warehouse-sdk-hengjian +``` + +> 6 个模块的根包都是 `common/ecommerce/xxx`,各占一个子目录,合并时**不会冲突**。 + +### 方式 B:作为独立模块加入现有构建 + +如果你们是 Gradle 多模块: + +```kotlin +// settings.gradle.kts +include(":sdk-common", ":warehouse-sdk-core", ":warehouse-sdk-edayun") + +// warehouse-sdk-edayun/build.gradle.kts +dependencies { + api(project(":sdk-common")) + api(project(":warehouse-sdk-core")) +} + +java { + sourceCompatibility = JavaVersion.VERSION_1_8 + targetCompatibility = JavaVersion.VERSION_1_8 +} +tasks.withType { options.encoding = "UTF-8" } +``` + +Maven 多模块同理,在每个模块的 pom 里用 `compile` 依赖相邻模块即可。 + +## 1.4 关于测试代码(可选) + +如果想把单元测试一起带过去: + +- 拷 `src/test/java` 需要额外引入 **`junit-jupiter 5.8.2`** +- **`sdk-testkit` 主代码引用了 `channel` 包**(`FakeDirectAdapter` 这个类), + 只想测仓库域的话,**只拷这几个类**即可: + `RecordingTransport`、`Responses`、`InMemoryTokenStore`、 + `InMemoryLockProvider`、`InMemoryIdempotencyStore`,跳过 `FakeDirectAdapter` +- 或者干脆不拷测试,只用源码跑业务 + +--- + +# 二、必须引入的第三方库 + +仓库域主代码**只用到三个**第三方库(已用 `grep import` 全量核对): + +| 库 | 版本 | 用在哪 | 必须? | +|---|---|---|---| +| `com.fasterxml.jackson.core:jackson-databind` | 2.13.5 | 所有 DTO 序列化 | ✅ | +| `org.slf4j:slf4j-api` | 1.7.36 | `Slf4jCallObserver` 打日志 | ✅(实现由你们提供) | +| `com.squareup.okhttp3:okhttp` | 4.12.0 | `sdk-common` 的 `OkHttpTransport` | ✅(可自己实现替换) | + +**不需要 Lombok**——仓库域主代码一个文件都没用(只有 `lingxing` 用了,那个模块不拷)。 + +### Gradle + +```kotlin +dependencies { + implementation("com.fasterxml.jackson.core:jackson-databind:2.13.5") + implementation("org.slf4j:slf4j-api:1.7.36") + implementation("com.squareup.okhttp3:okhttp:4.12.0") + // 日志实现你们项目应该已经有了 +} +``` + +### Maven + +```xml - ecommerce - warehouse-sdk-yqn - 1.0.0-SNAPSHOT + com.fasterxml.jackson.core + jackson-databind + 2.13.5 - ecommerce - warehouse-sdk-xincang - 1.0.0-SNAPSHOT + org.slf4j + slf4j-api + 1.7.36 - ecommerce - warehouse-sdk-hengjian - 1.0.0-SNAPSHOT + com.squareup.okhttp3 + okhttp + 4.12.0 ``` -需要 **JDK 1.8**。日志实现(logback / log4j2)宿主要自己提供。 +**版本冲突**:如果你们已有更高版本的 jackson / okhttp,直接用你们的版本。 +代码只用了最基础的 API(`ObjectMapper`、`MediaType`、`OkHttpClient`),向上兼容。 + +**OkHttp 4.x 是 Kotlin 写的**,需要 classpath 上有 `kotlin-stdlib`。不想引 Kotlin 就: + +- 用 OkHttp 3.14.x(纯 Java,API 兼容),或者 +- 自己实现 `HttpTransport`(只有一个方法),换成你们已有的 HTTP 客户端,见下。 + +### 自己实现 `HttpTransport`(可选) + +不想引 OkHttp 时: + +```java +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.HttpTransport; + +public class MyHttpTransport implements HttpTransport { + @Override + public HttpResponse execute(HttpRequest request) { + // request.method() / url() / headers() / body() / contentType() + // 返回 HttpResponse.of(statusCode, headers, body, latencyMillis) + // 用你们项目已有的 HttpClient / RestTemplate 实现 + return ...; + } +} +``` + +然后在组装 SDK 时把它传给适配器(见 3.2 的 `EdayunAdapterFactory` 参数说明)。 -## 1.2 一次性配置 +--- -**这一步整个应用只做一次**,之后复用这个 `sdk`。 +# 三、5 分钟上手 -### 你只需要实现两个东西 +## 3.1 实现两个 SPI -**① 告诉 SDK「仓编码对应哪家仓」** +### ① 仓编码 → 哪家仓 ```java import common.ecommerce.warehouse.spi.WarehouseRepository; @@ -80,7 +213,7 @@ public class MyWarehouseRepository implements WarehouseRepository { private final Map accounts = new HashMap<>(); public MyWarehouseRepository() { - // 从你的仓主数据表里加载 + // 从你们的仓主数据表加载 accounts.put("EDY-USLA", WarehouseAccount.builder() .warehouseCode("EDY-USLA") // OMS 侧仓编码 .provider("EDAYUN") // 决定用哪个适配器 @@ -113,13 +246,22 @@ public class MyWarehouseRepository implements WarehouseRepository { } ``` -**② 告诉 SDK「写操作怎么防重复」** +**`providerWarehouseId` 各仓填什么** + +| 仓 | 填什么 | 例子 | +|---|---|---| +| 易达云 | 数字仓 id | `"2"` | +| 运去哪 | 仓编码 | `"RF_NY_US"` | +| 信仓 | 仓编码 | | +| 恒健 | 仓编码 | | + +### ② 写操作怎么防重复 -只要你有建单 / 取消这类写操作就必须实现。用 Redis 或 DB 都行,核心是**「查 + 写」必须原子**: +只要你们有建单 / 取消这类写操作就必须实现。核心是**「查 + 写」必须原子**。 -> 下面这段里的 `loadFromRedisOrDb` / `reclaimable` / `writeInProgress` / -> `markStatus` 是**示意方法名**,需要你按自己的存储实现。可参考 -> `sdk-testkit` 里的 `InMemoryIdempotencyStore`(结构完全一样,只是把内存换成 Redis/DB)。 +> 下面代码里的 `loadFromRedisOrDb` / `reclaimable` / `writeInProgress` / `markStatus` +> 是**示意方法名**,按你们自己的存储实现。 +> 结构可以照抄 `sdk-testkit/InMemoryIdempotencyStore`(如果拷了的话)。 ```java import common.ecommerce.shared.spi.*; @@ -129,23 +271,21 @@ import java.util.Optional; public class MyIdempotencyStore implements IdempotencyStore { /** - * 抢占。四种返回结果: - * acquire() 抢占成功,去调仓 - * of(SUCCEEDED, record) 之前做过了,直接用 record.resultRef() 回放 - * of(IN_PROGRESS, record) 别人正在做,等一会儿或报冲突 - * of(FAILED_FINAL, record) 之前终态失败,需人工介入 + * 抢占。四种返回: + * acquire() 抢占成功 → 去调仓 + * of(SUCCEEDED, record) 之前做过了 → 用 record.resultRef() 回放 + * of(IN_PROGRESS, record) 别人正在做 → 等一下或报冲突 + * of(FAILED_FINAL, record) 之前终态失败 → 人工介入 */ @Override public IdempotencyClaim claim(String key, String owner, String provider, Instant now, long ttlSeconds) { IdempotencyRecord existing = loadFromRedisOrDb(key); - // 无记录 / 可重试失败 / IN_PROGRESS 已过 TTL → 可以抢占 if (existing == null || reclaimable(existing, now, ttlSeconds)) { writeInProgress(key, owner, provider, now); return IdempotencyClaim.acquire(); } - // 否则按已有记录的状态返回 switch (existing.status()) { case SUCCEEDED: return IdempotencyClaim.of(IdempotencyClaim.Outcome.SUCCEEDED, existing); case FAILED_FINAL: return IdempotencyClaim.of(IdempotencyClaim.Outcome.FAILED_FINAL, existing); @@ -172,18 +312,15 @@ public class MyIdempotencyStore implements IdempotencyStore { } ``` -**必须满足的两条** +**必须满足两条** -1. **`claim()` 的「查 + 写」要原子**。Redis 用 `SET key value NX EX ttl`,MySQL 用唯一索引 + `INSERT IGNORE`。先查再写会让并发穿透。 -2. **`complete` / `fail` 只能由当前 owner 写**。否则过期的 owner 会覆盖新抢占者的结果。 +1. `claim()` 的「查 + 写」要原子:Redis 用 `SET key value NX EX ttl`,MySQL 用唯一索引 +2. `complete` / `fail` 只能由当前 owner 写,否则过期 owner 会覆盖新抢占者的结果 -> 只做查询的话可以暂时不实现;但一旦要建单就会抛 +> 只做查询可以先不实现;一旦建单会抛 > `IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations`。 -> -> **没有 Redis 可以先用内存版**(`InMemoryIdempotencyStore`,在 `sdk-testkit` 里), -> 但它只适合单实例测试,生产必须换成 Redis / DB。 -### 组装 SDK +## 3.2 组装 SDK ```java import common.ecommerce.warehouse.sdk.WarehouseSdk; @@ -193,12 +330,12 @@ import common.ecommerce.yqn.adapter.YqnAdapterFactory; import java.time.Clock; import java.time.ZoneId; -// 定义成 Spring 单例 Bean +// Spring 里定义成单例 Bean WarehouseSdk sdk = WarehouseSdk.builder() .warehouseRepository(new MyWarehouseRepository()) // 必需 .idempotencyStore(myIdempotencyStore) // 写操作必需 .clock(Clock.systemUTC()) - .callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) // 日志,强烈建议 + .callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) .register(new EdayunAdapterFactory(tokenStore, lockProvider, Clock.systemUTC())) .register(new YqnAdapterFactory(Clock.systemUTC())) .build(); @@ -208,16 +345,16 @@ WarehouseSdk sdk = WarehouseSdk.builder() | 工厂 | 构造参数 | |---|---| -| `EdayunAdapterFactory` | `(TokenStore, LockProvider, Clock)` | +| `EdayunAdapterFactory` | `(TokenStore, LockProvider, Clock)`;前两个可传 `null`(则每次重登) | | `YqnAdapterFactory` | `(Clock)` | | `XincangAdapterFactory` | `(TokenStore, LockProvider, Clock)` | | `HengjianAdapterFactory` | 无参 | -> **务必做成单例。** 适配器里缓存了 token 和限流器,每次 `new` 会重复登录。 +> **务必做成单例。** 适配器里缓存了 token 与限流器,每次 `new` 会重复登录。 -### 连接信息(端点 + 凭据) +## 3.3 连接信息(端点 + 凭据) -SDK **不保存**端点和凭据,每次调用由你传: +SDK 不保存端点和凭据,每次调用由你们传: ```java import common.ecommerce.warehouse.sdk.WarehouseConnection; @@ -233,18 +370,16 @@ WarehouseConnection conn = WarehouseConnection.of( .build()); ``` -**各仓需要哪些凭据字段** +**各仓需要的凭据字段** -| 仓 | 必填字段 | 说明 | +| 仓 | 必填 | 说明 | |---|---|---| | 易达云 | `appKey` `appSecret` `clientId` `clientSecret` | 前两个算签名,后两个换 token | | 运去哪 | `appSecret` | 组织级 token,直接放 `appSecret` | | 信仓 | `appKey` `appSecret` | 换 token | | 恒健 | `appSecret` | 算签名 | -## 1.3 拿到一个仓的操作入口 - -**所有业务接口都从这里进**: +## 3.4 拿到仓的操作入口 ```java import common.ecommerce.warehouse.sdk.WarehouseOperations; @@ -252,38 +387,35 @@ import common.ecommerce.warehouse.sdk.WarehouseOperations; WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn); ``` -后面所有示例里的 `wh` 都是这行拿到的。 +后面所有 `wh.xxx()` 都从这个对象出发。 -## 1.4 验证能跑通 +## 3.5 验证能跑通 -在正式写业务前,先跑这一行——**只读,不改任何数据**: +**只读,不改任何数据**: ```java import common.ecommerce.warehouse.model.WarehouseFacility; import java.util.List; List warehouses = wh.warehouses(); - System.out.println("该账户有权限的仓:" + warehouses.size()); for (WarehouseFacility w : warehouses) { - System.out.println(" " + w.warehouseCode() + " " + w.name() + " " + w.country()); + System.out.println(" " + w.warehouseCode() + " " + w.name()); } ``` -能打出仓,说明**凭据、端点、配置全都对了**。 - -跑不通时的对照: +能打出仓,说明凭据、端点、配置全对。跑不通时: | 现象 | 原因 | |---|---| -| `IllegalStateException: 该仓没有配置接入账户` | `warehouseCode` 和你的 `WarehouseRepository` 对不上 | -| `WarehouseUnsupportedCapabilityException` | 这家仓没有仓库清单接口(先看 [二](#二我要做的事能不能做)) | -| `WarehouseException ... http 401` | `appKey` / `appSecret` / `clientId` / `clientSecret` 有错 | -| 超时 | 端点不通;易达云首次调用较慢,建议重试一次 | +| `该仓没有配置接入账户` | `warehouseCode` 和 `WarehouseRepository` 对不上 | +| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [四](#四我要做的事能不能做)) | +| `http 401` / token 错误 | `ChannelSecret` 字段填错 | +| 超时 | 端点不通;易达云首次调用慢,重试一次 | --- -# 二、我要做的事能不能做? +# 四、我要做的事能不能做? | 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 | |---|---|:---:|:---:|:---:|:---:| @@ -295,7 +427,7 @@ for (WarehouseFacility w : warehouses) { | 退货(建单 / 查 / 取消) | `returns().create` / `.get` / `.cancel` | ✅ | ✅ | ❌ | ✅ | | 退货检验后处理 | `returns().process` | ❌ | ✅ | ❌ | ❌ | | 拉费用明细 | `fees().settlements` | ✅ | ✅ | ❌ | ✅ | -| 费用试算(发货前报价) | `fees().estimate` | ✅ | ✅ | ❌ | ✅ | +| 费用试算 | `fees().estimate` | ✅ | ✅ | ❌ | ✅ | | 商品建档 | `createProduct` | ✅ | ✅ | ✅ | ✅ | | 商品查询 | `queryProducts` | ✅ | ✅ | ❌ | ❌ | | 物流轨迹 | `track` / `trackShipment` | ✅ | ✅ | ❌ | ❌ | @@ -308,19 +440,16 @@ for (WarehouseFacility w : warehouses) { | 销毁 | `createDestruction` | ❌ | ✅ | ❌ | ✅ | | 物流异动(召回 / 改址) | `createTrackingChange` | ❌ | ❌ | ❌ | ✅ | -> **不支持就是抛异常**,不会返回空列表让你误以为「没有数据」。 -> 代码里判断:`sdk.capabilities("EDY-USLA").supported().contains(WarehouseCapability.RETURN)` +> **不支持就是抛异常**,不返回空列表。 +> 代码判断:`sdk.capabilities("EDY-USLA").supported().contains(WarehouseCapability.RETURN)` --- -# 三、按任务 - -> 以下示例假设 `wh` 已就绪(见 [1.3](#13-拿到一个仓的操作入口))。 -> 所有代码都是**片段**,省略了 import 与 try-catch,完整写法见 [五](#五出错了怎么办)。 +# 五、按任务 -## 3.1 发货:建出库单 → 拿面单 +> 以下假设 `wh` 已就绪(见 [3.4](#34-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。 -### 第一步:建单 +## 5.1 发货:建出库单 → 拿面单 ```java import common.ecommerce.shared.model.Platform; @@ -329,13 +458,13 @@ import common.ecommerce.warehouse.model.*; OutboundCommand cmd = OutboundCommand.builder() // ===== 必填 ===== - .outboundRequestNo("OB-20261117-001") // 我们自己的单号 - .salesPlatform(Platform.AMAZON_SC) // 销售平台 + .outboundRequestNo("OB-20261117-001") + .salesPlatform(Platform.AMAZON_SC) .shipTo(ShipTo.builder() .name("John Smith") .phone("+1-555-0100") .countryCode("US") // 二字码 - .stateOrProvince("California") // ⚠️ 见下方坑 1 + .stateOrProvince("California") // ⚠️ 易达云要全称、运去哪要 CA .city("Escondido") .addressLine1("1308 E Washington Ave") .postalCode("92027") @@ -343,255 +472,139 @@ OutboundCommand cmd = OutboundCommand.builder() .line(OutboundLine.builder() .lineNo("1") .omsSku("SKU-001") - .providerSku("AP0000X9US0010601") // ⚠️ 见 [4.2 SKU](#42-sku到底传哪一个最容易错) + .providerSku("AP0000X9US0010601") // ⚠️ 见 6.2 SKU .quantity(2) .declareName("蓝牙音箱") .declareValue(Money.of("19.99", "USD")) // 单价,不是总额 .build()) // ===== 强烈建议 ===== .orderRef("SO-20261117-001") // 平台单号,仓侧幂等键 - .warehouseId("2") // 不传则用账户配置的仓 + .warehouseId("2") .currency("USD") .declaredTotal(Money.of("39.98", "USD")) .build(); OutboundReceipt receipt = wh.outbound().create(cmd); - -receipt.providerOrderId(); // 仓侧单号,**保存下来**,后续查单/取消要用 +receipt.providerOrderId(); // 仓侧单号,**保存下来** ``` -### 第二步:拿面单 +拿面单: ```java List pkgs = wh.outbound().packages( - OutboundRef.ofRequestNo("OB-20261117-001")); // 用我们自己的单号查 - + OutboundRef.ofRequestNo("OB-20261117-001")); for (PackageResult p : pkgs) { p.trackingNumber(); // 跟踪号 - p.labelRef(); // 面单地址(URL) - p.carrier(); // 承运商 + p.labelRef(); // 面单 URL + p.carrier(); } ``` -### 你会拿到什么 - -| 字段 | 用途 | -|---|---| -| `receipt.providerOrderId()` | 仓侧单号,落库 | -| `p.trackingNumber()` | 跟踪号,回填到订单 | -| `p.labelRef()` | 面单文件地址,用来打印 | +**⚠️ 坑** -### ⚠️ 坑 +1. 州名:易达云要 `California`,运去哪要 `CA` +2. 平台面单把 `labelMode` 设为 `PLATFORM_LABEL`;易达云要**文件 URL 不是 base64** +3. 重复建单不会重复下单(幂等键 = `orderRef`,没有则 `outboundRequestNo`) +4. 保存 `providerOrderId`,后续查单 / 取消能少一次请求 -1. **州名易达云要全称**(`California`),运去哪要二字码(`CA`)。 -2. **平台面单**要把 `labelMode` 设成 `PLATFORM_LABEL`,且易达云要的是 **文件 URL 不是 base64**——传 base64 会本地报错。 -3. **重复建单不会重复下单**:幂等键是 `orderRef`(没有则用 `outboundRequestNo`),同样的键再调一次会返回上次结果。 -4. **保存 `providerOrderId`**,取消和查单时能少一次请求。 - ---- - -## 3.2 查物流轨迹 +## 5.2 查物流轨迹 ```java -// 只要节点 List events = wh.track("1Z999AA10123456784"); -for (TrackEvent e : events) { - e.occurredAt(); // 时间 - e.description(); // 如「上网」「已派送」 - e.status(); // 仓方原值 -} -// 要运单整体状态(推荐) TrackingInfo info = wh.trackShipment("1Z999AA10123456784"); - -info.firstOnlineAt(); // 上网时间(承运商首次揽收) -info.deliveredAt(); // 妥投时间 -info.carrier(); -info.events(); // 节点列表 +info.firstOnlineAt(); // 上网时间(为空 = 物流还没启动) +info.deliveredAt(); // 妥投时间(为空 = 未签收) +info.signedBy(); // 签收人(未签收 = null) +info.events(); ``` -### 你会拿到什么 +**⚠️ 坑**:查不到不报错 —— `track()` 返回空列表、`trackShipment()` 返回 `null`。 -| 字段 | 含义 | -|---|---| -| `firstOnlineAt()` | **包裹到底有没有交给承运商** —— 为空说明物流还没启动 | -| `deliveredAt()` | 妥投时间,为空表示未签收 | -| `signedBy()` | 签收人;**未签收就是 null** | - -### ⚠️ 坑 - -- **查不到不报错**:`track()` 返回空列表、`trackShipment()` 返回 `null`。这表示「还没轨迹」,不是失败。 -- 易达云 PR 环境目前没有可查到的轨迹数据,接口通但返回空。 - ---- - -## 3.3 取消出库单 - -### 先问仓方能不能取消 +## 5.3 取消出库单 ```java -import common.ecommerce.warehouse.enums.CancelEligibility; - CancelEligibility e = wh.outbound().checkCancel( OutboundRef.ofRequestNo("OB-20261117-001")); +// FREE / CHARGED / BLOCKED -// FREE 可以免费取消 -// CHARGED 取消要收钱 -// BLOCKED 不能取消(已发货 / 已取消) -``` - -### 再决定要不要取消 - -```java if (e == CancelEligibility.FREE) { CancelResult r = wh.outbound().cancel(CancelCommand.builder() .outboundRequestNo("OB-20261117-001") - .providerOrderId("ORD123") // 有就一起给,定位更准 - .acceptCharge(false) // 收费取消时传 false 会抛异常 + .providerOrderId("ORD123") + .acceptCharge(false) .build()); - - r.cancelled(); // true = 取消成功 + r.cancelled(); } ``` -### ⚠️ 坑 - -- `CHARGED` 时如果 `acceptCharge=false`,抛 `OutboundCancelChargeRequiredException`——**先 catch 再跟用户确认**。 -- `BLOCKED` 时抛 `OutboundCancelBlockedException`。 -- 重复调用不会重复取消(幂等),可以放心重试。 - ---- - -## 3.4 退货 +**⚠️ 坑**:`CHARGED` + `acceptCharge(false)` 抛 `OutboundCancelChargeRequiredException`; +`BLOCKED` 抛 `OutboundCancelBlockedException`。 -### 建退货单 +## 5.4 退货 ```java import common.ecommerce.warehouse.enums.ReturnDealMethod; WarehouseReturn r = wh.returns().create(ReturnCommand.builder() - // ===== 必填 ===== - .returnRequestNo("RT-20261117-001") // 我们自己的退货单号,幂等键 - .saleOrderNo("SO-20261117-001") // 关联原单 - .returnTrackingNo("1Z999AA10123456784")// 买家寄回的运单号 + .returnRequestNo("RT-20261117-001") // 幂等键 + .saleOrderNo("SO-20261117-001") + .returnTrackingNo("1Z999AA10123456784") .carrierCode("FedEx") .line("AP0000X9US0010601", 1, ReturnDealMethod.WAREHOUSE_CONFIRM) - // ===== 选填 ===== .warehouseId("2") - .remark("客户寄回") .build()); r.providerReturnId(); // 仓侧 RMA 号,**保存下来** ``` -**`ReturnDealMethod` 选哪个** - -| 值 | 含义 | -|---|---| -| `WAREHOUSE_CONFIRM` | 仓库确认后处理(最常用) | -| `DESTROY` | 直接销毁 | -| `CUSTOMER_PICKUP` | 客户自提 | -| `PHOTO_CONFIRM` | 拍照确认后再定 | - -> ⚠️ **易达云只支持「自行退回」**,且**拒绝** `lineName` / `estimatedReceiveDate` / -> `returnReason`——传了会直接报错。 - -### 查退货进度 - -```java -WarehouseReturn detail = wh.returns().get("RMA2411053149"); // 仓侧 RMA 号 - -detail.status(); // DRAFT / RETURNING / PENDING_RECEIPT / COMPLETED / CLOSED ... -detail.rawStatus(); // 仓方原文,排查时看这个 -detail.lines(); // 明细:SKU / 数量 / 检验结果 -``` - -### 分页查退货单 +查进度 / 取消: ```java -Page page = wh.returns().query(ReturnQuery.builder() - .createdAfter(Instant.parse("2026-11-01T00:00:00Z")) - .createdBefore(Instant.parse("2026-11-18T00:00:00Z")) - .pageSize(100) - .build()); -``` - -### 取消退货单 +WarehouseReturn detail = wh.returns().get("RMA2411053149"); +detail.status(); // 统一状态 +detail.rawStatus(); // 仓方原文 +detail.lines(); -```java -boolean ok = wh.returns().cancel("RMA2411053149"); +boolean ok = wh.returns().cancel("RMA2411053149"); // 传仓侧 RMA 号 ``` -> 传的是**仓侧 RMA 号**,不是我们的单号。 -> 仓方拒绝时**抛异常**,不返回 false。 - ---- - -## 3.5 库存同步 +**⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` / +`returnReason`(传了直接报错)。 -### 单次查询 +## 5.5 库存同步 ```java -import common.ecommerce.warehouse.model.InventoryQuery; - Page page = wh.inventory().query( InventoryQuery.builder() - .sku("AP0000X9US0010601") // 单个;多个用 .skus(list) - .warehouseCode("EDY-USLA") - .includeZeroStock(true) // 是否要零库存 + .sku("AP0000X9US0010601") + .includeZeroStock(true) .pageSize(500) .build()); for (InventorySnapshot s : page.items()) { - s.providerSku(); - s.available(); // 可用 - s.onHand(); // 总库存 - s.inTransit(); // 在途 - s.reserved(); // 冻结 + s.available(); s.onHand(); s.inTransit(); s.reserved(); } -``` - -### 全量同步怎么做 -```java -// 先问这家仓支不支持增量 +// 先问支不支持增量 InventorySyncStrategy strategy = wh.inventorySyncStrategy(); -// TIME_WINDOW 可以按 updatedAfter 增量 -// FULL_PULL_DIFF 只能全量拉再自己比对 -``` - -```java -// 全量翻页模板 -String cursor = null; -do { - Page p = wh.inventory().query( - InventoryQuery.builder().cursor(cursor).pageSize(500).build()); - saveToDb(p.items()); - cursor = p.nextCursor(); -} while (cursor != null); +// TIME_WINDOW 可按 updatedAfter 增量 / FULL_PULL_DIFF 只能全量拉再比对 ``` -### ⚠️ 坑 - -- **`-1` 是「仓方没给」,不是 0**:`pendingOutbound` / `alertQuantity` 这类字段,仓方常返回 null,SDK 统一映射成 -1。展示时要区分。 -- **易达云没有时间维度**,`updatedAfter` 不生效,只能全量。 -- **零库存**:`includeZeroStock` 不传时由仓方默认(多数仓只返回 >0 的)。 - ---- +**⚠️ 坑** -## 3.6 商品主数据 +- **`-1` 是「仓方没给」不是 0**(`pendingOutbound` / `alertQuantity` 常为 null → 映射成 -1) +- 易达云没有时间维度,`updatedAfter` 不生效 -### 建档 +## 5.6 商品主数据 ```java WarehouseProduct p = WarehouseProduct.builder() - // ===== 必填 ===== .omsSku("SKU-001") .name("蓝牙音箱") .lengthCm(12).widthCm(10).heightCm(8) .weightGrams(500) - // ===== 强烈建议 ===== - .providerSku("AP0000X9US0010601") // ⚠️ 见 [4.2 SKU](#42-sku到底传哪一个最容易错) + .providerSku("AP0000X9US0010601") .nameEn("Bluetooth Speaker") .barcode("N94900373802") .declaredValue(Money.of("19.99", "USD")) @@ -610,106 +623,62 @@ wh.createProduct(p); | `packingType` | 不用 | **必填**(0 原包装 / 1 重新打包) | 不用 | | `hsCode` 三项 | 用 | **必填整组** | 只用 `declaredValue` | -> 不知道传哪个?**看目标仓是哪家,按那一列的要求传。** - -### 查询 +查询: ```java Page page = wh.queryProducts( - ProductQuery.builder() - .providerSku("AP0000X9US0010601") // 仓侧 SKU - .pageSize(100) - .build()); - -ProductInfo info = page.items().get(0); -info.lengthCm(); info.weightGrams(); // **实际值**,不是预报值 -info.packedQuantity(); + ProductQuery.builder().providerSku("AP0000X9US0010601").build()); ``` -### ⚠️ 坑 +**⚠️ 坑** -- **易达云是「创建」不是「保存」**:同 SKU 重复建档会报错。运去哪才是 upsert。 -- **易达云不带时间窗时只查最近一个月**,查老商品必须显式给 `createdAfter/Before`。 -- **运去哪不支持条码和时间窗过滤**,传了会本地报错(不会静默忽略)。 - ---- +- 易达云是「创建」不是 upsert,同 SKU 重复建档会报错 +- 易达云不带时间窗只查最近一个月 +- 运去哪不支持条码 / 时间窗过滤,传了本地报错 -## 3.7 对账:拉费用明细 - -三个方法,看你要什么: +## 5.7 对账:拉费用明细 ```java -// ① 账户流水(充值 / 扣费 / 退费 + 余额) +// ① 账户流水 List flows = wh.fees().settlements(FeeQuery.builder() .settledAfter(Instant.parse("2026-10-01T00:00:00Z")) .settledBefore(Instant.parse("2026-11-01T00:00:00Z")) - .pageSize(200) .build()); -// ② 按订单拆的费用(应收 / 折扣 / 实付 + 计费重) +// ② 按订单拆的费用 List costs = wh.fees().orderCosts(FeeQuery.builder() - .saleOrderNo("SO-20261117-001") - .build()); + .saleOrderNo("SO-20261117-001").build()); -// ③ 仓租(按 SKU + 计费日) +// ③ 仓租 List rents = wh.fees().storageRents(FeeQuery.builder() .settledAfter(Instant.parse("2026-10-01T00:00:00Z")) .settledBefore(Instant.parse("2026-10-31T00:00:00Z")) .build()); -``` - -**你会拿到什么** -```java -d.documentNo(); // 单据号 -d.feeName(); // 计费项名,如「尾程-燃油附加费」 -d.feeType(); // OPERATION / STORAGE / VALUE_ADDED / LAST_MILE -d.amount(); // Money(金额 + 币种) -d.settledAt(); // 计费时间 -d.estimated(); // true 预估 / false 实际 -``` - -### 发货前算运费 - -```java +// 发货前算运费 List quotes = wh.fees().estimate(FeeEstimateQuery.builder() .lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000) .receiveCountry("US").receivePostal("91761") - .logisticsServiceCode("80") // 指定渠道;空则返回所有渠道 + .logisticsServiceCode("80") .build()); - -for (FeeEstimateResult q : quotes) { - for (FeeEstimateResult.CarrierQuote c : q.carriers()) { - c.carrier(); // 渠道名 - c.totalRate(); // 总价(Money) - c.costItems(); // 细分 - } -} ``` -### ⚠️ 坑 - -- **必须给成本类型或时间窗**,否则本地拒绝(防止拉全量把账户拉爆)。 -- **易达云的「3 个月」时间窗阈值很怪**:同天数不同起点,结果可能一个通一个拒。超限时仓方返回明确错误,catch 后缩小窗口重试即可。 -- **费用试算第一次常超时**,重试一次就好。 +单据字段:`documentNo()` / `feeName()` / `feeType()` / `amount()` / `settledAt()` / `estimated()` ---- - -## 3.8 打单:箱唛 / BOL +**⚠️ 坑**:必须给成本类型或时间窗,否则本地拒绝;易达云时间窗阈值较怪,超限 catch 后缩窗重试。 -### 箱唛(外箱标) +## 5.8 打单:箱唛 / BOL ```java import common.ecommerce.warehouse.enums.CaseMarkPaperSize; import common.ecommerce.warehouse.model.CaseMarkPrintCommand; WarehouseLabel label = wh.printCaseMarks(CaseMarkPrintCommand.builder() - .paperSize(CaseMarkPaperSize.SIZE_70_30) // 见下表 + .paperSize(CaseMarkPaperSize.SIZE_70_30) .printSkuName(false) .remark("Made in China") - .item("AP0000X9US0010601", 2) // SKU + 份数,最多 50 个 + .item("AP0000X9US0010601", 2) // SKU + 份数,最多 50 个 .build()); - label.url(); // PDF 地址 ``` @@ -720,36 +689,26 @@ label.url(); // PDF 地址 | `SIZE_100_150` | 100 × 150 mm | | `SIZE_60_40` | 60 × 40 mm | -> ⚠️ **枚举是按实测尺寸命名的**。仓方文档标的和实际印出来的对不上(文档说第 2 档 6×4cm、第 3 档 A4,实际反过来),以枚举名为准。 +> 枚举按**实测尺寸**命名。仓方文档标的与实际印出来的对不上,以枚举名为准。 -### BOL(提货单 / 签收凭证) +BOL(提货单 / 签收凭证): ```java -List bols = wh.orderBols("FBA473182144"); // EDA 平台仓订单号 - -for (BolDocument b : bols) { - b.bolCode(); - b.fileUrl(); // BOL 文件 - b.podFileUrl(); // 签收凭证 POD - b.statusName(); // 如「已妥投」 - b.scheduledPickupQuantity(); -} +List bols = wh.orderBols("FBA473182144"); +b.fileUrl(); // BOL 文件 +b.podFileUrl(); // 签收凭证 +b.statusName(); // 如「已妥投」 ``` --- -# 四、几条贯穿全局的规则 - -## 4.1 单位:尺寸 cm、重量 g +# 六、几条贯穿全局的规则 -| 项 | 单位 | 字段名 | -|---|---|---| -| 尺寸 | **cm** | 带 `Cm` 后缀 | -| 重量 | **g** | 带 `Grams` 后缀 | +## 6.1 单位:尺寸 cm、重量 g -**不要自己换算**——易达云内部要 kg,适配器会自己转。 +字段名带 `Cm` / `Grams` 后缀。**不要自己换算**——易达云内部要 kg,适配器会转。 -## 4.2 SKU:到底传哪一个(最容易错) +## 6.2 SKU:到底传哪一个(最容易错) **所有地方都用「建档时下发给仓方的那一串」。** @@ -760,26 +719,14 @@ for (BolDocument b : bols) { 之后:查商品 / 下单 / 查库存 都用同一串 ``` -| 你建档时 | 仓方存的 | 之后必须传 | +| 建档时 | 仓方存的 | 之后必须传 | |---|---|---| | 传了 `providerSku`(如 `AP0000X9US0010601`) | 它 | **它**(≠ OMS SKU) | | 没传 | `omsSku` | `omsSku` | -各仓字段名不同,但**值一样**: - -| 场景 | 易达云字段 | 运去哪字段 | -|---|---|---| -| 建档 | `skuCode` | `sku` | -| 查商品 | `skuCode` | `skuList` | -| 下单 | `productSku` | `sku` | -| 查库存 | `skuCodeList` | `sku` | +**SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。 -> **SDK 不做 OMS→仓侧 SKU 转换**。映射表在你们手里。 -> 传错不会报错,只会**查不到**——这是最难排查的坑之一。 - -## 4.3 分页:怎么翻页 - -每个查询都有 `pageSize` 和 `cursor`: +## 6.3 分页 ```java String cursor = null; @@ -790,32 +737,21 @@ do { } while (cursor != null); ``` -- `cursor` 第一页传 `null` -- **不要自己算页码**:各仓起点不同(易达云从 1、运去哪从 0),游标已经屏蔽了差异 -- `hasMore()` 由游标推导,**不要拿 `items().size()` 去猜** - -## 4.4 金额:为什么一定要用 Money +- 第一页 `cursor` 传 `null` +- **不要自己算页码**:各仓起点不同(易达云 1、运去哪 0),游标已屏蔽差异 +- 判断有没有下一页用 `hasMore()`,不要拿 `items().size()` 猜 -```java -Money.of("19.99", "USD") // ✅ -19.99 // ❌ -``` +## 6.4 金额 -裸 `double` 会丢币种,对账时美元和加元混在一起就完了。所有金额字段都是 `Money`,带 `amount()` 和 `currencyCode()`。 +一律 `Money.of("19.99", "USD")`,不要传裸 `double`——会丢币种,对账时美元和加元混在一起就完了。 --- -# 五、出错了怎么办 +# 七、出错了怎么办 -## 5.1 五类异常 +## 7.1 五类异常 ```java -import common.ecommerce.warehouse.error.WarehouseException; -import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; -import common.ecommerce.warehouse.error.OutboundCancelBlockedException; -import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException; -import common.ecommerce.shared.error.TransientException; - try { wh.outbound().create(cmd); } catch (OutboundCancelChargeRequiredException e) { @@ -823,9 +759,9 @@ try { } catch (OutboundCancelBlockedException e) { // 已发货不能取消 } catch (WarehouseUnsupportedCapabilityException e) { - // 这家仓不支持这个功能,换方案 + // 该仓不支持,换方案 } catch (TransientException e) { - // 网络 / 超时,可以重试 + // 网络 / 超时,可重试 } catch (WarehouseException e) { // 其它仓方错误 } @@ -833,45 +769,43 @@ try { | 异常 | 含义 | 重试? | |---|---|---| -| `TransientException` | 网络 / 超时 | ✅ 可以 | -| `WarehouseException`(`retryable=true`) | HTTP 5xx | ✅ 可以 | -| `WarehouseException`(`retryable=false`) | 业务错误(参数错 / 单号不存在) | ❌ 不要 | -| `WarehouseUnsupportedCapabilityException` | 该仓不支持 | ❌ 换方案 | -| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需用户确认 | +| `TransientException` | 网络 / 超时 | ✅ | +| `WarehouseException`(`retryable=true`) | HTTP 5xx | ✅ | +| `WarehouseException`(`retryable=false`) | 业务错误(参数 / 单号) | ❌ | +| `WarehouseUnsupportedCapabilityException` | 该仓不支持 | ❌ | +| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需确认 | | `OutboundCancelBlockedException` | 不能取消 | ❌ | -## 5.2 异常里有什么 +## 7.2 异常里有什么 ```java catch (WarehouseException e) { - e.operation(); // "warehouse.outbound.create" 哪个操作 + e.operation(); // "warehouse.outbound.create" e.warehouseCode(); // 哪个仓 e.requestId(); // 我们的链路 ID e.platformCode(); // 仓方业务码 - e.platformRequestId(); // 仓方的链路 ID,问仓方时给他们这个 - e.retryable(); // 要不要重试 - e.getMessage(); // 错误描述 + e.platformRequestId(); // 仓方链路 ID,问仓方时给这个 + e.retryable(); + e.getMessage(); } ``` -> `rawResponse()` 里有**完整原始报文**,可能含买家地址电话。 -> **不要直接写进日志**,排查时临时看可以。 +> `rawResponse()` 有完整报文,可能含买家地址电话。**别直接落日志**。 -## 5.3 常见报错对照 +## 7.3 常见报错对照 | 报错 | 原因 | 怎么办 | |---|---|---| -| `requires an idempotencyStore` | 没配 `IdempotencyStore` | 见 [1.2](#12-一次性配置) | -| `该仓没有配置接入账户` | `warehouseCode` 对不上 | 检查 `WarehouseRepository` | -| `WarehouseUnsupportedCapabilityException` | 这家仓没这个接口 | 看 [二](#二我要做的事能不能做) 的表 | -| `http 401` / token 相关 | 凭据错 | 检查 `ChannelSecret` 的字段 | -| `SKU 不存在` / 查不到数据 | SKU 用了 OMS 的而不是仓侧的 | 见 [4.2](#42-sku到底传哪一个最容易错) | -| `查询无数据` | 时间窗不对(如易达云只查最近一月) | 显式给 `createdAfter/Before` | -| `参数不能为空` | 必填字段漏了 | 看对应任务的「必填」段 | +| `requires an idempotencyStore` | 没配 | 见 [3.1](#31-实现两个-spi) | +| `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` | +| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [四](#四我要做的事能不能做) | +| `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` | +| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [6.2](#62-sku到底传哪一个最容易错) | +| `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` | -## 5.4 幂等:重复调用安全吗 +## 7.4 幂等:重复调用安全吗 -**写操作都安全**,同样的单号调两次不会重复下单: +写操作都安全,同样单号调两次不会重复下单: | 操作 | 幂等键 | |---|---| @@ -881,7 +815,7 @@ catch (WarehouseException e) { | 取消退货单 | 仓编码 + 仓侧 RMA 号 | | 建调拨单 | 仓编码 + `transferRequestNo` | -**重试策略建议**: +重试建议: ```java int maxRetry = 3; @@ -890,50 +824,30 @@ for (int i = 0; i < maxRetry; i++) { return wh.outbound().create(cmd); } catch (WarehouseException e) { if (!e.retryable() || i == maxRetry - 1) throw e; - Thread.sleep(1000L << i); // 1s / 2s / 4s 退避 + Thread.sleep(1000L << i); // 1s / 2s / 4s } } ``` --- -## 附录 A:日志怎么看 +## 附录 A:日志 -配了 `Slf4jCallObserver` 后,每次调用打一行: +配了 `Slf4jCallObserver` 后每次调用打一行: ``` sdk-call at=2026-11-17 10:00:00 op=warehouse.outbound.create provider=EDAYUN requestId=xxx cost=812ms result=-1 failed=0 code=200 params={omsSku=SKU-001} ``` -失败时多带 `retryable` / `platformCode` / `error`: - -``` -sdk-call-failed at=... op=warehouse.outbound.create provider=EDAYUN - cost=200ms code=500 platformCode=500 - error=WarehouseException: edayun outbound.create business error: ... -``` - -| 字段 | 含义 | -|---|---| -| `op` | 哪个操作 | -| `provider` | 哪家仓 | -| `requestId` | 我们的链路 ID | -| `cost` | 耗时 | -| `result` | 返回条数(-1 表示不适用) | -| `code` / `platformCode` | 业务码 / 仓方码 | -| `params` | 关键入参摘要(不含 PII) | - -日志**不含凭据和完整报文**,可以放心长期保留。 - ---- +失败时多带 `retryable` / `platformCode` / `error`。日志**不含凭据与完整报文**。 ## 附录 B:枚举速查 | 枚举 | 取值 | |---|---| | `Platform` | `AMAZON_SC` `AMAZON_VC` `WALMART_SC` `WALMART_1P` `TIKTOK` `TEMU` `EBAY` `SHEIN` `ALIEXPRESS` `TARGET` `BESTBUY` `WAYFAIR` `CUSTOM` | -| `LabelMode` | `WAREHOUSE_LABEL`(仓出)/ `PLATFORM_LABEL`(我们传面单) | +| `LabelMode` | `WAREHOUSE_LABEL` / `PLATFORM_LABEL` | | `CancelEligibility` | `FREE` / `CHARGED` / `BLOCKED` | | `ReturnDealMethod` | `CUSTOMER_PICKUP` / `PHOTO_CONFIRM` / `DESTROY` / `WAREHOUSE_CONFIRM` | | `ReturnStatus` | `DRAFT` / `PENDING_REVIEW` / `REJECTED` / `RETURNING` / `PENDING_RECEIPT` / `COMPLETED` / `CLOSED` / `UNKNOWN` | @@ -942,20 +856,13 @@ sdk-call-failed at=... op=warehouse.outbound.create provider=EDAYUN | `AddressType` | `BUSINESS` / `RESIDENTIAL` / `MIXED` / `UNKNOWN` | | `CaseMarkPaperSize` | `SIZE_70_30` / `SIZE_100_60` / `SIZE_100_150` / `SIZE_60_40` | ---- - -## 附录 C:需要更细的字段说明? +## 附录 C:各仓接口细节 -本手册只覆盖**怎么用**。每个字段的完整语义在代码的 javadoc 里: - -```java -OutboundCommand cmd = ...; -cmd.lines(); // IDE 里按住 Ctrl 点进去看注释 -``` - -各仓的接口细节(文档与真机差异、码表、已知问题)在: +文档与真机的差异、码表、已知问题都在源码的 `docs-warehouse/` 目录: - `docs-warehouse/edayun/README.md`、`docs-warehouse/edayun/TODO.md` - `docs-warehouse/yqn/README.md` - `docs-warehouse/hengjian/README.md` - `docs-warehouse/architecture.md`(分层与能力位设计) + +字段的完整语义在每个模型的 javadoc 里(IDE 里 Ctrl+点击看)。