Browse Source

feat(hengjian): 对接商品创建 / 编辑 /v1/product/save

- 新增 HengjianProductSaveDtos + HengjianProductMapper,声明 PRODUCT 能力位
- 保存语义:同 SKU 再调即更新,不区分 create/update;响应无 data,
  status 固定 SAVED、rawStatus 取仓方 message,不编 ADDED/UPDATED
- 恒健必填项(nameEn / description / packingType / 外箱四项 / packedQty)
  在本地拒绝,缺项一个请求都不发
- 三组尺寸(产品 / 单品 / 外箱)各归各位,不做回退填充
- 不发送恒健没有语义对应的字段:imageUrl(恒健是测量图)、packageStyle、
  SN / 批次 / HS / 原产国 / 链接 / 客退 / 品类
- 新增写探针(默认跳过,另需 -Dhengjian.probe.write=true)验证保存幂等
- 文档补商品保存的字段口径与本地校验清单

验证:mvn test 全量通过,恒健 48 个用例 + 2 个探针跳过。

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 1 week ago
parent
commit
fc1753165d
  1. 12
      README.md
  2. 98
      docs-warehouse/hengjian/README.md
  3. 7
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  4. 36
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  5. 165
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java
  6. 123
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java
  7. 3
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java
  8. 338
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java
  9. 126
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java

12
README.md

@ -141,7 +141,7 @@ sequenceDiagram @@ -141,7 +141,7 @@ sequenceDiagram
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;本期只接只读基础资料:仓库目录、物流渠道 / 按仓渠道) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑) |
依赖方向:
```
@ -376,9 +376,11 @@ common.ecommerce @@ -376,9 +376,11 @@ common.ecommerce
│
└── hengjian 恒健三方仓(warehouse-sdk-hengjian)
├── HengjianConstants 测试基址、当前接入路径、双授权头名、成功码 / 未授权码、限流
├── adapter HengjianAdapter(仓库目录 + 承运商 + 按仓渠道)/
│ HengjianAdapterFactory / HengjianDirectoryMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos
├── adapter HengjianAdapter(仓库目录 + 承运商 + 按仓渠道 + 商品保存)/
│ HengjianAdapterFactory / HengjianDirectoryMapper /
│ HengjianProductMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos
├── enums (package-info:调拨 / 出库状态枚举约定,待建)
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter
└── webhook (package-info:文档无回调页,未实现)
@ -1074,7 +1076,7 @@ mvn -pl lingxing test # 单模块 @@ -1074,7 +1076,7 @@ mvn -pl lingxing test # 单模块
mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test
mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试
mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 商品 / 下单 / 转运
mvn -pl warehouse-sdk-hengjian -am test # 恒健仓库目录 / 物流渠道 / 信封校验
mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 物流渠道 / 商品保存 / 信封校验
```
---

98
docs-warehouse/hengjian/README.md

