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.

16 KiB

接入新三方仓:操作清单

按这个顺序做,每一步都有验收标准。以运去哪(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 注册

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。

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:

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 方法

@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 里:

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

阶段 2.5:出入参怎么处理(详述)

三层各管什么

仓方 JSON  ──(DTO)──►  平台对象  ──(Mapper)──►  标准模型
            原样照抄字段名      单位换算/码值映射    跨仓统一
            只管反序列化        才允许写业务逻辑      宿主只依赖这层
层 位置 允许做的事 禁止的事
DTO <name>/dto/ 字段声明、@JsonProperty 改映射 任何逻辑、任何默认值
Mapper <name>/adapter/ 单位换算、码值映射、字段拼装 发请求、读配置
标准模型 warehouse-sdk-core/model/ 校验跨仓共有约束 认识任何仓的字段名

判断标准:标准模型里出现 yqn / unshipped / hopeDestroyData 这类字符串,就是泄漏了。

入参(标准 → 平台)

顺序:先看标准模型有什么 → 再看平台要什么 → 缺的补哪边。

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)→ 别在模型里预填,交给平台

出参(平台 → 标准)

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),标准模型要不要跟着嵌套,看用途:

// 附件:多个接口都用 → 建成通用模型
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)

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) 落库后反查

平台枚举(适配器)

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) 一起带出去:

.rawEventType("ORDER_STATUS:" + body.orderNoType)
.rawStatus(String.valueOf(body.orderNoStatus))

Javadoc 必须写明「不能脱离类型单独解释」。

什么时候不建枚举

情况 做法
码表 > 50 个且宿主不判断 透传字符串(如运去哪 29 个物流服务码 → 建常量枚举但不映射到 core)
平台按中文名归类 在 Mapper 里用 switch(name),认不出留 null,不猜
只是展示用 原值放 raw* 字段

枚举测试必须覆盖什么

@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.1 先写只读探针

@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

@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 就丢过)