|
|
|
@ -136,6 +136,227 @@ return CallSupport.observe(observer, ctx, "warehouse.outbound.create", |
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 阶段 2.5:出入参怎么处理(详述) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 三层各管什么 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
仓方 JSON ──(DTO)──► 平台对象 ──(Mapper)──► 标准模型 |
|
|
|
|
|
|
|
原样照抄字段名 单位换算/码值映射 跨仓统一 |
|
|
|
|
|
|
|
只管反序列化 才允许写业务逻辑 宿主只依赖这层 |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 层 | 位置 | 允许做的事 | 禁止的事 | |
|
|
|
|
|
|
|
|---|---|---|---| |
|
|
|
|
|
|
|
| **DTO** | `<name>/dto/` | 字段声明、`@JsonProperty` 改映射 | 任何逻辑、任何默认值 | |
|
|
|
|
|
|
|
| **Mapper** | `<name>/adapter/` | 单位换算、码值映射、字段拼装 | 发请求、读配置 | |
|
|
|
|
|
|
|
| **标准模型** | `warehouse-sdk-core/model/` | 校验跨仓共有约束 | 认识任何仓的字段名 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**判断标准**:标准模型里出现 `yqn` / `unshipped` / `hopeDestroyData` 这类字符串,就是泄漏了。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 入参(标准 → 平台) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**顺序**:先看标准模型有什么 → 再看平台要什么 → 缺的补哪边。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
public static YqnCreateOrderDtos.CreateOrderRequest toRequest(OutboundCommand cmd, String warehouseCode, ZoneId zone) { |
|
|
|
|
|
|
|
YqnCreateOrderDtos.CreateOrderRequest req = new YqnCreateOrderDtos.CreateOrderRequest(); |
|
|
|
|
|
|
|
req.orderNo = cmd.outboundRequestNo(); // ① 直接搬 |
|
|
|
|
|
|
|
req.latestShipDate = formatTime(cmd.latestShipDate(), zone); // ② 需要换算 |
|
|
|
|
|
|
|
req.isPrime = isPrimeOf(cmd.sfp()); // ③ 需要映射 |
|
|
|
|
|
|
|
req.attachInfoItems = toAttachInfoItems(cmd, warehouseCode); // ④ 需要拼装 |
|
|
|
|
|
|
|
return req; |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**四种情况分别处理**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 情况 | 做法 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| 字段一一对应 | 直接赋值 | |
|
|
|
|
|
|
|
| 需要换算(单位 / 时间格式) | 在 Mapper 里换,写明换算系数 | |
|
|
|
|
|
|
|
| 需要码值映射 | 用平台枚举的 `codeOf()`,不用裸数字 | |
|
|
|
|
|
|
|
| 平台没有该字段 | **不静默丢弃**:要么在模型上标「平台不支持」,要么抛异常 | |
|
|
|
|
|
|
|
| 平台有多余必填字段 | 标准模型必须有对应入口,别让调用方拼字符串 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**坑**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- 平台字段名有拼写错误(运去哪 `hopeDestroyData`)→ **照抄**,加注释说明不是笔误 |
|
|
|
|
|
|
|
- 平台要求字符串但标准是数字(运去哪 `qty`)→ 在 Mapper 转,别改模型类型 |
|
|
|
|
|
|
|
- 平台有默认值(`currency` 不填默认 USD)→ 别在模型里预填,交给平台 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 出参(平台 → 标准) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
public static OutboundOrder toOrder(YqnOrderDetailDtos.OrderDetail detail, ..., ZoneId zone) { |
|
|
|
|
|
|
|
return OutboundOrder.builder() |
|
|
|
|
|
|
|
.outboundRequestNo(detail.orderNo) |
|
|
|
|
|
|
|
.status(YqnOutboundStatus.of(detail.orderStatusEnum).toCore()) // 枚举映射 |
|
|
|
|
|
|
|
.rawStatus(detail.orderStatusEnum) // 原值保留 |
|
|
|
|
|
|
|
.paidAt(parseTime(detail.paidAt, zone)) // 时间解析 |
|
|
|
|
|
|
|
.totalWeightKg(ouncesToGrams(detail.weight)) // 单位换算 |
|
|
|
|
|
|
|
.attachments(toAttachments(detail.enclosure)) // 子结构映射 |
|
|
|
|
|
|
|
.sourceProvider(WarehouseProvider.YQN) // 标记来源 |
|
|
|
|
|
|
|
.build(); |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**必须做的四件事**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. **`rawStatus` / `rawType` 一定填**——它是映射出错时唯一能回滚的依据 |
|
|
|
|
|
|
|
2. **`sourceProvider` 一定填**——否则 `rawStatus` 无法解释 |
|
|
|
|
|
|
|
3. **认不出归 UNKNOWN**,原值仍在 `raw` |
|
|
|
|
|
|
|
4. **平台没给的字段不要伪造**(别用 `Instant.now()` 兜底时间、别用 0 兜底数量) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**平台有、模型没有的字段**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 处理 | 场景 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| 加字段到模型 | 常用(附件、SN、行金额) | |
|
|
|
|
|
|
|
| 加来源标注 | 字段名含义不同(`skuAmount` 是总额不是单价) | |
|
|
|
|
|
|
|
| 丢弃并标注 | 极少用(`thirdPartyAccount`) | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**模型有、平台没有的字段**:**Javadoc 写明「XX 仓不返回,恒为 null」**,不要让后来人以为是漏接。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 子结构别图省事复制 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
平台返回嵌套结构(`enclosure[]` / `snList[]` / `batchInfo`),标准模型要不要跟着嵌套,看用途: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
// 附件:多个接口都用 → 建成通用模型 |
|
|
|
|
|
|
|
public final class WarehouseAttachment { name / type / url / packageNo; } |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// 单次用的 → 用内部类 |
|
|
|
|
|
|
|
OutboundOrder.Line |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
运去哪退货一开始自己建了个 `WarehouseReturn.Attachment`,后来合并成 `WarehouseAttachment`——**同一个概念别建两遍**。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 阶段 2.6:枚举怎么处理(详述) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 为什么必须两层 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
仓方码 平台枚举 底层枚举 |
|
|
|
|
|
|
|
"unshipped" ──► YqnOutboundStatus.UNSHIPPED ──► OutboundStatus.SUBMITTED |
|
|
|
|
|
|
|
0/1/2 XincangOrderStatus? (同一套,全仓共用) |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**只建一层的问题**: |
|
|
|
|
|
|
|
- 放在 core:core 认识运去哪的 `"unshipped"`,接第二家仓就要改 core |
|
|
|
|
|
|
|
- 放在适配器:core 的 `OutboundOrder.status` 类型没法写,宿主无法统一 `switch` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 底层枚举(core) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
public enum OutboundStatus { |
|
|
|
|
|
|
|
SUBMITTED(20, "已下发", 1), |
|
|
|
|
|
|
|
SHIPPED(70, "已交运", 6), |
|
|
|
|
|
|
|
UNKNOWN(0, "未知", -1); |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
private final int code; // SDK 自编,永不复用、永不重排 |
|
|
|
|
|
|
|
private final String label; // 中文名,可以改 |
|
|
|
|
|
|
|
private final int rank; // 推进序号,用于丢弃乱序回调 |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**规则**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 规则 | 理由 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| `code` 从 10 起、步长 10 | 中间可插入新值 | |
|
|
|
|
|
|
|
| `UNKNOWN` 固定 codes=0 | 不与业务值冲突 | |
|
|
|
|
|
|
|
| **只追加不合并** | 合并了就分不出细分状态 | |
|
|
|
|
|
|
|
| 不含任何仓方码 | 加了就是 core 认识平台 | |
|
|
|
|
|
|
|
| 提供 `ofCode(int)` | 落库后反查 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 平台枚举(适配器) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
public enum YqnOutboundStatus { |
|
|
|
|
|
|
|
UNSHIPPED("unshipped", OutboundStatus.SUBMITTED), |
|
|
|
|
|
|
|
SHIPPED("shipped", OutboundStatus.SHIPPED), |
|
|
|
|
|
|
|
UNKNOWN(null, OutboundStatus.UNKNOWN); |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
private final String rawValue; // 仓方原值 |
|
|
|
|
|
|
|
private final OutboundStatus core; |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
public static YqnOutboundStatus of(String raw) { ... } // 精确匹配 |
|
|
|
|
|
|
|
public static OutboundStatus toCore(String raw) { ... } |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**规则**: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 规则 | 理由 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| **精确匹配**,不用 `contains` | `UNSHIPPED` 会被 `contains("SHIP")` 误判 | |
|
|
|
|
|
|
|
| 未知归 `UNKNOWN`,不猜 | 猜错比抛错更难查(未发货被判已交运) | |
|
|
|
|
|
|
|
| 容器类型按仓方原样 | 数字码用 `Integer`,文本用 `String`,别强转 | |
|
|
|
|
|
|
|
| 提供反向 `codeOf()` | 下发时要转回去 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 三套码表不能混 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
运去哪退货有三套: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| API 81 预约 | API 77 检验后 | API 142 回调 | |
|
|
|
|
|
|
|
|---|---|---| |
|
|
|
|
|
|
|
| 0 自提 / 1 拍照 / 2 销毁 / 5 仓库确认 | 0 自提 / 2 销毁 / 3 良品上架 / 4 换标 | 2 销毁 / 3 不良品 / 4 换标 / 5 良品 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
同样的 `2` 和 `5` 在不同表里含义不同。**一码一表,绝不共用**。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 状态码依赖上下文时 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
运去哪 API 154 回调的 `orderNoStatus` 含义随 `orderNoType` 变化: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
orderNoType=1(入库) status=5 → 审核通过 |
|
|
|
|
|
|
|
orderNoType=3(调拨) status=5 → 待审核 |
|
|
|
|
|
|
|
orderNoType=5(退货认领) status=5 → 待处理 |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
**做法**:不改枚举,把 `(type, status)` 一起带出去: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
.rawEventType("ORDER_STATUS:" + body.orderNoType) |
|
|
|
|
|
|
|
.rawStatus(String.valueOf(body.orderNoStatus)) |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Javadoc 必须写明「不能脱离类型单独解释」。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 什么时候不建枚举 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 情况 | 做法 | |
|
|
|
|
|
|
|
|---|---| |
|
|
|
|
|
|
|
| 码表 > 50 个且宿主不判断 | 透传字符串(如运去哪 29 个物流服务码 → 建常量枚举但不映射到 core) | |
|
|
|
|
|
|
|
| 平台按中文名归类 | 在 Mapper 里用 `switch(name)`,认不出留 null,不猜 | |
|
|
|
|
|
|
|
| 只是展示用 | 原值放 `raw*` 字段 | |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 枚举测试必须覆盖什么 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
```java |
|
|
|
|
|
|
|
@Test |
|
|
|
|
|
|
|
void allDocumentedValuesMap() { |
|
|
|
|
|
|
|
// 文档里每一个值都断言一遍——错一位会静默错处理 |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@Test |
|
|
|
|
|
|
|
void unknownIsNotGuessed() { |
|
|
|
|
|
|
|
assertEquals(UNKNOWN, ... .toCore("某个新值")); |
|
|
|
|
|
|
|
assertEquals("某个新值", order.rawStatus()); // 原值必须还在 |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@Test |
|
|
|
|
|
|
|
void precisionMatters() { |
|
|
|
|
|
|
|
// 专门测容易子串误判的:UNSHIPPED vs SHIPPED |
|
|
|
|
|
|
|
assertEquals(SUBMITTED, YqnOutboundStatus.toCore("unshipped")); |
|
|
|
|
|
|
|
} |
|
|
|
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
--- |
|
|
|
|
|
|
|
|
|
|
|
## 阶段 3:真机验证(不可跳过) |
|
|
|
## 阶段 3:真机验证(不可跳过) |
|
|
|
|
|
|
|
|
|
|
|
### 3.1 先写只读探针 |
|
|
|
### 3.1 先写只读探针 |
|
|
|
|