From 56e3406f7cb3eb3ff6e3854ae6b45fad78b5c846 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 10 Nov 2026 17:24:04 +0800 Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E8=A1=A5=E9=BD=90=E5=8F=A6?= =?UTF-8?q?=E5=A4=96=E4=B8=89=E4=B8=AA=E5=9B=9E=E8=B0=83=EF=BC=9A=E5=8D=95?= =?UTF-8?q?=E6=8D=AE=E5=8F=98=E5=8A=A8=20/=20=E9=80=80=E8=B4=A7=E5=85=A5?= =?UTF-8?q?=E5=BA=93=E5=AE=8C=E6=88=90=20/=20=E5=BA=93=E5=AD=98=E5=8F=98?= =?UTF-8?q?=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 四个回调共用同一套验签(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 --- README.md | 8 +- .../warehouse/enums/WarehouseEventType.java | 50 ++++++ .../warehouse/model/WarehouseCallback.java | 188 ++++++++++++++++++++- .../common/ecommerce/yqn/adapter/YqnAdapter.java | 26 +++ .../yqn/dto/YqnInventoryCallbackDtos.java | 56 ++++++ .../yqn/dto/YqnOrderStatusCallbackDtos.java | 41 +++++ .../yqn/dto/YqnReturnInboundCallbackDtos.java | 66 ++++++++ .../yqn/webhook/YqnInventoryCallbackParser.java | 87 ++++++++++ .../yqn/webhook/YqnLabelCallbackParser.java | 6 +- .../yqn/webhook/YqnOrderCallbackParser.java | 127 ++++++++++++++ .../yqn/webhook/YqnCallbackParsersTest.java | 174 +++++++++++++++++++ .../yqn/webhook/YqnLabelCallbackParserTest.java | 4 +- 12 files changed, 819 insertions(+), 14 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseEventType.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInventoryCallbackDtos.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnOrderStatusCallbackDtos.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnReturnInboundCallbackDtos.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnInventoryCallbackParser.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java create mode 100644 warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java diff --git a/README.md b/README.md index 819e57d..17a0a47 100644 --- a/README.md +++ b/README.md @@ -299,7 +299,7 @@ common.ecommerce │ │ WarehouseProvider / WarehouseCapability / OutboundStatus / │ │ InboundStatus / TransferStatus / TransferType / LabelMode / │ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType / -│ │ ReturnDealMethod / ReturnProcessDisposition / AttachmentType / +│ │ ReturnDealMethod / ReturnProcessDisposition / AttachmentType / WarehouseEventType / │ │ LabelDownloadMode / LabelSizeType / LabelsPerPage / SkuLabelSizeType │ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine / │ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec / @@ -328,7 +328,8 @@ common.ecommerce │ WebhookSignatures(HMAC / 恒定时间比较 / 时间窗) │ ├── yqn 运去哪三方仓(warehouse-sdk-yqn) -│ ├── webhook 回调验签与解析(YqnLabelCallbackParser) +│ ├── webhook 回调验签与解析:YqnLabelCallbackParser(API 149)/ +│ │ YqnOrderCallbackParser(API 154 + 142)/ YqnInventoryCallbackParser(API 150) │ ├── dto (按接口拆分,一个接口一个文件) │ │ YqnCreateOrderDtos / YqnOrderDetailDtos / YqnCancelOrderDtos / │ │ YqnProductDtos / YqnFeeDetailDtos / YqnInventoryDtos / @@ -337,7 +338,8 @@ common.ecommerce │ │ YqnFeeEstimateDtos / YqnTrackingDtos / YqnDestroyPlanDtos / │ │ YqnBoxLabelDtos / YqnSkuLabelDtos / │ │ YqnLogisticsProductDtos / YqnWarehouseDtos / -│ │ YqnLabelCallbackDtos +│ │ YqnLabelCallbackDtos / YqnOrderStatusCallbackDtos / +│ │ YqnReturnInboundCallbackDtos / YqnInventoryCallbackDtos │ ├── YqnConstants 端点、路径、固定 token 请求头名、限流 │ ├── adapter YqnAdapter(P1 出库) / YqnAdapterFactory / YqnOutboundMapper │ ├── dto YqnDtos(字段级契约待打样核对) diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseEventType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseEventType.java new file mode 100644 index 0000000..7ffd2d0 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseEventType.java @@ -0,0 +1,50 @@ +package common.ecommerce.warehouse.enums; + +/** + * 仓方回调事件的类型(统一枚举)。 + * + *

各仓的事件名不同、粒度不同,适配器负责映射到这里;调用方按本枚举分派, + * 不需要认识任何仓的原始事件名。原始值仍保留在 + * {@code WarehouseCallback.rawEventType()} 里。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java index 92358e9..c3602c3 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseCallback.java @@ -1,5 +1,6 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.WarehouseEventType; import common.ecommerce.warehouse.enums.WarehouseProvider; import java.time.Instant; @@ -11,8 +12,9 @@ import java.time.Instant; * SDK 不监听端口、不做去重存储,只负责「验签 + 解析成统一结构」。

* *

不同业务的载荷放在各自的可空字段里,按 {@link #eventType()} 区分: - * 出库存 {@link #outbound()},退货存 {@link #returns()},入库存 {@link #inbound()}。 - * 没用到的字段为 null,不用再建一套平行的类型层级。

+ * 面单 / 出库存 {@link #outbound()},退货存 {@link #returns()}, + * 入库存 {@link #inbound()},库存变动存 {@link #inventory()}。 + * 用到的字段之外恒为 null。

* *

{@link #rawBody()} 原样保留:解析出错或以后加字段时,它是唯一能回溯的依据。

*/ @@ -21,8 +23,10 @@ public final class WarehouseCallback { private final WarehouseProvider sourceProvider; /** 仓方给的事件 id;没有时用 {@link #fingerprint()} 去重。 */ private final String eventId; - /** 仓方的事件类型原值,如 {@code LABEL_PURCHASED};不猜语义。 */ - private final String eventType; + /** 事件类型(统一枚举),调用方按它分派。 */ + private final WarehouseEventType eventType; + /** 仓方的事件原值,便于排查;不同仓叫法不同,不要用它做业务判断。 */ + private final String rawEventType; /** 仓方仓 code;报文未给时为 null。 */ private final String providerWarehouseCode; /** 仓方单据号(运去哪 {@code orderNo})。 */ @@ -36,11 +40,13 @@ public final class WarehouseCallback { private final OutboundPayload outbound; private final ReturnPayload returns; private final InboundPayload inbound; + private final InventoryPayload inventory; private WarehouseCallback(Builder b) { this.sourceProvider = b.sourceProvider; 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.providerOrderNo = b.providerOrderNo; this.requestNo = b.requestNo; @@ -49,6 +55,7 @@ public final class WarehouseCallback { this.outbound = b.outbound; this.returns = b.returns; this.inbound = b.inbound; + this.inventory = b.inventory; } public static Builder builder() { @@ -63,10 +70,16 @@ public final class WarehouseCallback { return eventId; } - public String eventType() { + /** 事件类型;无法识别时为 {@link WarehouseEventType#UNKNOWN}。 */ + public WarehouseEventType eventType() { return eventType; } + /** 仓方的事件原值;用于排查,不用于业务判断。 */ + public String rawEventType() { + return rawEventType; + } + public String providerWarehouseCode() { return providerWarehouseCode; } @@ -103,6 +116,11 @@ public final class WarehouseCallback { return inbound; } + /** 库存变动载荷;非库存事件为 null。 */ + public InventoryPayload inventory() { + return inventory; + } + /** * 去重指纹:仓方没给事件 id 时用它。 * @@ -334,10 +352,153 @@ public final class WarehouseCallback { } } + /** + * 库存变动载荷(增量流水,不是库存快照)。 + * + *

{@link #quantity()} 是本次变动量,方向由 {@link #inbound()} 表示—— + * 不要把它当当前库存覆盖写。

+ */ + 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 { private WarehouseProvider sourceProvider; private String eventId; - private String eventType; + private WarehouseEventType eventType; + private String rawEventType; private String providerWarehouseCode; private String providerOrderNo; private String requestNo; @@ -346,6 +507,7 @@ public final class WarehouseCallback { private OutboundPayload outbound; private ReturnPayload returns; private InboundPayload inbound; + private InventoryPayload inventory; public Builder sourceProvider(WarehouseProvider v) { this.sourceProvider = v; @@ -357,11 +519,16 @@ public final class WarehouseCallback { return this; } - public Builder eventType(String v) { + public Builder eventType(WarehouseEventType v) { this.eventType = v; return this; } + public Builder rawEventType(String v) { + this.rawEventType = v; + return this; + } + public Builder providerWarehouseCode(String v) { this.providerWarehouseCode = v; return this; @@ -402,6 +569,11 @@ public final class WarehouseCallback { return this; } + public Builder inventory(InventoryPayload v) { + this.inventory = v; + return this; + } + public WarehouseCallback build() { return new WarehouseCallback(this); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 94bf387..b005e14 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/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); } + /** + * 回调解析:按报文特征分派到四个接口。 + * + * + * + *

四个接口共用同一套验签,但报文不同;运去哪不区分回调路径,所以只能按结构分派。

+ */ @Override public List parse(WarehouseContext ctx, common.ecommerce.shared.spi.ChannelSecret secret, Map 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); } + /** 轻量判断报文里是否有某字段;不建对象、不抛异常。 */ + private static boolean hasJsonField(String rawBody, String field) { + return rawBody != null && rawBody.contains("\"" + field + "\""); + } + // ------------------------------------------------------------------ 仓库目录 /** diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInventoryCallbackDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnInventoryCallbackDtos.java new file mode 100644 index 0000000..4e8b965 --- /dev/null +++ b/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,仓方推送到商户配置的地址)。 + * + *

每次推送是一条 SKU 的变动流水(增量),不是库存快照。 + * 宿主落流水后用增量累加或回查接口校正,不要直接当绝对值覆盖。

+ */ +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; + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnOrderStatusCallbackDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnOrderStatusCallbackDtos.java new file mode 100644 index 0000000..aa3c243 --- /dev/null +++ b/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,仓方推送到商户配置的地址)。 + * + *

一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构; + * 与其它接口共用的结构各自复制一份,避免跨接口耦合。

+ */ +public final class YqnOrderStatusCallbackDtos { + + private YqnOrderStatusCallbackDtos() { + } + + /** + * 业务单据变动。 + * + *

状态码含义随 {@link #orderNoType} 变化:同一个数字在不同单据类型下 + * 意思不同(如 5 在入库计划里是「审核通过」,在退货认领里是「待处理」), + * 所以两者必须一起解释。

+ */ + @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; + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnReturnInboundCallbackDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnReturnInboundCallbackDtos.java new file mode 100644 index 0000000..8642c43 --- /dev/null +++ b/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,仓方推送到商户配置的地址)。 + * + *

这是退货链路的唯一结果来源——运去哪没有退货查询接口, + * 检验后的处理方式与上架数量只能从这里拿。

+ */ +public final class YqnReturnInboundCallbackDtos { + + private YqnReturnInboundCallbackDtos() { + } + + /** 退货入库单上架 / 销毁结果。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ReturnInboundPushed { + + /** + * 来源单号。 + * + *

含义随单据类型变化:无来源退货是 NI 开头的计划单号、认领计划是 RL 开头的认领单号、 + * 退货计划是物流单号。

+ */ + 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 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; + } + + /** 批次属性键值。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class BatchParam { + /** 生产批次 {@code LotCode} / 效期 {@code ProductionDateNumber}。 */ + public String batchAttriKey; + public String batchAttriValue; + } + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnInventoryCallbackParser.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnInventoryCallbackParser.java new file mode 100644 index 0000000..ee77e3d --- /dev/null +++ b/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)。 + * + *

报文是一条 SKU 的增量流水,不是库存快照:{@code quantity} 是本次变动量, + * 方向由 {@code opLabel}(2 入库 / 3 出库)决定。宿主应按流水累加或回查校正, + * 不要直接覆盖本地库存。

+ */ +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 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 out = new ArrayList(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; + } + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParser.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParser.java index cdd7c7d..6e14177 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParser.java +++ b/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.shared.spi.ChannelSecret; +import common.ecommerce.warehouse.enums.WarehouseEventType; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.model.WarehouseCallback; import common.ecommerce.warehouse.sdk.WebhookSignatures; @@ -29,7 +30,7 @@ public final class YqnLabelCallbackParser { /** 时间戳窗口:5 分钟。回调重推一般在秒级,窗口过大会放大重放风险。 */ public static final long TIMESTAMP_TOLERANCE_MILLIS = 5 * 60 * 1000L; - /** 事件类型:面单购买成功。 */ + /** 事件类型原值:面单购买成功。 */ static final String EVENT_LABEL_PURCHASED = "LABEL_PURCHASED"; private static final String HEADER_APP_KEY = "X-AppKey"; @@ -92,7 +93,8 @@ public final class YqnLabelCallbackParser { .sourceProvider(WarehouseProvider.YQN) // 报文没有事件 id 与时间:用仓单号 + 来源单号做去重依据 .eventId(null) - .eventType(EVENT_LABEL_PURCHASED) + .eventType(WarehouseEventType.LABEL_PURCHASED) + .rawEventType(EVENT_LABEL_PURCHASED) .providerOrderNo(body.orderNo) .requestNo(body.sourceNo) .rawBody(rawBody) diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/webhook/YqnOrderCallbackParser.java new file mode 100644 index 0000000..93b9cb8 --- /dev/null +++ b/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)回调。 + * + *

两个接口共用同一套验签({@code X-AppKey/X-Timestamp/X-Signature},算法同 API 149), + * 但报文结构不同,所以分成两个入口;由适配器按报文特征分派。

+ * + *

状态码含义随单据类型变化:API 154 的 {@code orderNoStatus} 在 + * 「入库计划 / 调拨 / 销售出库 / 退货认领」四套码表下含义完全不同, + * 所以这里都把「类型 + 状态」原样带出去,由平台枚举解释,不在本类里猜。

+ */ +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 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 out = new ArrayList(1); + out.add(callback); + return out; + } + + /** + * 退货入库完成(API 142)。 + * + *

这是退货链路的唯一结果来源。{@code processMode} 映射到 + * {@link ReturnProcessDisposition}——注意它的码值集合与 API 81 的 + * 「预约处理方式」不同,别混用(见 {@code YqnReturnProcessDisposition})。

+ */ + public static List 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 out = new ArrayList(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; + } + } + + /** + * 解析变更时间。 + * + *

两个回调都写明 UTC+0 且格式为 {@code yyyy-MM-dd HH:mm:ss},所以直接按 UTC 解释, + * 不看 {@code timeZone} 字段——那里恒为 {@code UTC+0},信任报文反而容易出错。

+ */ + 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; + } + } +} diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnCallbackParsersTest.java new file mode 100644 index 0000000..fe3e9ec --- /dev/null +++ b/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)。 + * + *

验签与 API 149 完全相同,已由 {@link YqnLabelCallbackParserTest} 覆盖, + * 这里只测报文解析。

+ */ +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 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 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)); + } +} diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParserTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParserTest.java index 0318903..5649f5c 100644 --- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParserTest.java +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/webhook/YqnLabelCallbackParserTest.java @@ -1,6 +1,7 @@ package common.ecommerce.yqn.webhook; import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.warehouse.enums.WarehouseEventType; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.WarehouseWebhookVerificationException; import common.ecommerce.warehouse.model.WarehouseCallback; @@ -126,7 +127,8 @@ class YqnLabelCallbackParserTest { assertEquals(1, list.size()); WarehouseCallback cb = list.get(0); 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("OB-123", cb.requestNo()); assertNull(cb.eventId());