From 4d2f8a0fc48804441da92076d4a7eaea5bf4518c Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Wed, 18 Nov 2026 11:19:08 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=BA=90=E7=A0=81=E9=9B=86=E6=88=90?= =?UTF-8?q?=E7=89=88=E5=8E=BB=E6=8E=89=E5=89=8D=E4=B8=A4=E7=AB=A0=EF=BC=8C?= =?UTF-8?q?=E7=9B=B4=E6=8E=A5=E4=BB=8E=E3=80=8C=E9=85=8D=E7=BD=AE=E3=80=8D?= =?UTF-8?q?=E5=BC=80=E5=A7=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 源码已经随交付提供,怎么拷、要引哪些库不需要再写在文档里。 删除「一、源码怎么集成」「二、必须引入的第三方库」,章节整体前移: 一、配置(原三) 二、快速上手(原四) 三、我要做的事能不能做(原五) 四、按任务 4.1~4.8(原 6.x) 五、贯穿全局的规则(原七) 六、出错了怎么办(原八) 依赖信息压缩成开头一行:jackson 2.13.5 / slf4j-api 1.7.36 / okhttp 4.12.0。 全部锚点已同步重编号并逐个核对,无失效链接。 Co-Authored-By: Claude --- docs-warehouse/SDK使用说明-源码集成.md | 250 +++++-------------------- 1 file changed, 45 insertions(+), 205 deletions(-) diff --git a/docs-warehouse/SDK使用说明-源码集成.md b/docs-warehouse/SDK使用说明-源码集成.md index 6174e70..17796a6 100644 --- a/docs-warehouse/SDK使用说明-源码集成.md +++ b/docs-warehouse/SDK使用说明-源码集成.md @@ -1,11 +1,11 @@ # 三方仓 SDK 使用说明(源码集成版) -> 我们提供完整源码,直接用源码方式集成,**不走 Maven 坐标**。 -> 本文档说明:源码怎么放、要引哪些第三方库、每个业务动作怎么写。 +> 源码已随交付提供,直接在本项目里使用即可。 > -> 想用 jar 引入的话,看同目录的 `SDK使用说明-Jar引入.md`。 +> JDK 1.8;需要 `jackson-databind 2.13.5`、`slf4j-api 1.7.36`、`okhttp 4.12.0` +> (或自己实现 `HttpTransport` 替换 OkHttp)。 > -> JDK 1.8 +> 想用 jar 引入的话,看同目录的 `SDK使用说明-Jar引入.md`。 --- @@ -13,181 +13,21 @@ | 我要… | 看这节 | |---|---| -| 把源码放进项目 | [一、源码怎么集成](#一源码怎么集成) | -| 知道要引哪些 jar | [二、必须引入的第三方库](#二必须引入的第三方库) | -| 配好 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 / 分页 / 金额 | [七、贯穿全局的规则](#七几条贯穿全局的规则) | -| 报错 / 重试 | [八、出错了怎么办](#八出错了怎么办) | - ---- - -# 一、源码怎么集成 - -## 1.1 源码结构 - -``` -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/ ← 领星,本次不用 -``` - -## 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:作为独立模块加入现有构建 - -```kotlin -// Gradle -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 - - com.fasterxml.jackson.core - jackson-databind - 2.13.5 - - - org.slf4j - slf4j-api - 1.7.36 - - - com.squareup.okhttp3 - okhttp - 4.12.0 - -``` - -**版本冲突**:如果你们已有更高版本的 jackson / okhttp,直接用你们的版本。 -代码只用了最基础的 API,向上兼容。 - -**OkHttp 4.x 是 Kotlin 写的**,需要 `kotlin-stdlib`。不想引 Kotlin 就: - -- 用 OkHttp 3.14.x(纯 Java,API 兼容),或者 -- 自己实现 `HttpTransport`(只有一个方法),换成你们已有的 HTTP 客户端: - -```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) - return ...; - } -} -``` - -然后在组装 SDK 时把它传给适配器(见 3.2 的工厂参数说明)。 +| 配好 SPI / SDK / 连接 | [一、配置](#一配置) | +| 确认能跑通 | [二、快速上手](#二快速上手) | +| 知道某仓支不支持某功能 | [三、我要做的事能不能做](#三我要做的事能不能做) | +| 发货 / 面单 | [4.1](#41-发货建出库单--拿面单) | +| 查轨迹 / 取消订单 | [4.2](#42-查物流轨迹) · [4.3](#43-取消出库单) | +| 退货 / 库存 / 商品 / 对账 | [4.4](#44-退货) · [4.5](#45-库存同步) · [4.6](#46-商品主数据) · [4.7](#47-对账拉费用明细) | +| 打箱唛 / BOL | [4.8](#48-打单箱唛--bol) | +| 单位 / SKU / 分页 / 金额 | [五、贯穿全局的规则](#五几条贯穿全局的规则) | +| 报错 / 重试 | [六、出错了怎么办](#六出错了怎么办) | --- -# 三、配置 +# 一、配置 -## 3.1 实现两个 SPI +## 1.1 实现两个 SPI ### ① 仓编码 → 哪家仓 @@ -308,7 +148,7 @@ public class MyIdempotencyStore implements IdempotencyStore { > 只做查询可以先不实现;一旦建单会抛 > `IllegalStateException: WarehouseSdk requires an idempotencyStore for write operations`。 -## 3.2 组装 SDK +## 1.2 组装 SDK ```java import common.ecommerce.warehouse.sdk.WarehouseSdk; @@ -340,7 +180,7 @@ WarehouseSdk sdk = WarehouseSdk.builder() > **务必做成单例。** 适配器里缓存了 token 与限流器,每次 `new` 会重复登录。 -## 3.3 连接信息(端点 + 凭据) +## 1.3 连接信息(端点 + 凭据) SDK 不保存端点和凭据,每次调用由你们传: @@ -371,9 +211,9 @@ WarehouseConnection conn = WarehouseConnection.of( --- -# 四、快速上手 +# 二、快速上手 -## 4.1 拿到仓的操作入口 +## 2.1 拿到仓的操作入口 ```java import common.ecommerce.warehouse.sdk.WarehouseOperations; @@ -383,7 +223,7 @@ WarehouseOperations wh = sdk.warehouses("EDY-USLA", conn); 后面所有 `wh.xxx()` 都从这个对象出发。 -## 4.2 验证能跑通 +## 2.2 验证能跑通 **只读,不改任何数据**: @@ -403,7 +243,7 @@ for (WarehouseFacility w : warehouses) { | 现象 | 原因 | |---|---| | `该仓没有配置接入账户` | `warehouseCode` 和 `WarehouseRepository` 对不上 | -| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [五](#五我要做的事能不能做)) | +| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [五](#三我要做的事能不能做)) | | `http 401` / token 错误 | `ChannelSecret` 字段填错 | | 超时 | 端点不通;易达云首次调用慢,重试一次 | @@ -412,7 +252,7 @@ for (WarehouseFacility w : warehouses) { --- -# 五、我要做的事能不能做? +# 三、我要做的事能不能做? | 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 | |---|---|:---:|:---:|:---:|:---:| @@ -442,11 +282,11 @@ for (WarehouseFacility w : warehouses) { --- -# 六、按任务 +# 四、按任务 -> 以下假设 `wh` 已就绪(见 [3.4](#34-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。 +> 以下假设 `wh` 已就绪(见 [2.1](#21-拿到仓的操作入口))。代码为片段,省略 import 与 try-catch。 -## 6.1 发货:建出库单 → 拿面单 +## 4.1 发货:建出库单 → 拿面单 ```java import common.ecommerce.shared.model.Platform; @@ -504,7 +344,7 @@ for (PackageResult p : pkgs) { 3. 重复建单不会重复下单(幂等键 = `orderRef`,没有则 `outboundRequestNo`) 4. 保存 `providerOrderId`,后续查单 / 取消能少一次请求 -## 6.2 查物流轨迹 +## 4.2 查物流轨迹 ```java List events = wh.track("1Z999AA10123456784"); @@ -518,7 +358,7 @@ info.events(); **⚠️ 坑**:查不到不报错 —— `track()` 返回空列表、`trackShipment()` 返回 `null`。 -## 6.3 取消出库单 +## 4.3 取消出库单 ```java CancelEligibility e = wh.outbound().checkCancel( @@ -538,7 +378,7 @@ if (e == CancelEligibility.FREE) { **⚠️ 坑**:`CHARGED` + `acceptCharge(false)` 抛 `OutboundCancelChargeRequiredException`; `BLOCKED` 抛 `OutboundCancelBlockedException`。 -## 6.4 退货 +## 4.4 退货 ```java import common.ecommerce.warehouse.enums.ReturnDealMethod; @@ -569,7 +409,7 @@ boolean ok = wh.returns().cancel("RMA2411053149"); // 传仓侧 RMA 号 **⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` / `returnReason`(传了直接报错)。 -## 6.5 库存同步 +## 4.5 库存同步 ```java Page page = wh.inventory().query( @@ -593,7 +433,7 @@ InventorySyncStrategy strategy = wh.inventorySyncStrategy(); - **`-1` 是「仓方没给」不是 0**(`pendingOutbound` / `alertQuantity` 常为 null → 映射成 -1) - 易达云没有时间维度,`updatedAfter` 不生效 -## 6.6 商品主数据 +## 4.6 商品主数据 ```java WarehouseProduct p = WarehouseProduct.builder() @@ -633,7 +473,7 @@ Page page = wh.queryProducts( - 易达云不带时间窗只查最近一个月 - 运去哪不支持条码 / 时间窗过滤,传了本地报错 -## 6.7 对账:拉费用明细 +## 4.7 对账:拉费用明细 ```java // ① 账户流水 @@ -664,7 +504,7 @@ List quotes = wh.fees().estimate(FeeEstimateQuery.builder() **⚠️ 坑**:必须给成本类型或时间窗,否则本地拒绝;易达云时间窗阈值较怪,超限 catch 后缩窗重试。 -## 6.8 打单:箱唛 / BOL +## 4.8 打单:箱唛 / BOL ```java import common.ecommerce.warehouse.enums.CaseMarkPaperSize; @@ -699,13 +539,13 @@ b.statusName(); // 如「已妥投」 --- -# 七、几条贯穿全局的规则 +# 五、几条贯穿全局的规则 -## 7.1 单位:尺寸 cm、重量 g +## 5.1 单位:尺寸 cm、重量 g 字段名带 `Cm` / `Grams` 后缀。**不要自己换算**——易达云内部要 kg,适配器会转。 -## 7.2 SKU:到底传哪一个(最容易错) +## 5.2 SKU:到底传哪一个(最容易错) **所有地方都用「建档时下发给仓方的那一串」。** @@ -723,7 +563,7 @@ b.statusName(); // 如「已妥投」 **SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。 -## 7.3 分页 +## 5.3 分页 ```java String cursor = null; @@ -738,15 +578,15 @@ do { - **不要自己算页码**:各仓起点不同(易达云 1、运去哪 0),游标已屏蔽差异 - 判断有没有下一页用 `hasMore()`,不要拿 `items().size()` 猜 -## 7.4 金额 +## 5.4 金额 一律 `Money.of("19.99", "USD")`,不要传裸 `double`——会丢币种,对账时美元和加元混在一起就完了。 --- -# 八、出错了怎么办 +# 六、出错了怎么办 -## 8.1 五类异常 +## 6.1 五类异常 ```java try { @@ -773,7 +613,7 @@ try { | `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需确认 | | `OutboundCancelBlockedException` | 不能取消 | ❌ | -## 8.2 异常里有什么 +## 6.2 异常里有什么 ```java catch (WarehouseException e) { @@ -789,18 +629,18 @@ catch (WarehouseException e) { > `rawResponse()` 有完整报文,可能含买家地址电话。**别直接落日志**。 -## 8.3 常见报错对照 +## 6.3 常见报错对照 | 报错 | 原因 | 怎么办 | |---|---|---| -| `requires an idempotencyStore` | 没配 | 见 [3.1](#31-实现两个-spi) | +| `requires an idempotencyStore` | 没配 | 见 [1.1](#11-实现两个-spi) | | `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` | -| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [五](#五我要做的事能不能做) | +| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [五](#三我要做的事能不能做) | | `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` | -| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [6.2](#62-sku到底传哪一个最容易错) | +| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [5.2](#52-sku到底传哪一个最容易错) | | `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` | -## 8.4 幂等:重复调用安全吗 +## 6.4 幂等:重复调用安全吗 写操作都安全,同样单号调两次不会重复下单: