diff --git a/docs-warehouse/SDK使用说明-Jar引入.md b/docs-warehouse/SDK使用说明-Jar引入.md
new file mode 100644
index 0000000..ea62d7f
--- /dev/null
+++ b/docs-warehouse/SDK使用说明-Jar引入.md
@@ -0,0 +1,783 @@
+# 三方仓 SDK 使用说明(Jar 引入版)
+
+> 我们提供编译好的 jar,按正常 Maven / Gradle 依赖引入即可,**不需要拷源码**。
+> 本文档说明:引哪些 jar、怎么配置、每个业务动作怎么写。
+>
+> 想直接用源码集成的话,看同目录的 `SDK使用说明-源码集成.md`。
+>
+> JDK 1.8 · 版本 1.0.0-SNAPSHOT
+
+---
+
+## 快速导航
+
+| 我要… | 看这节 |
+|---|---|
+| 引入 jar | [一、集成方式](#一集成方式) |
+| 配好 SPI / SDK / 连接 | [二、配置](#二配置) |
+| 确认能跑通 | [三、快速上手](#三快速上手) |
+| 知道某仓支不支持某功能 | [四、我要做的事能不能做](#四我要做的事能不能做) |
+| 发货 / 面单 | [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 / 分页 / 金额 | [六、贯穿全局的规则](#六几条贯穿全局的规则) |
+| 报错 / 重试 | [七、出错了怎么办](#七出错了怎么办) |
+
+---
+
+# 一、集成方式
+
+## 1.1 需要引入的 jar
+
+**核心两个 + 按需引入适配器**:
+
+| jar | 说明 | 必需 |
+|---|---|---|
+| `warehouse-sdk-core` | 统一模型 + 门面 + 能力接口(会带出 `sdk-common`) | ✅ |
+| `warehouse-sdk-edayun` | 易达云适配器 | 用哪个仓引哪个 |
+| `warehouse-sdk-yqn` | 运去哪适配器 | 同上 |
+| `warehouse-sdk-xincang` | 信仓适配器 | 同上 |
+| `warehouse-sdk-hengjian` | 恒健适配器 | 同上 |
+
+> 适配器 jar 只依赖 `sdk-common` + `warehouse-sdk-core`,**互不依赖**,
+> 只引实际要用的那一个或几个即可,不会把别家仓的代码带进来。
+
+## 1.2 Maven
+
+```xml
+
+
+ ecommerce
+ warehouse-sdk-core
+ 1.0.0-SNAPSHOT
+
+
+
+
+ ecommerce
+ warehouse-sdk-edayun
+ 1.0.0-SNAPSHOT
+
+
+```
+
+## 1.3 Gradle
+
+```kotlin
+dependencies {
+ implementation("ecommerce:warehouse-sdk-core:1.0.0-SNAPSHOT")
+ implementation("ecommerce:warehouse-sdk-edayun:1.0.0-SNAPSHOT") // 按需
+}
+```
+
+## 1.4 jar 里有源码,建议开启 source 下载
+
+我们对外发布的 jar 同时带了 `-sources.jar`,IDE 里 Ctrl+点击能直接看到字段注释:
+
+```bash
+# Maven
+mvn dependency:sources
+
+# Gradle(IDEA 里右键项目 → Download Sources 也可)
+```
+
+## 1.5 传递依赖(jar 自动带上,不用手工加)
+
+| 库 | 版本 | 由谁带出 |
+|---|---|---|
+| `com.fasterxml.jackson.core:jackson-databind` | 2.13.5 | sdk-common |
+| `org.slf4j:slf4j-api` | 1.7.36 | sdk-common |
+| `com.squareup.okhttp3:okhttp` | 4.12.0 | sdk-common |
+
+> **不需要 Lombok**。
+
+**两个注意点**
+
+1. **OkHttp 4.x 是 Kotlin 写的**,需要 classpath 上有 `kotlin-stdlib`。
+ 不想引 Kotlin 的话,可以:
+ - 降级到 OkHttp 3.14.x(纯 Java,API 兼容),或
+ - 自己实现 `HttpTransport`(只有一个 `execute()` 方法),换成你们已有的 HTTP 客户端;
+ 需要的话我们出一个无 OkHttp 依赖的版本
+2. **版本冲突**:如果你们已有更高版本的 jackson / okhttp,直接用你们的,
+ 代码只用了最基础的 API(`ObjectMapper` / `MediaType` / `OkHttpClient`),向上兼容
+
+---
+
+# 二、配置
+
+## 2.1 实现两个 SPI
+
+### ① 仓编码 → 哪家仓
+
+```java
+import common.ecommerce.warehouse.spi.WarehouseRepository;
+import common.ecommerce.warehouse.spi.WarehouseAccount;
+import java.util.*;
+
+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") // 决定用哪个适配器
+ .providerWarehouseId("2") // 仓方仓 id
+ .credentialRef("kms://edayun") // 只是个标识,SDK 不会去取
+ .timeZone("America/Los_Angeles")
+ .build());
+
+ accounts.put("YQN-NY", WarehouseAccount.builder()
+ .warehouseCode("YQN-NY")
+ .provider("YQN")
+ .providerWarehouseId("RF_NY_US") // 运去哪用仓编码
+ .credentialRef("kms://yqn")
+ .timeZone("America/New_York")
+ .build());
+ }
+
+ @Override
+ public List findByWarehouseCode(String warehouseCode) {
+ WarehouseAccount a = accounts.get(warehouseCode);
+ return a == null ? Collections.emptyList()
+ : Collections.singletonList(a);
+ }
+
+ @Override
+ public Optional find(String warehouseCode, String provider) {
+ WarehouseAccount a = accounts.get(warehouseCode);
+ return a != null && a.provider().equals(provider) ? Optional.of(a) : Optional.empty();
+ }
+}
+```
+
+**`providerWarehouseId` 各仓填什么**
+
+| 仓 | 填什么 | 例子 |
+|---|---|---|
+| 易达云 | 数字仓 id | `"2"` |
+| 运去哪 | 仓编码 | `"RF_NY_US"` |
+| 信仓 | 仓编码 | |
+| 恒健 | 仓编码 | |
+
+### ② 写操作怎么防重复
+
+只要你们有建单 / 取消这类写操作就必须实现。核心是**「查 + 写」必须原子**。
+
+> 下面代码里的 `loadFromRedisOrDb` / `reclaimable` / `writeInProgress` / `markStatus`
+> 是**示意方法名**,按你们自己的存储实现。
+> 结构可以照抄 `sdk-testkit/InMemoryIdempotencyStore`(如果拷了的话)。
+
+```java
+import common.ecommerce.shared.spi.*;
+import java.time.Instant;
+import java.util.Optional;
+
+public class MyIdempotencyStore implements IdempotencyStore {
+
+ /**
+ * 抢占。四种返回:
+ * 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);
+
+ 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);
+ default: return IdempotencyClaim.of(IdempotencyClaim.Outcome.IN_PROGRESS, existing);
+ }
+ }
+
+ @Override
+ public void complete(String key, String owner, String resultRef, Instant now) {
+ markStatus(key, owner, IdempotencyStatus.SUCCEEDED, resultRef, now);
+ }
+
+ @Override
+ public void fail(String key, String owner, boolean retryable, Instant now) {
+ markStatus(key, owner,
+ retryable ? IdempotencyStatus.FAILED_RETRYABLE : IdempotencyStatus.FAILED_FINAL,
+ null, now);
+ }
+
+ @Override
+ public Optional get(String key) {
+ return Optional.ofNullable(loadFromRedisOrDb(key));
+ }
+}
+```
+
+**必须满足两条**
+
+1. `claim()` 的「查 + 写」要原子:Redis 用 `SET key value NX EX ttl`,MySQL 用唯一索引
+2. `complete` / `fail` 只能由当前 owner 写,否则过期 owner 会覆盖新抢占者的结果
+
+> 只做查询可以先不实现;一旦建单会抛
+> `IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations`。
+
+## 2.2 组装 SDK
+
+```java
+import common.ecommerce.warehouse.sdk.WarehouseSdk;
+import common.ecommerce.shared.audit.Slf4jCallObserver;
+import common.ecommerce.edayun.adapter.EdayunAdapterFactory;
+import common.ecommerce.yqn.adapter.YqnAdapterFactory;
+import java.time.Clock;
+import java.time.ZoneId;
+
+// Spring 里定义成单例 Bean
+WarehouseSdk sdk = WarehouseSdk.builder()
+ .warehouseRepository(new MyWarehouseRepository()) // 必需
+ .idempotencyStore(myIdempotencyStore) // 写操作必需
+ .clock(Clock.systemUTC())
+ .callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
+ .register(new EdayunAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
+ .register(new YqnAdapterFactory(Clock.systemUTC()))
+ .build();
+```
+
+**各仓工厂的构造参数**
+
+| 工厂 | 构造参数 |
+|---|---|
+| `EdayunAdapterFactory` | `(TokenStore, LockProvider, Clock)`;前两个可传 `null`(则每次重登) |
+| `YqnAdapterFactory` | `(Clock)` |
+| `XincangAdapterFactory` | `(TokenStore, LockProvider, Clock)` |
+| `HengjianAdapterFactory` | 无参 |
+
+> **务必做成单例。** 适配器里缓存了 token 与限流器,每次 `new` 会重复登录。
+
+## 2.3 连接信息(端点 + 凭据)
+
+SDK 不保存端点和凭据,每次调用由你们传:
+
+```java
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.shared.spi.ChannelSecret;
+
+WarehouseConnection conn = WarehouseConnection.of(
+ "https://test.omniselling.com.cn/saas-service/openapi/microService", // 端点
+ ChannelSecret.builder()
+ .appKey("...")
+ .appSecret("...")
+ .clientId("...") // 易达云换 token 用
+ .clientSecret("...")
+ .build());
+```
+
+**各仓需要的凭据字段**
+
+| 仓 | 必填 | 说明 |
+|---|---|---|
+| 易达云 | `appKey` `appSecret` `clientId` `clientSecret` | 前两个算签名,后两个换 token |
+| 运去哪 | `appSecret` | 组织级 token,直接放 `appSecret` |
+| 信仓 | `appKey` `appSecret` | 换 token |
+| 恒健 | `appSecret` | 算签名 |
+
+
+---
+
+# 三、快速上手
+
+## 3.1 拿到仓的操作入口
+
+```java
+import common.ecommerce.warehouse.sdk.WarehouseOperations;
+
+WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);
+```
+
+后面所有 `wh.xxx()` 都从这个对象出发。
+
+## 3.2 验证能跑通
+
+**只读,不改任何数据**:
+
+```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());
+}
+```
+
+能打出仓,说明凭据、端点、配置全对。跑不通时:
+
+| 现象 | 原因 |
+|---|---|
+| `该仓没有配置接入账户` | `warehouseCode` 和 `WarehouseRepository` 对不上 |
+| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [四](#四我要做的事能不能做)) |
+| `http 401` / token 错误 | `ChannelSecret` 字段填错 |
+| 超时 | 端点不通;易达云首次调用慢,重试一次 |
+
+---
+
+
+---
+
+# 四、我要做的事能不能做?
+
+| 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 |
+|---|---|:---:|:---:|:---:|:---:|
+| 建出库单 / 打面单 | `outbound().create` / `.packages` | ✅ | ✅ | ✅ | ✅ |
+| 查出库单 | `outbound().get` / `.query` | ✅ | ✅ | ✅ | ✅ |
+| 取消出库单 | `outbound().cancel` | ✅ | ✅ | ✅ | ✅ |
+| 查库存 | `inventory().query` | ✅ | ✅ | ✅ | ✅ |
+| 建入库单 | `inbound().create` | ✅ | ✅ | ✅ | ✅ |
+| 退货(建单 / 查 / 取消) | `returns().create` / `.get` / `.cancel` | ✅ | ✅ | ❌ | ✅ |
+| 退货检验后处理 | `returns().process` | ❌ | ✅ | ❌ | ❌ |
+| 拉费用明细 | `fees().settlements` | ✅ | ✅ | ❌ | ✅ |
+| 费用试算 | `fees().estimate` | ✅ | ✅ | ❌ | ✅ |
+| 商品建档 | `createProduct` | ✅ | ✅ | ✅ | ✅ |
+| 商品查询 | `queryProducts` | ✅ | ✅ | ❌ | ❌ |
+| 物流轨迹 | `track` / `trackShipment` | ✅ | ✅ | ❌ | ❌ |
+| 仓库清单 | `warehouses()` | ✅ | ✅ | ✅ | ✅ |
+| 承运商清单 | `carrierDirectory()` | ✅ | ❌ | ❌ | ❌ |
+| 物流产品清单 | `logisticsProducts(code)` | ✅ | ✅ | ❌ | ✅ |
+| BOL(平台仓订单) | `orderBols(no)` | ✅ | ❌ | ❌ | ❌ |
+| 打印箱唛 | `printCaseMarks(cmd)` | ✅ | ❌ | ❌ | ❌ |
+| 调拨 | `createTransfer` | ❌ | ✅ | ✅ | ✅ |
+| 销毁 | `createDestruction` | ❌ | ✅ | ❌ | ✅ |
+| 物流异动(召回 / 改址) | `createTrackingChange` | ❌ | ❌ | ❌ | ✅ |
+
+> **不支持就是抛异常**,不返回空列表。
+> 代码判断:`sdk.capabilities("EDY-USLA").supported().contains(WarehouseCapability.RETURN)`
+
+---
+
+# 五、按任务
+
+> 以下假设 `wh` 已就绪(见 [3.4](#34-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。
+
+## 5.1 发货:建出库单 → 拿面单
+
+```java
+import common.ecommerce.shared.model.Platform;
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.model.*;
+
+OutboundCommand cmd = OutboundCommand.builder()
+ // ===== 必填 =====
+ .outboundRequestNo("OB-20261117-001")
+ .salesPlatform(Platform.AMAZON_SC)
+ .shipTo(ShipTo.builder()
+ .name("John Smith")
+ .phone("+1-555-0100")
+ .countryCode("US") // 二字码
+ .stateOrProvince("California") // ⚠️ 易达云要全称、运去哪要 CA
+ .city("Escondido")
+ .addressLine1("1308 E Washington Ave")
+ .postalCode("92027")
+ .build())
+ .line(OutboundLine.builder()
+ .lineNo("1")
+ .omsSku("SKU-001")
+ .providerSku("AP0000X9US0010601") // ⚠️ 见 6.2 SKU
+ .quantity(2)
+ .declareName("蓝牙音箱")
+ .declareValue(Money.of("19.99", "USD")) // 单价,不是总额
+ .build())
+ // ===== 强烈建议 =====
+ .orderRef("SO-20261117-001") // 平台单号,仓侧幂等键
+ .warehouseId("2")
+ .currency("USD")
+ .declaredTotal(Money.of("39.98", "USD"))
+ .build();
+
+OutboundReceipt receipt = wh.outbound().create(cmd);
+receipt.providerOrderId(); // 仓侧单号,**保存下来**
+```
+
+拿面单:
+
+```java
+List pkgs = wh.outbound().packages(
+ OutboundRef.ofRequestNo("OB-20261117-001"));
+for (PackageResult p : pkgs) {
+ p.trackingNumber(); // 跟踪号
+ p.labelRef(); // 面单 URL
+ p.carrier();
+}
+```
+
+**⚠️ 坑**
+
+1. 州名:易达云要 `California`,运去哪要 `CA`
+2. 平台面单把 `labelMode` 设为 `PLATFORM_LABEL`;易达云要**文件 URL 不是 base64**
+3. 重复建单不会重复下单(幂等键 = `orderRef`,没有则 `outboundRequestNo`)
+4. 保存 `providerOrderId`,后续查单 / 取消能少一次请求
+
+## 5.2 查物流轨迹
+
+```java
+List events = wh.track("1Z999AA10123456784");
+
+TrackingInfo info = wh.trackShipment("1Z999AA10123456784");
+info.firstOnlineAt(); // 上网时间(为空 = 物流还没启动)
+info.deliveredAt(); // 妥投时间(为空 = 未签收)
+info.signedBy(); // 签收人(未签收 = null)
+info.events();
+```
+
+**⚠️ 坑**:查不到不报错 —— `track()` 返回空列表、`trackShipment()` 返回 `null`。
+
+## 5.3 取消出库单
+
+```java
+CancelEligibility e = wh.outbound().checkCancel(
+ OutboundRef.ofRequestNo("OB-20261117-001"));
+// FREE / CHARGED / BLOCKED
+
+if (e == CancelEligibility.FREE) {
+ CancelResult r = wh.outbound().cancel(CancelCommand.builder()
+ .outboundRequestNo("OB-20261117-001")
+ .providerOrderId("ORD123")
+ .acceptCharge(false)
+ .build());
+ r.cancelled();
+}
+```
+
+**⚠️ 坑**:`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")
+ .carrierCode("FedEx")
+ .line("AP0000X9US0010601", 1, ReturnDealMethod.WAREHOUSE_CONFIRM)
+ .warehouseId("2")
+ .build());
+
+r.providerReturnId(); // 仓侧 RMA 号,**保存下来**
+```
+
+查进度 / 取消:
+
+```java
+WarehouseReturn detail = wh.returns().get("RMA2411053149");
+detail.status(); // 统一状态
+detail.rawStatus(); // 仓方原文
+detail.lines();
+
+boolean ok = wh.returns().cancel("RMA2411053149"); // 传仓侧 RMA 号
+```
+
+**⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` /
+`returnReason`(传了直接报错)。
+
+## 5.5 库存同步
+
+```java
+Page page = wh.inventory().query(
+ InventoryQuery.builder()
+ .sku("AP0000X9US0010601")
+ .includeZeroStock(true)
+ .pageSize(500)
+ .build());
+
+for (InventorySnapshot s : page.items()) {
+ s.available(); s.onHand(); s.inTransit(); s.reserved();
+}
+
+// 先问支不支持增量
+InventorySyncStrategy strategy = wh.inventorySyncStrategy();
+// TIME_WINDOW 可按 updatedAfter 增量 / FULL_PULL_DIFF 只能全量拉再比对
+```
+
+**⚠️ 坑**
+
+- **`-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")
+ .nameEn("Bluetooth Speaker")
+ .barcode("N94900373802")
+ .declaredValue(Money.of("19.99", "USD"))
+ .countryOfOrigin("CN")
+ .hsCode("8517.62")
+ .build();
+
+wh.createProduct(p);
+```
+
+**分仓必填差异**
+
+| 字段 | 易达云 | 运去哪 | 信仓 |
+|---|---|---|---|
+| `nameEn` | 可选 | **必填** | 不用 |
+| `packingType` | 不用 | **必填**(0 原包装 / 1 重新打包) | 不用 |
+| `hsCode` 三项 | 用 | **必填整组** | 只用 `declaredValue` |
+
+查询:
+
+```java
+Page page = wh.queryProducts(
+ ProductQuery.builder().providerSku("AP0000X9US0010601").build());
+```
+
+**⚠️ 坑**
+
+- 易达云是「创建」不是 upsert,同 SKU 重复建档会报错
+- 易达云不带时间窗只查最近一个月
+- 运去哪不支持条码 / 时间窗过滤,传了本地报错
+
+## 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"))
+ .build());
+
+// ② 按订单拆的费用
+List costs = wh.fees().orderCosts(FeeQuery.builder()
+ .saleOrderNo("SO-20261117-001").build());
+
+// ③ 仓租
+List rents = wh.fees().storageRents(FeeQuery.builder()
+ .settledAfter(Instant.parse("2026-10-01T00:00:00Z"))
+ .settledBefore(Instant.parse("2026-10-31T00:00:00Z"))
+ .build());
+
+// 发货前算运费
+List quotes = wh.fees().estimate(FeeEstimateQuery.builder()
+ .lengthCm(22).widthCm(22).heightCm(22).weightGrams(1000)
+ .receiveCountry("US").receivePostal("91761")
+ .logisticsServiceCode("80")
+ .build());
+```
+
+单据字段:`documentNo()` / `feeName()` / `feeType()` / `amount()` / `settledAt()` / `estimated()`
+
+**⚠️ 坑**:必须给成本类型或时间窗,否则本地拒绝;易达云时间窗阈值较怪,超限 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)
+ .printSkuName(false)
+ .remark("Made in China")
+ .item("AP0000X9US0010601", 2) // SKU + 份数,最多 50 个
+ .build());
+label.url(); // PDF 地址
+```
+
+| 纸张 | 实际尺寸 |
+|---|---|
+| `SIZE_70_30` | 70 × 30 mm |
+| `SIZE_100_60` | 100 × 60 mm |
+| `SIZE_100_150` | 100 × 150 mm |
+| `SIZE_60_40` | 60 × 40 mm |
+
+> 枚举按**实测尺寸**命名。仓方文档标的与实际印出来的对不上,以枚举名为准。
+
+BOL(提货单 / 签收凭证):
+
+```java
+List bols = wh.orderBols("FBA473182144");
+b.fileUrl(); // BOL 文件
+b.podFileUrl(); // 签收凭证
+b.statusName(); // 如「已妥投」
+```
+
+---
+
+# 六、几条贯穿全局的规则
+
+## 6.1 单位:尺寸 cm、重量 g
+
+字段名带 `Cm` / `Grams` 后缀。**不要自己换算**——易达云内部要 kg,适配器会转。
+
+## 6.2 SKU:到底传哪一个(最容易错)
+
+**所有地方都用「建档时下发给仓方的那一串」。**
+
+```
+建档时:providerSku 有值 → 仓方存它
+ 没值 → 仓方存 omsSku
+ ↓
+之后:查商品 / 下单 / 查库存 都用同一串
+```
+
+| 建档时 | 仓方存的 | 之后必须传 |
+|---|---|---|
+| 传了 `providerSku`(如 `AP0000X9US0010601`) | 它 | **它**(≠ OMS SKU) |
+| 没传 | `omsSku` | `omsSku` |
+
+**SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。
+
+## 6.3 分页
+
+```java
+String cursor = null;
+do {
+ Page page = wh.xxx(Query.builder().cursor(cursor).pageSize(100).build());
+ // 处理 page.items()
+ cursor = page.nextCursor();
+} while (cursor != null);
+```
+
+- 第一页 `cursor` 传 `null`
+- **不要自己算页码**:各仓起点不同(易达云 1、运去哪 0),游标已屏蔽差异
+- 判断有没有下一页用 `hasMore()`,不要拿 `items().size()` 猜
+
+## 6.4 金额
+
+一律 `Money.of("19.99", "USD")`,不要传裸 `double`——会丢币种,对账时美元和加元混在一起就完了。
+
+---
+
+# 七、出错了怎么办
+
+## 7.1 五类异常
+
+```java
+try {
+ wh.outbound().create(cmd);
+} catch (OutboundCancelChargeRequiredException e) {
+ // 取消要收费,等用户确认
+} catch (OutboundCancelBlockedException e) {
+ // 已发货不能取消
+} catch (WarehouseUnsupportedCapabilityException e) {
+ // 该仓不支持,换方案
+} catch (TransientException e) {
+ // 网络 / 超时,可重试
+} catch (WarehouseException e) {
+ // 其它仓方错误
+}
+```
+
+| 异常 | 含义 | 重试? |
+|---|---|---|
+| `TransientException` | 网络 / 超时 | ✅ |
+| `WarehouseException`(`retryable=true`) | HTTP 5xx | ✅ |
+| `WarehouseException`(`retryable=false`) | 业务错误(参数 / 单号) | ❌ |
+| `WarehouseUnsupportedCapabilityException` | 该仓不支持 | ❌ |
+| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需确认 |
+| `OutboundCancelBlockedException` | 不能取消 | ❌ |
+
+## 7.2 异常里有什么
+
+```java
+catch (WarehouseException e) {
+ e.operation(); // "warehouse.outbound.create"
+ e.warehouseCode(); // 哪个仓
+ e.requestId(); // 我们的链路 ID
+ e.platformCode(); // 仓方业务码
+ e.platformRequestId(); // 仓方链路 ID,问仓方时给这个
+ e.retryable();
+ e.getMessage();
+}
+```
+
+> `rawResponse()` 有完整报文,可能含买家地址电话。**别直接落日志**。
+
+## 7.3 常见报错对照
+
+| 报错 | 原因 | 怎么办 |
+|---|---|---|
+| `requires an idempotencyStore` | 没配 | 见 [3.1](#31-实现两个-spi) |
+| `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` |
+| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [四](#四我要做的事能不能做) |
+| `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` |
+| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [6.2](#62-sku到底传哪一个最容易错) |
+| `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` |
+
+## 7.4 幂等:重复调用安全吗
+
+写操作都安全,同样单号调两次不会重复下单:
+
+| 操作 | 幂等键 |
+|---|---|
+| 建出库单 | 仓编码 + `outboundRequestNo`(或 `orderRef`) |
+| 建入库单 | 仓编码 + `inboundRequestNo` |
+| 建退货单 | 仓编码 + `returnRequestNo` |
+| 取消退货单 | 仓编码 + 仓侧 RMA 号 |
+| 建调拨单 | 仓编码 + `transferRequestNo` |
+
+重试建议:
+
+```java
+int maxRetry = 3;
+for (int i = 0; i < maxRetry; i++) {
+ try {
+ return wh.outbound().create(cmd);
+ } catch (WarehouseException e) {
+ if (!e.retryable() || i == maxRetry - 1) throw e;
+ Thread.sleep(1000L << i); // 1s / 2s / 4s
+ }
+}
+```
+
+---
+
+## 附录 A:日志
+
+配了 `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`。日志**不含凭据与完整报文**。
+
+## 附录 B:枚举速查
+
+| 枚举 | 取值 |
+|---|---|
+| `Platform` | `AMAZON_SC` `AMAZON_VC` `WALMART_SC` `WALMART_1P` `TIKTOK` `TEMU` `EBAY` `SHEIN` `ALIEXPRESS` `TARGET` `BESTBUY` `WAYFAIR` `CUSTOM` |
+| `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` |
+| `WarehouseFeeType` | `OPERATION` / `STORAGE` / `VALUE_ADDED` / `LAST_MILE` |
+| `InventorySyncStrategy` | `TIME_WINDOW` / `FULL_PULL_DIFF` |
+| `AddressType` | `BUSINESS` / `RESIDENTIAL` / `MIXED` / `UNKNOWN` |
+| `CaseMarkPaperSize` | `SIZE_70_30` / `SIZE_100_60` / `SIZE_100_150` / `SIZE_60_40` |
+
+## 附录 C:各仓接口细节
+
+文档与真机的差异、码表、已知问题都在源码的 `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+点击看)。
diff --git a/docs-warehouse/SDK操作手册.md b/docs-warehouse/SDK使用说明-源码集成.md
similarity index 90%
rename from docs-warehouse/SDK操作手册.md
rename to docs-warehouse/SDK使用说明-源码集成.md
index 02c6688..6174e70 100644
--- a/docs-warehouse/SDK操作手册.md
+++ b/docs-warehouse/SDK使用说明-源码集成.md
@@ -1,7 +1,9 @@
# 三方仓 SDK 使用说明(源码集成版)
-> 贵方拿到的是一份**完整源码**,直接用源码方式集成,不走 Maven / Gradle 依赖坐标。
-> 本文档说明:**源码怎么放、要引哪些第三方库、每个业务动作怎么写**。
+> 我们提供完整源码,直接用源码方式集成,**不走 Maven 坐标**。
+> 本文档说明:源码怎么放、要引哪些第三方库、每个业务动作怎么写。
+>
+> 想用 jar 引入的话,看同目录的 `SDK使用说明-Jar引入.md`。
>
> JDK 1.8
@@ -13,18 +15,15 @@
|---|---|
| 把源码放进项目 | [一、源码怎么集成](#一源码怎么集成) |
| 知道要引哪些 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 / 分页 / 金额 | [六、贯穿全局的规则](#六几条贯穿全局的规则) |
-| 报错 / 重试 | [七、出错了怎么办](#七出错了怎么办) |
+| 配好 SPI / SDK / 连接 | [三、配置](#三配置) |
+| 确认能跑通 | [四、快速上手](#四快速上手) |
+| 知道某仓支不支持某功能 | [五、我要做的事能不能做](#五我要做的事能不能做) |
+| 发货 / 面单 | [6.1](#61-发货建出库单--拿面单) |
+| 查轨迹 / 取消订单 | [6.2](#62-查物流轨迹) · [6.3](#63-取消出库单) |
+| 退货 / 库存 / 商品 / 对账 | [6.4](#64-退货) · [6.5](#65-库存同步) · [6.6](#66-商品主数据) · [6.7](#67-对账拉费用明细) |
+| 打箱唛 / BOL | [6.8](#68-打单箱唛--bol) |
+| 单位 / SKU / 分页 / 金额 | [七、贯穿全局的规则](#七几条贯穿全局的规则) |
+| 报错 / 重试 | [八、出错了怎么办](#八出错了怎么办) |
---
@@ -48,7 +47,7 @@ common-ecommerce/
## 1.2 需要拷贝的模块
-**必拷**(只拷 `src/main/java`):
+**只拷 `src/main/java`**:
| 目录 | 作用 | 文件数 |
|---|---|---|
@@ -63,7 +62,7 @@ common-ecommerce/
- `channel-sdk-core/`、`lingxing/` —— 平台商品域 / 领星,与三方仓无关
- 各模块的 `src/test/java` —— 单测,不影响运行
-- **仓库域主代码完全没有引用 `channel` 包**(已 grep 全量核对),可以只拷上面 6 个
+- 仓库域主代码**完全没有引用 `channel` 包**(已全量 grep 核对),只拷上面 6 个即可
## 1.3 放进项目的两种方式
@@ -88,10 +87,8 @@ common-ecommerce/
### 方式 B:作为独立模块加入现有构建
-如果你们是 Gradle 多模块:
-
```kotlin
-// settings.gradle.kts
+// Gradle
include(":sdk-common", ":warehouse-sdk-core", ":warehouse-sdk-edayun")
// warehouse-sdk-edayun/build.gradle.kts
@@ -99,7 +96,6 @@ dependencies {
api(project(":sdk-common"))
api(project(":warehouse-sdk-core"))
}
-
java {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
@@ -107,18 +103,16 @@ java {
tasks.withType { options.encoding = "UTF-8" }
```
-Maven 多模块同理,在每个模块的 pom 里用 `compile` 依赖相邻模块即可。
+Maven 多模块同理:每个模块的 pom 用 `compile` 依赖相邻模块。
## 1.4 关于测试代码(可选)
-如果想把单元测试一起带过去:
-
-- 拷 `src/test/java` 需要额外引入 **`junit-jupiter 5.8.2`**
-- **`sdk-testkit` 主代码引用了 `channel` 包**(`FakeDirectAdapter` 这个类),
- 只想测仓库域的话,**只拷这几个类**即可:
+- 拷 `src/test/java` 需要额外引入 `junit-jupiter 5.8.2`
+- **`sdk-testkit` 主代码引用了 `channel` 包**(`FakeDirectAdapter`),
+ 只想测仓库域的话,**只拷这几个类**:
`RecordingTransport`、`Responses`、`InMemoryTokenStore`、
`InMemoryLockProvider`、`InMemoryIdempotencyStore`,跳过 `FakeDirectAdapter`
-- 或者干脆不拷测试,只用源码跑业务
+- 或者干脆不拷测试
---
@@ -141,7 +135,6 @@ 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")
- // 日志实现你们项目应该已经有了
}
```
@@ -166,16 +159,12 @@ dependencies {
```
**版本冲突**:如果你们已有更高版本的 jackson / okhttp,直接用你们的版本。
-代码只用了最基础的 API(`ObjectMapper`、`MediaType`、`OkHttpClient`),向上兼容。
+代码只用了最基础的 API,向上兼容。
-**OkHttp 4.x 是 Kotlin 写的**,需要 classpath 上有 `kotlin-stdlib`。不想引 Kotlin 就:
+**OkHttp 4.x 是 Kotlin 写的**,需要 `kotlin-stdlib`。不想引 Kotlin 就:
- 用 OkHttp 3.14.x(纯 Java,API 兼容),或者
-- 自己实现 `HttpTransport`(只有一个方法),换成你们已有的 HTTP 客户端,见下。
-
-### 自己实现 `HttpTransport`(可选)
-
-不想引 OkHttp 时:
+- 自己实现 `HttpTransport`(只有一个方法),换成你们已有的 HTTP 客户端:
```java
import common.ecommerce.http.HttpRequest;
@@ -187,17 +176,16 @@ public class MyHttpTransport implements HttpTransport {
public HttpResponse execute(HttpRequest request) {
// request.method() / url() / headers() / body() / contentType()
// 返回 HttpResponse.of(statusCode, headers, body, latencyMillis)
- // 用你们项目已有的 HttpClient / RestTemplate 实现
return ...;
}
}
```
-然后在组装 SDK 时把它传给适配器(见 3.2 的 `EdayunAdapterFactory` 参数说明)。
+然后在组装 SDK 时把它传给适配器(见 3.2 的工厂参数说明)。
---
-# 三、5 分钟上手
+# 三、配置
## 3.1 实现两个 SPI
@@ -379,7 +367,13 @@ WarehouseConnection conn = WarehouseConnection.of(
| 信仓 | `appKey` `appSecret` | 换 token |
| 恒健 | `appSecret` | 算签名 |
-## 3.4 拿到仓的操作入口
+
+
+---
+
+# 四、快速上手
+
+## 4.1 拿到仓的操作入口
```java
import common.ecommerce.warehouse.sdk.WarehouseOperations;
@@ -389,7 +383,7 @@ WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn);
后面所有 `wh.xxx()` 都从这个对象出发。
-## 3.5 验证能跑通
+## 4.2 验证能跑通
**只读,不改任何数据**:
@@ -409,13 +403,16 @@ for (WarehouseFacility w : warehouses) {
| 现象 | 原因 |
|---|---|
| `该仓没有配置接入账户` | `warehouseCode` 和 `WarehouseRepository` 对不上 |
-| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [四](#四我要做的事能不能做)) |
+| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [五](#五我要做的事能不能做)) |
| `http 401` / token 错误 | `ChannelSecret` 字段填错 |
| 超时 | 端点不通;易达云首次调用慢,重试一次 |
---
-# 四、我要做的事能不能做?
+
+---
+
+# 五、我要做的事能不能做?
| 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 |
|---|---|:---:|:---:|:---:|:---:|
@@ -445,11 +442,11 @@ for (WarehouseFacility w : warehouses) {
---
-# 五、按任务
+# 六、按任务
> 以下假设 `wh` 已就绪(见 [3.4](#34-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。
-## 5.1 发货:建出库单 → 拿面单
+## 6.1 发货:建出库单 → 拿面单
```java
import common.ecommerce.shared.model.Platform;
@@ -507,7 +504,7 @@ for (PackageResult p : pkgs) {
3. 重复建单不会重复下单(幂等键 = `orderRef`,没有则 `outboundRequestNo`)
4. 保存 `providerOrderId`,后续查单 / 取消能少一次请求
-## 5.2 查物流轨迹
+## 6.2 查物流轨迹
```java
List events = wh.track("1Z999AA10123456784");
@@ -521,7 +518,7 @@ info.events();
**⚠️ 坑**:查不到不报错 —— `track()` 返回空列表、`trackShipment()` 返回 `null`。
-## 5.3 取消出库单
+## 6.3 取消出库单
```java
CancelEligibility e = wh.outbound().checkCancel(
@@ -541,7 +538,7 @@ if (e == CancelEligibility.FREE) {
**⚠️ 坑**:`CHARGED` + `acceptCharge(false)` 抛 `OutboundCancelChargeRequiredException`;
`BLOCKED` 抛 `OutboundCancelBlockedException`。
-## 5.4 退货
+## 6.4 退货
```java
import common.ecommerce.warehouse.enums.ReturnDealMethod;
@@ -572,7 +569,7 @@ boolean ok = wh.returns().cancel("RMA2411053149"); // 传仓侧 RMA 号
**⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` /
`returnReason`(传了直接报错)。
-## 5.5 库存同步
+## 6.5 库存同步
```java
Page page = wh.inventory().query(
@@ -596,7 +593,7 @@ InventorySyncStrategy strategy = wh.inventorySyncStrategy();
- **`-1` 是「仓方没给」不是 0**(`pendingOutbound` / `alertQuantity` 常为 null → 映射成 -1)
- 易达云没有时间维度,`updatedAfter` 不生效
-## 5.6 商品主数据
+## 6.6 商品主数据
```java
WarehouseProduct p = WarehouseProduct.builder()
@@ -636,7 +633,7 @@ Page page = wh.queryProducts(
- 易达云不带时间窗只查最近一个月
- 运去哪不支持条码 / 时间窗过滤,传了本地报错
-## 5.7 对账:拉费用明细
+## 6.7 对账:拉费用明细
```java
// ① 账户流水
@@ -667,7 +664,7 @@ List quotes = wh.fees().estimate(FeeEstimateQuery.builder()
**⚠️ 坑**:必须给成本类型或时间窗,否则本地拒绝;易达云时间窗阈值较怪,超限 catch 后缩窗重试。
-## 5.8 打单:箱唛 / BOL
+## 6.8 打单:箱唛 / BOL
```java
import common.ecommerce.warehouse.enums.CaseMarkPaperSize;
@@ -702,13 +699,13 @@ b.statusName(); // 如「已妥投」
---
-# 六、几条贯穿全局的规则
+# 七、几条贯穿全局的规则
-## 6.1 单位:尺寸 cm、重量 g
+## 7.1 单位:尺寸 cm、重量 g
字段名带 `Cm` / `Grams` 后缀。**不要自己换算**——易达云内部要 kg,适配器会转。
-## 6.2 SKU:到底传哪一个(最容易错)
+## 7.2 SKU:到底传哪一个(最容易错)
**所有地方都用「建档时下发给仓方的那一串」。**
@@ -726,7 +723,7 @@ b.statusName(); // 如「已妥投」
**SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。
-## 6.3 分页
+## 7.3 分页
```java
String cursor = null;
@@ -741,15 +738,15 @@ do {
- **不要自己算页码**:各仓起点不同(易达云 1、运去哪 0),游标已屏蔽差异
- 判断有没有下一页用 `hasMore()`,不要拿 `items().size()` 猜
-## 6.4 金额
+## 7.4 金额
一律 `Money.of("19.99", "USD")`,不要传裸 `double`——会丢币种,对账时美元和加元混在一起就完了。
---
-# 七、出错了怎么办
+# 八、出错了怎么办
-## 7.1 五类异常
+## 8.1 五类异常
```java
try {
@@ -776,7 +773,7 @@ try {
| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需确认 |
| `OutboundCancelBlockedException` | 不能取消 | ❌ |
-## 7.2 异常里有什么
+## 8.2 异常里有什么
```java
catch (WarehouseException e) {
@@ -792,18 +789,18 @@ catch (WarehouseException e) {
> `rawResponse()` 有完整报文,可能含买家地址电话。**别直接落日志**。
-## 7.3 常见报错对照
+## 8.3 常见报错对照
| 报错 | 原因 | 怎么办 |
|---|---|---|
| `requires an idempotencyStore` | 没配 | 见 [3.1](#31-实现两个-spi) |
| `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` |
-| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [四](#四我要做的事能不能做) |
+| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [五](#五我要做的事能不能做) |
| `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` |
| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [6.2](#62-sku到底传哪一个最容易错) |
| `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` |
-## 7.4 幂等:重复调用安全吗
+## 8.4 幂等:重复调用安全吗
写操作都安全,同样单号调两次不会重复下单: