You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

193 lines
5.8 KiB

# 通用注意事项
跨仓通用的约定与踩过的坑。运去哪专属的见 [yqn/README.md](yqn/README.md)。
## 1. 写操作
### 所有写操作强制幂等
门面层拦截,调用方无法绕过。未注入 `IdempotencyStore` 时直接抛异常,不提供「无幂等」的降级路径。
**原因**:出库重复下发 = 重复发货;调拨重复下发 = 搬两次货;销毁重复下发 = 报废两次。
### 销毁 / 退货按明细行做键
```java
// 退货条目处理:一张单的多行可以分别上架 / 销毁
warehouseCode + providerReturnNo + lineId + process
```
按整单做键会把「第二行上架」误判成重复。
### 联调时不要随便跑写接口
写接口会真实创建单据。没有 Testing 环境时,只跑查询类探针。运去哪的 PR 环境可以走单,但创建的单据要能识别(探针用 `PROBE-<时间戳>` 前缀)。
## 2. 状态与原始值
### rawStatus 必须落库
```java
// 模型的固定搭配
OutboundStatus status; // 归一化,给代码判断
String rawStatus; // 仓方原话,给展示和排查
WarehouseProvider sourceProvider; // 解释 rawStatus 的前提
```
**rawStatus 必须与 sourceProvider 成对保存**——同一个数字在不同仓含义不同。
它是映射调整后**唯一能重跑、修正历史数据**的依据;只存枚举则改映射等于污染存量。
### 认不出的状态归 UNKNOWN,不猜
反例(已修):
```java
// 之前:contains("SHIP") 把 UNSHIPPED 判成 SHIPPED
// 后果:未发货被判已交运,取消被锁
```
正确做法:按完整值精确匹配,未收录归 `UNKNOWN`,原值留在 `rawStatus`。
### 底层枚举只追加,不合并
合并了就分不出「待审核」和「审核中」。加新仓时只加值,不改已有值的语义。
## 3. 时区
### 仓方给的时间不带时区
`yyyy-MM-dd HH:mm:ss` 需要知道它属于哪个地方。由调用方经 `WarehouseConnection` 传:
```java
WarehouseConnection.of(baseUrl, secret, ZoneId.of("America/New_York"))
```
**未指定时按 UTC 解释,不猜成北京时间。** 美国仓猜错会整体平移 13–16 小时。
### SDK 不读系统时钟
- 普通调用:`WarehouseContext.clock()`
- 回调时间戳校验:`nowMillis` 由宿主传入
## 4. 单位
**单位写进字段名**,不靠注释约定:
```java
double weightGrams; // 不是 weight
double lengthCm; // 不是 length
Double totalVolumeCbm;
Double totalWeightKg;
```
### 换算在适配器里做
仓方给的单位不同(oz / inch / lb / in³),**适配器统一换算后落模型**,宿主不用各仓处理。
例:运去哪轨迹的 `parcel.weight`(oz)→ `TrackingInfo.parcelWeightGrams()`(g)。
### 单位未核实时要标注
```java
/**
* <b>单位待核实</b>:文档未标单位,这里按 kg 原样透传;
* 若确认是 lb,数值会偏大约 2.2 倍。
*/
```
## 5. 字段口径
### 同一个名字在不同接口含义可能不同
| 字段 | 含义 |
|---|---|
| `OutboundOrder.providerOrderId` | **仓侧单号** |
| `OutboundQuery.outboundRequestNo` | **我们下发的来源单号**(原名 `providerOrderId` 有误导,已改) |
| `FeeQuery.saleOrderNo` | 运去哪要**数字单号**(`providerOrderId`),不是来源单号 |
| `ReturnProcessCommand.lineId` | 来自**退货查询接口**,不是回调 |
### 传出去了不等于查得回来
下单发的字段,查详情时不一定返回。例:
- 运去哪订单详情不回传 `orderRef`(平台单号)和 `requestedAt`
- 宿主需要这些值时自行保存映射
## 6. 能力与降级
### 能力缺失显式抛异常
```java
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.TRACKING);
```
不静默返回空集合 / 空列表——调用方分不清「不支持」和「没数据」。
### 不静默降级
例:平台面单要求仓声明 `PLATFORM_LABEL_DELIVERY`,缺失时拒绝,**不自动退回仓自有面单**——面单归属影响标发方式。
### 能力位要与实现一致
反例(已修):声明了 `SPLIT` 但接口没有拆单字段。调用方看能力位会以为能用。
## 7. 校验的位置
### 跨仓共有的约束放模型构造期
```java
if (b.inventoryType != 0 && b.inventoryType != 1) {
throw new IllegalArgumentException("inventoryType must be 0 or 1");
}
```
### 仓方协议特有的约束放适配器
```java
// 尺寸与每页数量联动(运去哪箱标)
if (perPage == 1 && !size.singlePerPage()) { throw ... }
```
**原因**:`TransferCommand` 这类模型承载多家仓字段的并集,在模型里加强制校验会让另一家仓用不了。
## 8. 回调
见 [callback.md](callback.md)。三个要点:
1. **`@RequestBody String`** —— 必须拿原文,反序列化会破坏签名
2. **验签失败返回 4xx** —— 不要吞
3. **`Boolean inbound()` 是三态** —— 不能 `if (!inbound)`
## 9. 测试
### 契约测试用 `RecordingTransport`
```java
RecordingTransport.create().route(PATH, req -> Responses.ok("..."))
```
验证「按文档构造的报文能正确映射」,不打真实接口。
### 真机探针默认跳过
```java
@EnabledIfSystemProperty(named = "yqn.probe", matches = "true")
```
**真机验证不能省**——运去哪有 4 处文档与实际不符(参数名、成功码、字段缺失),只有真跑才能发现。
## 10. PII
`ShipTo` / `WarehouseInfo` 含联系人、电话、邮箱:
- 不打印完整报文(探针只打字段摘要)
- 落库与日志按宿主安全策略处理
- 异常信息里 `safeRelay()` 只保留前 300 字节
## 11. 已发现但未修的问题
| 项 | 说明 |
|---|---|
| `InboundCommand` 请求侧部分字段 | 已补,但运去哪对 `lineCode` 有「项目必须存在」的约束 |
| 出库 `declaredTotal` | 运去哪无落点,不影响(行级 `skuAmount` 已覆盖) |