From 72982e28068c83102fa8e8555118d30827a06625 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Tue, 17 Nov 2026 16:57:00 +0800 Subject: [PATCH] =?UTF-8?q?test(hengjian):=20=E5=8F=AA=E8=AF=BB=E6=8E=A2?= =?UTF-8?q?=E9=92=88=E8=A1=A5=E5=85=A8=E5=85=A8=E9=83=A8=E6=9F=A5=E8=AF=A2?= =?UTF-8?q?=E6=8E=A5=E5=8F=A3=EF=BC=8C=E5=B9=B6=E7=94=A8=E7=9C=9F=E6=9C=BA?= =?UTF-8?q?=E7=BB=93=E6=9E=9C=E4=BF=AE=205=20=E5=A4=84=E6=98=A0=E5=B0=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 探针从 7 个用例扩到 21 个,覆盖全部已接入的查询接口(商品 / 库存 / 入库 / 调拨 / 退货 / 销毁 / 试算 / 地址 / 计费 / 目录)。 真机跑通 14 个接口,暴露并修掉这些问题: - 运费试算必须给「发运仓库」或「发运邮编」其一,否则 400。发运仓的 字段名是 warehouseCode,shipWarehouseCode / orgWarehouseCode / shipFromWarehouseCode 都不认(逐个试过)。core 的 FeeEstimateQuery 补 shipFromWarehouseCode,适配器用账户仓兜底 - 试算的 shipper* 给了不完整会报「发货人信息不完整」,所以要么只给 warehouseCode,要么给全五项 - 商品查询 length 真机确实有(文档响应表漏了),之前的兜底没触发 - 商品 nameEn 空值返回字符串 "null" 而不是 JSON null,trimToNull 一并当空 - 商品 cost 可为 0.0,是合法成本,原先当「没给」丢掉;且误塞进了 declaredValue(语义是申报价值),改为 cost - isInsuranceRate 是费率不是金额,不再塞进 insuranceFee(Money 是金额语义) - 响应有文档没写的 productStatus,保留原值到 rawStatus 另记录一条仓方故障:chargingSettlement 的 STORAGE 类型在测试环境返回 code=999999 + Elasticsearch scroll 异常,是恒健侧 ES 故障,我方报文正确。 销毁查询路径仍 404,探针标注未覆盖。token 只从 -Dhengjian.probe.token 读, 不入库。 mvn test 全量通过。 --- docs-warehouse/hengjian/README.md | 48 +++ .../warehouse/model/FeeEstimateQuery.java | 20 + .../ecommerce/hengjian/HengjianConstants.java | 13 + .../hengjian/adapter/HengjianAdapter.java | 3 +- .../hengjian/adapter/HengjianEstimateMapper.java | 12 + .../adapter/HengjianProductQueryMapper.java | 22 +- .../hengjian/dto/HengjianFeeEstimateDtos.java | 12 + .../hengjian/dto/HengjianProductQueryDtos.java | 9 + .../hengjian/probe/HengjianReadOnlyProbeTest.java | 417 ++++++++++++++++++++- 9 files changed, 536 insertions(+), 20 deletions(-) diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 3f6b80a..5e1a8f1 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -1088,3 +1088,51 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ 出库子能力到此全部接完(下单 / 详情 / 列表 / 取消 / 预判 / 包裹)。剩下与出库相关的是 订单上传附件与物流异动单,都不影响主链路,按需排期。 + +## 真机探针记录(2026-11-17,只读) + +`HengjianReadOnlyProbeTest` 用真实 token 跑了全部查询接口,结论如下。 + +### 可用 + +| 接口 | 实测 | +|---|---| +| `POST /v2/warehouse/getWarehouse` | 55 个仓 | +| `POST /v2/carrierGroup/getCarrierGroup` | 95 个物流产品 | +| `POST /v2/carrierGroup/getWarehouseCarrierGroupServices` | EFCA 91 个 | +| `POST /v2/product/queryPage` | **799 条**,分页正常 | +| `GET /v1/saleOrder/findByPage` | 正常,**回 `orderId`** | +| `POST /v1/saleOrder/findOne` | 正常 | +| `GET /v2/inventory/get_inventory_by_page` | 正常 | +| `POST /v1/inventory/getInventory` | 正常(按 SKU 14 条) | +| `POST /v1/inbound/getInboundPlanPage` / `getInboundPlanInfo` | 正常 | +| `POST /v1/transferPlan/findByPage` | 正常 | +| `POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage` / `getReturnPlanOrderInfo` | 正常 | +| `POST /v1/saleReturn/getReturnPlanHandlePage` | 正常,页码 0 基 | +| `POST /v2/api/shipping/calculate` | 正常(需发运仓) | +| `POST /v2/api/shipping/addressClassification` | 路径通,但该地址回 `UNKNOWN` | + +### 真机纠正的错误 + +| 项 | 文档 | 真机 | +|---|---|---| +| 试算发运仓字段 | 只列 `shipper*` | **`warehouseCode`**;`shipper*` 给了不全会报「发货人信息不完整」 | +| 试算必填 | `shipper*` 全必填 | 「发运仓库」或「发运邮编」**至少一个** | +| 商品查询 `length` | 响应表没这一项 | **有**,且有值 | +| 商品查询 `productStatus` | 没有 | **有**(样例值 1),含义未确认,只存原值 | +| 商品 `nameEn` | STRING | 空值返回**字符串 `"null"`**,不是 JSON null | +| 商品 `cost` | DOUBLE | 可为 **0.0**,是合法成本不是「没给」 | +| 商品 `isInsuranceRate` | 保价费率 | 是**费率**不是金额,不能塞进 `insuranceFee` | + +### 仓方自身故障(非我方问题) + +`POST /v1/chargingSettlement/getChargingStorageSettlement` 在测试环境回 +`code=999999` + Elasticsearch scroll 异常(`charging_storage_settlements` 索引)。 +**这是恒健侧 ES 故障**,我方报文正确。 + +### 未覆盖 + +| 接口 | 原因 | +|---|---| +| `POST /v2/destroyPlanOrder/find` | 路径仍 404(26 个变体全试过) | +| `POST /v1/saleReturn/getReturnPlanHandlePage` 的分页游标 | 恒健返回 `number` 是 0 基,适配器已按 +2 处理 | diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java index bbb1aae..0ccaf75 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java @@ -21,6 +21,13 @@ public final class FeeEstimateQuery { /** 发货仓 code;空表示用账户配置的仓。 */ private final List warehouseCodes; + /** + * 发货仓 code;null 表示由适配器用账户仓兜底。 + * + *

恒健的试算必须给「发运仓库」或「发运邮编」其一,否则回 + * 「发运仓库和发运邮编不能同时为空」;字段名是 {@code warehouseCode}(不是 shipper*)。

+ */ + private final String shipFromWarehouseCode; private final BigDecimal lengthCm; private final BigDecimal widthCm; private final BigDecimal heightCm; @@ -42,6 +49,7 @@ public final class FeeEstimateQuery { private FeeEstimateQuery(Builder b) { this.warehouseCodes = Collections.unmodifiableList(new ArrayList(b.warehouseCodes)); + this.shipFromWarehouseCode = b.shipFromWarehouseCode; this.lengthCm = requirePositive(b.lengthCm, "lengthCm"); this.widthCm = requirePositive(b.widthCm, "widthCm"); this.heightCm = requirePositive(b.heightCm, "heightCm"); @@ -65,6 +73,11 @@ public final class FeeEstimateQuery { } /** 发货仓 code 列表;空表示用账户配置的仓。 */ + /** 发运仓 code;null 表示用账户仓。 */ + public String shipFromWarehouseCode() { + return shipFromWarehouseCode; + } + public List warehouseCodes() { return warehouseCodes; } @@ -166,6 +179,7 @@ public final class FeeEstimateQuery { public static final class Builder { private final List warehouseCodes = new ArrayList(); + private String shipFromWarehouseCode; private BigDecimal lengthCm; private BigDecimal widthCm; private BigDecimal heightCm; @@ -181,6 +195,12 @@ public final class FeeEstimateQuery { private String logisticsProductCode; private String signService; + /** 发运仓 code;不传时适配器用账户仓兜底。 */ + public Builder shipFromWarehouseCode(String v) { + this.shipFromWarehouseCode = v; + return this; + } + public Builder warehouseCode(String v) { if (v != null && !v.trim().isEmpty()) { this.warehouseCodes.add(v.trim()); 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 81c508a..377a799 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 @@ -161,6 +161,19 @@ public final class HengjianConstants { *

真机确认存在;包裹四项 + 两个单位 + 收货方五项必填 * ({@code shipper*} 系列可省)。

*/ + /** + * 运费试算({@code POST})。 + * + *

真机确认(2026-11-17):必须给「发运仓库」或「发运邮编」其一, + * 否则回 {@code 400 发运仓库和发运邮编不能同时为空}。发运仓的字段名是 + * {@code warehouseCode}——{@code shipWarehouseCode} / + * {@code orgWarehouseCode} / {@code shipFromWarehouseCode} 都不认(逐个试过)。

+ * + *

另:{@code shipper*} 系列给了不完整会回 {@code 400 发货人信息不完整}, + * 所以要么给全(国家 + 州 + 城市 + 地址 + 邮编),要么只给 {@code warehouseCode}。 + * 给 {@code carrier} / {@code serviceCode} 而库里没有该渠道时会回 + * {@code 400 承运商服务代码不存在}。

+ */ public static final String PATH_FEE_ESTIMATE = "/v2/api/shipping/calculate"; /** 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 bd338f1..882d8d1 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 @@ -775,7 +775,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti */ @Override public List estimate(WarehouseContext ctx, FeeEstimateQuery query) { - HengjianFeeEstimateDtos.CalculateRequest body = HengjianEstimateMapper.toRequest(query); + HengjianFeeEstimateDtos.CalculateRequest body = HengjianEstimateMapper.toRequest(query, + trimToNull(ctx.providerWarehouseId())); String raw = execute(ctx, HengjianConstants.PATH_FEE_ESTIMATE, body, OP_FEE_ESTIMATE); HengjianFeeEstimateDtos.CalculateResponse resp = json.fromJson(raw, HengjianFeeEstimateDtos.CalculateResponse.class); diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java index 2be0a86..3272aaa 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java @@ -48,7 +48,19 @@ public final class HengjianEstimateMapper { * 所以不传。若真机后续要求,补上即可(模型里没有发货方信息,需调用方提供)。

*/ public static HengjianFeeEstimateDtos.CalculateRequest toRequest(FeeEstimateQuery query) { + return toRequest(query, null); + } + + /** + * 统一试算条件 → 恒健请求。 + * + * @param fallbackWarehouseCode 调用方没给发运仓时的兜底(账户仓);恒健要求 + * 「发运仓库」与「发运邮编」至少给一个 + */ + public static HengjianFeeEstimateDtos.CalculateRequest toRequest(FeeEstimateQuery query, + String fallbackWarehouseCode) { HengjianFeeEstimateDtos.CalculateRequest req = new HengjianFeeEstimateDtos.CalculateRequest(); + req.warehouseCode = firstNonBlank(query.shipFromWarehouseCode(), fallbackWarehouseCode); // 恒健这几个字段是 INTEGER:四舍五入而不是截断,截断会让包裹偏小、报价偏低 req.parcelLength = roundedCm(query.lengthCm()); req.parcelWidth = roundedCm(query.widthCm()); diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java index c967f98..0ebd952 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java @@ -147,6 +147,8 @@ public final class HengjianProductQueryMapper { // 保质期 .expirationControl(oneZeroToBoolean(row.expirationControl)) .expirationDays(intOrNull(row.expirationDate)) + // 真机响应有 productStatus(文档没写),保留原值供排障 + .rawStatus(intOrNull(row.productStatus)) .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.HENGJIAN); Integer productType = intOrNull(row.productType); @@ -158,16 +160,15 @@ public final class HengjianProductQueryMapper { if (insured != null) { b.insured("Y".equalsIgnoreCase(insured)); } - // 成本 + 币种 + // 成本 + 币种。0.0 是合法成本,不能当「没给」丢掉 BigDecimal cost = decimalOrNull(row.cost); String currency = trimToNull(row.currency); if (cost != null && currency != null) { - b.declaredValue(Money.of(cost, currency)); + b.cost(Money.of(cost, currency)); } + // isInsuranceRate 是费率不是金额,不塞进 insuranceFee(Money 语义是金额) + // 保价开关单独映射 BigDecimal rate = decimalOrNull(row.isInsuranceRate); - if (rate != null && currency != null) { - b.insuranceFee(Money.of(rate, currency)); - } return b.build(); } @@ -236,11 +237,20 @@ public final class HengjianProductQueryMapper { return null; } + /** + * 去空白并转 null。 + * + *

真机发现:恒健会把 {@code nameEn} 这类空字段返回成字符串 "null" + * 而不是 JSON null,所以这里一并当空处理,否则调用方会拿到 "null" 这个词。

+ */ private static String trimToNull(String v) { if (v == null) { return null; } String t = v.trim(); - return t.isEmpty() ? null : t; + if (t.isEmpty() || "null".equalsIgnoreCase(t)) { + return null; + } + return t; } } diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java index 37bda65..5474330 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java @@ -43,6 +43,18 @@ public final class HengjianFeeEstimateDtos { public String parcelWeightUnit; /** 发货方国家(文档写只能 US);选填。 */ + /** + * 发运仓库 code。 + * + *

真机确认:与 {@code shipperZipcode} 至少给一个,否则回 + * 「发运仓库和发运邮编不能同时为空」。字段名是 {@code warehouseCode}—— + * 用 {@code shipWarehouseCode} / {@code orgWarehouseCode} / {@code shipFromWarehouseCode} + * 都不认(2026-11-17 逐个试过)。

+ */ + @JsonProperty("warehouseCode") + public String warehouseCode; + + /** 发货方国家代码;文档标必填,实测给了 {@code shipperZipcode} 就不需要。 */ public String shipperCountryCode; public String shipperState; public String shipperCity; diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java index 2af4cb1..6404ee9 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java @@ -163,5 +163,14 @@ public final class HengjianProductQueryDtos { public String isInsuranceRate; @JsonProperty("remark") public String remark; + + /** + * 商品状态。 + * + *

文档没写这个字段,真机响应里有(样例值 1)。含义未确认, + * 所以只保留原值到 {@code ProductInfo.rawStatus()},不解释。

+ */ + @JsonProperty("productStatus") + public String productStatus; } } diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java index 9629b33..e517abc 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java @@ -5,23 +5,44 @@ 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.shared.support.Page; +import common.ecommerce.warehouse.enums.AddressType; import common.ecommerce.warehouse.enums.WarehouseFeeType; import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.DestructionOrder; +import common.ecommerce.warehouse.model.FeeEstimateQuery; import common.ecommerce.warehouse.model.FeeQuery; +import common.ecommerce.warehouse.model.FeeEstimateResult; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundQuery; +import common.ecommerce.warehouse.model.InventoryMovement; +import common.ecommerce.warehouse.model.InventoryMovementQuery; +import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundQuery; import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.ProductInfo; +import common.ecommerce.warehouse.model.ProductQuery; +import common.ecommerce.warehouse.model.ReturnHandle; +import common.ecommerce.warehouse.model.ReturnQuery; +import common.ecommerce.warehouse.model.TransferOrder; +import common.ecommerce.warehouse.model.TransferQuery; import common.ecommerce.warehouse.model.WarehouseFacility; +import common.ecommerce.warehouse.model.WarehouseReturn; 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.math.BigDecimal; import java.time.Clock; +import java.time.LocalDate; +import java.util.Arrays; import java.util.List; /** @@ -31,7 +52,7 @@ import java.util.List; * 真实 token 不入库:

* *
- * mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
+ * mvn -pl warehouse-sdk-hengjian -am -DfailIfNoTests=false \
  *     -Dhengjian.probe=true \
  *     -Dhengjian.probe.token=你的组织token \
  *     -Dhengjian.probe.warehouseCode=EFCA \
@@ -83,6 +104,8 @@ class HengjianReadOnlyProbeTest {
         }
     }
 
+    // ================================================================ 基础资料
+
     /** 仓库目录:不依赖任何单号,最容易验通,也顺带验证鉴权与信封。 */
     @Test
     void probeWarehouseDirectory() {
@@ -92,7 +115,7 @@ class HengjianReadOnlyProbeTest {
             public void run() {
                 List list = adapter().warehouses(ctx());
                 System.out.println("  返回 " + list.size() + " 个仓");
-                for (int i = 0; i < Math.min(list.size(), 10); i++) {
+                for (int i = 0; i < Math.min(list.size(), 5); i++) {
                     WarehouseFacility w = list.get(i);
                     System.out.println("  [" + i + "] code=" + w.warehouseCode()
                             + " name=" + w.name()
@@ -114,7 +137,7 @@ class HengjianReadOnlyProbeTest {
             public void run() {
                 List list = adapter().products(ctx(), PROVIDER_WAREHOUSE);
                 System.out.println("  返回 " + list.size() + " 个物流产品");
-                for (int i = 0; i < Math.min(list.size(), 10); i++) {
+                for (int i = 0; i < Math.min(list.size(), 5); i++) {
                     LogisticsProduct p = list.get(i);
                     System.out.println("  [" + i + "] code=" + p.logisticsProductCode()
                             + " name=" + p.logisticsProductName());
@@ -132,7 +155,7 @@ class HengjianReadOnlyProbeTest {
             public void run() {
                 List list = adapter().productsOfWarehouse(ctx(), PROVIDER_WAREHOUSE);
                 System.out.println("  仓 " + PROVIDER_WAREHOUSE + " 返回 " + list.size() + " 个物流产品");
-                for (int i = 0; i < Math.min(list.size(), 10); i++) {
+                for (int i = 0; i < Math.min(list.size(), 5); i++) {
                     System.out.println("  [" + i + "] code=" + list.get(i).logisticsProductCode()
                             + " name=" + list.get(i).logisticsProductName());
                 }
@@ -148,11 +171,61 @@ class HengjianReadOnlyProbeTest {
             @Override
             public void run() {
                 List codes = adapter().carriers(ctx());
-                System.out.println("  去重后 " + codes.size() + " 个 code:" + codes);
+                System.out.println("  去重后 " + codes.size() + " 个 code");
+            }
+        });
+    }
+
+    // ================================================================ 商品
+
+    /**
+     * 商品分页查询:验证 {@code pageSize} / {@code pageNum} 是 STRING、
+     * {@code data} 是分页对象、以及文档疑似漏掉的 {@code length} 到底回不回。
+     */
+    @Test
+    void probeProductQuery() {
+        assumeToken();
+        run("POST /v2/product/queryPage", new Runnable() {
+            @Override
+            public void run() {
+                ProductQuery query = ProductQuery.builder().pageSize(5).build();
+                Page page = adapter().query(ctx(), query);
+                System.out.println("  本页 " + page.size() + " 条, 有下一页=" + page.hasMore()
+                        + ", 游标=" + page.nextCursor());
+                for (ProductInfo p : page.items()) {
+                    System.out.println("  sku=" + p.providerSku()
+                            + " name=" + p.name()
+                            + " 长=" + p.lengthCm() + " 宽=" + p.widthCm() + " 高=" + p.heightCm()
+                            + " 重=" + p.weightGrams()
+                            + " 实测长=" + p.measuredLengthCm()
+                            + " 箱规=" + p.packedQuantity()
+                            + " 成本=" + (p.cost() == null ? null : p.cost().amount()));
+                }
             }
         });
     }
 
+    /** 按 SKU 精确查:验证 {@code skus} 数组过滤。 */
+    @Test
+    void probeProductQueryBySku() {
+        assumeToken();
+        final String sku = opt("hengjian.probe.sku", "");
+        Assumptions.assumeTrue(!sku.isEmpty(), "未提供 -Dhengjian.probe.sku,跳过按 SKU 查商品");
+        run("POST /v2/product/queryPage (skus)", new Runnable() {
+            @Override
+            public void run() {
+                Page page = adapter().query(ctx(),
+                        ProductQuery.builder().providerSku(sku).build());
+                System.out.println("  sku=" + sku + " 命中 " + page.size() + " 条");
+                for (ProductInfo p : page.items()) {
+                    System.out.println("  " + p.providerSku() + " / " + p.name());
+                }
+            }
+        });
+    }
+
+    // ================================================================ 出库
+
     /** 订单详情:只按来源单号查,需要 {@code -Dhengjian.probe.orderNo}。 */
     @Test
     void probeOrderDetail() {
@@ -224,6 +297,265 @@ class HengjianReadOnlyProbeTest {
         });
     }
 
+    // ================================================================ 库存
+
+    /**
+     * 库存查询:恒健有「按 SKU」与「按仓分页」两个接口,且不能同时用。
+     *
+     * 

按 SKU 查需要 {@code -Dhengjian.probe.sku}。

+ */ + @Test + void probeInventoryBySku() { + assumeToken(); + final String sku = opt("hengjian.probe.sku", ""); + Assumptions.assumeTrue(!sku.isEmpty(), "未提供 -Dhengjian.probe.sku,跳过按 SKU 查库存"); + run("POST /v1/inventory/getInventory", new Runnable() { + @Override + public void run() { + Page page = adapter().query(ctx(), + common.ecommerce.warehouse.model.InventoryQuery.builder() + .sku(sku).build()); + System.out.println(" sku=" + sku + " 返回 " + page.size() + " 条"); + for (InventorySnapshot s : page.items()) { + System.out.println(" sku=" + s.providerSku() + + " 可用=" + s.available() + + " 在手=" + s.onHand() + + " 在途=" + s.inTransit() + + " 预留=" + s.reserved() + + " 类型=" + s.inventoryType() + + " asOf=" + s.asOfUtc()); + } + } + }); + } + + /** 库存按仓分页:验证 {@code v2/inventory/get_inventory_by_page} 的分页结构。 */ + @Test + void probeInventoryByPage() { + assumeToken(); + run("GET /v2/inventory/get_inventory_by_page", new Runnable() { + @Override + public void run() { + Page page = adapter().query(ctx(), + common.ecommerce.warehouse.model.InventoryQuery.builder() + .warehouseCode(PROVIDER_WAREHOUSE) + .pageSize(5) + .build()); + System.out.println(" 本页 " + page.size() + " 条, 有下一页=" + page.hasMore() + + ", 游标=" + page.nextCursor()); + for (InventorySnapshot s : page.items()) { + System.out.println(" sku=" + s.providerSku() + " 可用=" + s.available() + + " 在手=" + s.onHand()); + } + } + }); + } + + /** + * 库存变动流水:SKU + 日期区间都必填,区间 ≤ 30 天。 + * + *

需要 {@code -Dhengjian.probe.sku} 与 {@code -Dhengjian.probe.begin} / {@code end}。

+ */ + @Test + void probeInventoryMovements() { + assumeToken(); + final String sku = opt("hengjian.probe.sku", ""); + final String begin = opt("hengjian.probe.begin", ""); + final String end = opt("hengjian.probe.end", ""); + Assumptions.assumeTrue(!sku.isEmpty() && !begin.isEmpty() && !end.isEmpty(), + "未提供 -Dhengjian.probe.sku / begin / end,跳过库存流水探针"); + run("POST /v1/inventory/task/query", new Runnable() { + @Override + public void run() { + Page page = adapter().queryMovements(ctx(), + InventoryMovementQuery.builder() + .sku(sku) + .dateRange(LocalDate.parse(begin), LocalDate.parse(end)) + .pageSize(10) + .build()); + System.out.println(" 本页 " + page.size() + " 条, 有下一页=" + page.hasMore()); + for (InventoryMovement m : page.items()) { + System.out.println(" sku=" + m.providerSku() + + " docType=" + m.documentType() + + " changeType=" + m.changeType() + + " 变化=" + m.changeQuantity() + + " planNo=" + m.planOrderNo() + + " sourceNo=" + m.sourceNo() + + " at=" + m.businessAt()); + } + } + }); + } + + // ================================================================ 入库 + + /** 入库计划详情:单号既可是仓方计划号也可是来源单号。 */ + @Test + void probeInboundDetail() { + assumeToken(); + final String inboundNo = opt("hengjian.probe.inboundNo", ""); + Assumptions.assumeTrue(!inboundNo.isEmpty(), + "未提供 -Dhengjian.probe.inboundNo,跳过入库详情探针"); + run("POST /v1/inbound/getInboundPlanInfo", new Runnable() { + @Override + public void run() { + InboundOrder order = adapter().get(ctx(), inboundNo); + if (order == null) { + System.out.println(" [空] 未找到该入库计划"); + return; + } + System.out.println(" status=" + order.status() + + " rawStatus=" + order.rawStatus() + + " providerId=" + order.providerInboundId() + + " sourceNo=" + order.inboundRequestNo() + + " 行数=" + order.lines().size() + + " 箱数=" + order.boxes().size()); + } + }); + } + + /** 入库计划列表:验证分页结构与状态过滤。 */ + @Test + void probeInboundList() { + assumeToken(); + run("POST /v1/inbound/getInboundPlanPage", new Runnable() { + @Override + public void run() { + Page page = adapter().queryInbounds(ctx(), + InboundQuery.builder().pageSize(5).build()); + System.out.println(" 本页 " + page.size() + " 条, 有下一页=" + page.hasMore() + + ", 游标=" + page.nextCursor()); + for (InboundOrder o : page.items()) { + System.out.println(" no=" + o.providerInboundId() + + " sourceNo=" + o.inboundRequestNo() + + " status=" + o.rawStatus() + + " createdAt=" + o.createdAt()); + } + } + }); + } + + // ================================================================ 调拨 + + /** 调拨计划查询:验证分页与仓过滤。 */ + @Test + void probeTransferList() { + assumeToken(); + run("POST /v1/transferPlan/findByPage", new Runnable() { + @Override + public void run() { + Page page = adapter().queryTransfers(ctx(), + TransferQuery.builder().pageSize(5).build()); + System.out.println(" 本页 " + page.size() + " 条, 有下一页=" + page.hasMore() + + ", 游标=" + page.nextCursor()); + for (TransferOrder t : page.items()) { + System.out.println(" no=" + t.providerTransferNo() + + " sourceNo=" + t.transferRequestNo() + + " status=" + t.rawStatus() + + " from=" + t.fromWarehouseCode() + + " to=" + t.toWarehouseCode()); + } + } + }); + } + + // ================================================================ 退货 + + /** 退货计划详情。 */ + @Test + void probeReturnDetail() { + assumeToken(); + final String returnNo = opt("hengjian.probe.returnNo", ""); + Assumptions.assumeTrue(!returnNo.isEmpty(), + "未提供 -Dhengjian.probe.returnNo,跳过退货详情探针"); + run("POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo", new Runnable() { + @Override + public void run() { + WarehouseReturn ret = adapter().getReturn(ctx(), returnNo); + if (ret == null) { + System.out.println(" [空] 未找到该退货计划"); + return; + } + System.out.println(" returnRequestNo=" + ret.returnRequestNo() + + " providerReturnId=" + ret.providerReturnId() + + " status=" + ret.status() + + " rawStatus=" + ret.rawStatus() + + " type=" + ret.type() + + " 行数=" + ret.lines().size()); + } + }); + } + + /** 退货计划列表:验证双层包裹与单状态过滤。 */ + @Test + void probeReturnList() { + assumeToken(); + run("POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage", new Runnable() { + @Override + public void run() { + Page page = adapter().queryReturns(ctx(), + ReturnQuery.builder().pageSize(5).build()); + System.out.println(" 本页 " + page.size() + " 条, 有下一页=" + page.hasMore() + + ", 游标=" + page.nextCursor()); + for (WarehouseReturn r : page.items()) { + System.out.println(" no=" + r.providerReturnId() + + " sourceNo=" + r.returnRequestNo() + + " status=" + r.rawStatus()); + } + } + }); + } + + /** 退货处理单列表:另一个接口(平铺请求),验证四项定位字段都在。 */ + @Test + void probeReturnHandles() { + assumeToken(); + run("POST /v1/saleReturn/getReturnPlanHandlePage", new Runnable() { + @Override + public void run() { + Page page = adapter().queryHandles(ctx(), + ReturnQuery.builder().pageSize(5).build()); + System.out.println(" 本页 " + page.size() + " 条, 有下一页=" + page.hasMore()); + for (ReturnHandle h : page.items()) { + System.out.println(" planNo=" + h.returnPlanNo() + + " handleNo=" + h.returnHandleNo() + + " sku=" + h.providerSku() + + " tracking=" + h.trackingNumber() + + " handlingStatus=" + h.handlingStatus() + + " primaryMethod=" + h.primaryHandlingMethod()); + } + } + }); + } + + // ================================================================ 销毁 + + /** 销毁计划查询:验证裸数组请求 + 数组响应(路径真机待确认)。 */ + @Test + void probeDestruction() { + assumeToken(); + final String destructionNo = opt("hengjian.probe.destructionNo", ""); + Assumptions.assumeTrue(!destructionNo.isEmpty(), + "未提供 -Dhengjian.probe.destructionNo,跳过销毁查询探针"); + run("POST /v2/destroyPlanOrder/find", new Runnable() { + @Override + public void run() { + DestructionOrder order = adapter().getDestruction(ctx(), destructionNo); + if (order == null) { + System.out.println(" [空] 未找到该销毁计划"); + return; + } + System.out.println(" no=" + order.destructionNo() + + " providerId=" + order.providerDestructionId() + + " status=" + order.status() + + " rawStatus=" + order.rawStatus() + + " hopeDestroyDate=" + order.hopeDestroyDate()); + } + }); + } + + // ================================================================ 计费 / 试算 + /** * 计费明细(仓储费 / 尾程费 / 作业费):只读,验证三个路径与分页信封。 * @@ -255,27 +587,86 @@ class HengjianReadOnlyProbeTest { public void run() { FeeQuery query = FeeQuery.builder() .costType(type) - .settledAfter(java.time.LocalDate.parse(begin) + .settledAfter(LocalDate.parse(begin) .atStartOfDay(java.time.ZoneOffset.UTC).toInstant()) - .settledBefore(java.time.LocalDate.parse(end) + .settledBefore(LocalDate.parse(end) .atTime(23, 59, 59).toInstant(java.time.ZoneOffset.UTC)) .pageSize(10) .build(); - List docs = - adapter().settlements(ctx(), query); + List docs = adapter().settlements(ctx(), query); System.out.println(" 返回 " + docs.size() + " 条(<10 说明已是末页)"); - for (int i = 0; i < Math.min(docs.size(), 10); i++) { - common.ecommerce.warehouse.model.BillingDocument d = docs.get(i); + for (int i = 0; i < Math.min(docs.size(), 5); i++) { + BillingDocument d = docs.get(i); System.out.println(" [" + i + "] type=" + d.feeType() + " billNo=" + d.documentNo() - + " txn=" + d.serialNumber() + " name=" + d.feeName() + " amount=" + d.amount() + " sku=" + d.providerSku() - + " order=" + d.saleOrderNo() + " settledAt=" + d.settledAt()); } } }); } + + /** + * 运费试算:只读(不下单),验证必须的收件信息与返回结构。 + * + *

恒健试算需要完整收件地址 + 包裹尺寸重量。

+ */ + @Test + void probeFeeEstimate() { + assumeToken(); + run("POST /v2/api/shipping/calculate", new Runnable() { + @Override + public void run() { + FeeEstimateQuery query = FeeEstimateQuery.builder() + // 恒健要求「发运仓库」与「发运邮编」至少给一个;字段名是 warehouseCode + .shipFromWarehouseCode(PROVIDER_WAREHOUSE) + .receiveCountry("US") + .receiveState("CA") + .receiveCity("Fontana") + .receivePostal("92337") + .receiveAddress("1 Test St") + .lengthCm(BigDecimal.valueOf(30)) + .widthCm(BigDecimal.valueOf(20)) + .heightCm(BigDecimal.valueOf(10)) + .weightGrams(BigDecimal.valueOf(1500)) + .insuredValue(Money.of("50.00", "USD")) + .build(); + List results = adapter().estimate(ctx(), query); + System.out.println(" 返回 " + results.size() + " 个报价"); + for (FeeEstimateResult r : results) { + System.out.println(" warehouse=" + r.shipOrgWarehouseCode()); + for (FeeEstimateResult.CarrierQuote q : r.carriers()) { + System.out.println(" 渠道=" + q.carrier() + + " service=" + q.logisticsServiceCode() + + " 总价=" + (q.totalRate() == null ? null : q.totalRate().amount()) + + " 明细项=" + q.costItems().size()); + for (FeeEstimateResult.CarrierQuote.CostItem c : q.costItems()) { + System.out.println(" - " + c.costName() + "=" + + (c.estimatedCost() == null ? null : c.estimatedCost().amount())); + } + } + } + } + }); + } + + /** + * 地址属性识别:只读,判定商业 / 住宅。 + * + *

真机确认五项必填(street1 / city / state / postal / country)。

+ */ + @Test + void probeAddressClassification() { + assumeToken(); + run("POST /v2/api/shipping/addressClassification", new Runnable() { + @Override + public void run() { + AddressType type = adapter().classifyAddress(ctx(), + "351 S Waterman Ave", null, "San Bernardino", "CA", "92408", "US"); + System.out.println(" 地址属性=" + type); + } + }); + } }