Browse Source

feat: 信仓 / 恒健全接商品查询

core 新增 ProductQuery(SKU 过滤 + 分页)与
WarehouseProductCapable.queryProducts(default 拒绝,两家覆盖),
门面加 queryProducts。WarehouseProduct 补查询结果才有的字段
(仓侧 id / 仓方实测尺寸 / 创建更新时间 / 状态原值 / 体积),
并加 allowUnknownDimensions 开关:查询结果允许尺寸重量为 0
表示「仓方未给」,建档仍必须为正数——不伪造 0.01 之类的假值。

恒健 /v2/product/queryPage:
- 文档把 pageSize / pageNum 的说明写反(pageSize 写「页码」),
  按响应里的含义实现:pageSize=每页条数、pageNum=页码;请求侧是 STRING
- 响应 data 是分页对象而非数组,按 total 判断是否还有下一页
- 文档漏了 length(只有 width/height/itemLength),映射时优先 length、
  缺失退回 itemLength
- measurement* 存到仓方实测字段,与申报尺寸分开

信仓 api.productlist:
- 字段表按 Apifox「OMS接口文档V2」全量映射(token/state/page/limit 四项必填)
- 固定 state=1 查正式产品:临时产品是建档中间态,混进业务列表会让人
  以为能下单;建档查重仍走 state=0
- key 是单值:传多个 SKU 时拒绝,不静默只取第一个
- 厘米与英寸两套尺寸都给,直接用厘米那套,避免二次换算舍入
- 数值全是字符串,空串转 null 不转 0;按 rst.count 判断下一页
- PRODUCTION_BASE_URL 确定为 https://oms.xincang-tech.com/oms(去掉末尾斜杠)

验证:mvn test 全量通过(恒健 +11、信仓 +10)。

Co-Authored-By: Claude Code <noreply@anthropic.com>
master
lml 3 days ago
parent
commit
aac75d5904
  1. 39
      docs-warehouse/hengjian/README.md
  2. 49
      docs-warehouse/xincang/README.md
  3. 207
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  4. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java
  5. 100
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java
  6. 16
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  7. 10
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  8. 22
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  9. 248
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java
  10. 167
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java
  11. 196
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java
  12. 11
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
  13. 34
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  14. 262
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java
  15. 178
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java
  16. 215
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java

39
docs-warehouse/hengjian/README.md

@ -480,6 +480,45 @@ isOriginCountry(是否展示原产地不能为空) @@ -480,6 +480,45 @@ isOriginCountry(是否展示原产地不能为空)
- `BoxLabelCommand` 补 `showIndexNo` / `showOriginCountry` / `paperTypeCode` / `fileNamingType`
- `LabelPrintTask.taskNo` 改为**可空**(恒健不回任务号),Javadoc 说明了 null 的含义
### 商品查询(`/v2/product/queryPage`)—— 已接入
真机确认(2026-11-17):无 token 时 `403 Unauthorized`,**鉴权先于参数校验**,必填项按文档实现。
#### 分页字段说明写反了
| 字段 | 文档说法 | 实际含义(按响应) |
|---|---|---|
| `pageSize` | 「页码」 | **每页条数** |
| `pageNum` | 「页数」 | **页码** |
响应里的 `pageSize` / `pageNum` 含义是明确的,所以按响应实现。请求侧两个字段都是 **STRING**。
#### 响应结构
`data` 是**分页对象**(不是数组):`{total, pageSize, pageNum, data[]}`。
是否还有下一页按 `total` 判断,不看本页是否满。
#### 文档漏了 `length`
商品主体长宽高里文档只列了 `width` / `height` 与 `itemLength`,**没有 `length`**,
但建档接口有。映射时优先 `length`,缺失退回 `itemLength`——两者语义不同
(主体 vs 单品),兜底只为不让「查回来没有长」变成 null。
#### 字段映射
| 恒健 | 落点 |
|---|---|
| `sku` / `upc` | `omsSku` / `barcode` |
| `name` / `nameEn` / `description` / `remark` | 同名 |
| `length` / `width` / `height` / `weight` | cm / cm / cm / g |
| `itemLength` / `itemWidth` / `itemHeight` | 单品尺寸 |
| `measurementLength` / `Width` / `Height` / `Weight` | **仓方实测**,与申报尺寸分开存 |
| `packedQty` / `packedLength` / `Width` / `Height` / `Weight` | 外箱 |
| `expirationControl`(0/1)/ `expirationDate` | `expirationControl` / `expirationDays` |
| `cost` + `currency` | `cost`(Money) |
| `isInsuranceFlag`(Y/N)/ `isInsuranceRate` | `insured` / `insuranceFee` |
| `productType`(1 成品 / 2 配件 / 3 耗材) | `productType` |
### 销毁(`DESTRUCTION`)—— 已接入,**路径未真机确认**
> **⚠ 重要**:2026-11-17 在测试环境对文档路径及 **26 个变体**请求,

49
docs-warehouse/xincang/README.md

@ -6,7 +6,7 @@ @@ -6,7 +6,7 @@
|---|---|
| 适配器 ID | `xincang` |
| 测试 / 联调环境 | `http://test.api.oms.13u3.com/oms` |
| 生产环境 | `https://oms.xincang-tech.com/oms/` |
| 生产环境 | `https://oms.xincang-tech.com/oms`(常量已去掉末尾斜杠,避免拼出 `//api.xxx`) |
| 鉴权 | 先 `GET /api.login?appkey=&secret=` 换 token;业务请求把 token 放 **query 参数 `token`**,不是 `Authorization` 头 |
| token 有效期 | 2 小时,**没有 refresh 接口**,到期只能重新登录 |
| token 维度 | 客户级(同一 appkey 下多仓共用一个 token) |
@ -22,7 +22,7 @@ @@ -22,7 +22,7 @@
| 1 | 登录 | `GET /api.login` | — |
| 2 | 新增产品 | `POST /api.add_product` | `PRODUCT` |
| 3 | 更新产品 | `POST /api.update_product` | `PRODUCT` |
| 4 | 产品列表(查重用) | `GET /api.productlist` | `PRODUCT` |
| 4 | 商品列表(查询 + 建档查重) | `GET /api.productlist` | `PRODUCT` |
| 5 | 新增订单一单多件 | `POST /api.add_order_multiple` | `OUTBOUND` |
| 6 | 订单详情 | `GET /api.get_order` | `OUTBOUND` |
| 7 | 删除订单 | `POST /api.delete_order` | `OUTBOUND` |
@ -89,11 +89,52 @@ @@ -89,11 +89,52 @@
```
① 查临时产品(决定 add 还是 update)
GET /api.productlist?state=0&key=<sku>
GET /api.productlist?state=0&key=<sku>&page=1&limit=20
② 新增(临时产品) POST /api.add_product
或 更新(仅临时产品可更新) POST /api.update_product
③ 商品查询(正式产品)
GET /api.productlist?state=1&page=1&limit=20[&key=<sku>]
```
### 商品查询(`api.productlist`)
| 项 | 值 |
|---|---|
| 方法 / 路径 | `GET /api.productlist` |
| 必填 query | `token` / `state` / `page` / `limit`(**四项都必填**,文档标 required) |
| 选填 query | `key`(产品 SKU,**单值**) |
| `state` | 0 临时产品 / 1 正式产品 |
| `limit` | 默认 20,**最大 100** |
适配器的 `queryProducts` **固定传 `state=1`**——临时产品是建档中间态,
混进业务列表会让人以为能下单。建档查重那条路径仍用 `state=0`。
**一次只能查一个 SKU**:`key` 是单值。传多个时适配器<b>拒绝</b>,
静默只取第一个会让其余 SKU 缺席,看起来像「仓里没有」。
响应 `rst.data[]` 字段(Apifox 2026-11 核对):
| 字段 | 含义 | 落点 |
|---|---|---|
| `id` | 产品 id | `providerProductId` |
| `product_no` | SKU | `omsSku` / `providerSku` |
| `bar_code` | 条码 | `barcode` |
| `en_name` / `chn_name` | 英文 / 中文名 | `nameEn` / `name` |
| `amount` | 金额(USD) | `declaredValue` |
| `packing_rate` | 装箱率 | `packedQuantity` |
| `weight_kg` / `weight_lbs` | 重量 | `weightGrams`(kg×1000) |
| `size_l_cm` / `size_w_cm` / `size_h_cm` | 厘米尺寸 | `lengthCm` 等(**直接用厘米那套**) |
| `size_l_ln` / `size_w_ln` / `size_h_ln` | 英寸尺寸 | 不用(避免二次换算舍入) |
| `volume_cm` / `volume_ln` / `volume_m` | 体积 | `volumeCm3`(立方厘米) |
| `gmt_create` / `gmt_modify` | 北京时间 | `createdAt` / `updatedAt`(转 UTC) |
| `state` / `state_name` | 状态码 / 中文名 | `rawState` / `stateName` |
| `image_url` | 图片签名 URL(有时效) | `imageUrl` |
| `product_image` | OSS 元数据 | 不映射(修改临时产品图片时回传用) |
| `ckm` | 仓库码 | 不映射 |
| `rst.count` | 总条数(**字符串**) | 判断是否有下一页 |
**所有数值字段都是字符串**——信仓全站风格。空串转 null,不转 0。
## 4. 枚举映射(信仓是两套码表,core 是第三套)
### 订单状态 `state`
@ -200,7 +241,7 @@ @@ -200,7 +241,7 @@
| 项 | 现状 |
|---|---|
| 生产域名 | 文档未给,常量写的是 `"待核对"` |
| 生产域名 | `https://oms.xincang-tech.com/oms`(已确认并写入常量) |
| 限流 | 未公开,按 2 req/s |
| **最优渠道 `calculate_order_v3`** | 文档标 `GET` + JSON body,**OkHttp 不支持 GET 带 body**;适配器按 **POST + JSON body** 下发 |

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

@ -161,6 +161,43 @@ public final class WarehouseProduct { @@ -161,6 +161,43 @@ public final class WarehouseProduct {
*/
private final Boolean specialOuterPackaging;
// ==================== 查询结果才有(下发时忽略)====================
/**
* 仓侧商品 id。查询结果里有;建档时忽略。
*
* <p>信仓 {@code id}、恒健无此字段。</p>
*/
private final String providerProductId;
/**
* 仓方实测尺寸 / 重量;null 表示仓方未给。
*
* <p><b>与 {@link #lengthCm()} 等不是一回事</b>:那些是我们申报的尺寸,
* 这些是仓方收货后实测的(恒健 {@code measurement*})。下标成本、抛重都以实测为准。</p>
*/
private final Double measuredLengthCm;
private final Double measuredWidthCm;
private final Double measuredHeightCm;
private final Double measuredWeightGrams;
/** 仓方记录的创建时间(UTC);查询结果才有。 */
private final java.time.Instant createdAt;
/** 仓方记录的更新时间(UTC);查询结果才有。 */
private final java.time.Instant updatedAt;
/**
* 仓方状态原值;查询结果才有,建档时为 null。
*
* <p>信仓 {@code state}:0 临时 / 1 正式;恒健无状态字段。</p>
*/
private final String rawState;
/** 仓方状态中文名(信仓 {@code state_name});无则为 null。 */
private final String stateName;
/**
* 体积(立方厘米);仓方原值。
*
* <p>信仓 {@code volume_cm};恒健无此字段。</p>
*/
private final java.math.BigDecimal volumeCm3;
/**
* 产品图片地址;null 表示不传。
*
@ -183,10 +220,23 @@ public final class WarehouseProduct { @@ -183,10 +220,23 @@ public final class WarehouseProduct {
// 不在构造期强制:这是运去哪的必填项,信仓不需要。必填性由各适配器按自己的
// 协议校验,见 YqnProductMapper;未给时保持 -1 表示「不传」。
this.packingType = b.packingType;
if (b.allowUnknownDimensions) {
// 查询结果:仓方可能没给尺寸 / 重量。用 0 表示「未给」,
// 不伪造一个值——伪造会让计费与抛重计算拿到假数据。
requireNonNegative(b.lengthCm, "lengthCm");
requireNonNegative(b.widthCm, "widthCm");
requireNonNegative(b.heightCm, "heightCm");
requireNonNegative(b.weightGrams, "weightGrams");
this.lengthCm = b.lengthCm;
this.widthCm = b.widthCm;
this.heightCm = b.heightCm;
this.weightGrams = b.weightGrams;
} else {
this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
this.widthCm = requirePositive(b.widthCm, "widthCm");
this.heightCm = requirePositive(b.heightCm, "heightCm");
this.weightGrams = requirePositive(b.weightGrams, "weightGrams");
}
this.itemLengthCm = b.itemLengthCm;
this.itemWidthCm = b.itemWidthCm;
this.itemHeightCm = b.itemHeightCm;
@ -206,6 +256,16 @@ public final class WarehouseProduct { @@ -206,6 +256,16 @@ public final class WarehouseProduct {
new java.util.ArrayList<String>(b.imageUrls));
this.specialOuterPackaging = b.specialOuterPackaging;
this.imageUrl = b.imageUrl;
this.providerProductId = b.providerProductId;
this.measuredLengthCm = b.measuredLengthCm;
this.measuredWidthCm = b.measuredWidthCm;
this.measuredHeightCm = b.measuredHeightCm;
this.measuredWeightGrams = b.measuredWeightGrams;
this.createdAt = b.createdAt;
this.updatedAt = b.updatedAt;
this.rawState = b.rawState;
this.stateName = b.stateName;
this.volumeCm3 = b.volumeCm3;
this.expirationControl = b.expirationControl;
this.expirationDays = b.expirationDays;
this.packedQuantity = b.packedQuantity;
@ -432,6 +492,17 @@ public final class WarehouseProduct { @@ -432,6 +492,17 @@ public final class WarehouseProduct {
return v != null && !v.trim().isEmpty();
}
/** 尺寸 / 重量是否为「未给」(0 表示仓方没给,仅查询结果适用)。 */
public boolean hasDimensions() {
return lengthCm > 0 && widthCm > 0 && heightCm > 0 && weightGrams > 0;
}
private static void requireNonNegative(double v, String name) {
if (v < 0) {
throw new IllegalArgumentException(name + " must not be negative");
}
}
private static String require(String v, String n) {
if (!hasText(v)) {
throw new IllegalArgumentException(n + " must not be blank");
@ -446,6 +517,56 @@ public final class WarehouseProduct { @@ -446,6 +517,56 @@ public final class WarehouseProduct {
return v;
}
/** 仓侧商品 id;查询结果才有。 */
public String providerProductId() {
return providerProductId;
}
/** 仓方实测长(cm);未给为 null。 */
public Double measuredLengthCm() {
return measuredLengthCm;
}
/** 仓方实测宽(cm);未给为 null。 */
public Double measuredWidthCm() {
return measuredWidthCm;
}
/** 仓方实测高(cm);未给为 null。 */
public Double measuredHeightCm() {
return measuredHeightCm;
}
/** 仓方实测重量(g);未给为 null。 */
public Double measuredWeightGrams() {
return measuredWeightGrams;
}
/** 仓方记录的创建时间(UTC);未给为 null。 */
public java.time.Instant createdAt() {
return createdAt;
}
/** 仓方记录的更新时间(UTC);未给为 null。 */
public java.time.Instant updatedAt() {
return updatedAt;
}
/** 仓方状态原值;建档时为 null。 */
public String rawState() {
return rawState;
}
/** 仓方状态中文名;无则为 null。 */
public String stateName() {
return stateName;
}
/** 体积(立方厘米);未给为 null。 */
public java.math.BigDecimal volumeCm3() {
return volumeCm3;
}
public static final class Builder {
private String omsSku;
@ -477,6 +598,22 @@ public final class WarehouseProduct { @@ -477,6 +598,22 @@ public final class WarehouseProduct {
private String remark;
private Integer productCategory;
private String imageUrl;
private String providerProductId;
private Double measuredLengthCm;
private Double measuredWidthCm;
private Double measuredHeightCm;
private Double measuredWeightGrams;
private java.time.Instant createdAt;
private java.time.Instant updatedAt;
private String rawState;
private String stateName;
private java.math.BigDecimal volumeCm3;
/**
* 允许尺寸 / 重量为 0(表示仓方未给)。
*
* <p>只给<b>查询结果</b>用:建档时仍然必须给正数。不设这个开关时行为不变。</p>
*/
private boolean allowUnknownDimensions;
private final List<String> imageUrls = new java.util.ArrayList<String>();
private Boolean specialOuterPackaging;
private Boolean expirationControl;
@ -722,6 +859,76 @@ public final class WarehouseProduct { @@ -722,6 +859,76 @@ public final class WarehouseProduct {
/**
* @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐
*/
/**
* 允许尺寸 / 重量为 0(表示仓方未给)。
*
* <p>只在把<b>查询结果</b>映射成模型时使用;建档仍是必填正数。</p>
*/
public Builder allowUnknownDimensions(boolean v) {
this.allowUnknownDimensions = v;
return this;
}
/** 仓侧商品 id(查询结果才有)。 */
public Builder providerProductId(String v) {
this.providerProductId = v;
return this;
}
/** 仓方实测长(cm)。 */
public Builder measuredLengthCm(Double v) {
this.measuredLengthCm = v;
return this;
}
/** 仓方实测宽(cm)。 */
public Builder measuredWidthCm(Double v) {
this.measuredWidthCm = v;
return this;
}
/** 仓方实测高(cm)。 */
public Builder measuredHeightCm(Double v) {
this.measuredHeightCm = v;
return this;
}
/** 仓方实测重量(g)。 */
public Builder measuredWeightGrams(Double v) {
this.measuredWeightGrams = v;
return this;
}
/** 仓方记录的创建时间(UTC)。 */
public Builder createdAt(java.time.Instant v) {
this.createdAt = v;
return this;
}
/** 仓方记录的更新时间(UTC)。 */
public Builder updatedAt(java.time.Instant v) {
this.updatedAt = v;
return this;
}
/** 仓方状态原值。 */
public Builder rawState(String v) {
this.rawState = v;
return this;
}
/** 仓方状态中文名。 */
public Builder stateName(String v) {
this.stateName = v;
return this;
}
/** 体积(立方厘米)。 */
public Builder volumeCm3(java.math.BigDecimal v) {
this.volumeCm3 = v;
return this;
}
public WarehouseProduct build() {
return new WarehouseProduct(this);
}

19
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java

@ -3,12 +3,29 @@ package common.ecommerce.warehouse.capability; @@ -3,12 +3,29 @@ package common.ecommerce.warehouse.capability;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
/** 商品建档 / 更新能力。 */
/** 商品建档 / 更新 / 查询能力。 */
public interface WarehouseProductCapable extends WarehouseAdapter {
/** 在某仓创建或更新一个 SKU。 */
ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product);
/**
* 分页查商品。<b>只读</b>,不走幂等。
*
* <p>各仓支持的过滤维度不同:不支持的维度由适配器<b>显式拒绝</b>,
* 不静默忽略——忽略一个过滤条件会让调用方以为「仓里就这些商品」。</p>
*
* @param query 查询条件;游标为空表示第一页
* @return 当前页商品;{@code nextCursor} 非空表示还有下一页
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不支持商品查询
*/
default common.ecommerce.shared.support.Page<WarehouseProduct> queryProducts(
WarehouseContext ctx, common.ecommerce.warehouse.model.ProductQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.PRODUCT);
}
/** 商品建档结果。 */
final class ProductResult {

100
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java

@ -0,0 +1,100 @@ @@ -0,0 +1,100 @@
package common.ecommerce.warehouse.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 商品查询条件。
*
* <p>与 {@code WarehouseProductCapable.createOrUpdate} 的区别:那个是写,这个是读。
* 各仓支持的维度不同:不支持的维度由适配器<b>显式拒绝</b>,不静默忽略——
* 忽略一个过滤条件会让调用方以为「仓里就这些商品」。</p>
*
* <p>目前两家仓(恒健 {@code /v2/product/queryPage}、信仓 {@code api.productlist})
* 都只支持按 SKU 过滤 + 分页,所以模型只放这两个维度。</p>
*/
public final class ProductQuery {
/**
* 仓方 SKU 列表;空表示不限。
*
* <p>恒健是 {@code skus} 数组(一次可传多个);信仓是 {@code key} 单值(精确匹配)。
* 信仓收到多个 SKU 时由适配器<b>拒绝</b>而不是只取第一个。</p>
*/
private final List<String> providerSkus;
/** 每页条数;0 表示用仓方默认。 */
private final int pageSize;
/** 页码游标;null 表示第一页。 */
private final String cursor;
private ProductQuery(Builder b) {
this.providerSkus = Collections.unmodifiableList(new ArrayList<String>(b.providerSkus));
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
public static Builder builder() {
return new Builder();
}
/** 仓方 SKU 列表;空表示不限。不可变。 */
public List<String> providerSkus() {
return providerSkus;
}
/** 每页条数;0 表示用仓方默认。 */
public int pageSize() {
return pageSize;
}
/** 页码游标;null 表示第一页。 */
public String cursor() {
return cursor;
}
public Builder toBuilder() {
Builder b = builder().pageSize(pageSize).cursor(cursor);
b.providerSkus.addAll(providerSkus);
return b;
}
public static final class Builder {
private final List<String> providerSkus = new ArrayList<String>();
private int pageSize;
private String cursor;
public Builder providerSkus(List<String> v) {
this.providerSkus.clear();
if (v != null) {
for (String sku : v) {
if (sku != null && !sku.trim().isEmpty()) {
this.providerSkus.add(sku.trim());
}
}
}
return this;
}
public Builder providerSku(String v) {
if (v != null && !v.trim().isEmpty()) {
this.providerSkus.add(v.trim());
}
return this;
}
public Builder pageSize(int v) {
this.pageSize = v;
return this;
}
public Builder cursor(String v) {
this.cursor = v;
return this;
}
public ProductQuery build() {
return new ProductQuery(this);
}
}
}

16
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -96,6 +96,22 @@ public final class WarehouseOperations { @@ -96,6 +96,22 @@ public final class WarehouseOperations {
}
/**
* 分页查商品。只读,不走幂等。
*
* <p>与 {@link #createProduct} 相对:那个写,这个读。</p>
*/
public common.ecommerce.shared.support.Page<
common.ecommerce.warehouse.capability.WarehouseProduct> queryProducts(
final common.ecommerce.warehouse.model.ProductQuery query) {
require(WarehouseCapability.PRODUCT, WarehouseProductCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.product.query",
CallSupport.params("skuCount", query.providerSkus().size(),
"pageSize", query.pageSize(), "cursor", query.cursor()),
p -> p.size(),
() -> ((WarehouseProductCapable) adapter).queryProducts(ctx, query));
}
/**
* 创建调拨单。<b>写操作</b>:强制经幂等守卫,幂等键
* {@code warehouseCode + transferRequestNo + create}。
*

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

@ -60,6 +60,16 @@ public final class HengjianConstants { @@ -60,6 +60,16 @@ public final class HengjianConstants {
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/**
* 分页查询 SKU({@code POST})。
*
* <p>真机确认(2026-11-17):无 token 时 {@code 403 Unauthorized},鉴权先于参数校验。</p>
*
* <p><b>请求里 {@code pageSize} / {@code pageNum} 标 STRING,且文档的字段说明写反了</b>
* (pageSize 写「页码」)。按响应里的含义实现:pageSize = 每页条数,pageNum = 页码。</p>
*/
public static final String PATH_PRODUCT_QUERY_PAGE = "/v2/product/queryPage";
/**
* 创建销售发货单。
*
* <p>响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与

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

@ -21,6 +21,7 @@ import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; @@ -21,6 +21,7 @@ import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos;
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos;
import common.ecommerce.hengjian.dto.HengjianOrderAttachmentDtos;
import common.ecommerce.hengjian.dto.HengjianOrderListDtos;
import common.ecommerce.hengjian.dto.HengjianProductQueryDtos;
import common.ecommerce.hengjian.dto.HengjianProductSaveDtos;
import common.ecommerce.hengjian.dto.HengjianStorageFeeDtos;
import common.ecommerce.hengjian.dto.HengjianTailDeliveryFeeDtos;
@ -93,6 +94,7 @@ import common.ecommerce.warehouse.model.LogisticsProduct; @@ -93,6 +94,7 @@ import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.PackageResult;
@ -130,6 +132,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -130,6 +132,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
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";
private static final String OP_PRODUCT_QUERY = "warehouse.product.query";
private static final String OP_ORDER_CREATE = "warehouse.outbound.create";
private static final String OP_ORDER_GET = "warehouse.outbound.get";
private static final String OP_ORDER_QUERY = "warehouse.outbound.query";
@ -1632,6 +1635,25 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti @@ -1632,6 +1635,25 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
return ProductResult.of(body.sku, SAVED, json.stringAt(raw, "message"));
}
/**
* 分页查商品({@code POST /v2/product/queryPage})。<b>只读</b>,不走幂等。
*
* <p>请求的 {@code pageSize} / {@code pageNum} 文档标 STRING;
* 文档的字段说明把两者写反了,按<b>响应</b>里的含义实现
* (pageSize = 每页条数,pageNum = 页码)。</p>
*
* <p>响应 {@code data} 是分页对象(不是数组);{@code total} 用来判断是否还有下一页。</p>
*/
@Override
public Page<WarehouseProduct> queryProducts(WarehouseContext ctx, ProductQuery query) {
HengjianProductQueryDtos.QueryRequest body = HengjianProductQueryMapper.toRequest(query);
String raw = execute(ctx, HengjianConstants.PATH_PRODUCT_QUERY_PAGE, body, OP_PRODUCT_QUERY);
HengjianProductQueryDtos.QueryResponse resp =
json.fromJson(raw, HengjianProductQueryDtos.QueryResponse.class);
return HengjianProductQueryMapper.toPage(resp == null ? null : resp.data,
query.cursor(), HengjianProductQueryMapper.pageSizeOf(query.pageSize()));
}
// ------------------------------------------------------------------ 仓库目录
/**

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

@ -0,0 +1,248 @@ @@ -0,0 +1,248 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianProductQueryDtos;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.model.ProductQuery;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;
/**
* 恒健商品查询映射({@code POST /v2/product/queryPage})。
*
* <h2>分页字段名容易搞反</h2>
* <p>请求的 {@code pageSize} / {@code pageNum} 文档标 STRING,且<b>字段说明写反了</b>
* (pageSize 写「页码」)。按响应里的含义实现:{@code pageSize} = 每页条数、
* {@code pageNum} = 页码。</p>
*
* <h2>长度字段</h2>
* <p>响应文档漏了 {@code length}(只有 {@code width} / {@code height})。
* 映射时优先 {@code length},缺失退回 {@code itemLength},不返回 null。</p>
*
* <h2>数值都是字符串</h2>
* <p>恒健这个接口把 DOUBLE 也按 JSON 数字返回,但 DTO 用 String 接(Jackson 会转)。
* 空值 / 非法值转 null,不转 0。</p>
*/
public final class HengjianProductQueryMapper {
/** 每页默认与上限;文档没写,取 200 并拒绝超标(不静默截断)。 */
static final int DEFAULT_PAGE_SIZE = 100;
static final int MAX_PAGE_SIZE = 200;
private HengjianProductQueryMapper() {
}
/**
* 统一查询 → 恒健请求。
*
* @throws IllegalArgumentException 页大小超上限 / 游标不是页码
*/
public static HengjianProductQueryDtos.QueryRequest toRequest(ProductQuery query) {
HengjianProductQueryDtos.QueryRequest req = new HengjianProductQueryDtos.QueryRequest();
// 文档标 STRING,按字符串下发
req.pageNum = String.valueOf(pageOf(query.cursor()));
req.pageSize = String.valueOf(pageSizeOf(query.pageSize()));
if (!query.providerSkus().isEmpty()) {
req.skus = new ArrayList<String>(query.providerSkus());
}
return req;
}
/** 页码:游标是字符串化页码,空游标为第 1 页。 */
static int pageOf(String cursor) {
if (cursor == null || cursor.trim().isEmpty()) {
return 1;
}
try {
int page = Integer.parseInt(cursor.trim());
return page < 1 ? 1 : page;
} catch (NumberFormatException e) {
throw new IllegalArgumentException(
"hengjian product cursor must be a page number, got " + cursor);
}
}
/** 每页条数:0 用默认;超上限拒绝不截断。 */
static int pageSizeOf(int requested) {
if (requested <= 0) {
return DEFAULT_PAGE_SIZE;
}
if (requested > MAX_PAGE_SIZE) {
throw new IllegalArgumentException(
"hengjian product pageSize must not exceed " + MAX_PAGE_SIZE + ", got " + requested);
}
return requested;
}
// ================================================================ 响应
/** 响应 → 分页商品。 */
public static Page<WarehouseProduct> toPage(HengjianProductQueryDtos.PageData data,
String requestedCursor, int requestedPageSize) {
if (data == null || data.data == null || data.data.isEmpty()) {
return Page.last(new ArrayList<WarehouseProduct>());
}
List<WarehouseProduct> out = new ArrayList<WarehouseProduct>(data.data.size());
for (HengjianProductQueryDtos.ProductRow row : data.data) {
if (row == null) {
continue;
}
WarehouseProduct product = toProduct(row);
if (product != null) {
out.add(product);
}
}
return nextPage(out, data.total, requestedCursor, requestedPageSize);
}
/** 按 {@code total} 判断是否还有下一页。 */
static Page<WarehouseProduct> nextPage(List<WarehouseProduct> items, Long totalRaw,
String requestedCursor, int requestedPageSize) {
int page = pageOf(requestedCursor);
if (totalRaw == null) {
return items.size() < requestedPageSize
? Page.last(items) : Page.of(items, String.valueOf(page + 1));
}
if ((long) page * requestedPageSize >= totalRaw) {
return Page.last(items);
}
return Page.of(items, String.valueOf(page + 1));
}
/** 一条商品 → 统一模型;{@code sku} 缺失时返回 null(跳过脏数据,不整页失败)。 */
static WarehouseProduct toProduct(HengjianProductQueryDtos.ProductRow row) {
String sku = trimToNull(row.sku);
if (sku == null) {
return null;
}
WarehouseProduct.Builder b = WarehouseProduct.builder()
// 查询结果允许尺寸 / 重量缺失(用 0 表示),不伪造
.allowUnknownDimensions(true)
.omsSku(sku)
.providerSku(sku)
.name(firstNonBlank(row.name, row.nameEn, sku))
.nameEn(trimToNull(row.nameEn))
.description(trimToNull(row.description))
.barcode(trimToNull(row.upc))
.remark(trimToNull(row.remark))
// 长:优先 length,文档漏了它时退回 itemLength
.lengthCm(doubleOrZero(firstNonBlank(row.length, row.itemLength)))
.widthCm(doubleOrZero(row.width))
.heightCm(doubleOrZero(row.height))
.weightGrams(doubleOrZero(row.weight))
.itemLengthCm(doubleOrZero(row.itemLength))
.itemWidthCm(doubleOrZero(row.itemWidth))
.itemHeightCm(doubleOrZero(row.itemHeight))
// 仓库实测,与申报尺寸分开存
.measuredLengthCm(doubleOrNull(row.measurementLength))
.measuredWidthCm(doubleOrNull(row.measurementWidth))
.measuredHeightCm(doubleOrNull(row.measurementHeight))
.measuredWeightGrams(doubleOrNull(row.measurementWeight))
// 外箱
.packedQuantity(intOrNull(row.packedQty))
.packedLengthCm(doubleOrNull(row.packedLength))
.packedWidthCm(doubleOrNull(row.packedWidth))
.packedHeightCm(doubleOrNull(row.packedHeight))
.packedWeightGrams(doubleOrNull(row.packedWeight))
// 保质期
.expirationControl(oneZeroToBoolean(row.expirationControl))
.expirationDays(intOrNull(row.expirationDate));
Integer productType = intOrNull(row.productType);
if (productType != null) {
b.productType(productType);
}
// 保价:Y / N
String insured = trimToNull(row.isInsuranceFlag);
if (insured != null) {
b.insured("Y".equalsIgnoreCase(insured));
}
// 成本:带币种
BigDecimal cost = decimalOrNull(row.cost);
String currency = trimToNull(row.currency);
if (cost != null && currency != null) {
b.cost(Money.of(cost, currency));
}
BigDecimal rate = decimalOrNull(row.isInsuranceRate);
if (rate != null && currency != null) {
b.insuranceFee(Money.of(rate, currency));
}
return b.build();
}
// ================================================================ 工具
private static Double doubleOrNull(String raw) {
BigDecimal v = decimalOrNull(raw);
return v == null ? null : v.doubleValue();
}
/** 尺寸 / 重量:仓方没给或非正数时返回 0(查询结果里 0 = 未给)。 */
private static double doubleOrZero(String raw) {
BigDecimal v = decimalOrNull(raw);
if (v == null || v.signum() <= 0) {
return 0;
}
return v.doubleValue();
}
static BigDecimal decimalOrNull(String raw) {
String v = trimToNull(raw);
if (v == null) {
return null;
}
try {
return new BigDecimal(v);
} catch (NumberFormatException e) {
return null;
}
}
static Integer intOrNull(String raw) {
String v = trimToNull(raw);
if (v == null) {
return null;
}
try {
return Integer.valueOf(v.trim());
} catch (NumberFormatException e) {
return null;
}
}
/** 0 / 1 → false / true;其它值返回 null(不猜)。 */
static Boolean oneZeroToBoolean(String raw) {
Integer v = intOrNull(raw);
if (v == null) {
return null;
}
if (v == 1) {
return Boolean.TRUE;
}
if (v == 0) {
return Boolean.FALSE;
}
return null;
}
private static String firstNonBlank(String... values) {
for (String v : values) {
String t = trimToNull(v);
if (t != null) {
return t;
}
}
return null;
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String t = v.trim();
return t.isEmpty() ? null : t;
}
}

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

@ -0,0 +1,167 @@ @@ -0,0 +1,167 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 恒健报文结构:分页查询 SKU({@code POST /v2/product/queryPage})。
*
* <p>真机确认(2026-11-17):无 token 时直接 {@code 403 Unauthorized},
* <b>鉴权先于参数校验</b>,所以必填项按文档实现。</p>
*
* <h2>请求</h2>
* <p>{@code pageSize} / {@code pageNum} 文档标 <b>STRING</b>(其它列表接口是 INTEGER,
* 这个页不一样);{@code skus} 选填。</p>
*
* <p><b>文档的字段说明写反了</b>:{@code pageSize} 写「页码」、{@code pageNum} 写「页数」,
* 与响应里的 {@code pageSize}(每页条数)/ {@code pageNum}(页码)自相矛盾。
* 按<b>响应</b>的含义实现:{@code pageSize} = 每页条数,{@code pageNum} = 页码。</p>
*
* <h2>响应</h2>
* <p>{@code data} 是<b>分页对象</b>(不是数组):{@code total} / {@code pageSize} /
* {@code pageNum} / {@code data[]}。</p>
*
* <p><b>文档漏了 {@code length}</b>:商品主体长宽高里只列了 {@code width} / {@code height}
* 与 {@code itemLength},但建档接口有 {@code length}。映射时优先取 {@code length},
* 缺失时退回 {@code itemLength}——两者语义不同(主体 vs 单品),
* 这里做兜底是为了不让「查回来没有长」变成 null。</p>
*/
public final class HengjianProductQueryDtos {
private HengjianProductQueryDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class QueryRequest {
/** 每页条数;文档标 STRING。 */
public String pageSize;
/** 页码;文档标 STRING。 */
public String pageNum;
/** 要查的 SKU 列表;选填。 */
public List<String> skus;
}
/** 响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class QueryResponse {
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public PageData data;
}
/** 分页对象。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class PageData {
@JsonProperty("total")
public Long total;
/** 每页条数。 */
@JsonProperty("pageSize")
public Integer pageSize;
/** 页码。 */
@JsonProperty("pageNum")
public Integer pageNum;
@JsonProperty("data")
public List<ProductRow> data;
}
/** 一条商品。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductRow {
@JsonProperty("sku")
public String sku;
@JsonProperty("upc")
public String upc;
/** 1 成品 / 2 配件 / 3 耗材。 */
@JsonProperty("productType")
public String productType;
@JsonProperty("name")
public String name;
@JsonProperty("nameEn")
public String nameEn;
@JsonProperty("description")
public String description;
/** 产品宽(cm)。 */
@JsonProperty("width")
public String width;
/** 产品高(cm)。 */
@JsonProperty("height")
public String height;
/**
* 产品长(cm)。
*
* <p><b>文档的响应表里没有这一项</b>,但建档接口有;按实际响应为准。</p>
*/
@JsonProperty("length")
public String length;
/** 产品重(g)。 */
@JsonProperty("weight")
public String weight;
/** 单品长 / 宽 / 高(cm)。 */
@JsonProperty("itemLength")
public String itemLength;
@JsonProperty("itemWidth")
public String itemWidth;
@JsonProperty("itemHeight")
public String itemHeight;
/** 保质期管理:0 否 / 1 是。 */
@JsonProperty("expirationControl")
public String expirationControl;
/** 保质期天数。 */
@JsonProperty("expirationDate")
public String expirationDate;
/** 装箱数量。 */
@JsonProperty("packedQty")
public String packedQty;
@JsonProperty("packedLength")
public String packedLength;
@JsonProperty("packedWidth")
public String packedWidth;
@JsonProperty("packedHeight")
public String packedHeight;
@JsonProperty("packedWeight")
public String packedWeight;
/** 仓库实测长 / 宽 / 高(cm)/ 重(g)。 */
@JsonProperty("measurementLength")
public String measurementLength;
@JsonProperty("measurementWidth")
public String measurementWidth;
@JsonProperty("measurementHeight")
public String measurementHeight;
@JsonProperty("measurementWeight")
public String measurementWeight;
@JsonProperty("cost")
public String cost;
@JsonProperty("currency")
public String currency;
/** 产品是否保价:N 否 / Y 是。 */
@JsonProperty("isInsuranceFlag")
public String isInsuranceFlag;
@JsonProperty("isInsuranceRate")
public String isInsuranceRate;
@JsonProperty("remark")
public String remark;
}
}

196
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java

@ -0,0 +1,196 @@ @@ -0,0 +1,196 @@
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.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ProductQuery;
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.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 恒健商品查询({@code POST /v2/product/queryPage})契约测试。
*/
class HengjianProductQueryTest {
private static final WarehouseContext CTX = WarehouseContext.of(
"HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build()),
"req-1", Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC));
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
private static String body(String rows, long total) {
return "{\"code\":200,\"message\":\"success\",\"data\":{"
+ "\"total\":" + total + ",\"pageSize\":100,\"pageNum\":1,"
+ "\"data\":[" + rows + "]}}";
}
private static RecordingTransport listing(String body) {
return RecordingTransport.create()
.route(HengjianConstants.PATH_PRODUCT_QUERY_PAGE, req -> Responses.ok(body));
}
private static final String ONE_ROW =
"{\"sku\":\"SKU-A\",\"upc\":\"UPC-A\",\"productType\":1,"
+ "\"name\":\"小部件\",\"nameEn\":\"Widget\",\"description\":\"desc\","
+ "\"length\":30,\"width\":20,\"height\":10,\"weight\":1500,"
+ "\"itemLength\":29,\"itemWidth\":19,\"itemHeight\":9,"
+ "\"packedQty\":6,\"packedLength\":60,\"packedWidth\":40,\"packedHeight\":30,"
+ "\"packedWeight\":9000,"
+ "\"measurementLength\":30.5,\"measurementWidth\":20.5,"
+ "\"measurementHeight\":10.5,\"measurementWeight\":1480,"
+ "\"cost\":12.34,\"currency\":\"USD\","
+ "\"isInsuranceFlag\":\"Y\",\"isInsuranceRate\":1.5,"
+ "\"expirationControl\":1,\"expirationDate\":365,"
+ "\"remark\":\"备注\"}";
// ---------------------------------------------------------------- 请求
/** pageSize / pageNum 文档标 STRING,按字符串下发。 */
@Test
void sendsPagingAsString() {
RecordingTransport transport = listing(body(ONE_ROW, 1));
adapter(transport).queryProducts(CTX, ProductQuery.builder().pageSize(50).build());
String json = transport.lastDataRequest().body();
assertTrue(json.contains("\"pageSize\":\"50\""), json);
assertTrue(json.contains("\"pageNum\":\"1\""), json);
}
@Test
void sendsSkusOnlyWhenGiven() {
RecordingTransport absent = listing(body("", 0));
adapter(absent).queryProducts(CTX, ProductQuery.builder().build());
assertFalse(absent.lastDataRequest().body().contains("\"skus\""));
RecordingTransport present = listing(body("", 0));
adapter(present).queryProducts(CTX, ProductQuery.builder()
.providerSkus(java.util.Arrays.asList("A", "B")).build());
String json = present.lastDataRequest().body();
assertTrue(json.contains("\"skus\":[\"A\",\"B\"]"), json);
}
@Test
void cursorBecomesPageNum() {
RecordingTransport transport = listing(body(ONE_ROW, 1000));
adapter(transport).queryProducts(CTX, ProductQuery.builder().cursor("3").pageSize(10).build());
assertTrue(transport.lastDataRequest().body().contains("\"pageNum\":\"3\""));
}
@Test
void rejectsPageSizeAboveMax() {
assertThrows(IllegalArgumentException.class,
() -> adapter(listing(body("", 0))).queryProducts(CTX,
ProductQuery.builder().pageSize(500).build()));
}
// ---------------------------------------------------------------- 响应
@Test
void mapsProductFields() {
Page<WarehouseProduct> page = adapter(listing(body(ONE_ROW, 1)))
.queryProducts(CTX, ProductQuery.builder().build());
assertEquals(1, page.size());
WarehouseProduct p = page.items().get(0);
assertEquals("SKU-A", p.omsSku());
assertEquals("小部件", p.name());
assertEquals("Widget", p.nameEn());
assertEquals("UPC-A", p.barcode());
assertEquals(30.0, p.lengthCm(), 0.001);
assertEquals(20.0, p.widthCm(), 0.001);
assertEquals(10.0, p.heightCm(), 0.001);
assertEquals(1500.0, p.weightGrams(), 0.001);
assertEquals(1, p.productType());
assertEquals(Integer.valueOf(6), p.packedQuantity());
assertEquals(60.0, p.packedLengthCm(), 0.001);
assertEquals(9000.0, p.packedWeightGrams(), 0.001);
assertEquals(Boolean.TRUE, p.expirationControl());
assertEquals(Integer.valueOf(365), p.expirationDays());
assertEquals(Boolean.TRUE, p.insured());
assertEquals("备注", p.remark());
}
/** 仓库实测尺寸与申报尺寸分开存。 */
@Test
void keepsMeasuredDimensionsSeparate() {
WarehouseProduct p = adapter(listing(body(ONE_ROW, 1)))
.queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(30.0, p.lengthCm(), 0.001);
assertEquals(30.5, p.measuredLengthCm(), 0.001);
assertEquals(1480.0, p.measuredWeightGrams(), 0.001);
}
/** 文档响应表漏了 length:缺失时退回 itemLength,不返回 null。 */
@Test
void fallsBackToItemLengthWhenLengthMissing() {
String row = "{\"sku\":\"SKU-B\",\"width\":20,\"height\":10,\"weight\":100,"
+ "\"itemLength\":29,\"itemWidth\":19,\"itemHeight\":9}";
WarehouseProduct p = adapter(listing(body(row, 1)))
.queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(29.0, p.lengthCm(), 0.001, "没有 length 时用 itemLength");
}
/** total 决定是否还有下一页。 */
@Test
void pagingUsesTotal() {
Page<WarehouseProduct> more = adapter(listing(body(ONE_ROW, 500)))
.queryProducts(CTX, ProductQuery.builder().pageSize(100).build());
assertTrue(more.hasMore());
assertEquals("2", more.nextCursor());
Page<WarehouseProduct> done = adapter(listing(body(ONE_ROW, 1)))
.queryProducts(CTX, ProductQuery.builder().pageSize(100).build());
assertFalse(done.hasMore());
assertNull(done.nextCursor());
}
@Test
void emptyPageIsLast() {
Page<WarehouseProduct> page = adapter(listing(body("", 0)))
.queryProducts(CTX, ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
assertFalse(page.hasMore());
}
/** 缺 sku 的脏数据跳过。 */
@Test
void skipsRowsWithoutSku() {
String row = "{\"name\":\"无SKU\"}";
assertTrue(adapter(listing(body(row, 1)))
.queryProducts(CTX, ProductQuery.builder().build()).items().isEmpty());
}
/** 尺寸缺失用 0 表示「仓方未给」。 */
@Test
void missingDimensionsBecomeZero() {
String row = "{\"sku\":\"SKU-C\"}";
WarehouseProduct p = adapter(listing(body(row, 1)))
.queryProducts(CTX, ProductQuery.builder().build()).items().get(0);
assertEquals(0.0, p.lengthCm(), 0.001);
assertFalse(p.hasDimensions());
}
}

11
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java

@ -29,11 +29,14 @@ public final class XincangConstants { @@ -29,11 +29,14 @@ public final class XincangConstants {
/**
* 生产环境基址。
*
* <p><b>待核对</b>:官方文档只给了测试地址(迁移说明里那句「生产环境接口路径与请求方法
* 全部保持不变」只谈路径)。生产域名确认后只改这一处。调用方需要时可直接传自己的
* {@code WarehouseConnection.endpointBaseUrl},不依赖本常量。</p>
* <p>生产地址为 {@code https://oms.xincang-tech.com/oms/};<b>末尾斜杠已去掉</b>,
* 与 {@link #TEST_BASE_URL} 及 {@code WarehouseConnection} 的归一化一致
* (路径都以 {@code /} 开头,留着斜杠会拼出 {@code //api.productlist})。</p>
*
* <p>调用方需要时可直接传自己的 {@code WarehouseConnection.endpointBaseUrl},
* 不依赖本常量。</p>
*/
public static final String PRODUCTION_BASE_URL = "待核对";
public static final String PRODUCTION_BASE_URL = "https://oms.xincang-tech.com/oms";
/** 登录换取 token。 */
public static final String PATH_LOGIN = "/api.login";

34
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java

@ -39,6 +39,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot; @@ -39,6 +39,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
@ -194,7 +195,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -194,7 +195,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
* <p>{@code api.productlist} 的 {@code key} 是 SKU 过滤条件,但文档没说是否精确匹配,
* 这里再按 {@code product_no} 精确比对一次。</p>
*/
private XincangProductListDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token,
private XincangProductListDtos.ProductItem findTemporaryProduct(WarehouseContext ctx, AccessToken token,
String sku) {
Map<String, Object> params = new LinkedHashMap<>();
params.put("state", 0);
@ -203,9 +204,9 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -203,9 +204,9 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
params.put("key", sku);
String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token, OP_PRODUCT_QUERY);
List<XincangProductListDtos.ProductListItem> items =
json.listAt(raw, "rst.data", XincangProductListDtos.ProductListItem.class);
for (XincangProductListDtos.ProductListItem item : items) {
List<XincangProductListDtos.ProductItem> items =
json.listAt(raw, "rst.data", XincangProductListDtos.ProductItem.class);
for (XincangProductListDtos.ProductItem item : items) {
if (sku.equals(item.productNo)) {
return item;
}
@ -213,6 +214,31 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -213,6 +214,31 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
return null;
}
/**
* 分页查商品({@code GET api.productlist})。<b>只读</b>,不走幂等。
*
* <p>{@code token} / {@code state} / {@code page} / {@code limit} 四项仓方<b>必填</b>,
* 适配器固定传 {@code state=1}(正式产品)——临时产品是建档中间态,
* 混进业务列表会让人以为能下单。</p>
*
* <p><b>只支持按单个 SKU 过滤</b>:信仓的 {@code key} 是单值。传多个时<b>拒绝</b>,
* 静默只取第一个会让调用方以为其余也查了,而它们缺席看起来像「仓里没有」。</p>
*
* <p>响应同时给厘米/英寸两套尺寸、千克/磅两套重量,统一模型是 cm/g,
* 映射时直接用厘米那套,不做二次换算。</p>
*/
@Override
public Page<WarehouseProduct> queryProducts(WarehouseContext ctx, ProductQuery query) {
AccessToken token = login(ctx);
Map<String, Object> params = XincangProductQueryMapper.toParams(query);
String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token,
OP_PRODUCT_QUERY);
XincangProductListDtos.ProductListResponse resp =
json.fromJson(raw, XincangProductListDtos.ProductListResponse.class);
return XincangProductQueryMapper.toPage(resp == null ? null : resp.rst,
query.cursor(), XincangProductQueryMapper.limitOf(query.pageSize()));
}
// ------------------------------------------------------------------ 出库
/**

262
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java

@ -0,0 +1,262 @@ @@ -0,0 +1,262 @@
package common.ecommerce.xincang.adapter;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangProductListDtos;
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 信仓商品查询映射({@code GET api.productlist})。
*
* <p>字段表来自 Apifox「OMS接口文档V2」→ 商品 → 获取商品列表(2026-11 核对)。</p>
*
* <h2>请求</h2>
* <p>{@code token} / {@code state} / {@code page} / {@code limit} 四项<b>必填</b>。
* 适配器的 {@code state} 固定传 <b>1(正式产品)</b>——商品查询是给业务用的,
* 临时产品是建档过程的中间态,混进列表会让调用方以为能下单。</p>
*
* <h2>单位</h2>
* <p>响应同时给厘米与英寸两套尺寸、千克与磅两套重量。统一模型是 cm / g,
* 所以<b>直接用厘米那套</b>、重量用 {@code weight_kg × 1000},
* 不做「英寸换算回来」的二次舍入。</p>
*
* <h2>数值全是字符串</h2>
* <p>信仓全站这个风格。空串转 null,不转 0——「仓方没给」和「就是 0」意义不同。</p>
*/
public final class XincangProductQueryMapper {
/** 查询固定查正式产品:临时产品是建档中间态,业务不该看到。 */
static final int STATE_FORMAL = 1;
/** 分页默认与上限(文档:limit 默认 20、最大 100)。 */
static final int DEFAULT_LIMIT = 20;
static final int MAX_LIMIT = 100;
private XincangProductQueryMapper() {
}
/**
* 统一查询 → query 参数。
*
* @throws IllegalArgumentException 传了多个 SKU(信仓 {@code key} 只收单值)
*/
public static Map<String, Object> toParams(ProductQuery query) {
int page = pageOf(query.cursor());
if (query.providerSkus().size() > 1) {
// 静默只取第一个会让调用方以为其余 SKU 也查了——而且它们会缺席列表,
// 看起来像「仓里没有这个商品」
throw new IllegalArgumentException(
"xincang product list accepts a single sku (key), got "
+ query.providerSkus().size() + "; query them one by one");
}
Map<String, Object> params = new LinkedHashMap<String, Object>();
params.put("state", STATE_FORMAL);
params.put("page", page);
params.put("limit", limitOf(query.pageSize()));
if (!query.providerSkus().isEmpty()) {
params.put("key", query.providerSkus().get(0));
}
return params;
}
/** 页码:游标是字符串化页码,空游标为第 1 页。 */
static int pageOf(String cursor) {
if (cursor == null || cursor.trim().isEmpty()) {
return 1;
}
try {
int page = Integer.parseInt(cursor.trim());
return page < 1 ? 1 : page;
} catch (NumberFormatException e) {
throw new IllegalArgumentException(
"xincang product list cursor must be a page number, got " + cursor);
}
}
/** 每页条数:0 用仓方默认;超上限拒绝不截断。 */
static int limitOf(int requested) {
if (requested <= 0) {
return DEFAULT_LIMIT;
}
if (requested > MAX_LIMIT) {
throw new IllegalArgumentException(
"xincang product list limit must not exceed " + MAX_LIMIT + ", got " + requested);
}
return requested;
}
// ================================================================ 响应
/** 响应 → 分页商品。 */
public static Page<WarehouseProduct> toPage(XincangProductListDtos.ProductListResult rst,
String requestedCursor, int requestedLimit) {
if (rst == null || rst.data == null || rst.data.isEmpty()) {
return Page.last(new ArrayList<WarehouseProduct>());
}
List<WarehouseProduct> out = new ArrayList<WarehouseProduct>(rst.data.size());
for (XincangProductListDtos.ProductItem item : rst.data) {
if (item == null) {
continue;
}
WarehouseProduct product = toProduct(item);
if (product != null) {
out.add(product);
}
}
return nextPage(out, rst.count, requestedCursor, requestedLimit);
}
/**
* 是否还有下一页。
*
* <p>按 {@code rst.count}(总数)判断,不按「本页是否满」——服务端可能对
* {@code limit} 做上限收窄,满页不代表还有。</p>
*/
static Page<WarehouseProduct> nextPage(List<WarehouseProduct> items, String totalRaw,
String requestedCursor, int requestedLimit) {
int page = pageOf(requestedCursor);
Integer total = intOrNull(totalRaw);
if (total == null) {
// 仓方没给总数就按「本页是否满」保守判断
return items.size() < requestedLimit
? Page.last(items) : Page.of(items, String.valueOf(page + 1));
}
if ((long) page * requestedLimit >= total) {
return Page.last(items);
}
return Page.of(items, String.valueOf(page + 1));
}
/**
* 一条商品 → 统一模型。
*
* <p>{@code product_no} 缺失时返回 null(无法定位的商品,跳过而不是抛——
* 列表里一条脏数据不该让整页失败)。</p>
*/
static WarehouseProduct toProduct(XincangProductListDtos.ProductItem item) {
String sku = trimToNull(item.productNo);
if (sku == null) {
return null;
}
WarehouseProduct.Builder b = WarehouseProduct.builder()
// 查询结果允许尺寸 / 重量为 0(仓方没给),不伪造最小值
.allowUnknownDimensions(true)
.omsSku(sku)
.providerSku(sku)
.name(firstNonBlank(item.chnName, item.enName, sku))
.nameEn(trimToNull(item.enName))
.barcode(trimToNull(item.barCode))
// 尺寸直接用厘米那套,不从英寸反算
.lengthCm(doubleOrZero(item.sizeLCm))
.widthCm(doubleOrZero(item.sizeWCm))
.heightCm(doubleOrZero(item.sizeHCm))
// weight_kg → g
.weightGrams(gramsOf(item))
// 查询结果才有
.providerProductId(trimToNull(item.id))
.rawState(trimToNull(item.state))
.stateName(trimToNull(item.stateName))
.volumeCm3(decimalOrNull(item.volumeCm))
.createdAt(XincangOrderDetailMapper.parseTime(item.gmtCreate))
.updatedAt(XincangOrderDetailMapper.parseTime(item.gmtModify))
.imageUrl(trimToNull(item.imageUrl))
.remark(null);
// packing_rate → 装箱数量
Integer packing = intOrNull(item.packingRate);
if (packing != null) {
b.packedQuantity(packing);
}
// amount → 申报价值(信仓固定美元)
BigDecimal amount = decimalOrNull(item.amount);
if (amount != null) {
b.declaredValue(Money.of(amount, "USD"));
}
// 统一模型没有「长度/重量单位」以外的差异;外箱尺寸信仓不提供,保持 null
return b.build();
}
/**
* 重量换算成克。
*
* <p>优先 {@code weight_kg × 1000};没有千克字段时退回 {@code weight_lbs × 453.59237}。</p>
*/
static double gramsOf(XincangProductListDtos.ProductItem item) {
BigDecimal kg = decimalOrNull(item.weightKg);
if (kg != null) {
return kg.multiply(BigDecimal.valueOf(1000)).doubleValue();
}
BigDecimal lbs = decimalOrNull(item.weightLbs);
if (lbs != null) {
return lbs.multiply(BigDecimal.valueOf(XincangConstants.GRAMS_PER_POUND)).doubleValue();
}
return 0;
}
// ================================================================ 工具
/**
* 尺寸 / 重量:仓方没给或给了非正数时返回 0。
*
* <p>0 在查询结果的模型里表示「仓方未给」(见
* {@code WarehouseProduct.hasDimensions()}),不伪造一个假的最小值。</p>
*/
private static double doubleOrZero(String raw) {
BigDecimal v = decimalOrNull(raw);
if (v == null || v.signum() <= 0) {
return 0;
}
return v.doubleValue();
}
static BigDecimal decimalOrNull(String raw) {
String v = trimToNull(raw);
if (v == null) {
return null;
}
try {
return new BigDecimal(v).setScale(4, RoundingMode.HALF_UP);
} catch (NumberFormatException e) {
return null;
}
}
static Integer intOrNull(String raw) {
String v = trimToNull(raw);
if (v == null) {
return null;
}
try {
return Integer.valueOf(v);
} catch (NumberFormatException e) {
return null;
}
}
private static String firstNonBlank(String... values) {
for (String v : values) {
String t = trimToNull(v);
if (t != null) {
return t;
}
}
return null;
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String t = v.trim();
return t.isEmpty() ? null : t;
}
}

178
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java

@ -3,28 +3,196 @@ package common.ecommerce.xincang.dto; @@ -3,28 +3,196 @@ package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:产品列表({@code GET api.productlist})。
* 信仓报文结构:商品列表({@code GET api.productlist})。
*
* <p>字段表来自 Apifox「OMS接口文档V2」→ 商品 → 获取商品列表(2026-11 核对)。</p>
*
* <h2>请求</h2>
* <pre>
* GET api.productlist?token=&amp;state=&amp;page=&amp;limit=&amp;key=
* </pre>
* <p>{@code token} / {@code state} / {@code page} / {@code limit} 均<b>必填</b>;
* {@code key} 是「产品sku」过滤条件,选填。{@code limit} 最大 100。</p>
*
* <h2>响应</h2>
* <p>外层是信仓标准信封({@code errno} / {@code err}),业务数据在
* {@code rst.data[]},{@code rst.count} 是总数(是<b>字符串</b>)。</p>
*
* <p><b>所有数值字段都是字符串</b>({@code amount} / {@code weight_lbs} /
* {@code size_*_cm} …)——信仓全站这个风格,解析时按空串转 null 处理。</p>
*
* <p><b>长度 / 重量两套单位都给</b>:{@code size_*_cm} 与 {@code size_*_ln}
* (英寸,字段名沿用建档接口的 {@code _ln} 拼写);{@code weight_kg} 与
* {@code weight_lbs}。统一模型用 cm / g,映射时直接用厘米那套,不做二次换算。</p>
*/
public final class XincangProductListDtos {
private XincangProductListDtos() {
}
/** 商品列表响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductListResponse {
@JsonProperty("rst")
public ProductListResult rst;
}
/** 业务数据。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductListResult {
/** 业务码:{@code "0"} 表示成功。 */
@JsonProperty("code")
public String code;
@JsonProperty("msg")
public String msg;
@JsonProperty("data")
public List<ProductItem> data;
/** 总条数;文档标 string。 */
@JsonProperty("count")
public String count;
}
/**
* 产品列表响应({@code GET api.productlist})中 {@code rst.data[]} 的元素。
* {@code rst.data[]} 的一条商品。
*
* <p>只声明判断「是否已存在、处于什么状态」需要的字段。</p>
* <p>所有字段用 String 接,避免仓方把数字/字符串混发时解析失败;
* 需要数值时由映射器转。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductListItem {
public static final class ProductItem {
/** 产品 id。 */
@JsonProperty("id")
public String id;
/** 产品 SKU。 */
@JsonProperty("product_no")
public String productNo;
/** 产品状态:0 临时产品 / 1 正式产品。 */
/** 产品条码。 */
@JsonProperty("bar_code")
public String barCode;
/** 英文名;可能为 null。 */
@JsonProperty("en_name")
public String enName;
/** 中文名;可能为 null。 */
@JsonProperty("chn_name")
public String chnName;
/** 客户 id。 */
@JsonProperty("customer_id")
public String customerId;
/** 客户代码。 */
@JsonProperty("customer_name")
public String customerName;
/** 金额(美元)。 */
@JsonProperty("amount")
public String amount;
/** 装箱率。 */
@JsonProperty("packing_rate")
public String packingRate;
/** 重量(千克)。 */
@JsonProperty("weight_kg")
public String weightKg;
/** 重量(磅)。 */
@JsonProperty("weight_lbs")
public String weightLbs;
/** 长(厘米)。 */
@JsonProperty("size_l_cm")
public String sizeLCm;
/** 宽(厘米)。 */
@JsonProperty("size_w_cm")
public String sizeWCm;
/** 高(厘米)。 */
@JsonProperty("size_h_cm")
public String sizeHCm;
/** 长(英寸)。 */
@JsonProperty("size_l_ln")
public String sizeLLn;
/** 宽(英寸)。 */
@JsonProperty("size_w_ln")
public String sizeWLn;
/** 高(英寸)。 */
@JsonProperty("size_h_ln")
public String sizeHLn;
/** 体积(立方厘米)。 */
@JsonProperty("volume_cm")
public String volumeCm;
/** 体积(立方英寸)。 */
@JsonProperty("volume_ln")
public String volumeLn;
/** 体积(立方米)。 */
@JsonProperty("volume_m")
public String volumeM;
/** 创建时间(北京时间 {@code yyyy-MM-dd HH:mm:ss})。 */
@JsonProperty("gmt_create")
public String gmtCreate;
/** 修改时间。 */
@JsonProperty("gmt_modify")
public String gmtModify;
/** 状态码:0 临时产品 / 1 正式产品。 */
@JsonProperty("state")
public String state;
/** 状态中文名。 */
@JsonProperty("state_name")
public String stateName;
/** 产品图片签名 URL;有有效期,用于下载保存。 */
@JsonProperty("image_url")
public String imageUrl;
/** 产品图片 OSS 元数据;修改临时产品图片时要原样回传。 */
@JsonProperty("product_image")
public ProductImage productImage;
/** 文档里没有中文名的字段,原样保留。 */
@JsonProperty("product_code")
public String productCode;
/** 仓库码。 */
@JsonProperty("ckm")
public String ckm;
}
/** 产品图片 OSS 元数据。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductImage {
@JsonProperty("type")
public String type;
@JsonProperty("bucket")
public String bucket;
@JsonProperty("file_url")
public String fileUrl;
@JsonProperty("file_name")
public String fileName;
}
}

215
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java

@ -0,0 +1,215 @@ @@ -0,0 +1,215 @@
package common.ecommerce.xincang.adapter;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants;
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.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 信仓商品查询({@code GET api.productlist})契约测试。
*
* <p>字段表来自 Apifox「OMS接口文档V2」→ 商品 → 获取商品列表。</p>
*/
class XincangProductQueryTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("XC-1", common.ecommerce.warehouse.enums.WarehouseProvider.XINCANG,
"LAX",
WarehouseConnection.of(XincangConstants.TEST_BASE_URL,
ChannelSecret.builder().appKey("k").appSecret("s").build()),
"req-1", CLOCK);
}
private static XincangAdapter adapter(RecordingTransport transport) {
return new XincangAdapter(transport, new JacksonJsonCodec(),
new common.ecommerce.shared.testkit.InMemoryTokenStore(),
new common.ecommerce.shared.testkit.InMemoryLockProvider(),
Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC));
}
/** 产品列表成功响应(登录也走同一 transport,这里单独 route 登录)。 */
private static RecordingTransport productListing(String body) {
return RecordingTransport.create()
.route(XincangConstants.PATH_LOGIN, req -> Responses.ok(
"{\"rst\":{\"id\":\"c-1\",\"token\":\"tk-1\",\"token_expire_time\":\""
+ java.time.LocalDateTime.ofInstant(Instant.parse("2026-11-17T02:00:00Z"),
XincangConstants.SYSTEM_ZONE)
.format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ "\"},\"errno\":0,\"err\":\"\"}"))
.route(XincangConstants.PATH_PRODUCT_LIST, req -> Responses.ok(body));
}
/** 取最近一次 productlist 请求的 URL。 */
private static String productListUrl(RecordingTransport transport) {
for (HttpRequest req : transport.recorded()) {
if (req.url().contains(XincangConstants.PATH_PRODUCT_LIST)) {
return req.url();
}
}
throw new AssertionError("no productlist request recorded");
}
private static String listBody(String rowsJson, String count) {
return "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":[" + rowsJson + "],"
+ "\"count\":\"" + count + "\"},\"errno\":0,\"err\":\"\"}";
}
private static final String ONE_ROW =
"{\"id\":\"9001\",\"product_no\":\"SKU-A\",\"bar_code\":\"BC-A\","
+ "\"en_name\":\"Widget\",\"chn_name\":\"小部件\","
+ "\"customer_id\":\"7\",\"customer_name\":\"C007\","
+ "\"amount\":\"12.34\",\"packing_rate\":\"6\","
+ "\"weight_kg\":\"1.5\",\"weight_lbs\":\"3.3069\","
+ "\"size_l_cm\":\"30\",\"size_w_cm\":\"20\",\"size_h_cm\":\"10\","
+ "\"size_l_ln\":\"11.81\",\"size_w_ln\":\"7.87\",\"size_h_ln\":\"3.94\","
+ "\"volume_cm\":\"6000\",\"volume_ln\":\"366.1\",\"volume_m\":\"0.006\","
+ "\"gmt_create\":\"2026-11-01 10:00:00\","
+ "\"gmt_modify\":\"2026-11-02 11:30:00\","
+ "\"state\":\"1\",\"state_name\":\"正式产品\","
+ "\"image_url\":\"https://oss/x.png\","
+ "\"ckm\":\"LAX\"}";
// ---------------------------------------------------------------- 请求
@Test
void sendsMandatoryQueryParams() {
RecordingTransport transport = productListing(listBody(ONE_ROW, "1"));
adapter(transport).queryProducts(ctx(), ProductQuery.builder().build());
String url = productListUrl(transport);
// 四项必填
assertTrue(url.contains("state=1"), url);
assertTrue(url.contains("page=1"), url);
assertTrue(url.contains("limit="), url);
assertTrue(url.contains("token="), url);
}
/** 固定查正式产品:临时产品是建档中间态,不该混进业务列表。 */
@Test
void alwaysQueriesFormalState() {
RecordingTransport transport = productListing(listBody("", "0"));
adapter(transport).queryProducts(ctx(), ProductQuery.builder().build());
assertTrue(productListUrl(transport).contains("state=1"));
}
/** key 是单值:传多个 SKU 时拒绝,不静默只取第一个。 */
@Test
void rejectsMultipleSkus() {
RecordingTransport transport = productListing(listBody("", "0"));
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(transport).queryProducts(ctx(), ProductQuery.builder()
.providerSkus(java.util.Arrays.asList("A", "B")).build()));
assertTrue(ex.getMessage().contains("single sku"), ex.getMessage());
}
@Test
void sendsSingleSkuAsKey() {
RecordingTransport transport = productListing(listBody(ONE_ROW, "1"));
adapter(transport).queryProducts(ctx(), ProductQuery.builder().providerSku("SKU-A").build());
assertTrue(productListUrl(transport).contains("key=SKU-A"));
}
@Test
void rejectsLimitAboveMax() {
RecordingTransport transport = productListing(listBody("", "0"));
assertThrows(IllegalArgumentException.class,
() -> adapter(transport).queryProducts(ctx(), ProductQuery.builder().pageSize(500).build()));
}
// ---------------------------------------------------------------- 响应
@Test
void mapsProductFields() {
Page<WarehouseProduct> page = adapter(productListing(listBody(ONE_ROW, "1")))
.queryProducts(ctx(), ProductQuery.builder().build());
assertEquals(1, page.size());
WarehouseProduct p = page.items().get(0);
assertEquals("SKU-A", p.omsSku());
assertEquals("SKU-A", p.providerSku());
assertEquals("小部件", p.name());
assertEquals("Widget", p.nameEn());
assertEquals("BC-A", p.barcode());
// 尺寸直接用厘米那套,不从英寸反算
assertEquals(30.0, p.lengthCm(), 0.001);
assertEquals(20.0, p.widthCm(), 0.001);
assertEquals(10.0, p.heightCm(), 0.001);
// weight_kg × 1000
assertEquals(1500.0, p.weightGrams(), 0.001);
assertEquals(Integer.valueOf(6), p.packedQuantity());
assertEquals("USD", p.declaredValue().currencyCode());
assertEquals(0, p.declaredValue().amount().compareTo(new java.math.BigDecimal("12.34")));
assertEquals("9001", p.providerProductId());
assertEquals("1", p.rawState());
assertEquals("正式产品", p.stateName());
assertEquals("https://oss/x.png", p.imageUrl());
// 北京时间 → UTC:10:00 北京 = 02:00 UTC
assertEquals(Instant.parse("2026-11-01T02:00:00Z"), p.createdAt());
}
/** count 决定是否还有下一页,不看本页是否满。 */
@Test
void pagingUsesCount() {
Page<WarehouseProduct> more = adapter(productListing(listBody(ONE_ROW, "50")))
.queryProducts(ctx(), ProductQuery.builder().pageSize(20).build());
assertTrue(more.hasMore());
assertEquals("2", more.nextCursor());
Page<WarehouseProduct> done = adapter(productListing(listBody(ONE_ROW, "1")))
.queryProducts(ctx(), ProductQuery.builder().pageSize(20).build());
assertFalse(done.hasMore());
assertNull(done.nextCursor());
}
@Test
void emptyDataIsLastPage() {
Page<WarehouseProduct> page = adapter(productListing(listBody("", "0")))
.queryProducts(ctx(), ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
assertFalse(page.hasMore());
}
/** 没有尺寸的商品用 0 表示「仓方未给」,不伪造。 */
@Test
void missingDimensionsBecomeZero() {
String row = "{\"product_no\":\"SKU-B\",\"state\":\"1\",\"weight_kg\":\"\"}";
WarehouseProduct p = adapter(productListing(listBody(row, "1")))
.queryProducts(ctx(), ProductQuery.builder().build()).items().get(0);
assertEquals(0.0, p.lengthCm(), 0.001);
assertEquals(0.0, p.weightGrams(), 0.001);
assertFalse(p.hasDimensions());
}
/** 缺 product_no 的脏数据跳过,不让整页失败。 */
@Test
void skipsRowsWithoutSku() {
String row = "{\"id\":\"1\",\"chn_name\":\"无 SKU\"}";
Page<WarehouseProduct> page = adapter(productListing(listBody(row, "1")))
.queryProducts(ctx(), ProductQuery.builder().build());
assertTrue(page.items().isEmpty());
}
}
Loading…
Cancel
Save