Browse Source

feat(yqn): 补齐另外三个回调:单据变动 / 退货入库完成 / 库存变动

四个回调共用同一套验签(appKey|timestamp|rawBody 的 HMAC-SHA256),
但报文结构不同。运去哪不按路径区分回调,因此在适配器里按报文特征分派:
含 processMode → 退货入库完成(142);含 opType → 库存变动(150);
含 orderNoType → 业务单据变动(154);否则按面单购买成功(149)。

出参改造:
- 新增 WarehouseEventType 底层枚举(LABEL_PURCHASED / ORDER_STATUS_CHANGED /
  RETURN_INBOUND_COMPLETED / INVENTORY_CHANGED / UNKNOWN),调用方按它分派;
  eventType 从 String 改为枚举,仓方原值另存 rawEventType
- 新增 InventoryPayload:库存推送是增量流水,quantity 恒为正、方向由
  inbound 布尔表达,避免调用方按符号猜测;providerOperationType 保留仓方
  单据类型码(100 销售出库等)

两处容易出错的地方已在实现里注明:
- API 154 的 orderNoStatus 含义随 orderNoType 变化(入库计划 / 调拨 /
  销售出库 / 退货认领四套码表),所以 rawEventType 里带上类型,不单独解释状态
- API 142 的 processMode 与 API 81 的预约处理方式码值集合不同,映射到
  ReturnProcessDisposition 时只用 142 的码表(2 销毁 / 3 不良品上架 /
  4 换标上架 / 5 良品上架);3 与 5 都归 RESTOCK,因为底层枚举没有区分良品与否

API 142 的回调里 items 没有明细行 id,所以 lineId 仍为 null——API 77
(退货条目处理)的操作键依然拿不到,这条链路还没闭环。

新增 YqnCallbackParsersTest(9 个)。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
56e3406f7c
  1. 8
      README.md
  2. 50
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseEventType.java
  3. 188
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java
  4. 26
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  5. 56
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInventoryCallbackDtos.java
  6. 41
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnOrderStatusCallbackDtos.java
  7. 66
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnReturnInboundCallbackDtos.java
  8. 87
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnInventoryCallbackParser.java
  9. 6
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParser.java
  10. 127
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java
  11. 174
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java
  12. 4
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParserTest.java

8
README.md

@ -299,7 +299,7 @@ common.ecommerce
│ │ WarehouseProvider / WarehouseCapability / OutboundStatus / │ │ WarehouseProvider / WarehouseCapability / OutboundStatus /
│ │ InboundStatus / TransferStatus / TransferType / LabelMode / │ │ InboundStatus / TransferStatus / TransferType / LabelMode /
│ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType / │ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType /
│ │ ReturnDealMethod / ReturnProcessDisposition / AttachmentType / │ │ ReturnDealMethod / ReturnProcessDisposition / AttachmentType / WarehouseEventType /
│ │ LabelDownloadMode / LabelSizeType / LabelsPerPage / SkuLabelSizeType │ │ LabelDownloadMode / LabelSizeType / LabelsPerPage / SkuLabelSizeType
│ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine / │ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine /
│ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec / │ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec /
@ -328,7 +328,8 @@ common.ecommerce
│ WebhookSignatures(HMAC / 恒定时间比较 / 时间窗) │ WebhookSignatures(HMAC / 恒定时间比较 / 时间窗)
│ │
├── yqn 运去哪三方仓(warehouse-sdk-yqn) ├── yqn 运去哪三方仓(warehouse-sdk-yqn)
│ ├── webhook 回调验签与解析(YqnLabelCallbackParser) │ ├── webhook 回调验签与解析:YqnLabelCallbackParser(API 149)/
│ │ YqnOrderCallbackParser(API 154 + 142)/ YqnInventoryCallbackParser(API 150)
│ ├── dto (按接口拆分,一个接口一个文件) │ ├── dto (按接口拆分,一个接口一个文件)
│ │ YqnCreateOrderDtos / YqnOrderDetailDtos / YqnCancelOrderDtos / │ │ YqnCreateOrderDtos / YqnOrderDetailDtos / YqnCancelOrderDtos /
│ │ YqnProductDtos / YqnFeeDetailDtos / YqnInventoryDtos / │ │ YqnProductDtos / YqnFeeDetailDtos / YqnInventoryDtos /
@ -337,7 +338,8 @@ common.ecommerce
│ │ YqnFeeEstimateDtos / YqnTrackingDtos / YqnDestroyPlanDtos / │ │ YqnFeeEstimateDtos / YqnTrackingDtos / YqnDestroyPlanDtos /
│ │ YqnBoxLabelDtos / YqnSkuLabelDtos / │ │ YqnBoxLabelDtos / YqnSkuLabelDtos /
│ │ YqnLogisticsProductDtos / YqnWarehouseDtos / │ │ YqnLogisticsProductDtos / YqnWarehouseDtos /
│ │ YqnLabelCallbackDtos │ │ YqnLabelCallbackDtos / YqnOrderStatusCallbackDtos /
│ │ YqnReturnInboundCallbackDtos / YqnInventoryCallbackDtos
│ ├── YqnConstants 端点、路径、固定 token 请求头名、限流 │ ├── YqnConstants 端点、路径、固定 token 请求头名、限流
│ ├── adapter YqnAdapter(P1 出库) / YqnAdapterFactory / YqnOutboundMapper │ ├── adapter YqnAdapter(P1 出库) / YqnAdapterFactory / YqnOutboundMapper
│ ├── dto YqnDtos(字段级契约待打样核对) │ ├── dto YqnDtos(字段级契约待打样核对)

