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 imageUrls; + /** + * 是否特殊外包装:null 未指定 / true 是 / false 否。 + * + *

与 {@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(b.imageUrls)); + this.specialOuterPackaging = b.specialOuterPackaging; this.imageUrl = b.imageUrl; this.expirationControl = b.expirationControl; this.expirationDays = b.expirationDays; @@ -396,6 +413,16 @@ public final class WarehouseProduct { return imageUrl; } + /** 产品测量图片(复核尺寸用);空表示不传。不可变。 */ + public List imageUrls() { + return imageUrls; + } + + /** 是否特殊外包装;null 表示不传。 */ + public Boolean specialOuterPackaging() { + return specialOuterPackaging; + } + /** 是否给了任何海关信息。 */ public boolean hasCustoms() { return declaredValue != null; @@ -450,6 +477,8 @@ public final class WarehouseProduct { private String remark; private Integer productCategory; private String imageUrl; + private final List imageUrls = new java.util.ArrayList(); + private Boolean specialOuterPackaging; private Boolean expirationControl; private Integer expirationDays; private Integer packedQuantity; @@ -672,6 +701,24 @@ public final class WarehouseProduct { return this; } + /** 产品测量图片列表;不传表示没有。 */ + public Builder imageUrls(List urls) { + if (urls != null) { + for (String url : urls) { + if (url != null && !url.trim().isEmpty()) { + this.imageUrls.add(url.trim()); + } + } + } + return this; + } + + /** 是否特殊外包装;null 表示不传。 */ + public Builder specialOuterPackaging(Boolean v) { + this.specialOuterPackaging = 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 d9dd244..42ced70 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 @@ -77,6 +77,49 @@ public final class OutboundCommand { */ private final Boolean signatureRequired; + // ==================== 仓方协议里有、统一模型原先缺的字段 ==================== + + /** + * 支付时间(UTC)。null 表示不传,由仓方按当前时间处理。 + * + *

恒健 {@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 attachments; + private OutboundCommand(Builder b) { if (b.outboundRequestNo == null || b.outboundRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("outboundRequestNo must not be blank"); @@ -107,6 +150,13 @@ public final class OutboundCommand { this.shopName = b.shopName; this.sfp = b.sfp; this.signatureRequired = b.signatureRequired; + this.paidAt = b.paidAt; + this.pickupTime = b.pickupTime; + this.directFulfillment = b.directFulfillment; + this.thirdPartyAccount = b.thirdPartyAccount; + this.warehouseRemark = b.warehouseRemark; + this.attachments = Collections.unmodifiableList( + new ArrayList(b.attachments)); } public static Builder builder() { @@ -223,6 +273,36 @@ public final class OutboundCommand { return signatureRequired; } + /** 支付时间(UTC);null 表示不传。 */ + public Instant paidAt() { + return paidAt; + } + + /** 提货时间;null 表示不传。 */ + public java.time.LocalDate pickupTime() { + return pickupTime; + } + + /** 是否 Amazon VC DF 订单;null 表示不传。 */ + public Boolean directFulfillment() { + return directFulfillment; + } + + /** 第三方账号;null 表示不传。 */ + public String thirdPartyAccount() { + return thirdPartyAccount; + } + + /** 仓库备注(给仓作业看);null 表示不传。 */ + public String warehouseRemark() { + return warehouseRemark; + } + + /** 随单附件;不可变,空表示没有。 */ + public List attachments() { + return attachments; + } + public static final class Builder { private String outboundRequestNo; @@ -247,6 +327,12 @@ public final class OutboundCommand { private String shopName; private Boolean sfp; private Boolean signatureRequired; + private Instant paidAt; + private java.time.LocalDate pickupTime; + private Boolean directFulfillment; + private String thirdPartyAccount; + private String warehouseRemark; + private final List attachments = new ArrayList(); public Builder outboundRequestNo(String outboundRequestNo) { this.outboundRequestNo = outboundRequestNo; @@ -376,6 +462,54 @@ public final class OutboundCommand { return this; } + /** 支付时间(UTC);null 表示不传。 */ + public Builder paidAt(Instant v) { + this.paidAt = v; + return this; + } + + /** 提货时间;null 表示不传。 */ + public Builder pickupTime(java.time.LocalDate v) { + this.pickupTime = v; + return this; + } + + /** 是否 Amazon VC DF 订单;null 表示不传。 */ + public Builder directFulfillment(Boolean v) { + this.directFulfillment = v; + return this; + } + + /** 第三方账号;null 表示不传。 */ + public Builder thirdPartyAccount(String v) { + this.thirdPartyAccount = v; + return this; + } + + /** 仓库备注(给仓作业看);null 表示不传。 */ + public Builder warehouseRemark(String v) { + this.warehouseRemark = v; + return this; + } + + /** 追加一个随单附件。 */ + public Builder attachment(WarehouseAttachment v) { + if (v != null) { + this.attachments.add(v); + } + return this; + } + + /** 追加一批随单附件。 */ + public Builder attachments(List v) { + if (v != null) { + for (WarehouseAttachment one : v) { + attachment(one); + } + } + return this; + } + public OutboundCommand build() { return new OutboundCommand(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java index fac98d6..8e395db 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java @@ -29,6 +29,32 @@ public final class OutboundQuery { private final String sortField; /** 排序方向;null 表示用适配器的默认方向。 */ private final SortDirection sortDirection; + /** + * 渠道账号 / 店铺标识(仓方口径)。null 表示不传。 + * + *

恒健 {@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 providerOrderIds; + /** PO 单号;null 表示不传。恒健 {@code poNo}。 */ + private final String poNo; + /** + * 更新时间窗起点(UTC);与 {@link #updatedBefore()} 成对。 + * + *

与 {@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(b.providerOrderIds)); + this.poNo = b.poNo; + if ((b.updatedAfter == null) != (b.updatedBefore == null)) { + throw new IllegalArgumentException( + "updatedAfter and updatedBefore must be set together"); + } + if (b.updatedAfter != null && b.updatedAfter.isAfter(b.updatedBefore)) { + throw new IllegalArgumentException("updatedAfter must not be after updatedBefore"); + } + this.updatedAfter = b.updatedAfter; + this.updatedBefore = b.updatedBefore; } public static Builder builder() { @@ -104,6 +144,41 @@ public final class OutboundQuery { return sortDirection; } + /** 渠道账号 / 店铺标识;null 表示不传。 */ + public String channelAccount() { + return channelAccount; + } + + /** 平台类型(仓方口径);null 表示不传。 */ + public String channel() { + return channel; + } + + /** 仓内部订单 id 列表;不可变,空表示不传。 */ + public List providerOrderIds() { + return providerOrderIds; + } + + /** PO 单号;null 表示不传。 */ + public String poNo() { + return poNo; + } + + /** 更新时间窗起点(UTC);null 表示不限。 */ + public Instant updatedAfter() { + return updatedAfter; + } + + /** 更新时间窗终点(UTC);null 表示不限。 */ + public Instant updatedBefore() { + return updatedBefore; + } + + /** 是否给了更新时间窗。 */ + public boolean hasUpdatedRange() { + return updatedAfter != null && updatedBefore != null; + } + /** 翻页时只改游标。 */ public Builder toBuilder() { return builder() @@ -115,7 +190,13 @@ public final class OutboundQuery { .pageSize(pageSize) .cursor(cursor) .sortField(sortField) - .sortDirection(sortDirection); + .sortDirection(sortDirection) + .channel(channel) + .channelAccount(channelAccount) + .providerOrderIds(providerOrderIds) + .poNo(poNo) + .updatedAfter(updatedAfter) + .updatedBefore(updatedBefore); } public static final class Builder { @@ -129,6 +210,12 @@ public final class OutboundQuery { private String cursor; private String sortField; private SortDirection sortDirection; + private String channel; + private String channelAccount; + private final List providerOrderIds = new ArrayList(); + private String poNo; + private Instant updatedAfter; + private Instant updatedBefore; public Builder after(Instant after) { this.after = after; @@ -186,6 +273,54 @@ public final class OutboundQuery { return this; } + /** 平台类型(仓方口径);null 表示不传。 */ + public Builder channel(String v) { + this.channel = v; + return this; + } + + /** 渠道账号 / 店铺标识;null 表示不传。 */ + public Builder channelAccount(String v) { + this.channelAccount = v; + return this; + } + + /** 仓内部订单 id;null / 空忽略。 */ + public Builder providerOrderId(String v) { + if (v != null && !v.trim().isEmpty()) { + this.providerOrderIds.add(v.trim()); + } + return this; + } + + /** 仓内部订单 id 列表。 */ + public Builder providerOrderIds(List v) { + if (v != null) { + for (String one : v) { + providerOrderId(one); + } + } + return this; + } + + /** PO 单号;null 表示不传。 */ + public Builder poNo(String v) { + this.poNo = v; + return this; + } + + /** 更新时间窗起点;必须与 {@link #updatedBefore} 成对。 */ + public Builder updatedAfter(Instant v) { + this.updatedAfter = v; + return this; + } + + /** 更新时间窗终点。 */ + public Builder updatedBefore(Instant v) { + this.updatedBefore = v; + return this; + } + public OutboundQuery build() { return new OutboundQuery(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseAttachment.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseAttachment.java index 4faa8cc..32538ea 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseAttachment.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseAttachment.java @@ -17,6 +17,13 @@ public final class WarehouseAttachment { /** 关联包裹号;不区分包裹的仓为 null。 */ private final String packageNo; private final String remark; + /** + * 附件内容(base64,可带 {@code data:} 前缀);null 表示只给 URL。 + * + *

下发时用:部分仓(恒健)只收 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 params = new LinkedHashMap(); // rows 上限是文档明写的「默认最高 100」,超过即拒绝(不静默截断) @@ -482,15 +482,33 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti params.put("sort", sortDirectionOf(query.sortDirection())); params.put("page", pageNumberOf(query.cursor())); + // 可选过滤:仓方支持就透传,不支持的维度已在上方拒绝 + putIfPresent(params, "channel", query.channel()); + putIfPresent(params, "channelAccount", query.channelAccount()); + putIfPresent(params, "poNo", query.poNo()); + if (!query.providerOrderIds().isEmpty()) { + params.put("orderIds", joinIds(query.providerOrderIds())); + } + if (query.hasUpdatedRange()) { + // 更新时间窗按 UTC 时间戳下发,格式 yyyy-MM-dd HH:mm:ss + params.put("updateBeginDate", formatDateTime(query.updatedAfter())); + params.put("updateEndDate", formatDateTime(query.updatedBefore())); + } + + // 文档:时间、订单号、订单 id 三者必填其一。 + // 「时间」取创建时间窗(beginDateTime/endDateTime);更新时间窗与 PO 单号是可选附加条件, + // 不能单独当主键——只给它们时仍按缺少主键拒绝。 String orderNo = trimToNull(query.outboundRequestNo()); if (orderNo != null) { params.put("orderNos", orderNo); } else if (query.after() != null && query.before() != null) { addDateRange(ctx, params, query); + } else if (!query.providerOrderIds().isEmpty()) { + // orderIds 已在上方放入 params,本身就是合法主键 } else { throw validation(ctx, OP_ORDER_QUERY, - "hengjian order list requires outboundRequestNo or both after/before " - + "(time, order number or order id - at least one)"); + "hengjian order list requires outboundRequestNo, providerOrderIds " + + "or both after/before (time, order number or order id - at least one)"); } rateLimiter.acquire(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, HengjianConstants.PERMITS_PER_SECOND); @@ -783,6 +801,34 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti return pageSize; } + + /** 逗号拼接(恒健多条单号用逗号分隔)。 */ + private static String joinIds(List ids) { + StringBuilder sb = new StringBuilder(); + for (String id : ids) { + if (sb.length() > 0) { + sb.append(','); + } + sb.append(id); + } + return sb.toString(); + } + + /** UTC 时间 → {@code yyyy-MM-dd HH:mm:ss}(恒健更新时间参数口径)。 */ + private static String formatDateTime(java.time.Instant instant) { + return instant == null ? null + : java.time.LocalDateTime.ofInstant(instant, ZoneOffset.UTC) + .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")); + } + + /** null / 空白不放进参数表。 */ + private static void putIfPresent(Map params, String key, String value) { + String v = trimToNull(value); + if (v != null) { + params.put(key, v); + } + } + /** 排序字段:调用方指定优先,否则用文档的默认 {@code id}。 */ private static String sortFieldOf(String requested) { String v = trimToNull(requested); diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java index f8de14d..8cdb58c 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java @@ -6,6 +6,7 @@ import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.model.WarehouseAttachment; import java.math.BigDecimal; import java.time.Clock; @@ -13,7 +14,6 @@ import java.time.Instant; import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; import java.util.ArrayList; -import java.util.Collections; import java.util.List; /** @@ -88,7 +88,16 @@ public final class HengjianOutboundMapper { req.expectedShipDate = formatTime(cmd.latestShipDate()); req.isPrime = flagOf(cmd.sfp()); req.createdAt = formatTime(Instant.now(clock)); + // 客户备注与仓库备注在恒健是两个字段,不能合并 req.customerRemark = trimToNull(cmd.remark()); + req.warehouseRemark = trimToNull(cmd.warehouseRemark()); + // 支付时间:调用方给了就发,没给由仓方按当前时间处理 + req.paidAt = formatTime(cmd.paidAt()); + // 提货时间:仅 FBALTL 等自提场景需要,格式 yyyy-MM-dd + req.pickupTime = cmd.pickupTime() == null ? null : cmd.pickupTime().toString(); + // VC Direct Fulfillment 由调用方显式指定,不按平台推断 + req.isDFOrder = flagOf(cmd.directFulfillment()); + req.thirdPartyAccount = trimToNull(cmd.thirdPartyAccount()); ShipTo shipTo = cmd.shipTo(); req.shipToCountry = require(shipTo.countryCode(), "shipTo.countryCode", orderNo); @@ -173,6 +182,14 @@ public final class HengjianOutboundMapper { */ private static List toAttachInfoItems( OutboundCommand cmd, String orderNo) { + // 1) 通用附件列表:支持 URL 与 base64、7 种类型 + List out = + new ArrayList(); + for (WarehouseAttachment att : cmd.attachments()) { + out.add(toAttachItem(att, orderNo)); + } + + // 2) 平台面单快捷入口:与 attachments 可以同时给 String content = cmd.labelContentBase64(); if (content == null || content.trim().isEmpty()) { if (cmd.labelMode() == LabelMode.PLATFORM_LABEL) { @@ -180,7 +197,7 @@ public final class HengjianOutboundMapper { "hengjian order " + orderNo + ": labelContentBase64 is required when labelMode=PLATFORM_LABEL"); } - return new ArrayList(); + return out; } if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) { throw new IllegalArgumentException( @@ -196,10 +213,45 @@ public final class HengjianOutboundMapper { // 这里统一剥掉,避免把 "data:application/pdf;base64," 当成文件内容解出来 item.file = stripDataUri(content); item.type = ATTACH_TYPE_SHIPPING_LABEL; - List out = - new ArrayList(1); out.add(item); - return Collections.unmodifiableList(out); + return out; + } + + /** + * 一个通用附件 → 恒健 {@code attachInfoItems} 元素。 + * + *

恒健要求 {@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(product.imageUrls()); + } + // 特殊外包装是布尔开关,独立于 packageStyle 的三选一 + if (product.specialOuterPackaging() != null) { + req.isSpecialOuterPackaging = product.specialOuterPackaging() ? 1 : 0; + } return req; } diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java index ebfdb49..f7327d1 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java @@ -62,6 +62,13 @@ public final class HengjianCreateOrderDtos { public Integer isPrime; /** + * 提货时间,{@code yyyy-MM-dd}。 + * + *

文档:{@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