@ -1,11 +1,11 @@
@@ -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 @@
@@ -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< JavaCompile > { 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
< dependency >
< groupId > com.fasterxml.jackson.core< / groupId >
< artifactId > jackson-databind< / artifactId >
< version > 2.13.5< / version >
< / dependency >
< dependency >
< groupId > org.slf4j< / groupId >
< artifactId > slf4j-api< / artifactId >
< version > 1.7.36< / version >
< / dependency >
< dependency >
< groupId > com.squareup.okhttp3< / groupId >
< artifactId > okhttp< / artifactId >
< version > 4.12.0< / version >
< / dependency >
```
**版本冲突**:如果你们已有更高版本的 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 {
@@ -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()
@@ -340,7 +180,7 @@ WarehouseSdk sdk = WarehouseSdk.builder()
> **务必做成单例。** 适配器里缓存了 token 与限流器,每次 `new` 会重复登录。
## 3 .3 连接信息(端点 + 凭据)
## 1 .3 连接信息(端点 + 凭据)
SDK 不保存端点和凭据,每次调用由你们传:
@ -371,9 +211,9 @@ WarehouseConnection conn = WarehouseConnection.of(
@@ -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);
@@ -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) {
@@ -403,7 +243,7 @@ for (WarehouseFacility w : warehouses) {
| 现象 | 原因 |
|---|---|
| `该仓没有配置接入账户` | `warehouseCode` 和 `WarehouseRepository` 对不上 |
| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [五 ](#五 我要做的事能不能做 )) |
| `WarehouseUnsupportedCapabilityException` | 该仓没有仓库清单接口(看 [五 ](#三 我要做的事能不能做 )) |
| `http 401` / token 错误 | `ChannelSecret` 字段填错 |
| 超时 | 端点不通;易达云首次调用慢,重试一次 |
@ -412,7 +252,7 @@ for (WarehouseFacility w : warehouses) {
@@ -412,7 +252,7 @@ for (WarehouseFacility w : warehouses) {
---
# 五 、我要做的事能不能做?
# 三 、我要做的事能不能做?
| 业务动作 | 方法 | 易达云 | 运去哪 | 信仓 | 恒健 |
|---|---|:---:|:---:|:---:|:---:|
@ -442,11 +282,11 @@ 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) {
@@ -504,7 +344,7 @@ for (PackageResult p : pkgs) {
3. 重复建单不会重复下单(幂等键 = `orderRef` ,没有则 `outboundRequestNo` )
4. 保存 `providerOrderId` ,后续查单 / 取消能少一次请求
## 6 .2 查物流轨迹
## 4 .2 查物流轨迹
```java
List< TrackEvent > events = wh.track("1Z999AA10123456784");
@ -518,7 +358,7 @@ info.events();
@@ -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) {
@@ -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 号
@@ -569,7 +409,7 @@ boolean ok = wh.returns().cancel("RMA2411053149"); // 传仓侧 RMA 号
**⚠️ 坑**:易达云只支持「自行退回」,且**拒绝** `lineName` / `estimatedReceiveDate` /
`returnReason` (传了直接报错)。
## 6 .5 库存同步
## 4 .5 库存同步
```java
Page< InventorySnapshot > page = wh.inventory().query(
@ -593,7 +433,7 @@ InventorySyncStrategy strategy = wh.inventorySyncStrategy();
@@ -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<ProductInfo> page = wh.queryProducts(
@@ -633,7 +473,7 @@ Page<ProductInfo> page = wh.queryProducts(
- 易达云不带时间窗只查最近一个月
- 运去哪不支持条码 / 时间窗过滤,传了本地报错
## 6 .7 对账:拉费用明细
## 4 .7 对账:拉费用明细
```java
// ① 账户流水
@ -664,7 +504,7 @@ List<FeeEstimateResult> quotes = wh.fees().estimate(FeeEstimateQuery.builder()
@@ -664,7 +504,7 @@ List<FeeEstimateResult> 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(); // 如「已妥投」
@@ -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(); // 如「已妥投」
@@ -723,7 +563,7 @@ b.statusName(); // 如「已妥投」
**SDK 不做 OMS→仓侧 SKU 转换**(映射表在你们手里)。传错不报错,只会查不到。
## 7 .3 分页
## 5 .3 分页
```java
String cursor = null;
@ -738,15 +578,15 @@ do {
@@ -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 {
@@ -773,7 +613,7 @@ try {
| `OutboundCancelChargeRequiredException` | 取消要收费 | ❌ 需确认 |
| `OutboundCancelBlockedException` | 不能取消 | ❌ |
## 8 .2 异常里有什么
## 6 .2 异常里有什么
```java
catch (WarehouseException e) {
@ -789,18 +629,18 @@ catch (WarehouseException e) {
@@ -789,18 +629,18 @@ catch (WarehouseException e) {
> `rawResponse()` 有完整报文,可能含买家地址电话。**别直接落日志**。
## 8 .3 常见报错对照
## 6 .3 常见报错对照
| 报错 | 原因 | 怎么办 |
|---|---|---|
| `requires an idempotencyStore` | 没配 | 见 [3.1 ](#3 1-实现两个-spi ) |
| `requires an idempotencyStore` | 没配 | 见 [1.1 ](#1 1-实现两个-spi ) |
| `该仓没有配置接入账户` | 仓编码对不上 | 检查 `WarehouseRepository` |
| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [五 ](#五 我要做的事能不能做 ) |
| `WarehouseUnsupportedCapabilityException` | 该仓没这接口 | 看 [五 ](#三 我要做的事能不能做 ) |
| `http 401` / token 错误 | 凭据错 | 检查 `ChannelSecret` |
| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [6.2 ](#6 2-sku到底传哪一个最容易错 ) |
| `SKU 不存在` / 查不到 | 用了 OMS SKU 而不是仓侧的 | 见 [5.2 ](#5 2-sku到底传哪一个最容易错 ) |
| `查询无数据` | 时间窗不对 | 显式给 `createdAfter/Before` |
## 8 .4 幂等:重复调用安全吗
## 6 .4 幂等:重复调用安全吗
写操作都安全,同样单号调两次不会重复下单: