From ca6d00ba18b47d595ac6f8c74e8269c1b09cdcb5 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Tue, 10 Nov 2026 13:55:48 +0800 Subject: [PATCH] =?UTF-8?q?fix(xincang):=20=E8=A1=A5=E9=BD=90=E4=B8=8B?= =?UTF-8?q?=E5=8D=95=E4=B8=8E=E8=BD=AC=E8=BF=90=E7=BC=BA=E5=A4=B1=E7=9A=84?= =?UTF-8?q?=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 上一版按文档只实现了部分字段,这次对齐到 schema 全量: 一单多件 api.add_order_multiple: - 补 gzh(trackingNumber)/ face_base64(labelContentBase64)/ shop_name / sfp;order_type=wayfair 时前两者必填,缺失在下单前拦下, 不再等仓返回看不懂的错误 - 移除 remark:该接口 schema 没有这个字段,之前是多发的 新增转运 fba.do_fba: - 补 4 个单附件(product_label_att / ctn_label_att / express_label_att / pallet_label_att)、2 个数组附件(other_att / bol_att)、 express_print_copies - products 明细补 fn_sku / ctn_sku / remark 模型配套: - OutboundCommand 增加 trackingNumber / labelContentBase64 / shopName / sfp - TransferCommand 增加 6 个附件字段与快递份数;TransferLine 增加三方 SKU、 箱标 SKU 与备注(保留原两参构造,YQN 不受影响) - 新增 TransferAttachment 承载 upload.files 返回的附件元数据, SDK 只搬运、不下载不落盘 字段覆盖已与文档逐项核对:两个接口均无缺、无多。 Co-Authored-By: Claude Code --- .../ecommerce/warehouse/model/OutboundCommand.java | 75 +++++++++++ .../warehouse/model/TransferAttachment.java | 122 +++++++++++++++++ .../ecommerce/warehouse/model/TransferCommand.java | 149 +++++++++++++++++++++ .../xincang/adapter/XincangOrderMapper.java | 24 +++- .../xincang/adapter/XincangTransferMapper.java | 41 ++++++ .../common/ecommerce/xincang/dto/XincangDtos.java | 117 +++++++++++++++- .../xincang/adapter/XincangOrderTest.java | 50 +++++++ .../xincang/adapter/XincangTransferTest.java | 50 +++++++ 8 files changed, 618 insertions(+), 10 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferAttachment.java diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java index 2f931de..6f5f175 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java @@ -45,6 +45,25 @@ public final class OutboundCommand { * 信仓 {@code is_split}:true 拆成一单一品(每件一张面单),false 打包成一张面单。

*/ private final Boolean splitOrder; + /** + * 平台/渠道侧的运单跟踪号。 + * + *

仅在「调用方自供面单」的仓上使用(信仓 {@code gzh}:{@code order_type=wayfair} 时必填)。 + * 仓自己出单时该字段为 null,运单号由仓在出库后回传。

+ */ + private final String trackingNumber; + /** + * 调用方自供的面单文件内容(base64,可带 data URI 头)。 + * + *

与 {@link LabelMode#PLATFORM_LABEL} 配套:渠道域先取平台面单, + * 这里把文件内容随单下发给仓打印贴标(信仓 {@code face_base64})。 + * 仓自己出单时为 null。

+ */ + private final String labelContentBase64; + /** 店铺名称;仓方按店铺做路由 / 计费时使用,null 表示用仓方默认。 */ + private final String shopName; + /** 是否 SFP(Seller Fulfilled Prime);null 表示不传,由仓按默认否处理。 */ + private final Boolean sfp; private OutboundCommand(Builder b) { if (b.outboundRequestNo == null || b.outboundRequestNo.trim().isEmpty()) { @@ -71,6 +90,10 @@ public final class OutboundCommand { this.estimatedDeliveryTime = b.estimatedDeliveryTime; this.currency = b.currency; this.splitOrder = b.splitOrder; + this.trackingNumber = b.trackingNumber; + this.labelContentBase64 = b.labelContentBase64; + this.shopName = b.shopName; + this.sfp = b.sfp; } public static Builder builder() { @@ -162,6 +185,26 @@ public final class OutboundCommand { return splitOrder; } + /** 调用方自供的运单跟踪号;仓自己出单时为 null。 */ + public String trackingNumber() { + return trackingNumber; + } + + /** 调用方自供的面单文件内容(base64);仓自己出单时为 null。 */ + public String labelContentBase64() { + return labelContentBase64; + } + + /** 店铺名称;null 表示用仓方默认。 */ + public String shopName() { + return shopName; + } + + /** 是否 SFP;null 表示不传。 */ + public Boolean sfp() { + return sfp; + } + public static final class Builder { private String outboundRequestNo; @@ -181,6 +224,10 @@ public final class OutboundCommand { private Instant estimatedDeliveryTime; private String currency; private Boolean splitOrder; + private String trackingNumber; + private String labelContentBase64; + private String shopName; + private Boolean sfp; public Builder outboundRequestNo(String outboundRequestNo) { this.outboundRequestNo = outboundRequestNo; @@ -276,6 +323,34 @@ public final class OutboundCommand { return this; } + /** 调用方自供的运单跟踪号(信仓 {@code gzh})。 */ + public Builder trackingNumber(String trackingNumber) { + this.trackingNumber = trackingNumber; + return this; + } + + /** + * 调用方自供的面单内容(base64,可带 data URI 头)。 + * + *

与 {@link LabelMode#PLATFORM_LABEL} 配套使用。

+ */ + public Builder labelContentBase64(String labelContentBase64) { + this.labelContentBase64 = labelContentBase64; + return this; + } + + /** 店铺名称;null 表示用仓方默认。 */ + public Builder shopName(String shopName) { + this.shopName = shopName; + return this; + } + + /** 是否 SFP;null 表示不传。 */ + public Builder sfp(Boolean sfp) { + this.sfp = sfp; + return this; + } + public OutboundCommand build() { return new OutboundCommand(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferAttachment.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferAttachment.java new file mode 100644 index 0000000..02b8b94 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferAttachment.java @@ -0,0 +1,122 @@ +package common.ecommerce.warehouse.model; + +import java.util.Objects; + +/** + * 仓方文件上传后的附件元数据。 + * + *

信仓的转运 / 订单附件要求先用 {@code upload.files} 上传,再把返回的对象原样放进 + * 对应字段({@code product_label_att} 等)。SDK 不下载、不解析、不落盘, + * 只做字段搬运。

+ */ +public final class TransferAttachment { + + /** 存储类型,如 {@code aliyun_oss}。 */ + private final String type; + /** bucket 名。 */ + private final String bucket; + /** 对象键。 */ + private final String fileName; + /** 可访问 URL。 */ + private final String fileUrl; + /** 文件类型(如 pdf / png);部分仓必填。 */ + private final String fileType; + /** 原始文件名。 */ + private final String name; + + private TransferAttachment(Builder b) { + this.type = b.type; + this.bucket = b.bucket; + this.fileName = require(b.fileName, "fileName"); + this.fileUrl = b.fileUrl; + this.fileType = b.fileType; + this.name = b.name; + } + + public static Builder builder() { + return new Builder(); + } + + /** 存储类型;可能为 null。 */ + public String type() { + return type; + } + + /** bucket 名;可能为 null。 */ + public String bucket() { + return bucket; + } + + /** 对象键;必填。 */ + public String fileName() { + return fileName; + } + + /** 可访问 URL;可能为 null。 */ + public String fileUrl() { + return fileUrl; + } + + /** 文件类型;可能为 null。 */ + public String fileType() { + return fileType; + } + + /** 原始文件名;可能为 null。 */ + public String name() { + return name; + } + + private static String require(String v, String n) { + Objects.requireNonNull(v, n); + if (v.trim().isEmpty()) { + throw new IllegalArgumentException(n + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + + private String type; + private String bucket; + private String fileName; + private String fileUrl; + private String fileType; + private String name; + + public Builder type(String v) { + this.type = v; + return this; + } + + public Builder bucket(String v) { + this.bucket = v; + return this; + } + + /** 对象键;必填。 */ + public Builder fileName(String v) { + this.fileName = v; + return this; + } + + public Builder fileUrl(String v) { + this.fileUrl = v; + return this; + } + + public Builder fileType(String v) { + this.fileType = v; + return this; + } + + public Builder name(String v) { + this.name = v; + return this; + } + + public TransferAttachment build() { + return new TransferAttachment(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java index cfbe34a..3008c6c 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java @@ -65,6 +65,23 @@ public final class TransferCommand { /** 目的仓不在仓方字典时的自填仓库名;null 表示不传。 */ private final String otherWarehouseName; + /** + * 各类附件(文件上传后的 OSS 元数据)。 + * + *

信仓要求附件先用 {@code upload.files} 上传,再把返回的 {@code data.data} + * 原样放进对应字段。SDK 不落文件、不访问对象存储,这里只承载宿主拿到的元数据。

+ */ + private final TransferAttachment productLabelAttachment; + private final TransferAttachment cartonLabelAttachment; + private final TransferAttachment expressLabelAttachment; + private final TransferAttachment palletLabelAttachment; + /** 其他附件;空列表表示不传。 */ + private final java.util.List otherAttachments; + /** BOL 附件;空列表表示不传。 */ + private final java.util.List bolAttachments; + /** 快递面单打印份数;null 表示不传。 */ + private final Integer expressLabelCopies; + private TransferCommand(Builder b) { if (b.transferRequestNo == null || b.transferRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("transferRequestNo must not be blank"); @@ -127,6 +144,15 @@ public final class TransferCommand { this.deliveryMode = b.deliveryMode; this.deliveryWay = b.deliveryWay; this.otherWarehouseName = b.otherWarehouseName; + this.productLabelAttachment = b.productLabelAttachment; + this.cartonLabelAttachment = b.cartonLabelAttachment; + this.expressLabelAttachment = b.expressLabelAttachment; + this.palletLabelAttachment = b.palletLabelAttachment; + this.otherAttachments = java.util.Collections.unmodifiableList( + new java.util.ArrayList(b.otherAttachments)); + this.bolAttachments = java.util.Collections.unmodifiableList( + new java.util.ArrayList(b.bolAttachments)); + this.expressLabelCopies = b.expressLabelCopies; } public static Builder builder() { @@ -260,6 +286,41 @@ public final class TransferCommand { return otherWarehouseName; } + /** 产品贴附件;null 表示不传。 */ + public TransferAttachment productLabelAttachment() { + return productLabelAttachment; + } + + /** 外箱贴附件;null 表示不传。 */ + public TransferAttachment cartonLabelAttachment() { + return cartonLabelAttachment; + } + + /** 快递面单附件;null 表示不传。 */ + public TransferAttachment expressLabelAttachment() { + return expressLabelAttachment; + } + + /** 托盘贴附件;null 表示不传。 */ + public TransferAttachment palletLabelAttachment() { + return palletLabelAttachment; + } + + /** 其他附件;空列表表示不传。 */ + public java.util.List otherAttachments() { + return otherAttachments; + } + + /** BOL 附件;空列表表示不传。 */ + public java.util.List bolAttachments() { + return bolAttachments; + } + + /** 快递面单打印份数;null 表示不传。 */ + public Integer expressLabelCopies() { + return expressLabelCopies; + } + public java.util.List batches() { return batches; } @@ -276,8 +337,20 @@ public final class TransferCommand { private final String providerSku; private final int quantity; + /** 三方 SKU(信仓 {@code fn_sku});可选。 */ + private final String fulfillmentSku; + /** 箱标 SKU(信仓 {@code ctn_sku});可选。 */ + private final String cartonSku; + private final String remark; + /** 只给 SKU 与数量。 */ public TransferLine(String providerSku, int quantity) { + this(providerSku, quantity, null, null, null); + } + + /** 完整构造:含三方 SKU、箱标 SKU 与备注。 */ + public TransferLine(String providerSku, int quantity, String fulfillmentSku, + String cartonSku, String remark) { if (providerSku == null || providerSku.trim().isEmpty()) { throw new IllegalArgumentException("providerSku must not be blank"); } @@ -286,6 +359,9 @@ public final class TransferCommand { } this.providerSku = providerSku.trim(); this.quantity = quantity; + this.fulfillmentSku = fulfillmentSku; + this.cartonSku = cartonSku; + this.remark = remark; } public String providerSku() { @@ -295,6 +371,21 @@ public final class TransferCommand { public int quantity() { return quantity; } + + /** 三方 SKU;可选。 */ + public String fulfillmentSku() { + return fulfillmentSku; + } + + /** 箱标 SKU;可选。 */ + public String cartonSku() { + return cartonSku; + } + + /** 行备注;可选。 */ + public String remark() { + return remark; + } } public static final class Builder { @@ -329,6 +420,15 @@ public final class TransferCommand { private String deliveryMode; private String deliveryWay; private String otherWarehouseName; + private TransferAttachment productLabelAttachment; + private TransferAttachment cartonLabelAttachment; + private TransferAttachment expressLabelAttachment; + private TransferAttachment palletLabelAttachment; + private final java.util.List otherAttachments = + new java.util.ArrayList(); + private final java.util.List bolAttachments = + new java.util.ArrayList(); + private Integer expressLabelCopies; public Builder transferRequestNo(String v) { this.transferRequestNo = v; @@ -424,6 +524,13 @@ public final class TransferCommand { return this; } + /** 带三方 SKU / 箱标 SKU / 备注的商品行。 */ + public Builder line(String providerSku, int quantity, String fulfillmentSku, + String cartonSku, String remark) { + this.lines.add(new TransferLine(providerSku, quantity, fulfillmentSku, cartonSku, remark)); + return this; + } + /** 标签 150 采集 SN / 160 后置提供 BOL。 */ public Builder tag(int code) { this.tags.add(code); @@ -495,6 +602,48 @@ public final class TransferCommand { return this; } + /** 产品贴附件。 */ + public Builder productLabelAttachment(TransferAttachment v) { + this.productLabelAttachment = v; + return this; + } + + /** 外箱贴附件。 */ + public Builder cartonLabelAttachment(TransferAttachment v) { + this.cartonLabelAttachment = v; + return this; + } + + /** 快递面单附件。 */ + public Builder expressLabelAttachment(TransferAttachment v) { + this.expressLabelAttachment = v; + return this; + } + + /** 托盘贴附件。 */ + public Builder palletLabelAttachment(TransferAttachment v) { + this.palletLabelAttachment = v; + return this; + } + + /** 追加一个其他附件。 */ + public Builder otherAttachment(TransferAttachment v) { + this.otherAttachments.add(v); + return this; + } + + /** 追加一个 BOL 附件。 */ + public Builder bolAttachment(TransferAttachment v) { + this.bolAttachments.add(v); + return this; + } + + /** 快递面单打印份数;null 表示不传。 */ + public Builder expressLabelCopies(Integer v) { + this.expressLabelCopies = v; + return this; + } + public TransferCommand build() { return new TransferCommand(this); } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java index 2e1edf0..6e22415 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java @@ -39,8 +39,11 @@ public final class XincangOrderMapper { /** 订单类型:信仓只接受 common / wayfair。 */ static final String ORDER_TYPE_COMMON = "common"; static final String ORDER_TYPE_WAYFAIR = "wayfair"; - /** 签名服务:信仓只收「是 / 否」,模型里没有该字段,默认否。 */ - private static final String SIGN_NOT_REQUIRED = "否"; + /** 信仓布尔字段统一用「是 / 否」。 */ + private static final String YES = "是"; + private static final String NO = "否"; + /** 签名服务:模型无对应字段,固定否。 */ + private static final String SIGN_NOT_REQUIRED = NO; private XincangOrderMapper() { } @@ -69,7 +72,8 @@ public final class XincangOrderMapper { requireText(cmd.carrierCode(), "carrierCode (信仓 logistics_type)", ctx); Map form = new LinkedHashMap(); - form.put("order_type", orderTypeOf(cmd.salesPlatform())); + String orderType = orderTypeOf(cmd.salesPlatform()); + form.put("order_type", orderType); form.put("warehouse_code", warehouseCode); // ckh = 参考号,信仓要求唯一;用 OMS 出库单号,便于回查 form.put("ckh", cmd.outboundRequestNo()); @@ -87,6 +91,18 @@ public final class XincangOrderMapper { form.put("logistics_type", cmd.carrierCode().trim()); form.put("is_sign", SIGN_NOT_REQUIRED); form.put("products", productsJson(cmd.lines(), json)); + putIfPresent(form, "shop_name", cmd.shopName()); + if (cmd.sfp() != null) { + form.put("sfp", cmd.sfp() ? YES : NO); + } + + // wayfair(自供面单)时 gzh + face_base64 都是必填,缺了必然被仓拒绝,这里提前挡 + if (ORDER_TYPE_WAYFAIR.equals(orderType)) { + requireText(cmd.trackingNumber(), "trackingNumber (信仓 gzh,wayfair 必填)", ctx); + requireText(cmd.labelContentBase64(), "labelContentBase64 (信仓 face_base64,wayfair 必填)", ctx); + } + putIfPresent(form, "gzh", cmd.trackingNumber()); + putIfPresent(form, "face_base64", cmd.labelContentBase64()); // 不传 is_split 时信仓默认 1(拆单);只有调用方显式给值才下发 if (cmd.splitOrder() != null) { @@ -97,7 +113,7 @@ public final class XincangOrderMapper { form.put("required_delivery_time", REQUIRED_DELIVERY_TIME.format( LocalDateTime.ofInstant(latest, XincangConstants.SYSTEM_ZONE))); } - putIfPresent(form, "remark", cmd.remark()); + // 该接口的 schema 没有 remark,不发 return form; } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java index 6c3e4e9..dbe39c4 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java @@ -3,6 +3,7 @@ package common.ecommerce.xincang.adapter; import common.ecommerce.shared.error.ChannelException; import common.ecommerce.shared.error.ValidationException; import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.model.TransferAttachment; import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.TransferStatus; @@ -67,10 +68,47 @@ public final class XincangTransferMapper { req.remark = blankToNull(cmd.remark()); req.productPrintCopies = copies(cmd.productLabelCopies()); req.ctnPrintCopies = copies(cmd.cartonLabelCopies()); + req.expressPrintCopies = copies(cmd.expressLabelCopies()); req.palletPrintCopies = copies(cmd.palletLabelCopies()); + req.productLabelAtt = attachment(cmd.productLabelAttachment()); + req.ctnLabelAtt = attachment(cmd.cartonLabelAttachment()); + req.expressLabelAtt = attachment(cmd.expressLabelAttachment()); + req.palletLabelAtt = attachment(cmd.palletLabelAttachment()); + req.otherAtt = attachments(cmd.otherAttachments()); + req.bolAtt = attachments(cmd.bolAttachments()); return req; } + /** 统一附件 → 信仓附件报文;null 透传(不发)。 */ + private static XincangDtos.Attachment attachment(TransferAttachment source) { + if (source == null) { + return null; + } + XincangDtos.Attachment target = new XincangDtos.Attachment(); + target.type = source.type(); + target.bucket = source.bucket(); + target.fileName = source.fileName(); + target.fileUrl = source.fileUrl(); + target.fileType = source.fileType(); + target.name = source.name(); + return target; + } + + /** 附件列表;空列表返回 null(不发空数组)。 */ + private static List attachments(List sources) { + if (sources == null || sources.isEmpty()) { + return null; + } + List out = new ArrayList(sources.size()); + for (TransferAttachment source : sources) { + XincangDtos.Attachment target = attachment(source); + if (target != null) { + out.add(target); + } + } + return out.isEmpty() ? null : out; + } + /** 转运单创建结果 → 统一模型;信仓只回 {@code order_no},其余字段留空。 */ public static TransferOrder toCreated(TransferCommand cmd, String providerTransferNo) { return TransferOrder.builder() @@ -93,6 +131,9 @@ public final class XincangTransferMapper { XincangDtos.TransferProduct product = new XincangDtos.TransferProduct(); product.productNo = line.providerSku(); product.skuCount = String.valueOf(line.quantity()); + product.fnSku = blankToNull(line.fulfillmentSku()); + product.ctnSku = blankToNull(line.cartonSku()); + product.remark = blankToNull(line.remark()); products.add(product); } return products; diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java index 5cd7db0..48f5856 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java @@ -5,6 +5,7 @@ import com.fasterxml.jackson.annotation.JsonInclude; import com.fasterxml.jackson.annotation.JsonProperty; import java.math.BigDecimal; +import java.util.List; /** * 信仓报文结构。 @@ -216,7 +217,7 @@ public final class XincangDtos { * 新增转运请求({@code POST fba.do_fba})。 * *

附件字段(产品贴 / 外箱贴 / 托盘贴 / BOL)要求先用 {@code upload.files} 上传, - * 再把它返回的 {@code data.data} 对象原样放进来;统一模型不承载附件,本轮不发送。

+ * 再把返回的 {@code data.data} 对象原样放进来;SDK 只做字段搬运。

*/ @JsonInclude(JsonInclude.Include.NON_NULL) public static final class TransferRequest { @@ -261,6 +262,10 @@ public final class XincangDtos { @JsonProperty("label_requirement") public String labelRequirement; + /** 备注。 */ + @JsonProperty("remark") + public String remark; + /** 是否需要打托:{@code 是} / {@code 否}。 */ @JsonProperty("is_pallet") public String isPallet; @@ -269,10 +274,6 @@ public final class XincangDtos { @JsonProperty("products") public String products; - /** 备注。 */ - @JsonProperty("remark") - public String remark; - /** 产品贴打印份数。 */ @JsonProperty("product_print_copies") public String productPrintCopies; @@ -281,12 +282,40 @@ public final class XincangDtos { @JsonProperty("ctn_print_copies") public String ctnPrintCopies; + /** 快递面单打印份数。 */ + @JsonProperty("express_print_copies") + public String expressPrintCopies; + /** 托盘贴打印份数。 */ @JsonProperty("pallet_print_copies") public String palletPrintCopies; + + /** 产品贴附件;{@code label_requirement} 含「产品贴」时必传。 */ + @JsonProperty("product_label_att") + public Attachment productLabelAtt; + + /** 外箱贴附件;{@code label_requirement} 含「外箱标签」时必传。 */ + @JsonProperty("ctn_label_att") + public Attachment ctnLabelAtt; + + /** 快递面单附件;{@code delivery_way} 为快递发货类型时必传。 */ + @JsonProperty("express_label_att") + public Attachment expressLabelAtt; + + /** 托盘贴附件;卡车 + 打托 + 含「托盘标签」三条件同时满足时必传。 */ + @JsonProperty("pallet_label_att") + public Attachment palletLabelAtt; + + /** 其他附件(数组)。 */ + @JsonProperty("other_att") + public List otherAtt; + + /** BOL 附件(数组)。 */ + @JsonProperty("bol_att") + public List bolAtt; } - /** 新增转运请求里的产品明细(序列化进 {@code products} 字符串)。 */ + /** 转运请求里的产品明细(序列化进 {@code products} 字符串)。 */ @JsonInclude(JsonInclude.Include.NON_NULL) public static final class TransferProduct { @@ -298,11 +327,87 @@ public final class XincangDtos { @JsonProperty("sku_count") public String skuCount; + /** 三方 SKU(可选)。 */ + @JsonProperty("fn_sku") + public String fnSku; + + /** 箱标 SKU(可选)。 */ + @JsonProperty("ctn_sku") + public String ctnSku; + /** 备注。 */ @JsonProperty("remark") public String remark; } + /** + * 附件元数据({@code upload.files} 返回的 {@code data.data} 原样回传)。 + * + *

字段名与上传接口返回保持一致,包括 {@code file_url} 与 {@code fileType} 的 + * 大小写差异——信仓文档里就是这么写的。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class Attachment { + + /** 存储类型,如 {@code aliyun_oss}。 */ + @JsonProperty("type") + public String type; + + /** bucket 名。 */ + @JsonProperty("bucket") + public String bucket; + + /** 对象键。 */ + @JsonProperty("file_name") + public String fileName; + + /** 可访问 URL。 */ + @JsonProperty("file_url") + public String fileUrl; + + /** 文件类型(信仓原文是 camelCase)。 */ + @JsonProperty("fileType") + public String fileType; + + /** 原始文件名。 */ + @JsonProperty("name") + public String name; + + /** 上传接口返回的 uid,通常为空串。 */ + @JsonProperty("uid") + public String uid; + + /** 上传接口返回的 url(与 file_url 同值)。 */ + @JsonProperty("url") + public String url; + } + + /** 文件上传响应({@code POST upload.files}):{@code {code,msg,data:{data:{...}}}}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class UploadResponse { + + /** 业务数据外层。 */ + @JsonProperty("data") + public UploadData data; + + /** 200 表示成功。 */ + @JsonProperty("code") + public Integer code; + + /** 描述。 */ + @JsonProperty("msg") + public String msg; + } + + /** 上传响应的 {@code data} 层。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class UploadData { + + /** 附件元数据;直接作为 {@code *_att} 传参。 */ + @JsonProperty("data") + public Attachment data; + } + /** 转运单创建结果 {@code rst}。 */ @JsonIgnoreProperties(ignoreUnknown = true) public static final class TransferResult { diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java index adda5c6..e0099cc 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java @@ -118,6 +118,56 @@ class XincangOrderTest { } @Test + void wayfairRequiresTrackingNumberAndFaceBase64() { + OutboundCommand wayfair = OutboundCommand.builder() + .outboundRequestNo("OB-WF-1") + .salesPlatform(Platform.WAYFAIR) + .labelMode(LabelMode.PLATFORM_LABEL) + .carrierCode("FEDEX-G") + .warehouseId("CA-3790") + .shipTo(ShipTo.builder().name("R").phone("1").countryCode("US").stateOrProvince("CA") + .city("Fontana").addressLine1("1 A St").postalCode("92337").build()) + .line(OutboundLine.builder().lineNo("1").omsSku("SKU-A").quantity(1).build()) + .build(); + + common.ecommerce.shared.error.ValidationException e = + assertThrows(common.ecommerce.shared.error.ValidationException.class, + () -> adapter.create(ctx(), wayfair)); + assertTrue(e.getMessage().contains("gzh"), e.getMessage()); + } + + @Test + void wayfairSendsGzhAndFaceBase64WhenProvided() { + transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"DS-WF\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}")); + OutboundCommand wayfair = OutboundCommand.builder() + .outboundRequestNo("OB-WF-2") + .salesPlatform(Platform.WAYFAIR) + .labelMode(LabelMode.PLATFORM_LABEL) + .carrierCode("FEDEX-G") + .warehouseId("CA-3790") + .trackingNumber("1Z999") + .labelContentBase64("data:application/pdf;base64,AAAA") + .shopName("MY-SHOP") + .sfp(true) + .shipTo(ShipTo.builder().name("R").phone("1").countryCode("US").stateOrProvince("CA") + .city("Fontana").addressLine1("1 A St").postalCode("92337").build()) + .line(OutboundLine.builder().lineNo("1").omsSku("SKU-A").quantity(1).build()) + .build(); + + adapter.create(ctx(), wayfair); + + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("name=\"order_type\"\r\n\r\nwayfair"), body); + assertTrue(body.contains("name=\"gzh\"\r\n\r\n1Z999"), body); + assertTrue(body.contains("name=\"face_base64\"\r\n\r\ndata:application/pdf;base64,AAAA"), body); + assertTrue(body.contains("name=\"shop_name\"\r\n\r\nMY-SHOP"), body); + assertTrue(body.contains("name=\"sfp\"\r\n\r\n是"), body); + // 该接口 schema 没有 remark,不应发送 + assertFalse(body.contains("name=\"remark\""), body); + } + + @Test void splitFlagIsOmittedWhenCallerDidNotSetIt() { transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok( "{\"rst\":{\"order_no\":\"DS-1\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}")); diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java index 4315968..900362c 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java @@ -142,6 +142,56 @@ class XincangTransferTest { } @Test + void sendsAttachmentsAndLineExtras() { + transport.route(XincangConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"LTL-ATT\"},\"errno\":0,\"err\":\"\"}")); + TransferCommand cmd = TransferCommand.builder() + .transferRequestNo("TR-ATT-1") + .type(TransferType.OUTBOUND) + .fromWarehouseCode("CA-3790").toWarehouseCode("ONT8") + .deliveryMode("FBA").deliveryWay("Amazon(亚马逊卡车自提)") + .orderType("FBA") + .estimateOutboundDate(LocalDate.parse("2026-11-12")) + .estimateInboundDate(LocalDate.parse("2026-11-20")) + .shipTo(ShipTo.builder().name("FBA").countryCode("US").stateOrProvince("CA") + .city("San Bernardino").addressLine1("1 Amazon Way").postalCode("92408").build()) + .palletRequired(true) + .labelRequirement("产品贴") + .productLabelCopies(2) + .expressLabelCopies(3) + .productLabelAttachment(att("product.pdf")) + .cartonLabelAttachment(att("ctn.pdf")) + .expressLabelAttachment(att("express.pdf")) + .palletLabelAttachment(att("pallet.pdf")) + .otherAttachment(att("other1.pdf")) + .bolAttachment(att("bol.pdf")) + .line("SKU-1", 5, "FNSKU-1", "CTN-1", "行备注") + .build(); + + adapter.create(ctx(), cmd); + + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"product_label_att\""), body); + assertTrue(body.contains("\"ctn_label_att\""), body); + assertTrue(body.contains("\"express_label_att\""), body); + assertTrue(body.contains("\"pallet_label_att\""), body); + assertTrue(body.contains("\"other_att\""), body); + assertTrue(body.contains("\"bol_att\""), body); + assertTrue(body.contains("\"express_print_copies\":\"3\""), body); + // products 是 JSON 字符串,含 fn_sku / ctn_sku / remark + assertTrue(body.contains("\\\"fn_sku\\\":\\\"FNSKU-1\\\""), body); + assertTrue(body.contains("\\\"ctn_sku\\\":\\\"CTN-1\\\""), body); + assertTrue(body.contains("\\\"remark\\\":\\\"行备注\\\""), body); + } + + private static common.ecommerce.warehouse.model.TransferAttachment att(String fileName) { + return common.ecommerce.warehouse.model.TransferAttachment.builder() + .type("aliyun_oss").bucket("b").fileName(fileName) + .fileUrl("https://oss/" + fileName).fileType("pdf").name(fileName) + .build(); + } + + @Test void nonOutboundTransferTypeIsRejected() { TransferCommand cmd = TransferCommand.builder() .transferRequestNo("TR-2")