Browse Source

test(hengjian): 只读探针补全全部查询接口,并用真机结果修 5 处映射

探针从 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 全量通过。
master
lml 3 days ago
parent
commit
72982e2806
  1. 48
      docs-warehouse/hengjian/README.md
  2. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java
  3. 13
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  4. 3
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  5. 12
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java
  6. 22
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java
  7. 12
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java
  8. 9
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java
  9. 417
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java

48
docs-warehouse/hengjian/README.md

@ -1088,3 +1088,51 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \ @@ -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 处理 |

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

@ -21,6 +21,13 @@ public final class FeeEstimateQuery { @@ -21,6 +21,13 @@ public final class FeeEstimateQuery {
/** 发货仓 code;空表示用账户配置的仓。 */
private final List<String> warehouseCodes;
/**
* 发货仓 code;null 表示由适配器用账户仓兜底。
*
* <p>恒健的试算<b>必须</b>给「发运仓库」或「发运邮编」其一,否则回
* 「发运仓库和发运邮编不能同时为空」;字段名是 {@code warehouseCode}(不是 shipper*)。</p>
*/
private final String shipFromWarehouseCode;
private final BigDecimal lengthCm;
private final BigDecimal widthCm;
private final BigDecimal heightCm;
@ -42,6 +49,7 @@ public final class FeeEstimateQuery { @@ -42,6 +49,7 @@ public final class FeeEstimateQuery {
private FeeEstimateQuery(Builder b) {
this.warehouseCodes = Collections.unmodifiableList(new ArrayList<String>(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 { @@ -65,6 +73,11 @@ public final class FeeEstimateQuery {
}
/** 发货仓 code 列表;空表示用账户配置的仓。 */
/** 发运仓 code;null 表示用账户仓。 */
public String shipFromWarehouseCode() {
return shipFromWarehouseCode;
}
public List<String> warehouseCodes() {
return warehouseCodes;
}
@ -166,6 +179,7 @@ public final class FeeEstimateQuery { @@ -166,6 +179,7 @@ public final class FeeEstimateQuery {
public static final class Builder {
private final List<String> warehouseCodes = new ArrayList<String>();
private String shipFromWarehouseCode;
private BigDecimal lengthCm;
private BigDecimal widthCm;
private BigDecimal heightCm;
@ -181,6 +195,12 @@ public final class FeeEstimateQuery { @@ -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());

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

@ -161,6 +161,19 @@ public final class HengjianConstants { @@ -161,6 +161,19 @@ public final class HengjianConstants {
* <p>真机确认存在;包裹四项 + 两个单位 + 收货方五项必填
* ({@code shipper*} 系列可省)。</p>
*/
/**
* 运费试算({@code POST})。
*
* <p><b>真机确认(2026-11-17)</b>:必须给「发运仓库」或「发运邮编」其一,
* 否则回 {@code 400 发运仓库和发运邮编不能同时为空}。发运仓的字段名是
* <b>{@code warehouseCode}</b>——{@code shipWarehouseCode} /
* {@code orgWarehouseCode} / {@code shipFromWarehouseCode} 都不认(逐个试过)。</p>
*
* <p>另:{@code shipper*} 系列给了不完整会回 {@code 400 发货人信息不完整},
* 所以要么给全(国家 + 州 + 城市 + 地址 + 邮编),要么只给 {@code warehouseCode}。
* 给 {@code carrier} / {@code serviceCode} 而库里没有该渠道时会回
* {@code 400 承运商服务代码不存在}。</p>
*/
public static final String PATH_FEE_ESTIMATE = "/v2/api/shipping/calculate";
/**

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

@ -775,7 +775,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -775,7 +775,8 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
*/
@Override
public List<FeeEstimateResult> 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);

12
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianEstimateMapper.java

@ -48,7 +48,19 @@ public final class HengjianEstimateMapper { @@ -48,7 +48,19 @@ public final class HengjianEstimateMapper {
* 所以不传。若真机后续要求,补上即可(模型里没有发货方信息,需调用方提供)。</p>
*/
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());

22
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java

@ -147,6 +147,8 @@ public final class HengjianProductQueryMapper { @@ -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 { @@ -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 是<b>费率</b>不是金额,不塞进 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 { @@ -236,11 +237,20 @@ public final class HengjianProductQueryMapper {
return null;
}
/**
* 去空白并转 null。
*
* <p><b>真机发现</b>:恒健会把 {@code nameEn} 这类空字段返回成<b>字符串 "null"</b>
* 而不是 JSON null,所以这里一并当空处理,否则调用方会拿到 "null" 这个词。</p>
*/
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;
}
}

12
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianFeeEstimateDtos.java

@ -43,6 +43,18 @@ public final class HengjianFeeEstimateDtos { @@ -43,6 +43,18 @@ public final class HengjianFeeEstimateDtos {
public String parcelWeightUnit;
/** 发货方国家(文档写只能 US);选填。 */
/**
* 发运仓库 code。
*
* <p>真机确认:与 {@code shipperZipcode} <b>至少给一个</b>,否则回
* 「发运仓库和发运邮编不能同时为空」。字段名是 {@code warehouseCode}——
* 用 {@code shipWarehouseCode} / {@code orgWarehouseCode} / {@code shipFromWarehouseCode}
* 都不认(2026-11-17 逐个试过)。</p>
*/
@JsonProperty("warehouseCode")
public String warehouseCode;
/** 发货方国家代码;文档标必填,实测给了 {@code shipperZipcode} 就不需要。 */
public String shipperCountryCode;
public String shipperState;
public String shipperCity;

9
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java

@ -163,5 +163,14 @@ public final class HengjianProductQueryDtos { @@ -163,5 +163,14 @@ public final class HengjianProductQueryDtos {
public String isInsuranceRate;
@JsonProperty("remark")
public String remark;
/**
* 商品状态。
*
* <p><b>文档没写这个字段</b>,真机响应里有(样例值 1)。含义未确认,
* 所以只保留原值到 {@code ProductInfo.rawStatus()},不解释。</p>
*/
@JsonProperty("productStatus")
public String productStatus;
}
}

417
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java

@ -5,23 +5,44 @@ import common.ecommerce.hengjian.adapter.HengjianAdapter; @@ -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; @@ -31,7 +52,7 @@ import java.util.List;
* <b>真实 token 不入库</b>:</p>
*
* <pre>
* 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 { @@ -83,6 +104,8 @@ class HengjianReadOnlyProbeTest {
}
}
// ================================================================ 基础资料
/** 仓库目录:不依赖任何单号,最容易验通,也顺带验证鉴权与信封。 */
@Test
void probeWarehouseDirectory() {
@ -92,7 +115,7 @@ class HengjianReadOnlyProbeTest { @@ -92,7 +115,7 @@ class HengjianReadOnlyProbeTest {
public void run() {
List<WarehouseFacility> 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 { @@ -114,7 +137,7 @@ class HengjianReadOnlyProbeTest {
public void run() {
List<LogisticsProduct> 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 { @@ -132,7 +155,7 @@ class HengjianReadOnlyProbeTest {
public void run() {
List<LogisticsProduct> 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 { @@ -148,11 +171,61 @@ class HengjianReadOnlyProbeTest {
@Override
public void run() {
List<String> 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<ProductInfo> 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<ProductInfo> 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 { @@ -224,6 +297,265 @@ class HengjianReadOnlyProbeTest {
});
}
// ================================================================ 库存
/**
* 库存查询:恒健有「按 SKU」与「按仓分页」两个接口,且<b>不能同时用</b>。
*
* <p>按 SKU 查需要 {@code -Dhengjian.probe.sku}。</p>
*/
@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<InventorySnapshot> 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<InventorySnapshot> 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 天。
*
* <p>需要 {@code -Dhengjian.probe.sku} 与 {@code -Dhengjian.probe.begin} / {@code end}。</p>
*/
@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<InventoryMovement> 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<InboundOrder> 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<TransferOrder> 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<WarehouseReturn> 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<ReturnHandle> 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 { @@ -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<common.ecommerce.warehouse.model.BillingDocument> docs =
adapter().settlements(ctx(), query);
List<BillingDocument> 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());
}
}
});
}
/**
* 运费试算:只读(不下单),验证必须的收件信息与返回结构。
*
* <p>恒健试算需要完整收件地址 + 包裹尺寸重量。</p>
*/
@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<FeeEstimateResult> 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()));
}
}
}
}
});
}
/**
* 地址属性识别:只读,判定商业 / 住宅。
*
* <p>真机确认五项必填(street1 / city / state / postal / country)。</p>
*/
@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);
}
});
}
}

Loading…
Cancel
Save