@ -60,9 +60,11 @@ @@ -60,9 +60,11 @@
| 1 | 获取当前组织仓库 | `POST /v2/warehouse/getWarehouse` | `DIRECTORY` | ✅ |
| 2 | 获取物流渠道(全量) | `POST /v2/carrierGroup/getCarrierGroup` | `DIRECTORY` / `LOGISTICS_PRODUCT` | ✅ |
| 3 | 获取仓库支持的物流渠道 | `POST /v2/carrierGroup/getWarehouseCarrierGroupServices` | 同上(适配器方法,非 capability) | ✅ |
| 4 | 回调 | — | — | ❌ 文档无回调页 |
| 4 | 创建 / 编辑产品 | `POST /v1/product/save` | `PRODUCT` | ✅ |
| 5 | 回调 | — | — | ❌ 文档无回调页 |
三个接口都是无副作用查询、都不依赖单号,所以用来先验证鉴权与信封。
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
但只写主数据、不产生履约单据,所以放在第二阶段。
### 返回形状差异
@ -87,6 +89,47 @@ @@ -87,6 +89,47 @@
| `LogisticsProduct.logisticsProductName` | `carrier` + `carrierServiceName` | 统一模型只有一个名称字段,拼成「UPS - Ground」 |
| `LogisticsProduct.crossCountry` | — | 恒健无此维度,恒 false(**不是**「不支持跨国」) |
### 商品保存(`/v1/product/save`)
**保存语义**:同一 SKU 再调即更新,没有单独的 create / update 接口,也不像信仓那样
要先查一次再决定调哪个。响应只有 `code / message`,**没有 data**,所以:
- `ProductResult.status` 固定为 `SAVED`;
- `ProductResult.rawStatus` 取仓方的 `message`(如「产品创建成功」);
- 仓方不告诉这次是新建还是更新,**不替它编** `ADDED` / `UPDATED`。
**三组尺寸不能互相顶替**:
| 恒健字段 | 含义 | 必填 | 统一模型 |
|---|---|---|---|
| `length / width / height / weight` | 产品(发货单元)尺寸与重量 | 是 | `lengthCm / widthCm / heightCm / weightGrams` |
| `itemLength / itemWidth / itemHeight` | 单品尺寸 | 否 | `itemLengthCm / …`(未给不发) |
| `packedLength / packedWidth / packedHeight / packedWeight / packedQty` | 外箱尺寸、外箱重量、装箱数量 | 是 | `packedLengthCm / … / packedQuantity` |
把单品尺寸填进 `length` 会让仓方的计费重与货架位算错,所以适配器不做任何回退填充。
**本地拒绝的必填项**(恒健要求、统一模型不强制):
`nameEn`、`description`、`packingType`(0 原包装 / 1 重新打包)、外箱四项尺寸重量、
`packedQty`。缺任何一项直接抛 `IllegalArgumentException`,**一个请求都不发**。
**不在报文里编造字段**:
| 统一模型字段 | 为什么不发 |
|---|---|
| `imageUrl` | 恒健的 `imageUrls` 是「产品测量图片」(复核长宽高用),不是商品主图;语义不同 |
| `packageStyle` | 恒健的 `isSpecialOuterPackaging` 是「是否特殊外包装」,不是同一套码 |
| `requireSn` / `snManagementMode` / `lotControl*` | 文档无对应字段 |
| `hsCode` / `countryOfOrigin` / `declaredValue` | 恒健只收报关名称(`customName` / `customNameEn`),没有 HS 与原产国 |
| `link` / `returnDealMethod` / `productCategory` | 文档无对应字段 |
**其它口径**:
- `isInsuranceFlag` 是 `Y` / `N`(不是 0 / 1);未指定则整组不发。
- `expirationDate` 只在 `expirationControl = 1` 时发送,避免仓方存「有天数但未启用」的脏数据。
- `cost` 与 `currency` 成对发送;`cost` 缺失则两个都不发。
- 单位与统一模型一致(cm / g),**不做换算**。
## 3. 未接入(文档已有,按需排期)
按能力位分组,路径取自文档(**标注 ⚠ 的表示文档没写路径或路径可疑,需真机核对**):
@ -132,10 +175,20 @@ @@ -132,10 +175,20 @@
### 商品(`PRODUCT`)
`POST /v1/product/save`(创建/编辑)、`POST /v1/product/getBySku`、`GET /v1/productChannel/findByPage`、
`POST /v2/product/queryPage`(分页 SKU,含产品打托信息)、`POST /v1/product/createProductAlias`。
| 接口 | 路径 | 状态 |
|---|---|---|
| 创建 / 编辑产品 | `POST /v1/product/save` | ✅ 已接入 |
| 查询 sku | `POST /v1/product/getBySku` | ⬜ |
| 分页查询 SKU / 产品打托信息 | `POST /v2/product/queryPage` | ⬜ |
| 渠道产品关系查询 | `GET /v1/productChannel/findByPage` | ⬜ |
| 创建产品识别码 | `POST /v1/product/createProductAlias` | ⬜ |
尺寸 cm / 重量 g,与统一模型一致(不需要换算)。
保存接口的字段口径见上一节。注意《查询 sku》页把「产品长」写作 `itemLength`,
而《创建/编辑产品》页写作 `length`——**两页对同一概念用了不同字段名**,
接查询接口时必须真机确认哪个才是产品长(见风险表 #7)。
### 入库(`INBOUND`)
入库计划创建 / 列表 / 查询 / 取消 / 加附件 / 上传附件 / 发运 / 更新到仓日期 / 生成箱标,
@ -160,12 +213,14 @@ warehouse-sdk-hengjian/ @@ -160,12 +213,14 @@ warehouse-sdk-hengjian/
├── main/java/common/ecommerce/hengjian/
│ ├── HengjianConstants.java 端点 / 路径 / 两个授权头 / 成功码 / 未授权码 / 限流
│ ├── adapter/
│ │ ├── HengjianAdapter.java 仓库目录 + 承运商 + 按仓渠道
│ │ ├── HengjianAdapter.java 仓库目录 + 承运商 + 按仓渠道 + 商品保存
│ │ ├── HengjianAdapterFactory.java
│ │ └── HengjianDirectoryMapper.java 字段搬运
│ │ ├── HengjianDirectoryMapper.java 仓库 / 渠道字段搬运
│ │ └── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验
│ ├── dto/
│ │ ├── HengjianWarehouseDtos.java
│ │ └── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
│ │ └── HengjianProductSaveDtos.java /v1/product/save
│ ├── enums/package-info.java 状态枚举约定(待建)
│ ├── http/
│ │ ├── HengjianRequestFactory.java 双授权头 + 链路 ID
@ -174,15 +229,19 @@ warehouse-sdk-hengjian/ @@ -174,15 +229,19 @@ warehouse-sdk-hengjian/
│ └── webhook/package-info.java 文档无回调,未实现
└── test/java/common/ecommerce/hengjian/
├── adapter/HengjianDirectoryTest.java 13 个:请求形状 / 鉴权头 / 映射 / 能力位
├── adapter/HengjianProductSaveTest.java 20 个:必填拒绝 / 三组尺寸 / 不编造字段
├── adapter/HengjianAdapterTest.java 4 个:注册 / 能力拒绝 / 枚举
├── http/HengjianEnvelopeTest.java 11 个:三种信封形态 + 错误路径
└── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true
```
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(28 个 + 1 个跳过)。
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(48 个 + 2 个跳过)。
## 5. 探针用法
只读探针:
```bash
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
-Dhengjian.probe=true \
@ -195,6 +254,20 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ @@ -195,6 +254,20 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
- 4 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重。异常只打印不中断。
- 只读,不建单。
写探针(会留下真实商品数据):
```bash
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
-Dhengjian.probe=true -Dhengjian.probe.write=true \
-Dhengjian.probe.token=<组织token> \
-Dhengjian.probe.sku=PROBE-SKU-001 \
-Dtest=HengjianWriteProbeTest test
```
- 两个开关同时打开才跑;SKU 默认带时间戳,重跑不撞唯一约束。
- 2 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)。
- **恒健没有删除产品的接口**,跑完需要人工在 Efulfill 后台清理。
## 6. 待确认(交给业务方 / 恒健)
| # | 要确认 | 影响 |
@ -206,15 +279,16 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ @@ -206,15 +279,16 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
| 5 | 限流值、单日配额 | 现在是保守默认 2 req/s |
| 6 | 能否在 PR 环境走写操作(建单 / 取消) | 决定全链路探针怎么设计 |
| 7 | 计费 / 测算接口的真实域名 | 文档写的是 `ehenglin.com` / `thebizark.com` |
| 8 | 商品「产品长」到底是 `length` 还是 `itemLength` | 接入商品前必须确认,否则尺寸错位 |
| 8 | 商品「产品长」到底是 `length` 还是 `itemLength` | 《创建/编辑产品》写 `length`、《查询 sku》写 `itemLength`;接查询接口前必须确认,否则尺寸错位 |
| 9 | 是否有沙箱测试 SKU | 建单需要仓方系统里真实存在的 SKU(运去哪的 `lineCode` 就踩过这个坑) |
| 10 | 时区口径 | 文档多处写 UTC,但仓在美国;需真机确认返回的时间到底是不是 UTC |
## 7. 下一步
1. 拿到 token 后跑 `HengjianReadOnlyProbeTest`,把结论补进本文档「文档与实际不一致」表。
1. 拿到 token 后跑 `HengjianReadOnlyProbeTest` 与 `HengjianWriteProbeTest`,把结论补进本文档
「文档与实际不一致」表;重点验商品保存的必填组合与保存语义。
2. 按 [onboarding-checklist.md](../onboarding-checklist.md) 阶段 2 逐接口接入,建议顺序:
**出库(创建 / 详情 / 列表 / 取消)→ 库存(按 SKU + 分页)→ 商品 → 入库 → 退货 v2**。
**出库(创建 / 详情 / 列表 / 取消)→ 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2**。
3. 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
4. 出库状态枚举按 `orderStatusEnum` 全量建(8 个值),未知归 `UNKNOWN`,原值进 `rawStatus`;
注意 `unshipped` / `shipped` 必须精确匹配,不能用 `contains("SHIP")`。

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

@ -52,6 +52,13 @@ public final class HengjianConstants { @@ -52,6 +52,13 @@ public final class HengjianConstants {
public static final String PATH_WAREHOUSE_CARRIER_GROUP =
"/v2/carrierGroup/getWarehouseCarrierGroupServices";
/**
* 创建 / 编辑产品。
*
* <p>接口是保存语义(同一 SKU 再调即更新),响应只有 {@code code/message},没有 data。</p>
*/
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/** 业务成功码;文档各接口一致写 {@code 200}。 */
public static final int SUCCESS_CODE = 200;

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

@ -3,6 +3,7 @@ package common.ecommerce.hengjian.adapter; @@ -3,6 +3,7 @@ package common.ecommerce.hengjian.adapter;
import com.fasterxml.jackson.databind.JsonNode;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos;
import common.ecommerce.hengjian.dto.HengjianProductSaveDtos;
import common.ecommerce.hengjian.dto.HengjianWarehouseDtos;
import common.ecommerce.hengjian.http.HengjianEnvelope;
import common.ecommerce.hengjian.http.HengjianRateLimiter;
@ -13,6 +14,8 @@ import common.ecommerce.http.HttpTransport; @@ -13,6 +14,8 @@ import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseException;
@ -30,9 +33,8 @@ import java.util.Map; @@ -30,9 +33,8 @@ import java.util.Map;
/**
* 恒健适配器。
*
* <p><b>本期只接只读基础资料</b>:仓库目录、承运商 / 物流产品、按仓的物流渠道。
* 这几个接口不依赖任何单号、也不产生副作用,是验证鉴权与信封最快的一步;
* 因此只声明 {@code DIRECTORY} 与 {@code LOGISTICS_PRODUCT} 两个能力位。</p>
* <p><b>已接入</b>:仓库目录、承运商 / 物流产品、按仓的物流渠道(只读),
* 以及商品创建 / 编辑({@code /v1/product/save},保存语义)。</p>
*
* <p>出库 / 库存 / 入库 / 退货等接口<b>尚未接入</b>,能力位不声明:
* 门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException},不返回空集合。</p>
@ -40,11 +42,15 @@ import java.util.Map; @@ -40,11 +42,15 @@ import java.util.Map;
* <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。</p>
*/
public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable {
public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable,
WarehouseProductCapable {
private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses";
private static final String OP_CARRIERS = "warehouse.directory.carriers";
private static final String OP_LOGISTICS_PRODUCTS = "warehouse.logistics.products";
private static final String OP_PRODUCT_SAVE = "warehouse.product.create";
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
private final HttpTransport transport;
private final JacksonJsonCodec json;
@ -71,10 +77,32 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -71,10 +77,32 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
@Override
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(
WarehouseCapability.PRODUCT,
WarehouseCapability.DIRECTORY,
WarehouseCapability.LOGISTICS_PRODUCT);
}
// ------------------------------------------------------------------ 商品
/**
* 创建 / 编辑商品({@code POST /v1/product/save})。
*
* <p>接口是<b>保存语义</b>:同一 SKU 再调即更新,所以不区分 create 与 update,
* 也不像信仓那样先查一次再决定调哪个接口。</p>
*
* <p>响应只有 {@code code / message},<b>没有 data</b>,因此结果里的
* {@code status} 固定为 {@code SAVED}、{@code rawStatus} 取仓方的 message——
* 仓方并不告诉我们这次是新建还是更新,不能替它编。</p>
*
* @throws IllegalArgumentException 恒健要求但统一模型未给的非空字段缺失(本地拒绝)
*/
@Override
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
HengjianProductSaveDtos.SaveProductRequest body = HengjianProductMapper.toRequest(product);
String raw = execute(ctx, HengjianConstants.PATH_PRODUCT_SAVE, body, OP_PRODUCT_SAVE);
return ProductResult.of(body.sku, SAVED, json.stringAt(raw, "message"));
}
// ------------------------------------------------------------------ 仓库目录
/**

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

@ -0,0 +1,165 @@ @@ -0,0 +1,165 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianProductSaveDtos;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.capability.WarehouseProduct;
/**
* 恒健商品报文映射({@code POST /v1/product/save})。
*
* <p>平台字段名只出现在本类与 {@link HengjianProductSaveDtos}。
* 单位与统一模型一致(cm / g),不做换算。</p>
*
* <h2>必填项在本地拒绝</h2>
* <p>恒健把 <b>产品尺寸 / 外箱尺寸 / 装箱数量 / 英文名 / 描述 / 发货包装</b> 都标为必填。
* 统一模型不强制这些(运去哪、信仓的要求各不相同),所以由本映射器按恒健的协议校验:
* 缺了直接抛 {@link IllegalArgumentException},<b>不拿其它字段顶替</b>——
* 发出去被仓方拒,排查成本比本地报错高得多。</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>统一模型里的 SN、批次、HS Code、原产国、商品链接、客退处理方式、产品品类,
* 恒健文档都没有对应字段,一律不发。</p>
*/
public final class HengjianProductMapper {
/** 保价开关的开 / 关取值(恒健用 Y / N,不是 0 / 1)。 */
private static final String INSURED_YES = "Y";
private static final String INSURED_NO = "N";
private HengjianProductMapper() {
}
/**
* 统一商品 → 恒健保存请求。
*
* @param product 已通过 {@link WarehouseProduct} 构造期校验的商品
* @throws IllegalArgumentException 恒健要求但统一模型未给的非空字段缺失
*/
public static HengjianProductSaveDtos.SaveProductRequest toRequest(WarehouseProduct product) {
String sku = skuOf(product);
HengjianProductSaveDtos.SaveProductRequest req = new HengjianProductSaveDtos.SaveProductRequest();
req.sku = sku;
req.upc = trimToNull(product.barcode());
req.productType = product.productType() > 0 ? product.productType() : null;
req.name = require(product.name(), "name", sku);
req.nameEn = require(product.nameEn(), "nameEn", sku);
req.description = require(product.description(), "description", sku);
req.packingType = requirePackingType(product, sku);
// 产品尺寸与重量:WarehouseProduct 构造期已保证为正
req.length = product.lengthCm();
req.width = product.widthCm();
req.height = product.heightCm();
req.weight = product.weightGrams();
// 外箱五项同为必填,缺一不可
req.packedLength = requirePacked(product.packedLengthCm(), "packedLengthCm", sku);
req.packedWidth = requirePacked(product.packedWidthCm(), "packedWidthCm", sku);
req.packedHeight = requirePacked(product.packedHeightCm(), "packedHeightCm", sku);
req.packedWeight = requirePacked(product.packedWeightGrams(), "packedWeightGrams", sku);
req.packedQty = requirePackedQty(product, sku);
// 单品尺寸选填;未给(0)不发
req.itemLength = positiveOrNull(product.itemLengthCm());
req.itemWidth = positiveOrNull(product.itemWidthCm());
req.itemHeight = positiveOrNull(product.itemHeightCm());
req.expirationControl = flagOf(product.expirationControl());
// 没开保质期管理就不该带天数,避免仓方按「已设保质期但未启用」存脏数据
req.expirationDate = Boolean.TRUE.equals(product.expirationControl())
? product.expirationDays() : null;
Money cost = product.cost();
if (cost != null) {
req.cost = cost.amount().doubleValue();
req.currency = cost.currency().getCurrencyCode();
}
req.isInsuranceFlag = insuranceFlag(product.insured());
if (product.insuranceFee() != null) {
req.isInsuranceRate = product.insuranceFee().amount().doubleValue();
}
req.remark = trimToNull(product.remark());
req.customName = trimToNull(product.declaredName());
req.customNameEn = trimToNull(product.declaredNameEn());
return req;
}
/** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */
public static String skuOf(WarehouseProduct product) {
String providerSku = product.providerSku();
if (providerSku != null && !providerSku.trim().isEmpty()) {
return providerSku.trim();
}
return product.omsSku();
}
/** 0 原包装发货 / 1 重新打包;未给(-1)在恒健是必填,直接拒绝。 */
private static Integer requirePackingType(WarehouseProduct product, String sku) {
int packingType = product.packingType();
if (packingType < 0) {
throw new IllegalArgumentException(
"hengjian product " + sku + " requires packingType (0 原包装发货 / 1 重新打包)");
}
return packingType;
}
private static Double requirePacked(Double value, String field, String sku) {
if (value == null || value <= 0) {
throw new IllegalArgumentException("hengjian product " + sku + " requires " + field
+ " (外箱尺寸与重量是必填项)");
}
return value;
}
private static Integer requirePackedQty(WarehouseProduct product, String sku) {
Integer qty = product.packedQuantity();
if (qty == null || qty <= 0) {
throw new IllegalArgumentException("hengjian product " + sku
+ " requires packedQuantity (装箱数量是必填项)");
}
return qty;
}
/** 0/1 开关 → Integer;null 不发(由仓方按默认处理)。 */
private static Integer flagOf(Boolean flag) {
return flag == null ? null : (flag ? 1 : 0);
}
/** 保价开关 → 恒健的 {@code Y / N};null 不发。 */
private static String insuranceFlag(Boolean insured) {
return insured == null ? null : (insured ? INSURED_YES : INSURED_NO);
}
private static Double positiveOrNull(double v) {
return v > 0 ? v : null;
}
private static String require(String value, String field, String sku) {
if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException("hengjian product " + sku + " requires " + field);
}
return value.trim();
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String trimmed = v.trim();
return trimmed.isEmpty() ? null : trimmed;
}
}

123
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java

@ -0,0 +1,123 @@ @@ -0,0 +1,123 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 恒健报文结构:创建 / 编辑产品({@code POST /v1/product/save})。
*
* <p>字段名照抄文档。注意<b>尺寸与重量分三组,含义不同</b>:</p>
* <ul>
* <li>{@code length / width / height / weight}:产品(发货单元)尺寸与重量;</li>
* <li>{@code itemLength / itemWidth / itemHeight}:单品尺寸,选填;</li>
* <li>{@code packedLength / packedWidth / packedHeight / packedWeight / packedQty}:
* 外箱尺寸、外箱重量与装箱数量,<b>文档标必填</b>。</li>
* </ul>
* <p>三组不能互相顶替:把单品尺寸填进 {@code length} 会让仓方的计费重与货架位算错。</p>
*/
public final class HengjianProductSaveDtos {
private HengjianProductSaveDtos() {
}
/** 保存请求;响应没有 data,只有一个 {@code message}。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaveProductRequest {
/** 产品 SKU;必填。 */
public String sku;
/** UPC 编码;选填。 */
public String upc;
/** 产品类型:1 成品 / 2 配件 / 3 耗材;不传由仓方按默认处理。 */
public Integer productType;
/** 中文名称;必填。 */
public String name;
/** 英文名称;必填。 */
public String nameEn;
/** 产品描述;必填。 */
public String description;
/** 产品发货包装:0 原包装发货 / 1 重新打包;必填。 */
public Integer packingType;
/** 产品长(cm);必填。 */
public Double length;
/** 产品宽(cm);必填。 */
public Double width;
/** 产品高(cm);必填。 */
public Double height;
/** 产品重量(g);必填。 */
public Double weight;
/** 外箱长(cm);必填。 */
public Double packedLength;
/** 外箱宽(cm);必填。 */
public Double packedWidth;
/** 外箱高(cm);必填。 */
public Double packedHeight;
/** 外箱重量(g);必填。 */
public Double packedWeight;
/** 装箱数量;必填。 */
public Integer packedQty;
/** 单品长(cm);选填。 */
public Double itemLength;
/** 单品宽(cm);选填。 */
public Double itemWidth;
/** 单品高(cm);选填。 */
public Double itemHeight;
/** 保质期管理:0 否 / 1 是;不填默认为否。 */
public Integer expirationControl;
/** 保质期天数;{@code expirationControl=1} 时才有意义。 */
public Integer expirationDate;
/** 成本。 */
public Double cost;
/** 币种,如 {@code USD}。 */
public String currency;
/** 是否保价:{@code Y} / {@code N};不填默认为否。 */
public String isInsuranceFlag;
/** 保价费用。 */
public Double isInsuranceRate;
/** 备注。 */
public String remark;
/** 报关中文名。 */
public String customName;
/** 报关英文名。 */
public String customNameEn;
/** 是否特殊外包装:0 否 / 1 是。 */
public Integer isSpecialOuterPackaging;
/**
* 产品测量图片地址列表。
*
* <p>文档说明「有变更产品长/宽/高重量时传入」——它不是商品主图,
* 而是仓方复核尺寸用的测量照片。</p>
*/
public List<String> imageUrls;
}
}

