From 76a1a810b5071ff4dd0d645d8db43047d03bbfda Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Wed, 18 Nov 2026 11:08:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8B=86=E6=88=90=E4=B8=A4=E4=BB=BD?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E=E2=80=94=E2=80=94jar=20?= =?UTF-8?q?=E5=BC=95=E5=85=A5=E7=89=88=20/=20=E6=BA=90=E7=A0=81=E9=9B=86?= =?UTF-8?q?=E6=88=90=E7=89=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 之前的「源码集成版」只覆盖了一种交付形态。按实际需要拆成两份, 共享的配置与业务章节保持一致,只替换集成方式: SDK使用说明-Jar引入.md - 一、集成方式:引哪些 jar(核心 warehouse-sdk-core + 按需适配器)、 Maven / Gradle 写法、建议开启 sources 下载、jar 自带的传递依赖 - 二、配置 / 三、快速上手 / 四~七 与源码版一致 SDK使用说明-源码集成.md - 一、源码怎么集成:必拷 6 个目录(已核对仓库域不引用 channel 包)、 两种投放方式(合并 src/main/java 或独立模块)、测试代码可选项 - 二、必须引入的第三方库:只有 jackson / slf4j / okhttp,不需要 Lombok - 三、配置 / 四、快速上手 / 五~八 与 jar 版一致 两版的业务章节(任务、全局规则、异常)内容完全相同,只是编号后移: jar 版 四~七,源码版 五~八。锚点同步改过。 删除原来的 SDK操作手册.md(已被这两份取代)。 Co-Authored-By: Claude --- docs-warehouse/SDK使用说明-Jar引入.md | 783 +++++++++++++++++++++ ...½œ手册.md => SDK使用说明-源码集成.md} | 121 ++-- 2 files changed, 842 insertions(+), 62 deletions(-) create mode 100644 docs-warehouse/SDK使用说明-Jar引入.md rename docs-warehouse/{SDK操作手册.md => SDK使用说明-源码集成.md} (90%) 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 幂等:重复调用安全吗 写操作都安全,同样单号调两次不会重复下单: