Browse Source

feat(warehouse): 补齐文档有而模型缺的入参,恒健已接接口全部可传

对照恒健接口文档逐个核对后,发现上一轮只修了「有字段但不生效」,
还有一批「模型里压根没字段、调用方传不进来」。这次补齐:

OutboundCommand(下单,5 项 + 附件列表)
- paidAt / pickupTime / directFulfillment / thirdPartyAccount / warehouseRemark
- warehouseRemark 与 remark 是两个字段:前者给仓作业看(恒健 warehouseRemark),
  后者是客户备注(customerRemark),不能合并
- attachments: List<WarehouseAttachment>,支持 URL 与 base64 的通用附件,
  与平台面单快捷入口 labelContentBase64 并存
- WarehouseAttachment 补 contentBase64(下发用;查询回来恒为 null)

OutboundQuery(列表查询,5 个维度)
- channel / channelAccount / poNo / providerOrderIds / updatedAfter+updatedBefore
- updatedAfter/Before 是独立的更新时间窗,与创建时间窗 after/before 分开——
  增量同步按更新时间更准

WarehouseProduct(商品建档,2 项)
- imageUrls:产品测量图(复核长宽高),不是商品主图 imageUrl
- specialOuterPackaging:特殊外包装布尔开关,不是 packageStyle 三选一
  二者原先被判为「语义不同不能顶替」直接丢弃,现在各有独立字段

恒健侧同步映射,并对不完整的附件(缺 name/type/url+base64)本地拒绝。

验证:mvn test 全量通过,恒健 166 个用例(+9)通过。

Co-Authored-By: Claude Code <noreply@anthropic.com>
feature/Walmart
lml 4 days ago
parent
commit
a4c38a4408
  1. 22
      docs-warehouse/hengjian/README.md
  2. 47
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  3. 134
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
  4. 137
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java
  5. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseAttachment.java
  6. 52
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  7. 62
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java
  8. 23
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java
  9. 7
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java
  10. 71
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java
  11. 31
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java
  12. 52
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java

22
docs-warehouse/hengjian/README.md

@ -130,8 +130,8 @@ @@ -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 @@ @@ -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 @@ @@ -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/ @@ -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. 探针用法

47
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java

@ -146,6 +146,20 @@ public final class WarehouseProduct { @@ -146,6 +146,20 @@ public final class WarehouseProduct {
* 5 化妆品 / 6 鞋类 / 7 玩具 / 8 电子 / 9 数码。取值由仓方字典定义,适配器不归一。</p>
*/
private final Integer productCategory;
/**
* 产品测量图片地址列表。
*
* <p><b>不是商品主图</b>:恒健({@code imageUrls})用它在长宽高 / 重量变更时
* 给仓方复核尺寸。没有该概念的仓忽略。</p>
*/
private final List<String> imageUrls;
/**
* 是否特殊外包装:null 未指定 / true 是 / false 否。
*
* <p>与 {@link #packageStyle} 不是一回事:后者是「裸包装 / 销售包装 / 物流包装」三选一,
* 前者是恒健的布尔开关({@code isSpecialOuterPackaging})。</p>
*/
private final Boolean specialOuterPackaging;
/**
* 产品图片地址;null 表示不传。
@ -188,6 +202,9 @@ public final class WarehouseProduct { @@ -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<String>(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 { @@ -396,6 +413,16 @@ public final class WarehouseProduct {
return imageUrl;
}
/** 产品测量图片(复核尺寸用);空表示不传。不可变。 */
public List<String> imageUrls() {
return imageUrls;
}
/** 是否特殊外包装;null 表示不传。 */
public Boolean specialOuterPackaging() {
return specialOuterPackaging;
}
/** 是否给了任何海关信息。 */
public boolean hasCustoms() {
return declaredValue != null;
@ -450,6 +477,8 @@ public final class WarehouseProduct { @@ -450,6 +477,8 @@ public final class WarehouseProduct {
private String remark;
private Integer productCategory;
private String imageUrl;
private final List<String> imageUrls = new java.util.ArrayList<String>();
private Boolean specialOuterPackaging;
private Boolean expirationControl;
private Integer expirationDays;
private Integer packedQuantity;
@ -672,6 +701,24 @@ public final class WarehouseProduct { @@ -672,6 +701,24 @@ public final class WarehouseProduct {
return this;
}
/** 产品测量图片列表;不传表示没有。 */
public Builder imageUrls(List<String> 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 必填项缺失、尺寸/重量非正、海关三项不齐
*/

134
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java

@ -77,6 +77,49 @@ public final class OutboundCommand { @@ -77,6 +77,49 @@ public final class OutboundCommand {
*/
private final Boolean signatureRequired;
// ==================== 仓方协议里有、统一模型原先缺的字段 ====================
/**
* 支付时间(UTC)。null 表示不传,由仓方按当前时间处理。
*
* <p>恒健 {@code paidAt};运去哪等仓没有该入参,忽略。</p>
*/
private final Instant paidAt;
/**
* 提货时间(仅 FBALTL 等自提场景必填)。null 表示不传。
*
* <p>恒健 {@code pickupTime},格式 {@code yyyy-MM-dd}。</p>
*/
private final java.time.LocalDate pickupTime;
/**
* 是否 Amazon VC Direct Fulfillment 订单;null 表示不传(仓方按「否」处理)。
*
* <p>恒健 {@code isDFOrder}。</p>
*/
private final Boolean directFulfillment;
/**
* 第三方账号(third party account)。null 表示不传。
*
* <p>恒健 {@code thirdPartyAccount}。</p>
*/
private final String thirdPartyAccount;
/**
* 仓库备注。null 表示不传。
*
* <p>与 {@link #remark()} 不同:{@code remark} 是客户/买家备注
* (恒健 {@code customerRemark}),本字段是<b>给仓作业看的备注</b>
* (恒健 {@code warehouseRemark})。两者在仓方是两个字段,不能合并。</p>
*/
private final String warehouseRemark;
/**
* 随单下发的附件(面单 / 装箱单 / BOL 等)。
*
* <p>与 {@link #labelContentBase64()} 的关系:那个是<b>平台面单</b>的专用快捷入口
* (运去哪只认这一种),本字段是<b>通用附件列表</b>(恒健支持 7 种类型 + URL)。
* 两者可以同时给;适配器按自己的协议需要取用。</p>
*/
private final List<WarehouseAttachment> 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 { @@ -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<WarehouseAttachment>(b.attachments));
}
public static Builder builder() {
@ -223,6 +273,36 @@ public final class OutboundCommand { @@ -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<WarehouseAttachment> attachments() {
return attachments;
}
public static final class Builder {
private String outboundRequestNo;
@ -247,6 +327,12 @@ public final class OutboundCommand { @@ -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<WarehouseAttachment> attachments = new ArrayList<WarehouseAttachment>();
public Builder outboundRequestNo(String outboundRequestNo) {
this.outboundRequestNo = outboundRequestNo;
@ -376,6 +462,54 @@ public final class OutboundCommand { @@ -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<WarehouseAttachment> v) {
if (v != null) {
for (WarehouseAttachment one : v) {
attachment(one);
}
}
return this;
}
public OutboundCommand build() {
return new OutboundCommand(this);
}

137
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundQuery.java

@ -29,6 +29,32 @@ public final class OutboundQuery { @@ -29,6 +29,32 @@ public final class OutboundQuery {
private final String sortField;
/** 排序方向;null 表示用适配器的默认方向。 */
private final SortDirection sortDirection;
/**
* 渠道账号 / 店铺标识(仓方口径)。null 表示不传。
*
* <p>恒健 {@code channelAccount};运去哪儿等仓没有该过滤项。</p>
*/
private final String channelAccount;
/**
* 平台类型(仓方口径,如 {@code amazon} / {@code ebay})。null 表示不传。
*
* <p>恒健 {@code channel}。与 {@link #channelAccount()} 不同:前者是平台,
* 后者是店铺。</p>
*/
private final String channel;
/** 仓内部订单 id 列表;null 表示不传。恒健 {@code orderIds}(逗号分隔)。 */
private final List<String> providerOrderIds;
/** PO 单号;null 表示不传。恒健 {@code poNo}。 */
private final String poNo;
/**
* 更新时间窗起点(UTC);与 {@link #updatedBefore()} 成对。
*
* <p>与 {@link #after()} 的区别:那个是<b>创建时间</b>窗,这个是<b>更新时间</b>窗。
* 做增量同步时按更新时间更准——已存在的单状态变了也能拉到。</p>
*/
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 { @@ -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<String>(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 { @@ -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<String> 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 { @@ -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 { @@ -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<String> providerOrderIds = new ArrayList<String>();
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 { @@ -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<String> 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);
}

20
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseAttachment.java

@ -17,6 +17,13 @@ public final class WarehouseAttachment { @@ -17,6 +17,13 @@ public final class WarehouseAttachment {
/** 关联包裹号;不区分包裹的仓为 null。 */
private final String packageNo;
private final String remark;
/**
* 附件内容(base64,可带 {@code data:} 前缀);null 表示只给 URL。
*
* <p>下发时用:部分仓(恒健)只收 base64,不认 URL;接口同时支持两者,
* 给了 {@code contentBase64} 时仓方以它为准。查询回来时恒为 null。</p>
*/
private final String contentBase64;
private WarehouseAttachment(Builder b) {
this.name = b.name;
@ -24,6 +31,7 @@ public final class WarehouseAttachment { @@ -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 { @@ -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 { @@ -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);
}

52
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java

@ -471,7 +471,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -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<String, Object> params = new LinkedHashMap<String, Object>();
// rows 上限是文档明写的「默认最高 100」,超过即拒绝(不静默截断)
@ -482,15 +482,33 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -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 @@ -783,6 +801,34 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
return pageSize;
}
/** 逗号拼接(恒健多条单号用逗号分隔)。 */
private static String joinIds(List<String> 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<String, Object> 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);

62
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java

@ -6,6 +6,7 @@ import common.ecommerce.warehouse.enums.LabelMode; @@ -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; @@ -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 { @@ -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 { @@ -173,6 +182,14 @@ public final class HengjianOutboundMapper {
*/
private static List<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> toAttachInfoItems(
OutboundCommand cmd, String orderNo) {
// 1) 通用附件列表:支持 URL 与 base64、7 种类型
List<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> out =
new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>();
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 { @@ -180,7 +197,7 @@ public final class HengjianOutboundMapper {
"hengjian order " + orderNo
+ ": labelContentBase64 is required when labelMode=PLATFORM_LABEL");
}
return new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>();
return out;
}
if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) {
throw new IllegalArgumentException(
@ -196,10 +213,45 @@ public final class HengjianOutboundMapper { @@ -196,10 +213,45 @@ public final class HengjianOutboundMapper {
// 这里统一剥掉,避免把 "data:application/pdf;base64," 当成文件内容解出来
item.file = stripDataUri(content);
item.type = ATTACH_TYPE_SHIPPING_LABEL;
List<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> out =
new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>(1);
out.add(item);
return Collections.unmodifiableList(out);
return out;
}
/**
* 一个通用附件 → 恒健 {@code attachInfoItems} 元素。
*
* <p>恒健要求 {@code url} 与 {@code file} 二选一、{@code name} 与 {@code type} 必填:
* 缺了本地拒绝,不发出去被仓方挡回来。{@code type} 用仓方原值直传——
* 统一模型不归一附件分类(各仓口径不同)。</p>
*/
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,} 头;没有头时原样返回。 */

23
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java

@ -4,6 +4,8 @@ import common.ecommerce.hengjian.dto.HengjianProductSaveDtos; @@ -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; @@ -17,15 +19,10 @@ import common.ecommerce.warehouse.capability.WarehouseProduct;
* 发出去被仓方拒,排查成本比本地报错高得多。</p>
*
* <h2>不发送的字段</h2>
* <table border="1">
* <tr><th>恒健字段</th><th>为什么不发</th></tr>
* <tr><td>{@code imageUrls}</td>
* <td>文档写明是「产品测量图片」,用于复核长宽高,<b>不是商品主图</b>。
* 统一模型的 {@code imageUrl} 是商品图片,语义不同,不能拿来顶替。</td></tr>
* <tr><td>{@code isSpecialOuterPackaging}</td>
* <td>「特殊外包装」与统一模型的 {@code packageStyle}(裸包装 / 销售包装 / 物流包装)
* 不是同一套码,映射需要业务确认,暂时不发。</td></tr>
* </table>
* <p>文档里的 {@code imageUrls}(产品测量图)与 {@code isSpecialOuterPackaging}
* (特殊外包装)已由 {@code WarehouseProduct.imageUrls()} /
* {@code specialOuterPackaging()} 承载——<b>不是</b>商品主图 {@code imageUrl},
* 也不是 {@code packageStyle} 的三选一,语义不同,各自独立下发。</p>
*
* <p>统一模型里的 SN、批次、HS Code、原产国、商品链接、客退处理方式、产品品类,
* 恒健文档都没有对应字段,一律不发。</p>
@ -95,6 +92,14 @@ public final class HengjianProductMapper { @@ -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<String>(product.imageUrls());
}
// 特殊外包装是布尔开关,独立于 packageStyle 的三选一
if (product.specialOuterPackaging() != null) {
req.isSpecialOuterPackaging = product.specialOuterPackaging() ? 1 : 0;
}
return req;
}

7
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java

@ -62,6 +62,13 @@ public final class HengjianCreateOrderDtos { @@ -62,6 +62,13 @@ public final class HengjianCreateOrderDtos {
public Integer isPrime;
/**
* 提货时间,{@code yyyy-MM-dd}。
*
* <p>文档:{@code carrierCode} 为 {@code FBALTL}(自提)时必填。</p>
*/
public String pickupTime;
/**
* 平台要求发货时间,UTC,{@code yyyy-MM-dd HH:mm:ss}。
*
* <p>文档:{@code isDFOrder=1} 时必填。</p>

71
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java

@ -295,7 +295,7 @@ class HengjianCreateOrderTest { @@ -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 { @@ -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() {

31
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderQueryTest.java

@ -341,6 +341,37 @@ class HengjianOrderQueryTest { @@ -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() {

52
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java

@ -206,8 +206,11 @@ class HengjianProductSaveTest { @@ -206,8 +206,11 @@ class HengjianProductSaveTest {
}
/**
* 恒健没有的字段不能编:SN、批次、HS Code、原产国、商品链接、客退处理、品类,
* 以及语义不同的 {@code imageUrls} / {@code isSpecialOuterPackaging}。
* 恒健<b>没有</b>的字段不能编:SN、批次、HS Code、原产国、商品链接、客退处理、品类。
*
* <p>{@code imageUrls} / {@code isSpecialOuterPackaging} 不在此列——恒健有这两个字段,
* 只是语义与 {@code imageUrl} / {@code packageStyle} 不同,见
* {@link #sendsMeasurementImagesAndSpecialPackaging()}。</p>
*/
@Test
void doesNotInventFieldsHengjianDoesNotHave() {
@ -225,14 +228,55 @@ class HengjianProductSaveTest { @@ -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

Loading…
Cancel
Save