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.

7.9 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

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