Browse Source
按运去哪 / 信仓的实践整理成 6 个阶段,每步带验收标准: 0. 先确认文档、测试环境、能否走写操作 1. 模块骨架(目录结构 + 注册 + 别漏 callObserver) 2. 每个接口的 6 步固定动作(DTO / Mapper / 平台枚举 / Capability / 门面 observe / 测试) 3. 真机验证:只读探针 + 全链路探针,重点核对参数名/成功码/单位 4. 回调:实现 WarehouseWebhookCapable + 确认时间戳单位与响应体 5. 收尾:文档、平台限制标注、待确认清单 附「踩过的坑速查」10 条,都是这段时间实际踩到的。 Co-Authored-By: Claude <noreply@anthropic.com>feature/supplier-lingxing
1 changed files with 227 additions and 0 deletions
@ -0,0 +1,227 @@
@@ -0,0 +1,227 @@
|
||||
# 接入新三方仓:操作清单 |
||||
|
||||
按这个顺序做,每一步都有验收标准。以运去哪(YQN)和信仓(Xincang)的实践为基准。 |
||||
|
||||
--- |
||||
|
||||
## 阶段 0:先确认三件事 |
||||
|
||||
| 要确认 | 为什么 | |
||||
|---|---| |
||||
| **接口文档**(含回调) | 没回调文档就不能接退货 / 状态同步 | |
||||
| **测试环境**(域名 + 凭证 + 测试仓 + 测试 SKU) | 没有真机验证的接口一律视为未验证 | |
||||
| **能不能走写操作** | PR 环境能否真实建单,决定探针怎么设计 | |
||||
|
||||
缺一项就先做只读部分,写接口留空并标注。 |
||||
|
||||
--- |
||||
|
||||
## 阶段 1:模块骨架 |
||||
|
||||
### 1.1 建模块 |
||||
|
||||
``` |
||||
warehouse-sdk-<name>/ |
||||
├── pom.xml 依赖 warehouse-sdk-core + sdk-common |
||||
└── src/main/java/common/ecommerce/<name>/ |
||||
├── <Name>Constants.java 端点、路径、限流、固定请求头名 |
||||
├── <Name>Adapter.java 实现各 capability |
||||
├── <Name>AdapterFactory.java |
||||
├── adapter/ 各接口的 Mapper(一个接口一个 Mapper) |
||||
├── dto/ 一个接口一个文件,不建大而全的 Dtos |
||||
├── enums/ 平台枚举(带仓方原值 + toCore()) |
||||
├── http/ 请求构造 / 限流 / 信封校验 |
||||
└── webhook/ 回调验签与解析 |
||||
``` |
||||
|
||||
**验收**:模块能编译,`mvn -pl warehouse-sdk-<name> -am install` 通过。 |
||||
|
||||
### 1.2 注册 |
||||
|
||||
```java |
||||
WarehouseSdk.builder() |
||||
.warehouseRepository(repo) |
||||
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai"))) // 别漏 |
||||
.register(new <Name>AdapterFactory()) |
||||
.build(); |
||||
``` |
||||
|
||||
--- |
||||
|
||||
## 阶段 2:按接口逐个接(每个接口一套动作) |
||||
|
||||
以「创建出库单」为例,**每个接口都要走完这 6 步**: |
||||
|
||||
### 2.1 定义 DTO |
||||
|
||||
`dto/<Name><Api>Dtos.java`,一个接口一个文件,**不塞进大 DTO**。 |
||||
|
||||
```java |
||||
public final class YqnCreateOrderDtos { |
||||
public static final class CreateOrderRequest { ... } // 请求 |
||||
public static final class CreateOrderResponse { ... } // 响应 data |
||||
} |
||||
``` |
||||
|
||||
- 字段名照抄文档,**连拼写错误也照抄**(运去哪的 `hopeDestroyData` 就是 `Data` 不是 `Date`) |
||||
- 保留 `@JsonInclude(NON_NULL)`——丢了会让请求多出 `"field": null` |
||||
|
||||
### 2.2 建 Mapper |
||||
|
||||
`adapter/<Name><Api>Mapper.java`,只做字段搬运。 |
||||
|
||||
**规则**: |
||||
- 平台字段名只出现在 Mapper 和 DTO 里 |
||||
- 单位换算在这里做(oz→g、inch→cm),宿主不用各仓处理 |
||||
- 时间解析失败返回 null,不因格式问题阻断整单 |
||||
|
||||
### 2.3 定义平台枚举(有状态/码表时) |
||||
|
||||
`enums/<Name>XxxStatus.java`: |
||||
|
||||
```java |
||||
public enum YqnOutboundStatus { |
||||
UNSHIPPED("unshipped", OutboundStatus.SUBMITTED), |
||||
SHIPPED("shipped", OutboundStatus.SHIPPED), |
||||
UNKNOWN(null, OutboundStatus.UNKNOWN); // 认不出就归 UNKNOWN,不猜 |
||||
|
||||
public static OutboundStatus toCore(String raw) { ... } |
||||
} |
||||
``` |
||||
|
||||
**规则**: |
||||
- **精确匹配**,不用 `contains`——运去哪的 `UNSHIPPED` 曾被 `contains("SHIP")` 判成已交运 |
||||
- 原值同时写进模型的 `rawStatus` |
||||
- 底层枚举**只追加不合并** |
||||
|
||||
### 2.4 实现 Capability 方法 |
||||
|
||||
```java |
||||
@Override |
||||
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { |
||||
YqnCreateOrderDtos.CreateOrderRequest body = YqnOutboundMapper.toRequest(cmd, wh, zoneOf(ctx)); |
||||
String raw = execute(ctx, PATH, body, "warehouse.outbound.create"); |
||||
return YqnOutboundMapper.toReceipt(raw, cmd); |
||||
} |
||||
``` |
||||
|
||||
- **能力位要与实现一致**(声明了 `SPLIT` 就必须真的有拆单字段) |
||||
- 未实现的能力**显式抛** `WarehouseUnsupportedCapabilityException`,不返回空集合 |
||||
- 找不到的必填字段在本地拒绝,发出去被仓方拒更难排查 |
||||
|
||||
### 2.5 门面包一层 |
||||
|
||||
`WarehouseOperations` 里: |
||||
|
||||
```java |
||||
return CallSupport.observe(observer, ctx, "warehouse.outbound.create", |
||||
CallSupport.params("outboundRequestNo", cmd.outboundRequestNo()), |
||||
r -> CallSupport.NO_COUNT, |
||||
() -> guard.execute(...)); // 写操作必须走幂等守卫 |
||||
``` |
||||
|
||||
**写完用脚本扫一遍**:确认新方法都包了 `CallSupport.observe`。 |
||||
|
||||
### 2.6 写测试 |
||||
|
||||
`<Name><Api>Test.java`,用 `RecordingTransport` 打桩: |
||||
|
||||
| 必须覆盖 | 例子 | |
||||
|---|---| |
||||
| 请求报文形状 | 断每个关键字段出现在 body 里 | |
||||
| 响应字段映射 | 逐字段断言 | |
||||
| 枚举全量映射 | 文档里每个状态值都测一遍 | |
||||
| 未知值兜底 | 未知状态 → UNKNOWN,`rawStatus` 保留 | |
||||
| 错误路径 | 4xx / 业务码失败 / 空 body | |
||||
|
||||
--- |
||||
|
||||
## 阶段 3:真机验证(不可跳过) |
||||
|
||||
### 3.1 先写只读探针 |
||||
|
||||
```java |
||||
@EnabledIfSystemProperty(named = "<name>.probe", matches = "true") |
||||
class <Name>ReadOnlyProbeTest { ... } |
||||
``` |
||||
|
||||
- 默认跳过,凭据走系统属性(**不入库**) |
||||
- 输出打 token 掩码(`n9yc***qn`),不打完整报文(可能含 PII) |
||||
- 异常只打印不中断,一次跑完看全 |
||||
|
||||
### 3.2 再写全链路探针 |
||||
|
||||
按 `@Order` 串起来,创建 → 查询 → 取消,一条链验多个接口。 |
||||
|
||||
- 单号用 `<PROBE>-<时间戳>` 前缀,便于识别 |
||||
- 写接口只在 PR 环境跑 |
||||
|
||||
### 3.3 真机一定要做的事 |
||||
|
||||
| 检查项 | 为什么 | |
||||
|---|---| |
||||
| 参数名是否带前缀 | 运去哪库存查询文档写 `query.warehouseCodes`,实际是 `warehouseCodes` | |
||||
| 成功码是 `code` 还是 `status` | 运去哪仓库目录/运费试算**没有 `code`**,只有 `status: 200` | |
||||
| 成功码的具体值 | 文档示例常是自动生成的占位符(`"message": "example"`),不可信 | |
||||
| 单位 | 运去哪调拨 `totalWeight` 文档没写单位,真机验证是 kg | |
||||
| 必填字段的实际约束 | 运去哪入库的 `lineCode` 要项目名真实存在 | |
||||
|
||||
> **运去哪 4 处文档与实际不符,全是靠真机才发现的。** |
||||
> 只按文档写代码,那些接口一个都跑不通。 |
||||
|
||||
--- |
||||
|
||||
## 阶段 4:回调(如果有) |
||||
|
||||
### 4.1 实现 `WarehouseWebhookCapable` |
||||
|
||||
```java |
||||
@Override |
||||
public void verify(ChannelSecret secret, Map<String,String> headers, String rawBody, long nowMillis) { |
||||
// 用 WebhookSignatures:HMAC + 恒定时间比较 + 时间窗 |
||||
} |
||||
|
||||
@Override |
||||
public List<WarehouseCallback> parse(WarehouseContext ctx, ChannelSecret secret, |
||||
Map<String,String> headers, String rawBody) { |
||||
// 多个回调共用一个地址时,按报文特征分派 |
||||
} |
||||
``` |
||||
|
||||
### 4.2 声明 `WEBHOOK` 能力位 |
||||
|
||||
### 4.3 确认三件事 |
||||
|
||||
| 项 | 为什么 | |
||||
|---|---| |
||||
| 时间戳单位(秒 / 毫秒) | 文档常不写;按位数兼容,联调后收紧 | |
||||
| 回调响应体要什么 | 运去哪文档写 200 但示例是 1,回错会无限重推 | |
||||
| 是否按路径区分 | 运去哪四个回调共用一个地址,只能按报文结构分派 | |
||||
|
||||
--- |
||||
|
||||
## 阶段 5:收尾 |
||||
|
||||
| 项 | 动作 | |
||||
|---|---| |
||||
| 文档 | `docs-warehouse/<name>/README.md`:接口清单、流程、真机结论、平台限制、字段口径、单位、探针用法 | |
||||
| 平台限制 | 每个恒 null 的字段在 **Javadoc 里标注**「XX 仓不返回」 | |
||||
| 单位未核实 | Javadoc 标「待核实,若为 lb 会偏大 2.2 倍」 | |
||||
| 待确认项 | 列成清单交给业务方 | |
||||
|
||||
--- |
||||
|
||||
## 附:踩过的坑速查 |
||||
|
||||
| 坑 | 教训 | |
||||
|---|---| |
||||
| 子串匹配状态 | `UNSHIPPED` 命中 `contains("SHIP")` → 未发货被判已交运 | |
||||
| 状态 null 默认值 | `settlementType` 为 null 被当成「实际结算」 | |
||||
| 方向未知默认出库 | `opLabel` 缺失时库存被反向扣减 | |
||||
| 必填字段静默兜底 | 认不出就猜一个值,比报错更难查 | |
||||
| 能力位与实现不符 | 声明 `SPLIT` 但接口无拆单字段 | |
||||
| 枚举合并 | 把「不良品上架」和「良品上架」合并成一个 | |
||||
| 时区硬编码 | 美国仓时间整体平移 13–16 小时 | |
||||
| 只测文档 | 4 处文档与实际不符,全靠真机发现 | |
||||
| 日志漏写方法 | 出库有日志、调拨没日志,排查时误判 | |
||||
| 合并冲突取一侧 | 另一家仓的字段被静默删掉(本次 `logisticsProducts` 就丢过) | |
||||
Loading…
Reference in new issue