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
仅在「调用方自供面单」的仓上使用(信仓 {@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附件字段(产品贴 / 外箱贴 / 托盘贴 / 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字段名与上传接口返回保持一致,包括 {@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")