diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 563999c..939023a 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -130,8 +130,8 @@ | 统一模型字段 | 为什么不发 | |---|---| -| `imageUrl` | 恒健的 `imageUrls` 是「产品测量图片」(复核长宽高用),不是商品主图;语义不同 | -| `packageStyle` | 恒健的 `isSpecialOuterPackaging` 是「是否特殊外包装」,不是同一套码 | +| `imageUrl` | 恒健的 `imageUrls` 是「产品测量图片」(复核长宽高用),不是商品主图;语义不同,改为由 `WarehouseProduct.imageUrls()` 表达 | +| `packageStyle` | 恒健的 `isSpecialOuterPackaging` 是「是否特殊外包装」,不是同一套码;改为由 `WarehouseProduct.specialOuterPackaging()` 表达 | | `requireSn` / `snManagementMode` / `lotControl*` | 文档无对应字段 | | `hsCode` / `countryOfOrigin` / `declaredValue` | 恒健只收报关名称(`customName` / `customNameEn`),没有 HS 与原产国 | | `link` / `returnDealMethod` / `productCategory` | 文档无对应字段 | @@ -153,6 +153,19 @@ `attachInfoItems`。适配器在本地逐项校验,缺任何一项直接抛 `IllegalArgumentException`, **一个请求都不发**。 +**统一模型字段映射(原先「不发」的现已全部打通)**: + +| 文档字段 | 统一模型 | 说明 | +|---|---|---| +| `paidAt` | `OutboundCommand.paidAt` | UTC;未给由仓方取当前时间 | +| `pickupTime` | `OutboundCommand.pickupTime` | `yyyy-MM-dd`,FBALTL 自提场景必填 | +| `isDFOrder` | `OutboundCommand.directFulfillment` | 布尔→0/1;**由调用方显式指定**,不按平台推断 | +| `thirdPartyAccount` | `OutboundCommand.thirdPartyAccount` | — | +| `customerRemark` | `OutboundCommand.remark` | 客户 / 买家备注 | +| `warehouseRemark` | `OutboundCommand.warehouseRemark` | **给仓作业看的备注**,与上一个是两个字段 | +| `attachInfoItems` | `OutboundCommand.attachments()` | 通用附件列表:支持 URL 与 base64、7 种类型 | +| `attachInfoItems`(面单快捷入口) | `OutboundCommand.labelContentBase64` | 平台面单专用,可与附件列表同时给 | + **几个关键口径**: | 项 | 处理 | @@ -253,6 +266,9 @@ - 时间跨度上限 **30 天**,超过也本地拒绝。 - 不支持状态过滤:`OutboundQuery.statuses()` 非空时**拒绝**而不是静默忽略 (静默忽略会让调用方以为过滤生效了)。 +- **新增可传维度**(原先是「模型里没有,调用方传不进来」): + `channel`(平台)、`channelAccount`(店铺)、`poNo`、`providerOrderIds` + (逗号拼接下发 `orderIds`)、`updatedAfter/Before`(更新时间窗,独立于创建时间窗)。 - `OutboundQuery.orderRef`(平台单号)恒健**没有**对应参数:传了就**拒绝**, 不静默忽略(静默忽略会让调用方以为过滤生效了)。 - **排序可配**:`sortField` / `sortDirection` 由调用方指定,未指定才用文档默认 @@ -465,7 +481,7 @@ warehouse-sdk-hengjian/ └── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true ``` -已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(157 个 + 4 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(166 个 + 4 个跳过)。 ## 5. 探针用法 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 bef8302..8b46474 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 @@ -146,6 +146,20 @@ public final class WarehouseProduct { * 5 化妆品 / 6 鞋类 / 7 玩具 / 8 电子 / 9 数码。取值由仓方字典定义,适配器不归一。
*/ private final Integer productCategory; + /** + * 产品测量图片地址列表。 + * + *不是商品主图:恒健({@code imageUrls})用它在长宽高 / 重量变更时 + * 给仓方复核尺寸。没有该概念的仓忽略。
+ */ + private final List与 {@link #packageStyle} 不是一回事:后者是「裸包装 / 销售包装 / 物流包装」三选一, + * 前者是恒健的布尔开关({@code isSpecialOuterPackaging})。
+ */ + private final Boolean specialOuterPackaging; /** * 产品图片地址;null 表示不传。 @@ -188,6 +202,9 @@ public final class WarehouseProduct { this.link = b.link; this.remark = b.remark; this.productCategory = b.productCategory; + this.imageUrls = java.util.Collections.unmodifiableList( + new java.util.ArrayList恒健 {@code paidAt};运去哪等仓没有该入参,忽略。
+ */ + private final Instant paidAt; + /** + * 提货时间(仅 FBALTL 等自提场景必填)。null 表示不传。 + * + *恒健 {@code pickupTime},格式 {@code yyyy-MM-dd}。
+ */ + private final java.time.LocalDate pickupTime; + /** + * 是否 Amazon VC Direct Fulfillment 订单;null 表示不传(仓方按「否」处理)。 + * + *恒健 {@code isDFOrder}。
+ */ + private final Boolean directFulfillment; + /** + * 第三方账号(third party account)。null 表示不传。 + * + *恒健 {@code thirdPartyAccount}。
+ */ + private final String thirdPartyAccount; + /** + * 仓库备注。null 表示不传。 + * + *与 {@link #remark()} 不同:{@code remark} 是客户/买家备注 + * (恒健 {@code customerRemark}),本字段是给仓作业看的备注 + * (恒健 {@code warehouseRemark})。两者在仓方是两个字段,不能合并。
+ */ + private final String warehouseRemark; + /** + * 随单下发的附件(面单 / 装箱单 / BOL 等)。 + * + *与 {@link #labelContentBase64()} 的关系:那个是平台面单的专用快捷入口 + * (运去哪只认这一种),本字段是通用附件列表(恒健支持 7 种类型 + URL)。 + * 两者可以同时给;适配器按自己的协议需要取用。
+ */ + private final List恒健 {@code channelAccount};运去哪儿等仓没有该过滤项。
+ */ + private final String channelAccount; + /** + * 平台类型(仓方口径,如 {@code amazon} / {@code ebay})。null 表示不传。 + * + *恒健 {@code channel}。与 {@link #channelAccount()} 不同:前者是平台, + * 后者是店铺。
+ */ + private final String channel; + /** 仓内部订单 id 列表;null 表示不传。恒健 {@code orderIds}(逗号分隔)。 */ + private final List与 {@link #after()} 的区别:那个是创建时间窗,这个是更新时间窗。 + * 做增量同步时按更新时间更准——已存在的单状态变了也能拉到。
+ */ + private final Instant updatedAfter; + /** 更新时间窗终点(UTC)。 */ + private final Instant updatedBefore; private OutboundQuery(Builder b) { if (b.after != null && b.before != null && !b.after.isBefore(b.before)) { @@ -43,6 +69,20 @@ public final class OutboundQuery { this.cursor = b.cursor; this.sortField = b.sortField; this.sortDirection = b.sortDirection; + this.channelAccount = b.channelAccount; + this.channel = b.channel; + this.providerOrderIds = Collections.unmodifiableList( + new ArrayList下发时用:部分仓(恒健)只收 base64,不认 URL;接口同时支持两者, + * 给了 {@code contentBase64} 时仓方以它为准。查询回来时恒为 null。
+ */ + private final String contentBase64; private WarehouseAttachment(Builder b) { this.name = b.name; @@ -24,6 +31,7 @@ public final class WarehouseAttachment { this.url = b.url; this.packageNo = b.packageNo; this.remark = b.remark; + this.contentBase64 = b.contentBase64; } public static Builder builder() { @@ -52,12 +60,18 @@ public final class WarehouseAttachment { return remark; } + /** 附件内容(base64);null 表示只给了 URL。 */ + public String contentBase64() { + return contentBase64; + } + public static final class Builder { private String name; private String type; private String url; private String packageNo; private String remark; + private String contentBase64; public Builder name(String v) { this.name = v; @@ -84,6 +98,12 @@ public final class WarehouseAttachment { return this; } + /** 附件内容(base64,可带 {@code data:} 前缀)。 */ + public Builder contentBase64(String v) { + this.contentBase64 = v; + return this; + } + public WarehouseAttachment build() { return new WarehouseAttachment(this); } diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java index d36520b..8353a89 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java @@ -471,7 +471,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti if (trimToNull(query.orderRef()) != null) { throw validation(ctx, OP_ORDER_QUERY, "hengjian order list cannot filter by platform order number (orderRef=" - + query.orderRef() + "); use outboundRequestNo instead"); + + query.orderRef() + "); use outboundRequestNo or poNo instead"); } Map恒健要求 {@code url} 与 {@code file} 二选一、{@code name} 与 {@code type} 必填: + * 缺了本地拒绝,不发出去被仓方挡回来。{@code type} 用仓方原值直传—— + * 统一模型不归一附件分类(各仓口径不同)。
+ */ + private static HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem toAttachItem( + WarehouseAttachment att, String orderNo) { + String name = trimToNull(att.name()); + String type = trimToNull(att.type()); + String url = trimToNull(att.url()); + String content = trimToNull(att.contentBase64()); + if (name == null) { + throw new IllegalArgumentException( + "hengjian order " + orderNo + ": attachment name is required"); + } + if (type == null) { + throw new IllegalArgumentException( + "hengjian order " + orderNo + ": attachment type is required for " + name); + } + if (url == null && content == null) { + throw new IllegalArgumentException( + "hengjian order " + orderNo + ": attachment " + name + + " needs url or contentBase64"); + } + HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem item = + new HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem(); + item.name = name; + item.type = type; + // file 优先于 url(仓方语义:给了 file 就忽略 url) + item.file = content == null ? null : stripDataUri(content); + item.url = content == null ? url : null; + item.remark = trimToNull(att.remark()); + return item; } /** 去掉 {@code data:xxx/base64,} 头;没有头时原样返回。 */ diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java index 005d837..b9202df 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java @@ -4,6 +4,8 @@ import common.ecommerce.hengjian.dto.HengjianProductSaveDtos; import common.ecommerce.shared.support.Money; import common.ecommerce.warehouse.capability.WarehouseProduct; +import java.util.ArrayList; + /** * 恒健商品报文映射({@code POST /v1/product/save})。 * @@ -17,15 +19,10 @@ import common.ecommerce.warehouse.capability.WarehouseProduct; * 发出去被仓方拒,排查成本比本地报错高得多。 * *| 恒健字段 | 为什么不发 |
|---|---|
| {@code imageUrls} | - *文档写明是「产品测量图片」,用于复核长宽高,不是商品主图。 - * 统一模型的 {@code imageUrl} 是商品图片,语义不同,不能拿来顶替。 |
| {@code isSpecialOuterPackaging} | - *「特殊外包装」与统一模型的 {@code packageStyle}(裸包装 / 销售包装 / 物流包装) - * 不是同一套码,映射需要业务确认,暂时不发。 |
文档里的 {@code imageUrls}(产品测量图)与 {@code isSpecialOuterPackaging} + * (特殊外包装)已由 {@code WarehouseProduct.imageUrls()} / + * {@code specialOuterPackaging()} 承载——不是商品主图 {@code imageUrl}, + * 也不是 {@code packageStyle} 的三选一,语义不同,各自独立下发。
* *统一模型里的 SN、批次、HS Code、原产国、商品链接、客退处理方式、产品品类, * 恒健文档都没有对应字段,一律不发。
@@ -95,6 +92,14 @@ public final class HengjianProductMapper { req.remark = trimToNull(product.remark()); req.customName = trimToNull(product.declaredName()); req.customNameEn = trimToNull(product.declaredNameEn()); + // 产品测量图(复核长宽高用),与商品主图 imageUrl 不是一回事 + if (!product.imageUrls().isEmpty()) { + req.imageUrls = new ArrayList文档:{@code carrierCode} 为 {@code FBALTL}(自提)时必填。
+ */ + public String pickupTime; + + /** * 平台要求发货时间,UTC,{@code yyyy-MM-dd HH:mm:ss}。 * *文档:{@code isDFOrder=1} 时必填。
diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java index c5becfc..61699b9 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java @@ -295,7 +295,7 @@ class HengjianCreateOrderTest { assertTrue(body.contains("\"customerRemark\":\"买家备注\""), body); } - /** 恒健没有平台维度:salesPlatform 不发,也不拿它推 isDFOrder。 */ + /** 恒健没有平台维度:salesPlatform 不发,也不按平台推断 isDFOrder。 */ @Test void doesNotSendSalesPlatformOrInferDfOrder() { RecordingTransport transport = creating(); @@ -303,9 +303,78 @@ class HengjianCreateOrderTest { String body = transport.lastDataRequest().body(); assertFalse(body.contains("salesPlatform"), body); + // 未显式指定时不发;不按 AMAZON_VC 之类去猜 assertFalse(body.contains("isDFOrder"), body); } + /** 原先缺失的 5 个文档字段现在都能传。 */ + @Test + void sendsPreviouslyMissingDocumentedFields() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order() + .paidAt(Instant.parse("2026-11-10T08:00:00Z")) + .pickupTime(java.time.LocalDate.parse("2026-11-12")) + .directFulfillment(true) + .thirdPartyAccount("THIRD-ACC-1") + .warehouseRemark("请加固外箱") + .remark("买家备注") + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"paidAt\":\"2026-11-10 08:00:00\""), body); + assertTrue(body.contains("\"pickupTime\":\"2026-11-12\""), body); + assertTrue(body.contains("\"isDFOrder\":1"), body); + assertTrue(body.contains("\"thirdPartyAccount\":\"THIRD-ACC-1\""), body); + assertTrue(body.contains("\"warehouseRemark\":\"请加固外箱\""), body); + // 客户备注与仓库备注是两个字段,各发各的 + assertTrue(body.contains("\"customerRemark\":\"买家备注\""), body); + } + + /** 未指定的新字段不出现(不编造默认值)。 */ + @Test + void omitsNewFieldsWhenUnset() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + for (String field : new String[]{"paidAt", "pickupTime", "isDFOrder", + "thirdPartyAccount", "warehouseRemark"}) { + assertFalse(body.contains("\"" + field + "\""), "未指定时不应发送 " + field + ",body=" + body); + } + } + + /** 通用附件列表:URL 与 base64 两种形态、type 用仓方原值。 */ + @Test + void sendsGenericAttachments() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order() + .attachment(common.ecommerce.warehouse.model.WarehouseAttachment.builder() + .name("packing-list").type("1") + .url("https://cdn/packing.pdf").build()) + .attachment(common.ecommerce.warehouse.model.WarehouseAttachment.builder() + .name("bol").type("2") + .contentBase64("data:application/pdf;base64,JVBERi0xLjQK").build()) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"name\":\"packing-list\""), body); + assertTrue(body.contains("\"type\":\"1\""), body); + assertTrue(body.contains("\"url\":\"https://cdn/packing.pdf\""), body); + assertTrue(body.contains("\"file\":\"JVBERi0xLjQK\""), body); + } + + /** 附件缺 name / type / url+base64 时本地拒绝,不发出去被仓方挡回来。 */ + @Test + void rejectsIncompleteAttachment() { + RecordingTransport transport = creating(); + assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(ctx(), order() + .attachment(common.ecommerce.warehouse.model.WarehouseAttachment.builder() + .type("1").url("https://cdn/x.pdf").build()) + .build())); + assertTrue(transport.dataRequests().isEmpty()); + } + /** 仓代码:命令显式指定优先,否则用账户配置。 */ @Test void warehouseCodeResolvesFromCommandThenAccount() { diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java index e5718a9..878ac6b 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java @@ -341,6 +341,37 @@ class HengjianOrderQueryTest { assertTrue(url.contains("sort=" + HengjianConstants.ORDER_LIST_DEFAULT_SORT), url); } + /** 新补的查询维度都能下发。 */ + @Test + void sendsNewQueryDimensions() { + RecordingTransport transport = list(); + adapter(transport).query(ctx(), OutboundQuery.builder() + .outboundRequestNo("OB-1").pageSize(10) + .channel("amazon").channelAccount("office-US") + .poNo("PO-123") + .updatedAfter(Instant.parse("2026-11-01T00:00:00Z")) + .updatedBefore(Instant.parse("2026-11-10T12:00:00Z")) + .build()); + + String url = transport.lastDataRequest().url(); + assertTrue(url.contains("channel=amazon"), url); + assertTrue(url.contains("channelAccount=office-US"), url); + assertTrue(url.contains("poNo=PO-123"), url); + assertTrue(url.contains("updateBeginDate=2026-11-01+00%3A00%3A00") + || url.contains("updateBeginDate=2026-11-01 00:00:00"), url); + } + + /** 多订单 id 用逗号拼接下发。 */ + @Test + void sendsProviderOrderIds() { + RecordingTransport transport = list(); + adapter(transport).query(ctx(), OutboundQuery.builder() + .pageSize(10).providerOrderIds(java.util.Arrays.asList("101", "102")).build()); + + assertTrue(transport.lastDataRequest().url().contains("orderIds=101%2C102") + || transport.lastDataRequest().url().contains("orderIds=101,102")); + } + /** orderRef(平台单号)恒健查不了:拒绝而不是静默忽略。 */ @Test void queryRejectsOrderRef() { diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java index d744936..12d45a5 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java @@ -206,8 +206,11 @@ class HengjianProductSaveTest { } /** - * 恒健没有的字段不能编:SN、批次、HS Code、原产国、商品链接、客退处理、品类, - * 以及语义不同的 {@code imageUrls} / {@code isSpecialOuterPackaging}。 + * 恒健没有的字段不能编:SN、批次、HS Code、原产国、商品链接、客退处理、品类。 + * + *{@code imageUrls} / {@code isSpecialOuterPackaging} 不在此列——恒健有这两个字段, + * 只是语义与 {@code imageUrl} / {@code packageStyle} 不同,见 + * {@link #sendsMeasurementImagesAndSpecialPackaging()}。
*/ @Test void doesNotInventFieldsHengjianDoesNotHave() { @@ -225,14 +228,55 @@ class HengjianProductSaveTest { .build()); String body = transport.lastDataRequest().body(); - String[] absent = {"imageUrls", "productCategory", "packageStyle", "isRequireSn", + String[] absent = {"productCategory", "packageStyle", "isRequireSn", "snMgmtMode", "link", "hsCode", "countryOfOrigin", "customs", - "lotControl", "returnDealMethod", "isSpecialOuterPackaging"}; + "lotControl", "returnDealMethod"}; for (String field : absent) { assertFalse(body.contains("\"" + field + "\""), "不应发送恒健没有的字段 " + field + ",body=" + body); } } + /** 产品测量图走 {@code imageUrls},与商品主图 {@code imageUrl} 不是一回事。 */ + @Test + void sendsMeasurementImages() { + RecordingTransport transport = saving(); + adapter(transport).createOrUpdate(ctx(), product() + .imageUrls(java.util.Arrays.asList("https://cdn/1.jpg", "https://cdn/2.jpg")) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"imageUrls\":[\"https://cdn/1.jpg\",\"https://cdn/2.jpg\"]"), body); + } + + /** 主图 {@code imageUrl} 仍不下发:恒健的 imageUrls 是测量图,语义不同。 */ + @Test + void doesNotTreatMainImageAsMeasurementImage() { + RecordingTransport transport = saving(); + adapter(transport).createOrUpdate(ctx(), product() + .imageUrl("https://example.com/main.jpg").build()); + + assertFalse(transport.lastDataRequest().body().contains("imageUrls"), + "商品主图不能冒充测量图"); + } + + /** 特殊外包装是独立布尔开关,与 packageStyle 三选一无关。 */ + @Test + void sendsSpecialOuterPackaging() { + RecordingTransport transport = saving(); + adapter(transport).createOrUpdate(ctx(), product().specialOuterPackaging(true).build()); + + assertTrue(transport.lastDataRequest().body().contains("\"isSpecialOuterPackaging\":1")); + + RecordingTransport no = saving(); + adapter(no).createOrUpdate(ctx(), product().specialOuterPackaging(false).build()); + assertTrue(no.lastDataRequest().body().contains("\"isSpecialOuterPackaging\":0")); + + RecordingTransport unset = saving(); + adapter(unset).createOrUpdate(ctx(), product().build()); + assertFalse(unset.lastDataRequest().body().contains("isSpecialOuterPackaging"), + "未指定时不下发"); + } + // ---------------------------------------------------------------- 本地必填校验 @Test