3
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java

@ -227,11 +227,12 @@ class HengjianDirectoryTest { @@ -227,11 +227,12 @@ class HengjianDirectoryTest {
// ---------------------------------------------------------------- 能力位
@Test
void declaresOnlyReadOnlyDirectoryCapabilities() {
void declaresDirectoryAndProductCapabilitiesOnly() {
HengjianAdapter adapter = adapter(RecordingTransport.create());
assertTrue(adapter.capabilities().contains(WarehouseCapability.DIRECTORY));
assertTrue(adapter.capabilities().contains(WarehouseCapability.LOGISTICS_PRODUCT));
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
// 出库 / 库存 / 入库 / 退货都还没接:声明了就必须有实现
assertTrue(!adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));

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

@ -0,0 +1,338 @@ @@ -0,0 +1,338 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 商品创建 / 编辑({@code POST /v1/product/save})契约测试。
*
* <p>重点在三件容易出错的事:必填项本地拒绝、三组尺寸不互相顶替、
* 不在报文里编造恒健没有的字段。</p>
*/
class HengjianProductSaveTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-12T00:00:00Z"), ZoneOffset.UTC);
private static final String SAVE_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"产品创建成功\"}";
private static WarehouseContext ctx() {
return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build()),
"req-1", CLOCK);
}
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
private static RecordingTransport saving() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(SAVE_BODY));
}
/** 一份满足恒健全部必填项的商品。 */
private static WarehouseProduct.Builder product() {
return WarehouseProduct.builder()
.omsSku("DM00001")
.name("测试商品")
.nameEn("Test Product")
.description("用于契约测试的商品")
.packingType(1)
.lengthCm(30)
.widthCm(20)
.heightCm(10)
.weightGrams(500)
.packedQuantity(6)
.packedLengthCm(60.0)
.packedWidthCm(40.0)
.packedHeightCm(30.0)
.packedWeightGrams(3200.0);
}
// ---------------------------------------------------------------- 请求形状
@Test
void sendsPostToProductSave() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().build());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/product/save",
transport.lastDataRequest().url());
}
/** 文档必填的字段必须全部出现在报文里。 */
@Test
void sendsAllMandatoryFields() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().build());
String body = transport.lastDataRequest().body();
String[] mandatory = {"sku", "name", "nameEn", "description", "packingType",
"length", "width", "height", "weight",
"packedLength", "packedWidth", "packedHeight", "packedWeight", "packedQty"};
for (String field : mandatory) {
assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body);
}
}
/**
* 三组尺寸各归各位:产品尺寸、单品尺寸、外箱尺寸不能互相顶替。
* 顶替会让仓方的计费重与货架位算错。
*/
@Test
void keepsThreeDimensionGroupsSeparate() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product()
.itemLengthCm(12.5)
.itemWidthCm(8)
.itemHeightCm(3.5)
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"length\":30.0"), body);
assertTrue(body.contains("\"width\":20.0"), body);
assertTrue(body.contains("\"height\":10.0"), body);
assertTrue(body.contains("\"itemLength\":12.5"), body);
assertTrue(body.contains("\"itemWidth\":8.0"), body);
assertTrue(body.contains("\"itemHeight\":3.5"), body);
assertTrue(body.contains("\"packedLength\":60.0"), body);
assertTrue(body.contains("\"packedWidth\":40.0"), body);
assertTrue(body.contains("\"packedHeight\":30.0"), body);
assertTrue(body.contains("\"packedWeight\":3200.0"), body);
assertTrue(body.contains("\"packedQty\":6"), body);
}
/** 单品尺寸选填:没给就不出现在报文里,不能填 0 占位。 */
@Test
void omitsOptionalItemDimensionsWhenAbsent() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().build());
String body = transport.lastDataRequest().body();
assertFalse(body.contains("itemLength"), body);
assertFalse(body.contains("itemWidth"), body);
assertFalse(body.contains("itemHeight"), body);
}
/** 没开保质期管理就不带天数,避免仓方存「已设天数但未启用」的脏数据。 */
@Test
void expirationDaysOnlySentWhenControlOn() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().expirationDays(365).build());
assertFalse(transport.lastDataRequest().body().contains("expirationDate"),
"未启用保质期管理时不应发送天数");
RecordingTransport on = saving();
adapter(on).createOrUpdate(ctx(), product().expirationControl(true).expirationDays(365).build());
String body = on.lastDataRequest().body();
assertTrue(body.contains("\"expirationControl\":1"), body);
assertTrue(body.contains("\"expirationDate\":365"), body);
}
/** 保价开关用 Y / N,不是 0 / 1。 */
@Test
void insuranceFlagUsesYn() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product()
.insured(true)
.insuranceFee(Money.of("2.50", "USD"))
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"isInsuranceFlag\":\"Y\""), body);
assertTrue(body.contains("\"isInsuranceRate\":2.5"), body);
RecordingTransport no = saving();
adapter(no).createOrUpdate(ctx(), product().insured(false).build());
assertTrue(no.lastDataRequest().body().contains("\"isInsuranceFlag\":\"N\""));
}
/** 未指定保价时整组不发,由仓方按默认(否)处理。 */
@Test
void insuranceFieldsOmittedWhenUnspecified() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().build());
String body = transport.lastDataRequest().body();
assertFalse(body.contains("isInsuranceFlag"), body);
assertFalse(body.contains("isInsuranceRate"), body);
}
@Test
void mapsCostCurrencyAndCustomsNames() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product()
.cost(Money.of("12.30", "USD"))
.declaredName("测试品")
.declaredNameEn("Test Item")
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"cost\":12.3"), body);
assertTrue(body.contains("\"currency\":\"USD\""), body);
assertTrue(body.contains("\"customName\":\"测试品\""), body);
assertTrue(body.contains("\"customNameEn\":\"Test Item\""), body);
}
/** 仓侧 SKU 优先。 */
@Test
void providerSkuWins() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().providerSku("HJ-SKU-1").build());
assertTrue(transport.lastDataRequest().body().contains("\"sku\":\"HJ-SKU-1\""));
}
/**
* 恒健没有的字段不能编:SN、批次、HS Code、原产国、商品链接、客退处理、品类,
* 以及语义不同的 {@code imageUrls} / {@code isSpecialOuterPackaging}。
*/
@Test
void doesNotInventFieldsHengjianDoesNotHave() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product()
.imageUrl("https://example.com/main.jpg")
.productCategory(5)
.packageStyle(1)
.requireSn(1)
.link("https://example.com/p/1")
.hsCode("9503.00")
.countryOfOrigin("CN")
.lotControlEnabled(true)
.lotAttributeCode("LOT")
.build());
String body = transport.lastDataRequest().body();
String[] absent = {"imageUrls", "productCategory", "packageStyle", "isRequireSn",
"snMgmtMode", "link", "hsCode", "countryOfOrigin", "customs",
"lotControl", "returnDealMethod", "isSpecialOuterPackaging"};
for (String field : absent) {
assertFalse(body.contains("\"" + field + "\""), "不应发送恒健没有的字段 " + field + ",body=" + body);
}
}
// ---------------------------------------------------------------- 本地必填校验
@Test
void rejectsMissingNameEn() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), product().nameEn(null).build()));
assertTrue(ex.getMessage().contains("nameEn"), ex.getMessage());
}
@Test
void rejectsMissingDescription() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), product().description(null).build()));
assertTrue(ex.getMessage().contains("description"), ex.getMessage());
}
@Test
void rejectsMissingPackingType() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), product().packingType(-1).build()));
assertTrue(ex.getMessage().contains("packingType"), ex.getMessage());
}
/** 外箱五项缺任何一个都本地拒绝,不静默补值。 */
@Test
void rejectsMissingPackedDimensions() {
String[] fields = {"packedLengthCm", "packedWidthCm", "packedHeightCm", "packedWeightGrams"};
for (String field : fields) {
WarehouseProduct.Builder b = product();
if ("packedLengthCm".equals(field)) {
b.packedLengthCm(null);
} else if ("packedWidthCm".equals(field)) {
b.packedWidthCm(null);
} else if ("packedHeightCm".equals(field)) {
b.packedHeightCm(null);
} else {
b.packedWeightGrams(null);
}
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), b.build()), field);
assertTrue(ex.getMessage().contains("packedLengthCm") || ex.getMessage().contains("外箱"),
ex.getMessage());
}
}
@Test
void rejectsMissingPackedQuantity() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), product().packedQuantity(null).build()));
assertTrue(ex.getMessage().contains("packedQuantity"), ex.getMessage());
}
/** 校验失败时一个请求都不该发出去。 */
@Test
void noRequestSentWhenValidationFails() {
RecordingTransport transport = saving();
assertThrows(IllegalArgumentException.class,
() -> adapter(transport).createOrUpdate(ctx(), product().nameEn(null).build()));
assertTrue(transport.dataRequests().isEmpty(), "本地校验失败不应发出请求");
}
// ---------------------------------------------------------------- 响应
@Test
void resultCarriesSkuAndProviderMessage() {
WarehouseProductCapable.ProductResult result =
adapter(saving()).createOrUpdate(ctx(), product().build());
assertEquals("DM00001", result.providerSku());
assertEquals("SAVED", result.status());
assertEquals("产品创建成功", result.rawStatus(), "仓方没有 data,只回 message");
}
/** 空 body 不能被当成成功。 */
@Test
void emptyResponseBodyIsRejected() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(""));
assertThrows(RuntimeException.class,
() -> adapter(transport).createOrUpdate(ctx(), product().build()));
}
@Test
void businessErrorIsPropagated() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(
"{\"statusCode\":500,\"status\":1,\"code\":500,\"message\":\"sku 已存在\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).createOrUpdate(ctx(), product().build()));
assertTrue(ex.getMessage().contains("sku 已存在"), ex.getMessage());
}
// ---------------------------------------------------------------- 能力位
@Test
void declaresProductCapability() {
assertTrue(adapter(RecordingTransport.create()).capabilities()
.contains(WarehouseCapability.PRODUCT));
}
}

