From fc1753165d5924e2553d22a0a37474218a6ea4b6 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Thu, 12 Nov 2026 17:22:33 +0800 Subject: [PATCH] =?UTF-8?q?feat(hengjian):=20=E5=AF=B9=E6=8E=A5=E5=95=86?= =?UTF-8?q?=E5=93=81=E5=88=9B=E5=BB=BA=20/=20=E7=BC=96=E8=BE=91=20/v1/prod?= =?UTF-8?q?uct/save?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 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 --- README.md | 12 +- docs-warehouse/hengjian/README.md | 98 +++++- .../ecommerce/hengjian/HengjianConstants.java | 7 + .../hengjian/adapter/HengjianAdapter.java | 36 ++- .../hengjian/adapter/HengjianProductMapper.java | 165 ++++++++++ .../hengjian/dto/HengjianProductSaveDtos.java | 123 ++++++++ .../hengjian/adapter/HengjianDirectoryTest.java | 3 +- .../hengjian/adapter/HengjianProductSaveTest.java | 338 +++++++++++++++++++++ .../hengjian/probe/HengjianWriteProbeTest.java | 126 ++++++++ 9 files changed, 886 insertions(+), 22 deletions(-) create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java create mode 100644 warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java create mode 100644 warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java diff --git a/README.md b/README.md index 54da08e..d5af3c0 100644 --- a/README.md +++ b/README.md @@ -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 │ └── 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 # 单模块 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 # 恒健目录 / 物流渠道 / 商品保存 / 信封校验 ``` --- diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 04b6e5a..696ed37 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -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 @@ | `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 @@ ### 商品(`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/ ├── 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/ │ └── 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 \ - 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 \ | 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")`。 diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java index 4fbca02..5a90283 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java @@ -52,6 +52,13 @@ public final class HengjianConstants { public static final String PATH_WAREHOUSE_CARRIER_GROUP = "/v2/carrierGroup/getWarehouseCarrierGroupServices"; + /** + * 创建 / 编辑产品。 + * + *

接口是保存语义(同一 SKU 再调即更新),响应只有 {@code code/message},没有 data。

+ */ + public static final String PATH_PRODUCT_SAVE = "/v1/product/save"; + /** 业务成功码;文档各接口一致写 {@code 200}。 */ public static final int SUCCESS_CODE = 200; 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 db31303..8fe404e 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 @@ -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; 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; /** * 恒健适配器。 * - *

本期只接只读基础资料:仓库目录、承运商 / 物流产品、按仓的物流渠道。 - * 这几个接口不依赖任何单号、也不产生副作用,是验证鉴权与信封最快的一步; - * 因此只声明 {@code DIRECTORY} 与 {@code LOGISTICS_PRODUCT} 两个能力位。

+ *

已接入:仓库目录、承运商 / 物流产品、按仓的物流渠道(只读), + * 以及商品创建 / 编辑({@code /v1/product/save},保存语义)。

* *

出库 / 库存 / 入库 / 退货等接口尚未接入,能力位不声明: * 门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException},不返回空集合。

@@ -40,11 +42,15 @@ import java.util.Map; *

适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * {@code WarehouseConnection} 传入。

*/ -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 @Override public EnumSet capabilities() { return EnumSet.of( + WarehouseCapability.PRODUCT, WarehouseCapability.DIRECTORY, WarehouseCapability.LOGISTICS_PRODUCT); } + // ------------------------------------------------------------------ 商品 + + /** + * 创建 / 编辑商品({@code POST /v1/product/save})。 + * + *

接口是保存语义:同一 SKU 再调即更新,所以不区分 create 与 update, + * 也不像信仓那样先查一次再决定调哪个接口。

+ * + *

响应只有 {@code code / message},没有 data,因此结果里的 + * {@code status} 固定为 {@code SAVED}、{@code rawStatus} 取仓方的 message—— + * 仓方并不告诉我们这次是新建还是更新,不能替它编。

+ * + * @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")); + } + // ------------------------------------------------------------------ 仓库目录 /** 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 new file mode 100644 index 0000000..005d837 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java @@ -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})。 + * + *

平台字段名只出现在本类与 {@link HengjianProductSaveDtos}。 + * 单位与统一模型一致(cm / g),不做换算。

+ * + *

必填项在本地拒绝

+ *

恒健把 产品尺寸 / 外箱尺寸 / 装箱数量 / 英文名 / 描述 / 发货包装 都标为必填。 + * 统一模型不强制这些(运去哪、信仓的要求各不相同),所以由本映射器按恒健的协议校验: + * 缺了直接抛 {@link IllegalArgumentException},不拿其它字段顶替—— + * 发出去被仓方拒,排查成本比本地报错高得多。

+ * + *

不发送的字段

+ * + * + * + * + * + * + *
恒健字段为什么不发
{@code imageUrls}文档写明是「产品测量图片」,用于复核长宽高,不是商品主图。 + * 统一模型的 {@code imageUrl} 是商品图片,语义不同,不能拿来顶替。
{@code isSpecialOuterPackaging}「特殊外包装」与统一模型的 {@code packageStyle}(裸包装 / 销售包装 / 物流包装) + * 不是同一套码,映射需要业务确认,暂时不发。
+ * + *

统一模型里的 SN、批次、HS Code、原产国、商品链接、客退处理方式、产品品类, + * 恒健文档都没有对应字段,一律不发。

+ */ +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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java new file mode 100644 index 0000000..fe0856c --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java @@ -0,0 +1,123 @@ +package common.ecommerce.hengjian.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.util.List; + +/** + * 恒健报文结构:创建 / 编辑产品({@code POST /v1/product/save})。 + * + *

字段名照抄文档。注意尺寸与重量分三组,含义不同:

+ * + *

三组不能互相顶替:把单品尺寸填进 {@code length} 会让仓方的计费重与货架位算错。

+ */ +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; + + /** + * 产品测量图片地址列表。 + * + *

文档说明「有变更产品长/宽/高重量时传入」——它不是商品主图, + * 而是仓方复核尺寸用的测量照片。

+ */ + public List imageUrls; + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java index cc5be62..8854855 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java @@ -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)); 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 new file mode 100644 index 0000000..d744936 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java @@ -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})契约测试。 + * + *

重点在三件容易出错的事:必填项本地拒绝、三组尺寸不互相顶替、 + * 不在报文里编造恒健没有的字段。

+ */ +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)); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java new file mode 100644 index 0000000..a272dfb --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java @@ -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; + +/** + * 恒健写接口探针:真实创建商品,用于核对 {@code /v1/product/save} 的报文。 + * + *

需要两个开关同时打开,避免误跑在正式环境:

+ *
+ * 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
+ * 
+ * + *

会在仓方测试环境留下真实商品数据:恒健文档里没有删除产品的接口, + * 跑完需要人工在 Efulfill 后台清理。SKU 默认带时间戳,重跑不会撞唯一约束。

+ * + *

输出只打印结果与关键字段,不打印 token。

+ */ +@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(); + } + + /** + * 建商品:验证必填项组合与保存语义。 + * + *

同 SKU 连跑两次可确认 {@code save} 是幂等保存(第二次应为更新而非报重复)。

+ */ + @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 已存在"); + } + } +}