From 3e5eb84c2936d4f5b4c95669102044410e724e21 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Wed, 11 Nov 2026 17:08:09 +0800 Subject: [PATCH] =?UTF-8?q?feat(warehouse):=20=E5=86=99=E5=85=A5=E6=A8=A1?= =?UTF-8?q?=E5=9E=8B=E8=A1=A5=E9=BD=90=E4=BB=93=E6=96=B9=E5=8E=9F=E5=A7=8B?= =?UTF-8?q?=E5=AD=97=E6=AE=B5=EF=BC=8Cis=5Fsign=20=E4=B8=8D=E5=86=8D?= =?UTF-8?q?=E5=86=99=E6=AD=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 写入侧此前同样是「模型没有的字段一律不传」,导致调用方无法把仓方支持的参数 传下去。这次按只增不改补齐: - OutboundCommand 增加 signatureRequired(信仓 is_sign) 下单 mapper 改为:调用方给值按值下发,未给才退回「否」 - WarehouseProduct 增加 productCategory(信仓 product_category)与 imageUrl(product_image 的最终地址) 适配器只发送调用方显式给的值,不做字典猜测 - XincangProductMapper:product_category 按调用方给值下发; product_image 需要 upload.files 的 OSS 元数据,只有 URL 无法组装, 明确置空并注释说明 字段注释写明对应的仓方原字段与取值含义。 Co-Authored-By: Claude Code --- .../warehouse/capability/WarehouseProduct.java | 44 ++++++++++++++++++++++ .../ecommerce/warehouse/model/OutboundCommand.java | 23 +++++++++++ .../xincang/adapter/XincangOrderMapper.java | 7 +++- .../xincang/adapter/XincangProductMapper.java | 8 ++++ .../xincang/adapter/XincangOrderTest.java | 21 +++++++++++ 5 files changed, 101 insertions(+), 2 deletions(-) diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java index 41bf3f5..202eff1 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java @@ -51,6 +51,24 @@ public final class WarehouseProduct { private final String link; private final String remark; + // ==================== 仓方原始字段 ==================== + + /** + * 产品品类;null 表示不传。 + * + *

信仓 {@code product_category}:0 其它 / 1 家具 / 2 食品 / 3 汽配 / 4 服饰 / + * 5 化妆品 / 6 鞋类 / 7 玩具 / 8 电子 / 9 数码。取值由仓方字典定义,适配器不归一。

+ */ + private final Integer productCategory; + + /** + * 产品图片地址;null 表示不传。 + * + *

信仓走「先上传文件、再回传 OSS 元数据」的两步流程({@code upload.files}), + * 这里只承载最终可访问的 URL;适配器拿不到 OSS 元数据时不发送该字段。

+ */ + private final String imageUrl; + private WarehouseProduct(Builder b) { this.omsSku = require(b.omsSku, "omsSku"); this.providerSku = b.providerSku; @@ -82,6 +100,8 @@ public final class WarehouseProduct { this.cost = b.cost; this.link = b.link; this.remark = b.remark; + this.productCategory = b.productCategory; + this.imageUrl = b.imageUrl; // 海关信息要么整组给、要么整组不给:国家编码 / HS Code / 申报价值缺一即失败 int customsFields = 0; @@ -218,6 +238,16 @@ public final class WarehouseProduct { return remark; } + /** 产品品类(仓方字典值);null 表示不传。 */ + public Integer productCategory() { + return productCategory; + } + + /** 产品图片地址;null 表示不传。 */ + public String imageUrl() { + return imageUrl; + } + /** 是否给了任何海关信息。 */ public boolean hasCustoms() { return declaredValue != null; @@ -270,6 +300,8 @@ public final class WarehouseProduct { private Money cost; private String link; private String remark; + private Integer productCategory; + private String imageUrl; public Builder omsSku(String v) { this.omsSku = v; @@ -408,6 +440,18 @@ public final class WarehouseProduct { return this; } + /** 产品品类(信仓 {@code product_category} 等字典值);null 表示不传。 */ + public Builder productCategory(Integer v) { + this.productCategory = v; + return this; + } + + /** 产品图片地址;null 表示不传。 */ + public Builder imageUrl(String v) { + this.imageUrl = v; + return this; + } + /** * @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐 */ 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 15fde17..d9dd244 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 @@ -67,6 +67,16 @@ public final class OutboundCommand { /** 是否 SFP(Seller Fulfilled Prime);null 表示不传,由仓按默认否处理。 */ private final Boolean sfp; + // ==================== 仓方原始字段(下单时用)==================== + + /** + * 是否需要签名签收;null 表示不传,由仓方按默认处理。 + * + *

信仓 {@code is_sign}({@code "1"} / {@code "0"})。适配器不会替你猜: + * 不传就不发,仓方默认值与业务要求未必一致。

+ */ + private final Boolean signatureRequired; + private OutboundCommand(Builder b) { if (b.outboundRequestNo == null || b.outboundRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("outboundRequestNo must not be blank"); @@ -96,6 +106,7 @@ public final class OutboundCommand { this.labelContentBase64 = b.labelContentBase64; this.shopName = b.shopName; this.sfp = b.sfp; + this.signatureRequired = b.signatureRequired; } public static Builder builder() { @@ -207,6 +218,11 @@ public final class OutboundCommand { return sfp; } + /** 是否需要签名签收;null 表示不传(信仓 {@code is_sign})。 */ + public Boolean signatureRequired() { + return signatureRequired; + } + public static final class Builder { private String outboundRequestNo; @@ -230,6 +246,7 @@ public final class OutboundCommand { private String labelContentBase64; private String shopName; private Boolean sfp; + private Boolean signatureRequired; public Builder outboundRequestNo(String outboundRequestNo) { this.outboundRequestNo = outboundRequestNo; @@ -353,6 +370,12 @@ public final class OutboundCommand { return this; } + /** 是否需要签名签收;null 表示不传(信仓 {@code is_sign})。 */ + public Builder signatureRequired(Boolean v) { + this.signatureRequired = v; + return this; + } + public OutboundCommand build() { return new OutboundCommand(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 e39c422..fabc8b3 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 @@ -40,7 +40,7 @@ public final class XincangOrderMapper { /** 信仓布尔字段统一用「是 / 否」。 */ private static final String YES = "是"; private static final String NO = "否"; - /** 签名服务:模型无对应字段,固定否。 */ + /** 签名服务未指定时的兜底值:文档把它列为必填,只能给「否」。 */ private static final String SIGN_NOT_REQUIRED = NO; private XincangOrderMapper() { @@ -87,7 +87,10 @@ public final class XincangOrderMapper { form.put("phone", shipTo.phone().trim()); putIfPresent(form, "email", shipTo.email()); form.put("logistics_type", cmd.carrierCode().trim()); - form.put("is_sign", SIGN_NOT_REQUIRED); + // is_sign 是必填项:调用方给值就按值发,没给才退回「否」并说明原因 + form.put("is_sign", cmd.signatureRequired() == null + ? SIGN_NOT_REQUIRED + : (cmd.signatureRequired() ? YES : NO)); form.put("products", productsJson(cmd.lines(), json)); putIfPresent(form, "shop_name", cmd.shopName()); if (cmd.sfp() != null) { diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java index 8a3764f..326ec70 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java @@ -17,6 +17,9 @@ import java.math.RoundingMode; * *

文档未定义「包装方式 / 是否 SN / 客退处理 / 海关信息」等字段,这些统一模型字段 * 不发送,避免自行编造平台不认的键。

+ * + *

文档里标「已废弃」的 {@code ahs_weight} / {@code ahs_dimensions} / {@code oversize} + * 只在 DTO 里占位,一律不填——仓方已改为按服务商参数自动计算。

*/ public final class XincangProductMapper { @@ -54,6 +57,11 @@ public final class XincangProductMapper { req.remark = trimToNull(product.remark()); req.ckm = trimToNull(product.customItemNo()); req.productType = product.productType() > 0 ? product.productType() : null; + // product_category 由调用方按仓方字典显式给,适配器不猜 + req.productCategory = product.productCategory(); + // product_image 需要 upload.files 返回的 OSS 元数据;只有 URL 时无法组装, + // 因此这里不填 —— 明确不发送,避免被仓方当成无效图片 + req.productImage = null; return req; } 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 711f01f..1e42797 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 @@ -168,6 +168,27 @@ class XincangOrderTest { } @Test + void signatureFlagFollowsCaller() { + transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"DS-SIG\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}")); + OutboundCommand signed = OutboundCommand.builder() + .outboundRequestNo("OB-SIG") + .salesPlatform(Platform.AMAZON_SC) + .carrierCode("FEDEX-G") + .warehouseId("CA-3790") + .signatureRequired(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(), signed); + + assertTrue(transport.lastDataRequest().body().contains("name=\"is_sign\"\r\n\r\n是"), + transport.lastDataRequest().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\":\"\"}"));