diff --git a/README.md b/README.md index bf7ac01..6b8cc9a 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 +│ │ ReturnDealMethod / ReturnProcessDisposition / AttachmentType │ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine / │ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec / │ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult / @@ -308,7 +308,7 @@ common.ecommerce │ │ InboundReceipt / ReturnCommand / ReturnProcessCommand / │ │ WarehouseReturn / TransferCommand / TransferOrder / │ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult / -│ │ TrackEvent / TrackingInfo / DestructionOrder +│ │ TrackEvent / TrackingInfo / DestructionCommand / DestructionOrder │ ├── capability OutboundCapable / InventoryCapable / InboundCapable / │ │ WarehouseReturnCapable / WarehouseFeeCapable / │ │ WarehouseFeeEstimateCapable / TransferCapable / diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/DestructionCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/DestructionCapable.java index dcfb53b..51cd17c 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/DestructionCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/DestructionCapable.java @@ -1,5 +1,6 @@ package common.ecommerce.warehouse.capability; +import common.ecommerce.warehouse.model.DestructionCommand; import common.ecommerce.warehouse.model.DestructionOrder; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; @@ -7,9 +8,23 @@ import common.ecommerce.warehouse.sdk.WarehouseContext; /** 销毁 / 报废能力。仅运去哪有接口。 */ public interface DestructionCapable extends WarehouseAdapter { - /** 创建销毁计划。 */ - DestructionOrder create(WarehouseContext ctx, String destructionNo, String warehouseId, String skus); + /** + * 创建销毁计划。写操作,幂等键 + * {@code warehouseCode + destructionNo + create}。 + * + *
创建成功只代表「销毁申请已提交」,仓方是否执行、何时执行都不由本调用决定; + * 返回的 {@code status} 为 null,不要据此判断库存已扣减。
+ */ + DestructionOrder create(WarehouseContext ctx, DestructionCommand cmd); - /** 查询销毁计划。 */ - DestructionOrder get(WarehouseContext ctx, String destructionNo); + /** + * 查询销毁计划。 + * + *方法名带 {@code Destruction} 后缀:{@code OutboundCapable} 已有完全同签名的 + * {@code get(ctx, …)},同一适配器实现两者时无法区分。
+ * + *仓方查询接口未接入时抛 + * {@link common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException}。
+ */ + DestructionOrder getDestruction(WarehouseContext ctx, String destructionNo); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AttachmentType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AttachmentType.java new file mode 100644 index 0000000..e7cc563 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AttachmentType.java @@ -0,0 +1,46 @@ +package common.ecommerce.warehouse.enums; + +/** + * 销毁单附件类型。 + * + *取值来自仓方协议的分类口径;core 只表达语义,仓方码值由适配器映射。
+ */ +public enum AttachmentType { + + /** 面单。 */ + SHIPPING_LABEL(10, "面单"), + /** 装箱单。 */ + PACKING_LIST(20, "装箱单"), + /** 提单 / BOL。 */ + BOL(30, "提单"), + /** 其他。 */ + OTHER(40, "其他"); + + private final int code; + private final String label; + + AttachmentType(int code, String label) { + this.code = code; + this.label = label; + } + + /** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */ + public int code() { + return code; + } + + /** 中文显示名。 */ + public String label() { + return label; + } + + /** 按落库码反查。 */ + public static AttachmentType ofCode(int code) { + for (AttachmentType t : values()) { + if (t.code == code) { + return t; + } + } + return null; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java new file mode 100644 index 0000000..b87dd16 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java @@ -0,0 +1,237 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.AttachmentType; + +import java.time.LocalDate; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 销毁计划创建命令。写操作,幂等键是 {@link #destructionNo()}。 + * + *单据创建只代表「销毁申请已提交」,最终是否执行以仓方实际操作为准——不要把 + * 创建成功当成库存已扣减。
+ */ +public final class DestructionCommand { + + /** OMS 销毁单号,同时是仓方的来源单号 {@code sourceNo}。 */ + private final String destructionNo; + /** 销毁仓 code;null 时用账户配置的仓。 */ + private final String warehouseId; + /** 库存类型:0 可售 / 1 不可售。 */ + private final int inventoryType; + /** 期望销毁日期。 */ + private final LocalDate hopeDestroyDate; + private final String remark; + private final ListSDK 不落文件、不上传对象存储:{@link #url()} 由调用方提供,适配器原样下发。
+ */ + public static final class Attachment { + + private final String name; + private final String remark; + /** 附件类型;null 表示不指定,由仓方按默认处理。 */ + private final AttachmentType type; + private final String url; + + private Attachment(Builder b) { + this.name = b.name; + this.remark = b.remark; + this.type = b.type; + this.url = b.url; + } + + public static Builder builder() { + return new Builder(); + } + + public String name() { + return name; + } + + public String remark() { + return remark; + } + + public AttachmentType type() { + return type; + } + + public String url() { + return url; + } + + public static final class Builder { + private String name; + private String remark; + private AttachmentType type; + private String url; + + public Builder name(String v) { + this.name = v; + return this; + } + + public Builder remark(String v) { + this.remark = v; + return this; + } + + public Builder type(AttachmentType v) { + this.type = v; + return this; + } + + public Builder url(String v) { + this.url = v; + return this; + } + + public Attachment build() { + return new Attachment(this); + } + } + } + + public static final class Builder { + private String destructionNo; + private String warehouseId; + private int inventoryType; + private LocalDate hopeDestroyDate; + private String remark; + private final List{@link #destructionNo()} 是 OMS 下发单号,{@link #providerDestructionId()} 是仓侧 + * 计划单号。创建接口只回仓单号,没有状态——所以新建出来的单据 + * {@code status} 为 null,原值也为 null,不代表「已执行」。
+ */ public final class DestructionOrder { private final String destructionNo; private final String providerDestructionId; private final String warehouseCode; + /** 单据状态;创建接口不回传,查询接口接入后才会有值。 */ private final String status; + /** 仓方状态原值;必须与 {@link #sourceProvider()} 一起落库才有意义。 */ private final String rawStatus; + /** 该单据来自哪家仓;用于解释 {@link #rawStatus()}。 */ + private final WarehouseProvider sourceProvider; private DestructionOrder(Builder b) { if (b.destructionNo == null || b.destructionNo.trim().isEmpty()) { @@ -18,6 +30,7 @@ public final class DestructionOrder { this.warehouseCode = b.warehouseCode; this.status = b.status; this.rawStatus = b.rawStatus; + this.sourceProvider = b.sourceProvider; } public static Builder builder() { @@ -44,12 +57,18 @@ public final class DestructionOrder { return rawStatus; } + /** 该单据来自哪家仓。 */ + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + public static final class Builder { private String destructionNo; private String providerDestructionId; private String warehouseCode; private String status; private String rawStatus; + private WarehouseProvider sourceProvider; public Builder destructionNo(String v) { this.destructionNo = v; @@ -76,6 +95,11 @@ public final class DestructionOrder { return this; } + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + public DestructionOrder build() { return new DestructionOrder(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index d60cd51..17466ab 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -26,6 +26,7 @@ import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.capability.TransferCapable; +import common.ecommerce.warehouse.model.DestructionCommand; import common.ecommerce.warehouse.model.DestructionOrder; import common.ecommerce.warehouse.model.InboundCommand; import common.ecommerce.warehouse.model.InboundOrder; @@ -178,13 +179,43 @@ public final class WarehouseOperations { return new FeeView(); } - /** 销毁。 */ - public DestructionOrder createDestruction(String destructionNo, String warehouseId, String skus) { + /** + * 创建销毁计划。写操作:强制经幂等守卫,幂等键 + * {@code warehouseCode + destructionNo + create}。 + * + *销毁会减少库存,重复下发等于报废两次,所以不提供「无幂等」的降级路径。
+ */ + public DestructionOrder createDestruction(final DestructionCommand cmd) { + require(WarehouseCapability.DESTRUCTION, DestructionCapable.class); + if (guard == null) { + throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); + } + final DestructionCapable capable = (DestructionCapable) adapter; + common.ecommerce.shared.idempotency.WriteResult文档响应示例是 {@code "code": 1},与仓接口的 {@code 200} 不同,因此单独定义。
+ *该接口在另一个主机(ship-api),文档响应示例里 {@code code} 是 {@code 1}, + * 但同站的其它接口都是 {@code 200},且该文档的示例值是自动生成的占位符 + * ({@code message: "example"}),不能据此断定。因此两者都按成功处理, + * 联调确认后再收紧为单一值。
*/ - public static final int TRACK_SUCCESS_CODE = 1; + public static final int[] TRACK_SUCCESS_CODES = {1, 200}; + + /** 轨迹接口某次返回的业务码是否按成功处理。 */ + public static boolean isTrackSuccess(int code) { + for (int ok : TRACK_SUCCESS_CODES) { + if (ok == code) { + return true; + } + } + return false; + } /** 结算明细(API 133):作业费 / 仓储费 / 增值服务费 / 尾程费。 */ public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail"; /** 订单测算 / 运费试算(API 121):发货前按包裹 + 地址 + 渠道询价。 */ 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 6f2f4a9..944a270 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 @@ -27,8 +27,11 @@ import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable; +import common.ecommerce.warehouse.capability.DestructionCapable; import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; +import common.ecommerce.warehouse.model.DestructionCommand; +import common.ecommerce.warehouse.model.DestructionOrder; import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.TrackingInfo; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; @@ -73,7 +76,7 @@ import java.util.Map; */ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable, - TransferCapable, WarehouseReturnCapable, TrackingCapable { + TransferCapable, WarehouseReturnCapable, TrackingCapable, DestructionCapable { /** 运去哪请求里的时间格式;待核对。 */ private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); @@ -113,7 +116,8 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl WarehouseCapability.TRANSFER, WarehouseCapability.RETURN, WarehouseCapability.RETURN_DISPOSITION, - WarehouseCapability.TRACKING); + WarehouseCapability.TRACKING, + WarehouseCapability.DESTRUCTION); } // ------------------------------------------------------------------ 商品 @@ -489,6 +493,31 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); } + // ------------------------------------------------------------------ 销毁 + + /** + * 创建销毁计划(API 88)。 + * + *响应只回 {@code destroyPlanOrderNo},没有状态。创建成功只代表申请已提交, + * 不代表仓方已执行销毁。
+ */ + @Override + public DestructionOrder create(WarehouseContext ctx, DestructionCommand cmd) { + String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId()); + YqnDtos.CreateDestroyPlanRequest body = + YqnDestructionMapper.toRequest(cmd, ctx.providerWarehouseId()); + String raw = execute(ctx, YqnConstants.PATH_DESTRUCTION_CREATE, body, + "warehouse.destruction.create"); + String providerNo = json.stringAt(raw, "data.destroyPlanOrderNo"); + return YqnDestructionMapper.toCreated(cmd, warehouseCode, providerNo); + } + + /** 销毁计划查询未接入:文档只给了创建(API 88)。 */ + @Override + public DestructionOrder getDestruction(WarehouseContext ctx, String destructionNo) { + throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.DESTRUCTION); + } + // ------------------------------------------------------------------ 物流轨迹 /** @@ -539,7 +568,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl } // 这个接口的成功码是 1,不是 200,不能用 YqnEnvelope int code = json.intAt(raw, "code", -1); - if (code != YqnConstants.TRACK_SUCCESS_CODE) { + if (!YqnConstants.isTrackSuccess(code)) { throw WarehouseException.builder() .message("yqn track failed: code=" + code + ", message=" + json.stringAt(raw, "message")) .operation("warehouse.track") diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnDestructionMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnDestructionMapper.java new file mode 100644 index 0000000..811169b --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnDestructionMapper.java @@ -0,0 +1,122 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.warehouse.enums.AttachmentType; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.DestructionCommand; +import common.ecommerce.warehouse.model.DestructionOrder; +import common.ecommerce.yqn.dto.YqnDtos; + +import java.time.LocalDate; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.List; + +/** + * 运去哪销毁计划报文映射(API 88)。 + */ +public final class YqnDestructionMapper { + + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + + private YqnDestructionMapper() { + } + + /** + * 统一命令 → 运去哪创建请求。 + * + * @param cmd 统一命令 + * @param defaultWarehouseCode 命令未指定仓时的回退仓 code + */ + public static YqnDtos.CreateDestroyPlanRequest toRequest(DestructionCommand cmd, + String defaultWarehouseCode) { + YqnDtos.CreateDestroyPlanRequest req = new YqnDtos.CreateDestroyPlanRequest(); + req.warehouseCode = hasText(cmd.warehouseId()) ? cmd.warehouseId() : defaultWarehouseCode; + if (!hasText(req.warehouseCode)) { + throw new IllegalArgumentException( + "yqn destruction needs a warehouseCode; none given and account has none"); + } + req.sourceNo = cmd.destructionNo(); + req.inventoryType = cmd.inventoryType(); + req.hopeDestroyData = formatDate(cmd.hopeDestroyDate()); + req.remark = cmd.remark(); + req.destroyPlanOrderItems = toItems(cmd.lines()); + req.orderAttaches = toAttaches(cmd.attachments()); + return req; + } + + private static List接口只回 {@code destroyPlanOrderNo},没有状态,所以 {@code status}/ + * {@code rawStatus} 留空——不要把它当成「已执行」。
+ */ + public static DestructionOrder toCreated(DestructionCommand cmd, String warehouseCode, + String providerDestroyPlanNo) { + return DestructionOrder.builder() + .destructionNo(cmd.destructionNo()) + .providerDestructionId(providerDestroyPlanNo) + .warehouseCode(warehouseCode) + .sourceProvider(WarehouseProvider.YQN) + .build(); + } + + static String formatDate(LocalDate date) { + return date == null ? null : DATE.format(date); + } + + private static boolean hasText(String v) { + return v != null && !v.trim().isEmpty(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java index c57335c..3fdc3fc 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java @@ -1022,4 +1022,47 @@ public final class YqnDtos { public String initialDeliveryAttempt; } } + + // ------------------------------------------------------------------ 销毁计划(API 88) + + /** 创建销毁计划请求(API 88 {@code /v1/destroyPlan/createDestroyPlan})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateDestroyPlanRequest { + + /** 销毁的仓库 code。 */ + public String warehouseCode; + /** 来源单号(OMS 销毁单号)。 */ + public String sourceNo; + /** 0 可售库存 / 1 不可售库存。 */ + public Integer inventoryType; + /** 期望销毁日期 {@code yyyy-MM-dd}(字段名是仓方的 {@code Data},不是笔误)。 */ + public String hopeDestroyData; + public String remark; + public List