chenchuchuan
|
76a1a810b5
|
docs: 拆成两份使用说明——jar 引入版 / 源码集成版
之前的「源码集成版」只覆盖了一种交付形态。按实际需要拆成两份,
共享的配置与业务章节保持一致,只替换集成方式:
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 <noreply@anthropic.com>
|
2 days ago |
chenchuchuan
|
52a064707b
|
docs: 操作手册改为「源码集成版」
对方面对我们全量源码,不走 Maven 坐标,所以重写:
一、源码怎么集成(新增)
- 源码结构图与「必拷/不用拷」清单
- 关键事实:仓库域主代码完全不引用 channel 包(已 grep 核对),
所以只需拷 6 个目录
- 两种放法:合并进 src/main/java(包名不变,不用改 import)/ Gradle 多模块
- 测试代码可选:sdk-testkit 的 FakeDirectAdapter 引用了 channel 包,
只想测仓库域时只拷 5 个类即可
二、必须引入的第三方库(新增)
- 全量 grep import 核对后:只有 jackson / slf4j-api / okhttp 三个
- 明确「不需要 Lombok」(仓库域零使用,只有 lingxing 用了)
- 给了 Gradle 与 Maven 两种写法
- OkHttp 4.x 是 Kotlin 写的,需要 kotlin-stdlib;给两个规避方案
- 附 HttpTransport 自定义实现说明(不想引 OkHttp 时)
三~七 保持上一版的任务组织:
5 分钟上手 / 能不能做 / 8 个任务 / 全局规则 / 异常处理
只把「引入依赖」的 Maven 坐标换成了源码说明。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 days ago |
chenchuchuan
|
a7fedbe5b1
|
docs: 操作手册改为「业务开发版」,按任务组织
原来那版是按 SDK 结构写的(创建/入参出参/能力),业务开发要先读三章
才能寄一个快递。重写为面向使用方:
一、5 分钟上手
- 引入依赖 → 实现两个 SPI(含可参考的实现)→ 组装 SDK → 拿到仓视图
- 1.4 用「查仓库清单」做连通性自检,附失败对照表
二、我要做的事能不能做
- 一张 21 行的「业务动作 × 四个仓」矩阵,先看能不能做
三、按任务(8 节,每节统一结构:代码 → 拿到什么 → ⚠️ 坑)
- 发货 / 轨迹 / 取消 / 退货 / 库存 / 商品 / 对账 / 打单
四、贯穿全局的规则
- 单位、SKU 口径、分页、金额——写一次,各任务复用
五、出错了怎么办
- 五类异常 + 重试判定 + 常见报错对照 + 幂等键表
附录:日志格式、枚举速查、更深文档去哪看
相对上一版的取舍:
- 砍掉架构分层、WarehouseContext 组装、扩展新仓等维护者视角内容
- 快速开始给完整可运行代码,任务章节给片段 + 前置说明
- IdempotencyStore 的示例改成与真实 SPI 一致(四种 Claim 结果),
并把示意方法名标注清楚,避免被当成可直接编译的代码
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 days ago |
chenchuchuan
|
b6e3f05091
|
docs: 新增三方仓 SDK 操作手册
按「1. SDK 怎么创建、2. 入参怎么传出参怎么取、3. 各能力怎么调用」三段组织:
一、创建
- 依赖坐标、JDK 1.8
- 宿主必须实现的 SPI:WarehouseRepository / WarehouseAccount /
IdempotencyStore / CallObserver / TokenStore
- 构建门面(含 4 个仓工厂的构造参数、build 失败条件、单例要求)
- 连接信息与各仓凭据字段
- 取仓视图、查能力位
二、入参/出参
- 通用约定:cm/g/Instant/Money,以及 SKU 口径(建档下发的那串)
- Page<T> 翻页模板(游标已屏蔽各仓页码起点差异)
- OutboundCommand / OutboundLine / ShipTo 逐字段说明 + 必填/选填
- InventoryQuery / InboundCommand / ReturnCommand / ReturnQuery /
FeeQuery / FeeEstimateQuery / WarehouseProduct / ProductQuery
- 出参速查表(18 个模型的关键 getter)
三、能力调用
- 视图结构 + 23 行能力矩阵(四个仓逐项打勾)
- 商品 / 出库 / 库存 / 入库 / 退货 / 费用 / 基础资料 / 单据打印 /
调拨销毁异动 的调用示例
四、异常层级(ChannelException -> WarehouseException)、取值、重试判定、幂等键表
五、常见坑速查(SKU 口径、易达云反向布尔、地址州名、面单 URL、-1 语义等)
写的过程中核对并修正了几处:
- OutboundQuery.status 收的是仓侧原始字符串,不是统一枚举
- 能力矩阵按各适配器 EnumSet.of 实际声明提取,不是按接口实现推断
- 补上此前漏掉的 recommend / classifyAddress
- 箱唛两接口语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标)
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 days ago |