Browse Source

feat(yqn): 按 API 88 对接创建销毁计划

销毁能力此前只有接口和端点常量,没有任何实现。补齐:

- DestructionCommand:单号 / 仓 / 库存类型 / 期望销毁日期 / 商品行 / 附件
- AttachmentType 底层枚举(面单 / 装箱单 / 提单 / 其他),仓方码由
  YqnDestructionMapper 映射为 0/1/2/3
- DestructionCapable.create 改收命令对象;门面改为经幂等守卫,
  幂等键 warehouseCode + destructionNo + create(销毁会减库存,重复下发等于报废两次)

三处接口特性和其它接口不同:

- 路径与旧常量不一致:/destroyplan/DestructionPlanCreate → 文档给出的
  /v1/destroyPlan/createDestroyPlan
- 期望日期字段名是 hopeDestroyData(Data 不是 Date),照原样发
- 响应只有 destroyPlanOrderNo,没有状态。所以新建单据的 status/rawStatus
  留空,Javadoc 明确写了「创建成功 ≠ 已执行销毁」

另修一处签名冲突:DestructionCapable.get(ctx, String) 与 OutboundCapable.get
擦除后同签名,改为 getDestruction。查询接口仓方未提供,显式抛不支持。

顺带修正上一提交的轨迹成功码判定:该文档示例是自动生成的占位符
(message:"example"),code=1 不可靠,且同站其它接口都是 200。
改为两者都接受,标注待联调核对;测试相应改成兼容 1/200、拒绝 500。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
9b8f1222b4
  1. 4
      README.md
  2. 23
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/DestructionCapable.java
  3. 46
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AttachmentType.java
  4. 237
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java
  5. 26
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java
  6. 39
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  7. 23
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  8. 35
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  9. 122
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnDestructionMapper.java
  10. 43
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  11. 166
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnDestructionTest.java
  12. 24
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java

4
README.md

@ -299,7 +299,7 @@ common.ecommerce @@ -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 @@ -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 /

23
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/DestructionCapable.java

@ -1,5 +1,6 @@ @@ -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; @@ -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);
/**
* 创建销毁计划。<b>写操作</b>,幂等键
* {@code warehouseCode + destructionNo + create}。
*
* <p>创建成功只代表「销毁申请已提交」,仓方是否执行、何时执行都不由本调用决定;
* 返回的 {@code status} 为 null,不要据此判断库存已扣减。</p>
*/
DestructionOrder create(WarehouseContext ctx, DestructionCommand cmd);
/** 查询销毁计划。 */
DestructionOrder get(WarehouseContext ctx, String destructionNo);
/**
* 查询销毁计划。
*
* <p>方法名带 {@code Destruction} 后缀:{@code OutboundCapable} 已有完全同签名的
* {@code get(ctx, …)},同一适配器实现两者时无法区分。</p>
*
* <p>仓方查询接口未接入时抛
* {@link common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException}。</p>
*/
DestructionOrder getDestruction(WarehouseContext ctx, String destructionNo);
}

46
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/AttachmentType.java

@ -0,0 +1,46 @@ @@ -0,0 +1,46 @@
package common.ecommerce.warehouse.enums;
/**
* 销毁单附件类型。
*
* <p>取值来自仓方协议的分类口径;core 只表达语义,仓方码值由适配器映射。</p>
*/
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;
}
}

237
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionCommand.java

@ -0,0 +1,237 @@ @@ -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;
/**
* 销毁计划创建命令。<b>写操作</b>,幂等键是 {@link #destructionNo()}。
*
* <p>单据创建只代表「销毁申请已提交」,最终是否执行以仓方实际操作为准——不要把
* 创建成功当成库存已扣减。</p>
*/
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<DestructionLine> lines;
private final List<Attachment> 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<DestructionLine>(b.lines));
this.attachments = Collections.unmodifiableList(new ArrayList<Attachment>(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<DestructionLine> lines() {
return lines;
}
public List<Attachment> 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;
}
}
/**
* 附件。
*
* <p>SDK 不落文件、不上传对象存储:{@link #url()} 由调用方提供,适配器原样下发。</p>
*/
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<DestructionLine> lines = new ArrayList<DestructionLine>();
private final List<Attachment> attachments = new ArrayList<Attachment>();
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);
}
}
}

26
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/DestructionOrder.java

@ -1,13 +1,25 @@ @@ -1,13 +1,25 @@
package common.ecommerce.warehouse.model;
/** 销毁/报废计划。仅运去哪有接口。 */
import common.ecommerce.warehouse.enums.WarehouseProvider;
/**
* 销毁/报废计划。仅运去哪有接口。
*
* <p>{@link #destructionNo()} 是 OMS 下发单号,{@link #providerDestructionId()} 是仓侧
* 计划单号。创建接口只回仓单号,没有状态——所以新建出来的单据
* {@code status} 为 null,原值也为 null,不代表「已执行」。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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);
}

39
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -26,6 +26,7 @@ import common.ecommerce.warehouse.model.ReturnProcessCommand; @@ -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 { @@ -178,13 +179,43 @@ public final class WarehouseOperations {
return new FeeView();
}
/** 销毁。 */
public DestructionOrder createDestruction(String destructionNo, String warehouseId, String skus) {
/**
* 创建销毁计划。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + destructionNo + create}。
*
* <p>销毁会减少库存,重复下发等于报废两次,所以不提供「无幂等」的降级路径。</p>
*/
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<DestructionOrder> 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));
}
/** 回调验签。 */

23
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -44,8 +44,8 @@ public final class YqnConstants { @@ -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 { @@ -60,11 +60,24 @@ public final class YqnConstants {
public static final String AUX_BASE_URL_PR = "https://pr-ship-api.yqn.com";
/**
* 轨迹接口的成功码。
* 轨迹接口的成功码——<b>待联调核对</b>。
*
* <p>文档响应示例是 {@code "code": 1},与仓接口的 {@code 200} 不同,因此单独定义。</p>
* <p>该接口在另一个主机(ship-api),文档响应示例里 {@code code} 是 {@code 1},
* 但同站的其它接口都是 {@code 200},且该文档的示例值是自动生成的占位符
* ({@code message: "example"}),不能据此断定。因此两者都按成功处理,
* 联调确认后再收紧为单一值。</p>
*/
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):发货前按包裹 + 地址 + 渠道询价。 */

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

@ -27,8 +27,11 @@ import common.ecommerce.warehouse.capability.WarehouseProduct; @@ -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; @@ -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 @@ -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 @@ -489,6 +493,31 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
}
// ------------------------------------------------------------------ 销毁
/**
* 创建销毁计划(API 88)。
*
* <p>响应只回 {@code destroyPlanOrderNo},没有状态。创建成功只代表申请已提交,
* 不代表仓方已执行销毁。</p>
*/
@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 @@ -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")

122
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnDestructionMapper.java

@ -0,0 +1,122 @@ @@ -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<YqnDtos.CreateDestroyPlanRequest.DestroyPlanItem> toItems(
List<DestructionCommand.DestructionLine> lines) {
List<YqnDtos.CreateDestroyPlanRequest.DestroyPlanItem> items =
new ArrayList<YqnDtos.CreateDestroyPlanRequest.DestroyPlanItem>(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<YqnDtos.CreateDestroyPlanRequest.DestroyPlanAttach> toAttaches(
List<DestructionCommand.Attachment> attachments) {
if (attachments == null || attachments.isEmpty()) {
return null;
}
List<YqnDtos.CreateDestroyPlanRequest.DestroyPlanAttach> out =
new ArrayList<YqnDtos.CreateDestroyPlanRequest.DestroyPlanAttach>(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);
}
}
/**
* 创建响应 → 统一销毁单。
*
* <p>接口只回 {@code destroyPlanOrderNo},没有状态,所以 {@code status}/
* {@code rawStatus} 留空——不要把它当成「已执行」。</p>
*/
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();
}
}

43
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -1022,4 +1022,47 @@ public final class YqnDtos { @@ -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<DestroyPlanItem> destroyPlanOrderItems;
public List<DestroyPlanAttach> 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;
}
}

166
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnDestructionTest.java

@ -0,0 +1,166 @@ @@ -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));
}
}

24
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java

@ -140,17 +140,33 @@ class YqnTrackingTest { @@ -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

Loading…
Cancel
Save