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+点击看)。