126
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java

@ -0,0 +1,126 @@ @@ -0,0 +1,126 @@
package common.ecommerce.hengjian.probe;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.adapter.HengjianAdapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
import java.time.Clock;
/**
* 恒健<b>写接口</b>探针:真实创建商品,用于核对 {@code /v1/product/save} 的报文。
*
* <p>需要两个开关同时打开,避免误跑在正式环境:</p>
* <pre>
* mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
* -Dhengjian.probe=true -Dhengjian.probe.write=true \
* -Dhengjian.probe.token=你的组织token \
* -Dhengjian.probe.sku=PROBE-SKU-001 \
* -Dtest=HengjianWriteProbeTest test
* </pre>
*
* <p><b>会在仓方测试环境留下真实商品数据</b>:恒健文档里没有删除产品的接口,
* 跑完需要人工在 Efulfill 后台清理。SKU 默认带时间戳,重跑不会撞唯一约束。</p>
*
* <p>输出只打印结果与关键字段,不打印 token。</p>
*/
@EnabledIfSystemProperty(named = "hengjian.probe.write", matches = "true")
class HengjianWriteProbeTest {
private static final String TOKEN = System.getProperty("hengjian.probe.token", "");
private static final String BASE_URL = opt("hengjian.probe.baseUrl", HengjianConstants.TEST_BASE_URL);
private static final String WAREHOUSE_CODE = opt("hengjian.probe.warehouseCode", "HJ-PROBE");
private static final String PROVIDER_WAREHOUSE = opt("hengjian.probe.providerWarehouseId", "EFCA");
private static final String SKU =
opt("hengjian.probe.sku", "PROBE-" + System.currentTimeMillis());
private static String opt(String key, String fallback) {
String v = System.getProperty(key);
return v == null || v.trim().isEmpty() ? fallback : v.trim();
}
private static WarehouseContext ctx() {
return WarehouseContext.of(WAREHOUSE_CODE, WarehouseProvider.HENGJIAN, PROVIDER_WAREHOUSE,
WarehouseConnection.of(BASE_URL,
ChannelSecret.builder().appSecret(TOKEN.trim()).build()),
"probe-" + System.currentTimeMillis(), Clock.systemUTC());
}
private static HengjianAdapter adapter() {
return new HengjianAdapter(new OkHttpTransport("common-ecommerce-hengjian-probe"),
new JacksonJsonCodec());
}
private static void assumeToken() {
Assumptions.assumeTrue(!TOKEN.trim().isEmpty(),
"未提供 -Dhengjian.probe.token,跳过恒健写探针");
}
/** 一份满足恒健全部必填项的商品。 */
private static WarehouseProduct product(String sku) {
return WarehouseProduct.builder()
.omsSku(sku)
.name("探针商品")
.nameEn("Probe Product")
.description("SDK 探针创建,可删除")
.packingType(1)
.lengthCm(30)
.widthCm(20)
.heightCm(10)
.weightGrams(500)
.packedQuantity(6)
.packedLengthCm(60.0)
.packedWidthCm(40.0)
.packedHeightCm(30.0)
.packedWeightGrams(3200.0)
.cost(Money.of("1.00", "USD"))
.build();
}
/**
* 建商品:验证必填项组合与保存语义。
*
* <p>同 SKU 连跑两次可确认 {@code save} 是幂等保存(第二次应为更新而非报重复)。</p>
*/
@Test
void probeProductSave() {
assumeToken();
System.out.println("\n================ hengjian / v1/product/save ================");
System.out.println(" sku=" + SKU + " base=" + BASE_URL + " warehouse=" + PROVIDER_WAREHOUSE);
try {
WarehouseProductCapable.ProductResult result =
adapter().createOrUpdate(ctx(), product(SKU));
System.out.println(" [OK] status=" + result.status()
+ " providerSku=" + result.providerSku()
+ " rawStatus=" + result.rawStatus());
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage());
}
}
/** 再存一次:确认保存语义(更新)不会因 SKU 重复而失败。 */
@Test
void probeProductSaveTwice() {
assumeToken();
System.out.println("\n================ hengjian / v1/product/save (second save) ================");
try {
WarehouseProductCapable.ProductResult result =
adapter().createOrUpdate(ctx(), product(SKU));
System.out.println(" [OK] 第二次保存 status=" + result.status()
+ " rawStatus=" + result.rawStatus());
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage()
+ " ← 若非幂等保存,这里会报 SKU 已存在");
}
}
}
Loading…
Cancel
Save