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 List lines; + private final List attachments; + + private DestructionCommand(Builder b) { + this.destructionNo = require(b.destructionNo, "destructionNo"); + this.warehouseId = b.warehouseId; + if (b.inventoryType != 0 && b.inventoryType != 1) { + throw new IllegalArgumentException("inventoryType must be 0 (sellable) or 1 (unsellable)"); + } + this.inventoryType = b.inventoryType; + if (b.hopeDestroyDate == null) { + throw new IllegalArgumentException("hopeDestroyDate is required"); + } + this.hopeDestroyDate = b.hopeDestroyDate; + this.remark = b.remark; + if (b.lines.isEmpty()) { + throw new IllegalArgumentException("lines must not be empty"); + } + this.lines = Collections.unmodifiableList(new ArrayList(b.lines)); + this.attachments = Collections.unmodifiableList(new ArrayList(b.attachments)); + } + + public static Builder builder() { + return new Builder(); + } + + /** OMS 销毁单号;同时作为仓方的来源单号与幂等键。 */ + public String destructionNo() { + return destructionNo; + } + + /** 销毁仓 code;null 时用账户配置的仓。 */ + public String warehouseId() { + return warehouseId; + } + + /** 库存类型:0 可售 / 1 不可售。 */ + public int inventoryType() { + return inventoryType; + } + + public LocalDate hopeDestroyDate() { + return hopeDestroyDate; + } + + public String remark() { + return remark; + } + + public List lines() { + return lines; + } + + public List attachments() { + return attachments; + } + + private static String require(String v, String name) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return v.trim(); + } + + /** 待销毁商品行。 */ + public static final class DestructionLine { + + private final String providerSku; + private final int planQuantity; + + public DestructionLine(String providerSku, int planQuantity) { + if (providerSku == null || providerSku.trim().isEmpty()) { + throw new IllegalArgumentException("providerSku must not be blank"); + } + if (planQuantity <= 0) { + throw new IllegalArgumentException("planQuantity must be positive"); + } + this.providerSku = providerSku.trim(); + this.planQuantity = planQuantity; + } + + public String providerSku() { + return providerSku; + } + + public int planQuantity() { + return planQuantity; + } + } + + /** + * 附件。 + * + *

SDK 不落文件、不上传对象存储:{@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 lines = new ArrayList(); + private final List attachments = new ArrayList(); + + public Builder destructionNo(String v) { + this.destructionNo = v; + return this; + } + + public Builder warehouseId(String v) { + this.warehouseId = v; + return this; + } + + public Builder inventoryType(int v) { + this.inventoryType = v; + return this; + } + + public Builder hopeDestroyDate(LocalDate v) { + this.hopeDestroyDate = v; + return this; + } + + public Builder remark(String v) { + this.remark = v; + return this; + } + + public Builder line(String providerSku, int planQuantity) { + this.lines.add(new DestructionLine(providerSku, planQuantity)); + return this; + } + + public Builder attachment(Attachment v) { + this.attachments.add(v); + return this; + } + + public DestructionCommand build() { + return new DestructionCommand(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java index 5db0d8b..1f82502 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java @@ -1,13 +1,25 @@ package common.ecommerce.warehouse.model; -/** 销毁/报废计划。仅运去哪有接口。 */ +import common.ecommerce.warehouse.enums.WarehouseProvider; + +/** + * 销毁/报废计划。仅运去哪有接口。 + * + *

{@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 result = + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + cmd.destructionNo(), "create"), + () -> capable.create(ctx, cmd), + order -> order.providerDestructionId()); + if (result.alreadyCompleted()) { + // 回放:本次没有提交销毁,只有上次记录的仓单号 + return DestructionOrder.builder() + .destructionNo(cmd.destructionNo()) + .providerDestructionId(result.resultRef()) + .warehouseCode(account.warehouseCode()) + .sourceProvider(provider) + .build(); + } + return result.value(); + } + + /** 查询销毁计划。 */ + public DestructionOrder getDestruction(String destructionNo) { require(WarehouseCapability.DESTRUCTION, DestructionCapable.class); - return CallSupport.observe(observer, ctx, "warehouse.destruction.create", + return CallSupport.observe(observer, ctx, "warehouse.destruction.get", CallSupport.params("destructionNo", destructionNo), r -> CallSupport.NO_COUNT, - () -> ((DestructionCapable) adapter).create(ctx, destructionNo, warehouseId, skus)); + () -> ((DestructionCapable) adapter).getDestruction(ctx, destructionNo)); } /** 回调验签。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index ac35a92..e4b7578 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -44,8 +44,8 @@ public final class YqnConstants { public static final String PATH_RETURN_CREATE = "/v3/saleReturn/createSaleReturnPlan"; /** 退货条目处理(API 77):按明细行设置检验后处理方式。 */ public static final String PATH_RETURN_PROCESS = "/v3/saleReturn/addProcessMode"; - /** 销毁计划。 */ - public static final String PATH_DESTRUCTION_CREATE = "/destroyplan/DestructionPlanCreate"; + /** 创建销毁计划(API 88)。 */ + public static final String PATH_DESTRUCTION_CREATE = "/v1/destroyPlan/createDestroyPlan"; /** * 物流轨迹(API 189):{@code GET /api/v2/orderShipment/track/{trackingNo}}。 * @@ -60,11 +60,24 @@ public final class YqnConstants { public static final String AUX_BASE_URL_PR = "https://pr-ship-api.yqn.com"; /** - * 轨迹接口的成功码。 + * 轨迹接口的成功码——待联调核对。 * - *

文档响应示例是 {@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 toItems( + List lines) { + List items = + new ArrayList(lines.size()); + for (DestructionCommand.DestructionLine line : lines) { + YqnDtos.CreateDestroyPlanRequest.DestroyPlanItem item = + new YqnDtos.CreateDestroyPlanRequest.DestroyPlanItem(); + item.sku = line.providerSku(); + item.planQty = line.planQuantity(); + items.add(item); + } + return items; + } + + private static List toAttaches( + List attachments) { + if (attachments == null || attachments.isEmpty()) { + return null; + } + List out = + new ArrayList(attachments.size()); + for (DestructionCommand.Attachment attachment : attachments) { + YqnDtos.CreateDestroyPlanRequest.DestroyPlanAttach item = + new YqnDtos.CreateDestroyPlanRequest.DestroyPlanAttach(); + item.name = attachment.name(); + item.remark = attachment.remark(); + item.attachType = attachTypeCode(attachment.type()); + item.url = attachment.url(); + out.add(item); + } + return out; + } + + /** 底层附件类型 → 运去哪 attachType:0 面单 / 1 装箱单 / 2 提单 / 3 其他;null 不传。 */ + static Integer attachTypeCode(AttachmentType type) { + if (type == null) { + return null; + } + switch (type) { + case SHIPPING_LABEL: + return 0; + case PACKING_LIST: + return 1; + case BOL: + return 2; + case OTHER: + return 3; + default: + throw new IllegalArgumentException("yqn does not support attachType: " + type); + } + } + + /** + * 创建响应 → 统一销毁单。 + * + *

接口只回 {@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 destroyPlanOrderItems; + public List orderAttaches; + + /** 待销毁商品行。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class DestroyPlanItem { + public String sku; + public Integer planQty; + } + + /** 附件。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class DestroyPlanAttach { + public String name; + public String remark; + /** 0 面单 / 1 装箱单 / 2 提单 / 3 其他。 */ + public Integer attachType; + public String url; + } + } + + /** 创建销毁计划响应(API 88 {@code data})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateDestroyPlanResponse { + /** 仓侧销毁计划单号。 */ + public String destroyPlanOrderNo; + } } diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnDestructionTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnDestructionTest.java new file mode 100644 index 0000000..23b79b4 --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnDestructionTest.java @@ -0,0 +1,166 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.AttachmentType; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.DestructionCommand; +import common.ecommerce.warehouse.model.DestructionOrder; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.yqn.YqnConstants; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.LocalDate; +import java.time.ZoneOffset; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 创建销毁计划(API 88)契约测试。 + */ +class YqnDestructionTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC); + + private static WarehouseContext ctx() { + return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", + WarehouseConnection.of(YqnConstants.PR_BASE_URL, + ChannelSecret.builder().appSecret("key-1").build()), + "req-destroy", CLOCK); + } + + private static DestructionCommand command() { + return DestructionCommand.builder() + .destructionNo("DEST-001") + .inventoryType(1) + .hopeDestroyDate(LocalDate.of(2026, 11, 20)) + .remark("破损库存") + .line("DM00001", 3) + .line("DM00002", 1) + .attachment(DestructionCommand.Attachment.builder() + .name("销毁凭证.pdf") + .remark("客户签字") + .type(AttachmentType.OTHER) + .url("https://files.example/a.pdf") + .build()) + .build(); + } + + @Test + void sendsDocumentedShape() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_DESTRUCTION_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\"," + + "\"data\":{\"destroyPlanOrderNo\":\"DP123\"}}")); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + DestructionOrder order = adapter.create(ctx(), command()); + + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"warehouseCode\":\"RF_NY_US\""), body); + assertTrue(body.contains("\"sourceNo\":\"DEST-001\""), body); + assertTrue(body.contains("\"inventoryType\":1"), body); + // 字段名是仓方的 hopeDestroyData(不是 Date) + assertTrue(body.contains("\"hopeDestroyData\":\"2026-11-20\""), body); + assertTrue(body.contains("\"sku\":\"DM00001\""), body); + assertTrue(body.contains("\"planQty\":3"), body); + assertTrue(body.contains("\"attachType\":3"), body); + assertTrue(body.contains("\"url\":\"https://files.example/a.pdf\""), body); + + assertEquals("DEST-001", order.destructionNo()); + assertEquals("DP123", order.providerDestructionId()); + assertEquals("RF_NY_US", order.warehouseCode()); + assertEquals(WarehouseProvider.YQN, order.sourceProvider()); + } + + /** 创建响应只有单号、没有状态,不能把它当成「已执行」。 */ + @Test + void createdOrderHasNoStatus() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_DESTRUCTION_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"destroyPlanOrderNo\":\"DP9\"}}")); + DestructionOrder order = new YqnAdapter(transport, new JacksonJsonCodec()) + .create(ctx(), command()); + + assertNull(order.status()); + assertNull(order.rawStatus()); + } + + @Test + void omitsAttachesWhenNoneGiven() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_DESTRUCTION_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{}}")); + DestructionCommand noAttach = DestructionCommand.builder() + .destructionNo("DEST-002") + .inventoryType(0) + .hopeDestroyDate(LocalDate.of(2026, 12, 1)) + .line("DM00001", 1) + .build(); + new YqnAdapter(transport, new JacksonJsonCodec()).create(ctx(), noAttach); + + assertFalse(transport.lastDataRequest().body().contains("orderAttaches")); + } + + @Test + void commandWarehouseOverridesAccount() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_DESTRUCTION_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{}}")); + DestructionCommand other = DestructionCommand.builder() + .destructionNo("DEST-003") + .warehouseId("RF_LA_US") + .inventoryType(1) + .hopeDestroyDate(LocalDate.of(2026, 12, 1)) + .line("DM00001", 1) + .build(); + new YqnAdapter(transport, new JacksonJsonCodec()).create(ctx(), other); + + assertTrue(transport.lastDataRequest().body().contains("\"warehouseCode\":\"RF_LA_US\"")); + } + + @Test + void queryIsExplicitlyUnsupported() { + YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + assertThrows(common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException.class, + () -> adapter.getDestruction(ctx(), "DEST-001")); + } + + @Test + void declaresDestructionCapability() { + YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); + assertTrue(adapter.capabilities().contains(WarehouseCapability.DESTRUCTION)); + } + + @Test + void commandValidation() { + assertThrows(IllegalArgumentException.class, () -> DestructionCommand.builder() + .destructionNo("D").inventoryType(2) + .hopeDestroyDate(LocalDate.now()).line("S", 1).build()); + assertThrows(IllegalArgumentException.class, () -> DestructionCommand.builder() + .destructionNo("D").inventoryType(1) + .hopeDestroyDate(LocalDate.now()).build()); + assertThrows(IllegalArgumentException.class, () -> DestructionCommand.builder() + .destructionNo("D").inventoryType(1) + .hopeDestroyDate(LocalDate.now()).line("S", 0).build()); + } + + @Test + void attachTypeCodesMatchDocument() { + assertEquals(Integer.valueOf(0), YqnDestructionMapper.attachTypeCode(AttachmentType.SHIPPING_LABEL)); + assertEquals(Integer.valueOf(1), YqnDestructionMapper.attachTypeCode(AttachmentType.PACKING_LIST)); + assertEquals(Integer.valueOf(2), YqnDestructionMapper.attachTypeCode(AttachmentType.BOL)); + assertEquals(Integer.valueOf(3), YqnDestructionMapper.attachTypeCode(AttachmentType.OTHER)); + assertNull(YqnDestructionMapper.attachTypeCode(null)); + } +} diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java index 9b1d257..6bd68b7 100644 --- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java @@ -140,17 +140,33 @@ class YqnTrackingTest { assertEquals("IN_TRANSIT", events.get(0).status()); } - /** 成功码是 1;返回 200 之类要按失败处理,不能当成成功去解析 data。 */ + /** + * 成功码兼容 1 与 200:文档示例是 1,但同站其它接口是 200,示例值又是自动生成的 + * 占位符,两种都接受;真失败码必须拒绝。 + */ @Test - void nonOneCodeIsFailure() { + void acceptsBothOneAndTwoHundred() { + for (String code : new String[] {"1", "200"}) { + RecordingTransport transport = RecordingTransport.create() + .route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok( + "{\"code\":" + code + ",\"message\":\"ok\"," + + "\"data\":{\"trackingCode\":\"TRK123\",\"carrier\":\"FEDEX\"}}")); + TrackingInfo info = new YqnAdapter(transport, new JacksonJsonCodec()) + .trackShipment(ctx(), "TRK123"); + assertEquals("TRK123", info.trackingNumber()); + } + } + + @Test + void failedCodeIsRejected() { RecordingTransport transport = RecordingTransport.create() .route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok( - "{\"code\":200,\"message\":\"ok\",\"data\":{\"trackingCode\":\"TRK123\"}}")); + "{\"code\":500,\"message\":\"boom\",\"data\":{}}")); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); RuntimeException ex = assertThrows(RuntimeException.class, () -> adapter.trackShipment(ctx(), "TRK123")); - assertTrue(ex.getMessage().contains("code=200"), ex.getMessage()); + assertTrue(ex.getMessage().contains("code=500"), ex.getMessage()); } @Test