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
193 lines
5.8 KiB
|
1 week ago
|
# 通用注意事项
|
||
|
|
|
||
|
|
跨仓通用的约定与踩过的坑。运去哪专属的见 [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` 已覆盖) |
|