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每次推送是一条 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报文是一条 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两个接口共用同一套验签({@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这是退货链路的唯一结果来源。{@code processMode} 映射到 + * {@link ReturnProcessDisposition}——注意它的码值集合与 API 81 的 + * 「预约处理方式」不同,别混用(见 {@code YqnReturnProcessDisposition})。
+ */ + public static List两个回调都写明 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