50
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseEventType.java

@ -0,0 +1,50 @@
package common.ecommerce.warehouse.enums;
/**
* 仓方回调事件的类型(统一枚举)。
*
* <p>各仓的事件名不同、粒度不同,适配器负责映射到这里;调用方按本枚举分派,
* 不需要认识任何仓的原始事件名。原始值仍保留在
* {@code WarehouseCallback.rawEventType()} 里。</p>
*/
public enum WarehouseEventType {
/** 面单购买成功:拿到运单号 / 承运商 / 发货方式。 */
LABEL_PURCHASED(10, "面单购买成功"),
/** 业务单据状态变更:入库 / 调拨 / 出库 / 退货认领。 */
ORDER_STATUS_CHANGED(20, "单据状态变更"),
/** 退货入库完成:检验后的处理方式与上架数量。 */
RETURN_INBOUND_COMPLETED(30, "退货入库完成"),
/** 库存变动:一条 SKU 的增减流水。 */
INVENTORY_CHANGED(40, "库存变动"),
/** 无法识别的事件;原值见 {@code rawEventType}。 */
UNKNOWN(0, "未知");
private final int code;
private final String label;
WarehouseEventType(int code, String label) {
this.code = code;
this.label = label;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
/** 按落库码反查。 */
public static WarehouseEventType ofCode(int code) {
for (WarehouseEventType v : values()) {
if (v.code == code) {
return v;
}
}
return UNKNOWN;
}
}

188
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java

@ -1,5 +1,6 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.WarehouseEventType;
import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import java.time.Instant; import java.time.Instant;
@ -11,8 +12,9 @@ import java.time.Instant;
* SDK 不监听端口、不做去重存储,只负责「验签 + 解析成统一结构」。</p> * SDK 不监听端口、不做去重存储,只负责「验签 + 解析成统一结构」。</p>
* *
* <p>不同业务的载荷放在各自的可空字段里,按 {@link #eventType()} 区分: * <p>不同业务的载荷放在各自的可空字段里,按 {@link #eventType()} 区分:
* 出库存 {@link #outbound()},退货存 {@link #returns()},入库存 {@link #inbound()}。 * 面单 / 出库存 {@link #outbound()},退货存 {@link #returns()},
* 没用到的字段为 null,不用再建一套平行的类型层级。</p> * 入库存 {@link #inbound()},库存变动存 {@link #inventory()}。
* 用到的字段之外恒为 null。</p>
* *
* <p>{@link #rawBody()} 原样保留:解析出错或以后加字段时,它是唯一能回溯的依据。</p> * <p>{@link #rawBody()} 原样保留:解析出错或以后加字段时,它是唯一能回溯的依据。</p>
*/ */
@ -21,8 +23,10 @@ public final class WarehouseCallback {
private final WarehouseProvider sourceProvider; private final WarehouseProvider sourceProvider;
/** 仓方给的事件 id;没有时用 {@link #fingerprint()} 去重。 */ /** 仓方给的事件 id;没有时用 {@link #fingerprint()} 去重。 */
private final String eventId; private final String eventId;
/** 仓方的事件类型原值,如 {@code LABEL_PURCHASED};不猜语义。 */ /** 事件类型(统一枚举),调用方按它分派。 */
private final String eventType; private final WarehouseEventType eventType;
/** 仓方的事件原值,便于排查;不同仓叫法不同,不要用它做业务判断。 */
private final String rawEventType;
/** 仓方仓 code;报文未给时为 null。 */ /** 仓方仓 code;报文未给时为 null。 */
private final String providerWarehouseCode; private final String providerWarehouseCode;
/** 仓方单据号(运去哪 {@code orderNo})。 */ /** 仓方单据号(运去哪 {@code orderNo})。 */
@ -36,11 +40,13 @@ public final class WarehouseCallback {
private final OutboundPayload outbound; private final OutboundPayload outbound;
private final ReturnPayload returns; private final ReturnPayload returns;
private final InboundPayload inbound; private final InboundPayload inbound;
private final InventoryPayload inventory;
private WarehouseCallback(Builder b) { private WarehouseCallback(Builder b) {
this.sourceProvider = b.sourceProvider; this.sourceProvider = b.sourceProvider;
this.eventId = b.eventId; this.eventId = b.eventId;
this.eventType = b.eventType; this.eventType = b.eventType == null ? WarehouseEventType.UNKNOWN : b.eventType;
this.rawEventType = b.rawEventType;
this.providerWarehouseCode = b.providerWarehouseCode; this.providerWarehouseCode = b.providerWarehouseCode;
this.providerOrderNo = b.providerOrderNo; this.providerOrderNo = b.providerOrderNo;
this.requestNo = b.requestNo; this.requestNo = b.requestNo;
@ -49,6 +55,7 @@ public final class WarehouseCallback {
this.outbound = b.outbound; this.outbound = b.outbound;
this.returns = b.returns; this.returns = b.returns;
this.inbound = b.inbound; this.inbound = b.inbound;
this.inventory = b.inventory;
} }
public static Builder builder() { public static Builder builder() {
@ -63,10 +70,16 @@ public final class WarehouseCallback {
return eventId; return eventId;
} }
public String eventType() { /** 事件类型;无法识别时为 {@link WarehouseEventType#UNKNOWN}。 */
public WarehouseEventType eventType() {
return eventType; return eventType;
} }
/** 仓方的事件原值;用于排查,不用于业务判断。 */
public String rawEventType() {
return rawEventType;
}
public String providerWarehouseCode() { public String providerWarehouseCode() {
return providerWarehouseCode; return providerWarehouseCode;
} }
@ -103,6 +116,11 @@ public final class WarehouseCallback {
return inbound; return inbound;
} }
/** 库存变动载荷;非库存事件为 null。 */
public InventoryPayload inventory() {
return inventory;
}
/** /**
* 去重指纹:仓方没给事件 id 时用它。 * 去重指纹:仓方没给事件 id 时用它。
* *
@ -334,10 +352,153 @@ public final class WarehouseCallback {
} }
} }
/**
* 库存变动载荷(增量流水,不是库存快照)。
*
* <p>{@link #quantity()} 是本次变动量,方向由 {@link #inbound()} 表示——
* 不要把它当当前库存覆盖写。</p>
*/
public static final class InventoryPayload {
private final String sku;
/** 0 正常 / 1 不可售。 */
private final Integer inventoryType;
/** 是否越库。 */
private final Boolean overWarehouse;
private final String sourceNo;
private final String planNo;
private final String orderNo;
/** 仓方单据类型码原值(如 100 销售出库);语义由适配器的平台枚举解释。 */
private final Integer providerOperationType;
/** 是否入库方向;true 入库、false 出库。 */
private final boolean inbound;
/** 变动数量(正数)。 */
private final Integer quantity;
private InventoryPayload(Builder b) {
this.sku = b.sku;
this.inventoryType = b.inventoryType;
this.overWarehouse = b.overWarehouse;
this.sourceNo = b.sourceNo;
this.planNo = b.planNo;
this.orderNo = b.orderNo;
this.providerOperationType = b.providerOperationType;
this.inbound = b.inbound;
this.quantity = b.quantity;
}
public static Builder builder() {
return new Builder();
}
public String sku() {
return sku;
}
/** 0 正常 / 1 不可售;仓方未给时为 null。 */
public Integer inventoryType() {
return inventoryType;
}
/** 是否越库;仓方未给时为 null。 */
public Boolean overWarehouse() {
return overWarehouse;
}
public String sourceNo() {
return sourceNo;
}
public String planNo() {
return planNo;
}
public String orderNo() {
return orderNo;
}
/** 仓方单据类型码原值;用于关联出入库业务单据。 */
public Integer providerOperationType() {
return providerOperationType;
}
/** 是否入库方向。 */
public boolean inbound() {
return inbound;
}
/** 变动数量(正数,方向看 {@link #inbound()})。 */
public Integer quantity() {
return quantity;
}
public static final class Builder {
private String sku;
private Integer inventoryType;
private Boolean overWarehouse;
private String sourceNo;
private String planNo;
private String orderNo;
private Integer providerOperationType;
private boolean inbound;
private Integer quantity;
public Builder sku(String v) {
this.sku = v;
return this;
}
public Builder inventoryType(Integer v) {
this.inventoryType = v;
return this;
}
public Builder overWarehouse(Boolean v) {
this.overWarehouse = v;
return this;
}
public Builder sourceNo(String v) {
this.sourceNo = v;
return this;
}
public Builder planNo(String v) {
this.planNo = v;
return this;
}
public Builder orderNo(String v) {
this.orderNo = v;
return this;
}
public Builder providerOperationType(Integer v) {
this.providerOperationType = v;
return this;
}
public Builder inbound(boolean v) {
this.inbound = v;
return this;
}
public Builder quantity(Integer v) {
this.quantity = v;
return this;
}
public InventoryPayload build() {
return new InventoryPayload(this);
}
}
}
public static final class Builder { public static final class Builder {
private WarehouseProvider sourceProvider; private WarehouseProvider sourceProvider;
private String eventId; private String eventId;
private String eventType; private WarehouseEventType eventType;
private String rawEventType;
private String providerWarehouseCode; private String providerWarehouseCode;
private String providerOrderNo; private String providerOrderNo;
private String requestNo; private String requestNo;
@ -346,6 +507,7 @@ public final class WarehouseCallback {
private OutboundPayload outbound; private OutboundPayload outbound;
private ReturnPayload returns; private ReturnPayload returns;
private InboundPayload inbound; private InboundPayload inbound;
private InventoryPayload inventory;
public Builder sourceProvider(WarehouseProvider v) { public Builder sourceProvider(WarehouseProvider v) {
this.sourceProvider = v; this.sourceProvider = v;
@ -357,11 +519,16 @@ public final class WarehouseCallback {
return this; return this;
} }
public Builder eventType(String v) { public Builder eventType(WarehouseEventType v) {
this.eventType = v; this.eventType = v;
return this; return this;
} }
public Builder rawEventType(String v) {
this.rawEventType = v;
return this;
}
public Builder providerWarehouseCode(String v) { public Builder providerWarehouseCode(String v) {
this.providerWarehouseCode = v; this.providerWarehouseCode = v;
return this; return this;
@ -402,6 +569,11 @@ public final class WarehouseCallback {
return this; return this;
} }
public Builder inventory(InventoryPayload v) {
this.inventory = v;
return this;
}
public WarehouseCallback build() { public WarehouseCallback build() {
return new WarehouseCallback(this); return new WarehouseCallback(this);
} }

26
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -547,13 +547,39 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
secret, headers, rawBody, nowMillis); secret, headers, rawBody, nowMillis);
} }
/**
* 回调解析:按报文特征分派到四个接口。
*
* <ul>
* <li>带 {@code processMode} → 退货入库完成(API 142)</li>
* <li>带 {@code opType} / {@code sku} → 库存变动(API 150)</li>
* <li>带 {@code orderNoType} → 业务单据变动(API 154)</li>
* <li>否则按面单购买成功(API 149)</li>
* </ul>
*
* <p>四个接口共用同一套验签,但报文不同;运去哪不区分回调路径,所以只能按结构分派。</p>
*/
@Override @Override
public List<WarehouseCallback> parse(WarehouseContext ctx, public List<WarehouseCallback> parse(WarehouseContext ctx,
common.ecommerce.shared.spi.ChannelSecret secret, common.ecommerce.shared.spi.ChannelSecret secret,
Map<String, String> headers, String rawBody) { Map<String, String> headers, String rawBody) {
if (hasJsonField(rawBody, "processMode")) {
return common.ecommerce.yqn.webhook.YqnOrderCallbackParser.parseReturnInbound(rawBody);
}
if (hasJsonField(rawBody, "opType")) {
return common.ecommerce.yqn.webhook.YqnInventoryCallbackParser.parse(rawBody);
}
if (hasJsonField(rawBody, "orderNoType")) {
return common.ecommerce.yqn.webhook.YqnOrderCallbackParser.parseOrderStatus(rawBody);
}
return common.ecommerce.yqn.webhook.YqnLabelCallbackParser.parse(rawBody); return common.ecommerce.yqn.webhook.YqnLabelCallbackParser.parse(rawBody);
} }
/** 轻量判断报文里是否有某字段;不建对象、不抛异常。 */
private static boolean hasJsonField(String rawBody, String field) {
return rawBody != null && rawBody.contains("\"" + field + "\"");
}
// ------------------------------------------------------------------ 仓库目录 // ------------------------------------------------------------------ 仓库目录
/** /**

56
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInventoryCallbackDtos.java

@ -0,0 +1,56 @@
package common.ecommerce.yqn.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
/**
* 运去哪报文结构:库存变动推送(API 150,仓方推送到商户配置的地址)。
*
* <p>每次推送是<b>一条 SKU 的变动流水</b>(增量),不是库存快照。
* 宿主落流水后用增量累加或回查接口校正,不要直接当绝对值覆盖。</p>
*/
public final class YqnInventoryCallbackDtos {
private YqnInventoryCallbackDtos() {
}
/** 一条库存变动。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class InventoryChanged {
/** 组织仓库 code。 */
public String orgWarehouseCode;
/** 项目。 */
public String lineName;
/** 渠道。 */
public String sourceChannel;
public String sku;
/** 库存类型:0 正常 / 1 不可售。 */
public Integer inventoryType;
/** 是否越库 0 否 / 1 是。 */
public Integer isOverWarehouse;
/** 来源单号 id。 */
public String sourceId;
/** 来源单号。 */
public String sourceNo;
/** 计划单号。 */
public String planNo;
/** 执行单号。 */
public String orderNo;
/** 单据类型码,见文档 opType 表(5 初始化 / 10 采购入库 / 100 销售出库 …)。 */
public Integer opType;
/** 库存变动类型:2 入库 / 3 出库。 */
public Integer opLabel;
/** 变动数量(增量,带方向由 opLabel 决定)。 */
public Integer quantity;
/** 长(cm)。 */
public Double length;
/** 宽(cm)。 */
public Double width;
/** 重量(g)。 */
public Double weight;
/** 高(cm)。 */
public Double height;
/** 变更时间。 */
public String updatedAt;
}
}

41
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnOrderStatusCallbackDtos.java

@ -0,0 +1,41 @@
package common.ecommerce.yqn.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
/**
* 运去哪报文结构:业务单据变动推送(API 154,仓方推送到商户配置的地址)。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构;
* 与其它接口共用的结构各自复制一份,避免跨接口耦合。</p>
*/
public final class YqnOrderStatusCallbackDtos {
private YqnOrderStatusCallbackDtos() {
}
/**
* 业务单据变动。
*
* <p>状态码含义随 {@link #orderNoType} 变化:同一个数字在不同单据类型下
* 意思不同(如 5 在入库计划里是「审核通过」,在退货认领里是「待处理」),
* 所以两者必须一起解释。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class OrderStatusChanged {
/** 来源单号(上游业务单据号)。 */
public String sourceNo;
/** 单据号(运去哪单号)。 */
public String orderNo;
/** 单据类型:1 入库计划单 / 2 调拨入库 / 3 调拨出库 / 4 销售出库 / 5 退货认领。 */
public Integer orderNoType;
/** 当前状态码;含义随 {@code orderNoType} 变化。 */
public Integer orderNoStatus;
/** 状态码的文字描述(仓方原话)。 */
public String orderNoStatusDesc;
/** 时区,如 {@code UTC+0}。 */
public String timeZone;
/** 变更时间 {@code yyyy-MM-dd HH:mm:ss}(0 时区)。 */
public String changeTime;
}
}

66
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnReturnInboundCallbackDtos.java

@ -0,0 +1,66 @@
package common.ecommerce.yqn.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 运去哪报文结构:退货入库单完成推送(API 142,仓方推送到商户配置的地址)。
*
* <p>这是退货链路的<b>唯一结果来源</b>——运去哪没有退货查询接口,
* 检验后的处理方式与上架数量只能从这里拿。</p>
*/
public final class YqnReturnInboundCallbackDtos {
private YqnReturnInboundCallbackDtos() {
}
/** 退货入库单上架 / 销毁结果。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ReturnInboundPushed {
/**
* 来源单号。
*
* <p>含义随单据类型变化:无来源退货是 NI 开头的计划单号、认领计划是 RL 开头的认领单号、
* 退货计划是物流单号。</p>
*/
public String sourceNo;
/** 退货入库单号。 */
public String orderNo;
/** 单据类型:退货计划 3 / 认领计划 4 / 无来源退货 6。 */
public Integer orderNoType;
/** 当前状态:5 已完成 / 14 收货待暂存 / 8 拍照待确认 / 9 待处理 / 1 待上架 / 2 上架中 / 7 已关闭。 */
public Integer orderNoStatus;
/** 变更时间 {@code yyyy-MM-dd HH:mm:ss}(UTC+0)。 */
public String changeTime;
/** 时区,如 {@code UTC+0}。 */
public String timeZone;
/** 处理方式:销毁 2 / 不良品上架 3 / 换标上架 4 / 良品上架 5。 */
public Integer processMode;
/** 运单号。 */
public String trackingNo;
public List<ReturnItem> items;
/** 一条明细。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ReturnItem {
/** 换标上架场景下传换标后的 SKU。 */
public String sku;
/** 上架数量;处理方式为销毁时不返回。 */
public Integer shelfQuantity;
/** 批次号,PC 开头。 */
public String batchParamNo;
/** 批次属性;换标上架场景下不传。 */
public List<BatchParam> batchParam;
}
/** 批次属性键值。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class BatchParam {
/** 生产批次 {@code LotCode} / 效期 {@code ProductionDateNumber}。 */
public String batchAttriKey;
public String batchAttriValue;
}
}
}

87
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnInventoryCallbackParser.java

@ -0,0 +1,87 @@
package common.ecommerce.yqn.webhook;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.warehouse.enums.WarehouseEventType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseCallback;
import common.ecommerce.yqn.dto.YqnInventoryCallbackDtos;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.List;
/**
* 运去哪库存变动推送(API 150)。
*
* <p>报文是<b>一条 SKU 的增量流水</b>,不是库存快照:{@code quantity} 是本次变动量,
* 方向由 {@code opLabel}(2 入库 / 3 出库)决定。宿主应按流水累加或回查校正,
* 不要直接覆盖本地库存。</p>
*/
public final class YqnInventoryCallbackParser {
private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
/** 库存变动方向:入库。 */
private static final int OP_LABEL_INBOUND = 2;
private YqnInventoryCallbackParser() {
}
/** 解析库存变动。 */
public static List<WarehouseCallback> parse(String rawBody) {
YqnInventoryCallbackDtos.InventoryChanged body =
JSON.fromJson(rawBody, YqnInventoryCallbackDtos.InventoryChanged.class);
WarehouseCallback callback = WarehouseCallback.builder()
.sourceProvider(WarehouseProvider.YQN)
.eventType(WarehouseEventType.INVENTORY_CHANGED)
.rawEventType("INVENTORY_CHANGED:" + body.opType)
.providerWarehouseCode(body.orgWarehouseCode)
.providerOrderNo(body.orderNo)
.requestNo(body.sourceNo)
.occurredAt(parseTime(body.updatedAt))
.rawBody(rawBody)
.inventory(WarehouseCallback.InventoryPayload.builder()
.sku(body.sku)
.inventoryType(body.inventoryType)
.overWarehouse(isTrue(body.isOverWarehouse))
.sourceNo(body.sourceNo)
.planNo(body.planNo)
.orderNo(body.orderNo)
.providerOperationType(body.opType)
.inbound(body.opLabel != null && body.opLabel == OP_LABEL_INBOUND)
.quantity(body.quantity)
.build())
.build();
List<WarehouseCallback> out = new ArrayList<WarehouseCallback>(1);
out.add(callback);
return out;
}
private static Boolean isTrue(Integer flag) {
return flag == null ? null : flag != 0;
}
/** {@code updatedAt} 格式文档未给具体值,按常见本地格式解析;失败返回 null。 */
static Instant parseTime(String value) {
if (value == null || value.trim().isEmpty()) {
return null;
}
String v = value.trim();
try {
return LocalDateTime.parse(v, TIME).toInstant(ZoneOffset.UTC);
} catch (DateTimeParseException ignored) {
// 落下一个格式
}
try {
return Instant.parse(v);
} catch (DateTimeParseException ignored) {
return null;
}
}
}

6
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParser.java

@ -2,6 +2,7 @@ package common.ecommerce.yqn.webhook;
import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.warehouse.enums.WarehouseEventType;
import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseCallback; import common.ecommerce.warehouse.model.WarehouseCallback;
import common.ecommerce.warehouse.sdk.WebhookSignatures; import common.ecommerce.warehouse.sdk.WebhookSignatures;
@ -29,7 +30,7 @@ public final class YqnLabelCallbackParser {
/** 时间戳窗口:5 分钟。回调重推一般在秒级,窗口过大会放大重放风险。 */ /** 时间戳窗口:5 分钟。回调重推一般在秒级,窗口过大会放大重放风险。 */
public static final long TIMESTAMP_TOLERANCE_MILLIS = 5 * 60 * 1000L; public static final long TIMESTAMP_TOLERANCE_MILLIS = 5 * 60 * 1000L;
/** 事件类型:面单购买成功。 */ /** 事件类型原值:面单购买成功。 */
static final String EVENT_LABEL_PURCHASED = "LABEL_PURCHASED"; static final String EVENT_LABEL_PURCHASED = "LABEL_PURCHASED";
private static final String HEADER_APP_KEY = "X-AppKey"; private static final String HEADER_APP_KEY = "X-AppKey";
@ -92,7 +93,8 @@ public final class YqnLabelCallbackParser {
.sourceProvider(WarehouseProvider.YQN) .sourceProvider(WarehouseProvider.YQN)
// 报文没有事件 id 与时间:用仓单号 + 来源单号做去重依据 // 报文没有事件 id 与时间:用仓单号 + 来源单号做去重依据
.eventId(null) .eventId(null)
.eventType(EVENT_LABEL_PURCHASED) .eventType(WarehouseEventType.LABEL_PURCHASED)
.rawEventType(EVENT_LABEL_PURCHASED)
.providerOrderNo(body.orderNo) .providerOrderNo(body.orderNo)
.requestNo(body.sourceNo) .requestNo(body.sourceNo)
.rawBody(rawBody) .rawBody(rawBody)

127
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java

@ -0,0 +1,127 @@
package common.ecommerce.yqn.webhook;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.WarehouseEventType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseCallback;
import common.ecommerce.yqn.dto.YqnOrderStatusCallbackDtos;
import common.ecommerce.yqn.dto.YqnReturnInboundCallbackDtos;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.List;
/**
* 运去哪业务单据变动(API 154)与退货入库完成(API 142)回调。
*
* <p>两个接口共用同一套验签({@code X-AppKey/X-Timestamp/X-Signature},算法同 API 149),
* 但报文结构不同,所以分成两个入口;由适配器按报文特征分派。</p>
*
* <p><b>状态码含义随单据类型变化</b>:API 154 的 {@code orderNoStatus} 在
* 「入库计划 / 调拨 / 销售出库 / 退货认领」四套码表下含义完全不同,
* 所以这里都把「类型 + 状态」原样带出去,由平台枚举解释,不在本类里猜。</p>
*/
public final class YqnOrderCallbackParser {
private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private YqnOrderCallbackParser() {
}
/** 业务单据变动(API 154)。 */
public static List<WarehouseCallback> parseOrderStatus(String rawBody) {
YqnOrderStatusCallbackDtos.OrderStatusChanged body =
JSON.fromJson(rawBody, YqnOrderStatusCallbackDtos.OrderStatusChanged.class);
WarehouseCallback callback = WarehouseCallback.builder()
.sourceProvider(WarehouseProvider.YQN)
.eventType(WarehouseEventType.ORDER_STATUS_CHANGED)
.rawEventType("ORDER_STATUS:" + body.orderNoType)
.providerOrderNo(body.orderNo)
.requestNo(body.sourceNo)
.occurredAt(parseTime(body.changeTime))
.rawBody(rawBody)
.build();
List<WarehouseCallback> out = new ArrayList<WarehouseCallback>(1);
out.add(callback);
return out;
}
/**
* 退货入库完成(API 142)。
*
* <p>这是退货链路的<b>唯一结果来源</b>。{@code processMode} 映射到
* {@link ReturnProcessDisposition}——注意它的码值集合与 API 81 的
* 「预约处理方式」不同,别混用(见 {@code YqnReturnProcessDisposition})。</p>
*/
public static List<WarehouseCallback> parseReturnInbound(String rawBody) {
YqnReturnInboundCallbackDtos.ReturnInboundPushed body =
JSON.fromJson(rawBody, YqnReturnInboundCallbackDtos.ReturnInboundPushed.class);
WarehouseCallback.ReturnPayload.Builder payload = WarehouseCallback.ReturnPayload.builder();
if (body.items != null) {
for (YqnReturnInboundCallbackDtos.ReturnInboundPushed.ReturnItem item : body.items) {
payload.line(WarehouseCallback.ReturnLinePayload.builder()
.providerSku(item.sku)
.quantity(item.shelfQuantity)
// 回调不带明细行 id;API 77 的操作键只能从别处拿
.lineId(null)
.disposition(processModeLabel(body.processMode))
.build());
}
}
WarehouseCallback callback = WarehouseCallback.builder()
.sourceProvider(WarehouseProvider.YQN)
.eventType(WarehouseEventType.RETURN_INBOUND_COMPLETED)
.rawEventType("RETURN_INBOUND:" + body.orderNoType)
.providerOrderNo(body.orderNo)
.requestNo(body.sourceNo)
.occurredAt(parseTime(body.changeTime))
.rawBody(rawBody)
.returns(payload.build())
.build();
List<WarehouseCallback> out = new ArrayList<WarehouseCallback>(1);
out.add(callback);
return out;
}
/** 处理方式码 → 底层枚举;未知返回 null(不猜)。 */
static String processModeLabel(Integer processMode) {
if (processMode == null) {
return null;
}
switch (processMode) {
case 2:
return ReturnProcessDisposition.DESTROY.name();
case 3:
return ReturnProcessDisposition.RESTOCK.name();
case 4:
return ReturnProcessDisposition.RESTOCK_RELABEL.name();
case 5:
return ReturnProcessDisposition.RESTOCK.name();
default:
return null;
}
}
/**
* 解析变更时间。
*
* <p>两个回调都写明 UTC+0 且格式为 {@code yyyy-MM-dd HH:mm:ss},所以直接按 UTC 解释,
* 不看 {@code timeZone} 字段——那里恒为 {@code UTC+0},信任报文反而容易出错。</p>
*/
static Instant parseTime(String value) {
if (value == null || value.trim().isEmpty()) {
return null;
}
try {
return LocalDateTime.parse(value.trim(), TIME).toInstant(ZoneOffset.UTC);
} catch (DateTimeParseException e) {
return null;
}
}
}

174
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java

@ -0,0 +1,174 @@
package common.ecommerce.yqn.webhook;
import common.ecommerce.warehouse.enums.WarehouseEventType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.WarehouseCallback;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 另外三种回调的解析:业务单据变动(API 154)、退货入库完成(API 142)、
* 库存变动(API 150)。
*
* <p>验签与 API 149 完全相同,已由 {@link YqnLabelCallbackParserTest} 覆盖,
* 这里只测报文解析。</p>
*/
class YqnCallbackParsersTest {
// ---------------------------------------------------------------- API 154
@Test
void parsesOrderStatusChanged() {
String body = "{\"sourceNo\":\"OB-1\",\"orderNo\":\"IP900\",\"orderNoType\":1,"
+ "\"orderNoStatus\":5,\"orderNoStatusDesc\":\"审核通过\","
+ "\"timeZone\":\"UTC+0\",\"changeTime\":\"2026-11-10 03:20:00\"}";
List<WarehouseCallback> list = YqnOrderCallbackParser.parseOrderStatus(body);
assertEquals(1, list.size());
WarehouseCallback cb = list.get(0);
assertEquals(WarehouseProvider.YQN, cb.sourceProvider());
assertEquals(WarehouseEventType.ORDER_STATUS_CHANGED, cb.eventType());
// 单据类型带在 rawEventType 里:状态码含义随类型变化,调用方要一起看
assertEquals("ORDER_STATUS:1", cb.rawEventType());
assertEquals("IP900", cb.providerOrderNo());
assertEquals("OB-1", cb.requestNo());
assertEquals(Instant.parse("2026-11-10T03:20:00Z"), cb.occurredAt());
assertNull(cb.outbound());
assertNull(cb.returns());
assertNull(cb.inventory());
}
/** 同一状态码在不同单据类型下含义不同,不能丢。 */
@Test
void keepsOrderTypeAlongsideStatus() {
String redistribution = "{\"sourceNo\":\"S1\",\"orderNo\":\"O1\",\"orderNoType\":3,"
+ "\"orderNoStatus\":5,\"changeTime\":\"2026-11-10 00:00:00\"}";
String returnClaim = "{\"sourceNo\":\"S2\",\"orderNo\":\"O2\",\"orderNoType\":5,"
+ "\"orderNoStatus\":5,\"changeTime\":\"2026-11-10 00:00:00\"}";
assertEquals("ORDER_STATUS:3", YqnOrderCallbackParser.parseOrderStatus(redistribution)
.get(0).rawEventType());
assertEquals("ORDER_STATUS:5", YqnOrderCallbackParser.parseOrderStatus(returnClaim)
.get(0).rawEventType());
}
// ---------------------------------------------------------------- API 142
@Test
void parsesReturnInboundCompleted() {
String body = "{\"sourceNo\":\"TRK123\",\"orderNo\":\"RT900\",\"orderNoType\":3,"
+ "\"orderNoStatus\":5,\"changeTime\":\"2026-11-10 05:00:00\","
+ "\"timeZone\":\"UTC+0\",\"processMode\":5,\"trackingNo\":\"TRK123\","
+ "\"items\":[{\"sku\":\"DM00001\",\"shelfQuantity\":3,\"batchParamNo\":\"PC001\"},"
+ "{\"sku\":\"DM00002\",\"shelfQuantity\":1,\"batchParamNo\":\"PC002\"}]}";
List<WarehouseCallback> list = YqnOrderCallbackParser.parseReturnInbound(body);
WarehouseCallback cb = list.get(0);
assertEquals(WarehouseEventType.RETURN_INBOUND_COMPLETED, cb.eventType());
assertEquals("RETURN_INBOUND:3", cb.rawEventType());
assertEquals("RT900", cb.providerOrderNo());
assertEquals(2, cb.returns().lines().size());
assertEquals("DM00001", cb.returns().lines().get(0).providerSku());
assertEquals(Integer.valueOf(3), cb.returns().lines().get(0).quantity());
// 5 良品上架 → RESTOCK
assertEquals("RESTOCK", cb.returns().lines().get(0).disposition());
}
@Test
void processModeMapsToDisposition() {
assertEquals("DESTROY", YqnOrderCallbackParser.processModeLabel(2));
assertEquals("RESTOCK", YqnOrderCallbackParser.processModeLabel(3));
assertEquals("RESTOCK_RELABEL", YqnOrderCallbackParser.processModeLabel(4));
assertEquals("RESTOCK", YqnOrderCallbackParser.processModeLabel(5));
// 未知不猜
assertNull(YqnOrderCallbackParser.processModeLabel(99));
assertNull(YqnOrderCallbackParser.processModeLabel(null));
}
/** 销毁时不返回 shelfQuantity,数量为 null 是正常的。 */
@Test
void destroyWithoutShelfQuantityIsAllowed() {
String body = "{\"orderNo\":\"RT1\",\"orderNoType\":3,\"orderNoStatus\":5,"
+ "\"changeTime\":\"2026-11-10 05:00:00\",\"timeZone\":\"UTC+0\","
+ "\"processMode\":2,\"items\":[{\"sku\":\"DM1\",\"batchParamNo\":\"PC1\"}]}";
WarehouseCallback cb = YqnOrderCallbackParser.parseReturnInbound(body).get(0);
assertNull(cb.returns().lines().get(0).quantity());
assertEquals("DESTROY", cb.returns().lines().get(0).disposition());
}
// ---------------------------------------------------------------- API 150
@Test
void parsesInventoryChanged() {
String body = "{\"orgWarehouseCode\":\"RF_NY_US\",\"lineName\":\"默认项目\","
+ "\"sourceChannel\":\"API\",\"sku\":\"DM00001\",\"inventoryType\":0,"
+ "\"isOverWarehouse\":0,\"sourceId\":\"1001\",\"sourceNo\":\"OB-1\","
+ "\"planNo\":\"P900\",\"orderNo\":\"O900\",\"opType\":100,\"opLabel\":3,"
+ "\"quantity\":2,\"length\":10,\"width\":8,\"weight\":500,\"height\":6,"
+ "\"updatedAt\":\"2026-11-10 06:00:00\"}";
WarehouseCallback cb = YqnInventoryCallbackParser.parse(body).get(0);
assertEquals(WarehouseEventType.INVENTORY_CHANGED, cb.eventType());
assertEquals("INVENTORY_CHANGED:100", cb.rawEventType());
assertEquals("RF_NY_US", cb.providerWarehouseCode());
assertEquals("O900", cb.providerOrderNo());
WarehouseCallback.InventoryPayload inv = cb.inventory();
assertEquals("DM00001", inv.sku());
assertEquals(Integer.valueOf(0), inv.inventoryType());
assertEquals(Boolean.FALSE, inv.overWarehouse());
assertEquals(Integer.valueOf(100), inv.providerOperationType());
// opLabel 3 = 出库
assertEquals(false, inv.inbound());
assertEquals(Integer.valueOf(2), inv.quantity());
assertEquals(Instant.parse("2026-11-10T06:00:00Z"), cb.occurredAt());
}
@Test
void inventoryInboundDirection() {
String body = "{\"orgWarehouseCode\":\"W\",\"sku\":\"S\",\"inventoryType\":0,"
+ "\"isOverWarehouse\":1,\"sourceNo\":\"X\",\"planNo\":\"P\",\"orderNo\":\"O\","
+ "\"opType\":10,\"opLabel\":2,\"quantity\":5,\"updatedAt\":\"2026-11-10 06:00:00\"}";
WarehouseCallback.InventoryPayload inv =
YqnInventoryCallbackParser.parse(body).get(0).inventory();
assertTrue(inv.inbound());
assertEquals(Boolean.TRUE, inv.overWarehouse());
assertEquals(Integer.valueOf(5), inv.quantity());
}
/** 库存推送是增量流水,方向与数量分开表达。 */
@Test
void quantityIsAlwaysPositiveWithSeparateDirection() {
String body = "{\"sku\":\"S\",\"opType\":100,\"opLabel\":3,\"quantity\":7,"
+ "\"updatedAt\":\"2026-11-10 06:00:00\"}";
WarehouseCallback.InventoryPayload inv =
YqnInventoryCallbackParser.parse(body).get(0).inventory();
assertEquals(Integer.valueOf(7), inv.quantity());
assertEquals(false, inv.inbound());
}
// ---------------------------------------------------------------- 时间解析
@Test
void changeTimeIsUtc() {
assertEquals(Instant.parse("2026-11-10T03:20:00Z"),
YqnOrderCallbackParser.parseTime("2026-11-10 03:20:00"));
assertNull(YqnOrderCallbackParser.parseTime("not-a-time"));
assertNull(YqnOrderCallbackParser.parseTime(null));
}
}

4
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParserTest.java

@ -1,6 +1,7 @@
package common.ecommerce.yqn.webhook; package common.ecommerce.yqn.webhook;
import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.warehouse.enums.WarehouseEventType;
import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseWebhookVerificationException; import common.ecommerce.warehouse.error.WarehouseWebhookVerificationException;
import common.ecommerce.warehouse.model.WarehouseCallback; import common.ecommerce.warehouse.model.WarehouseCallback;
@ -126,7 +127,8 @@ class YqnLabelCallbackParserTest {
assertEquals(1, list.size()); assertEquals(1, list.size());
WarehouseCallback cb = list.get(0); WarehouseCallback cb = list.get(0);
assertEquals(WarehouseProvider.YQN, cb.sourceProvider()); assertEquals(WarehouseProvider.YQN, cb.sourceProvider());
assertEquals("LABEL_PURCHASED", cb.eventType()); assertEquals(WarehouseEventType.LABEL_PURCHASED, cb.eventType());
assertEquals("LABEL_PURCHASED", cb.rawEventType());
assertEquals("IP123", cb.providerOrderNo()); assertEquals("IP123", cb.providerOrderNo());
assertEquals("OB-123", cb.requestNo()); assertEquals("OB-123", cb.requestNo());
assertNull(cb.eventId()); assertNull(cb.eventId());

Loading…
Cancel
Save