# 通用注意事项 跨仓通用的约定与踩过的坑。运去哪专属的见 [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 /** * 单位待核实:文档未标单位,这里按 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` 已覆盖) |