From aac75d590416501210ca491f76d56eca60013ac5 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Tue, 17 Nov 2026 14:56:44 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E4=BF=A1=E4=BB=93=20/=20=E6=81=92?= =?UTF-8?q?=E5=81=A5=E5=85=A8=E6=8E=A5=E5=95=86=E5=93=81=E6=9F=A5=E8=AF=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs-warehouse/hengjian/README.md | 39 +++ docs-warehouse/xincang/README.md | 49 +++- .../warehouse/capability/WarehouseProduct.java | 215 ++++++++++++++++- .../capability/WarehouseProductCapable.java | 19 +- .../ecommerce/warehouse/model/ProductQuery.java | 100 ++++++++ .../warehouse/sdk/WarehouseOperations.java | 16 ++ .../ecommerce/hengjian/HengjianConstants.java | 10 + .../hengjian/adapter/HengjianAdapter.java | 22 ++ .../adapter/HengjianProductQueryMapper.java | 248 +++++++++++++++++++ .../hengjian/dto/HengjianProductQueryDtos.java | 167 +++++++++++++ .../hengjian/adapter/HengjianProductQueryTest.java | 196 +++++++++++++++ .../common/ecommerce/xincang/XincangConstants.java | 11 +- .../ecommerce/xincang/adapter/XincangAdapter.java | 36 ++- .../xincang/adapter/XincangProductQueryMapper.java | 262 +++++++++++++++++++++ .../xincang/dto/XincangProductListDtos.java | 178 +++++++++++++- .../xincang/adapter/XincangProductQueryTest.java | 215 +++++++++++++++++ 16 files changed, 1760 insertions(+), 23 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java create mode 100644 warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 4189c95..bf954e7 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -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 个变体**请求, diff --git a/docs-warehouse/xincang/README.md b/docs-warehouse/xincang/README.md index 93784af..029e694 100644 --- a/docs-warehouse/xincang/README.md +++ b/docs-warehouse/xincang/README.md @@ -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 @@ | 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 @@ ``` ① 查临时产品(决定 add 还是 update) - GET /api.productlist?state=0&key= + GET /api.productlist?state=0&key=&page=1&limit=20 ② 新增(临时产品) POST /api.add_product 或 更新(仅临时产品可更新) POST /api.update_product +③ 商品查询(正式产品) + GET /api.productlist?state=1&page=1&limit=20[&key=] ``` +### 商品查询(`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` 是单值。传多个时适配器拒绝, +静默只取第一个会让其余 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 @@ | 项 | 现状 | |---|---| -| 生产域名 | 文档未给,常量写的是 `"待核对"` | +| 生产域名 | `https://oms.xincang-tech.com/oms`(已确认并写入常量) | | 限流 | 未公开,按 2 req/s | | **最优渠道 `calculate_order_v3`** | 文档标 `GET` + JSON body,**OkHttp 不支持 GET 带 body**;适配器按 **POST + JSON body** 下发 | diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java index 8b46474..1b5e249 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java @@ -161,6 +161,43 @@ public final class WarehouseProduct { */ private final Boolean specialOuterPackaging; + // ==================== 查询结果才有(下发时忽略)==================== + + /** + * 仓侧商品 id。查询结果里有;建档时忽略。 + * + *

信仓 {@code id}、恒健无此字段。

+ */ + private final String providerProductId; + /** + * 仓方实测尺寸 / 重量;null 表示仓方未给。 + * + *

与 {@link #lengthCm()} 等不是一回事:那些是我们申报的尺寸, + * 这些是仓方收货后实测的(恒健 {@code measurement*})。下标成本、抛重都以实测为准。

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

信仓 {@code state}:0 临时 / 1 正式;恒健无状态字段。

+ */ + private final String rawState; + /** 仓方状态中文名(信仓 {@code state_name});无则为 null。 */ + private final String stateName; + /** + * 体积(立方厘米);仓方原值。 + * + *

信仓 {@code volume_cm};恒健无此字段。

+ */ + private final java.math.BigDecimal volumeCm3; + /** * 产品图片地址;null 表示不传。 * @@ -183,10 +220,23 @@ public final class WarehouseProduct { // 不在构造期强制:这是运去哪的必填项,信仓不需要。必填性由各适配器按自己的 // 协议校验,见 YqnProductMapper;未给时保持 -1 表示「不传」。 this.packingType = b.packingType; - this.lengthCm = requirePositive(b.lengthCm, "lengthCm"); - this.widthCm = requirePositive(b.widthCm, "widthCm"); - this.heightCm = requirePositive(b.heightCm, "heightCm"); - this.weightGrams = requirePositive(b.weightGrams, "weightGrams"); + 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 { new java.util.ArrayList(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 { 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 { 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 { 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(表示仓方未给)。 + * + *

只给查询结果用:建档时仍然必须给正数。不设这个开关时行为不变。

+ */ + private boolean allowUnknownDimensions; private final List imageUrls = new java.util.ArrayList(); private Boolean specialOuterPackaging; private Boolean expirationControl; @@ -722,6 +859,76 @@ public final class WarehouseProduct { /** * @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐 */ + /** + * 允许尺寸 / 重量为 0(表示仓方未给)。 + * + *

只在把查询结果映射成模型时使用;建档仍是必填正数。

+ */ + 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); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java index a8f4753..d5f960f 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java @@ -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); + /** + * 分页查商品。只读,不走幂等。 + * + *

各仓支持的过滤维度不同:不支持的维度由适配器显式拒绝, + * 不静默忽略——忽略一个过滤条件会让调用方以为「仓里就这些商品」。

+ * + * @param query 查询条件;游标为空表示第一页 + * @return 当前页商品;{@code nextCursor} 非空表示还有下一页 + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不支持商品查询 + */ + default common.ecommerce.shared.support.Page 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 { diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java new file mode 100644 index 0000000..aab234e --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java @@ -0,0 +1,100 @@ +package common.ecommerce.warehouse.model; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 商品查询条件。 + * + *

与 {@code WarehouseProductCapable.createOrUpdate} 的区别:那个是写,这个是读。 + * 各仓支持的维度不同:不支持的维度由适配器显式拒绝,不静默忽略—— + * 忽略一个过滤条件会让调用方以为「仓里就这些商品」。

+ * + *

目前两家仓(恒健 {@code /v2/product/queryPage}、信仓 {@code api.productlist}) + * 都只支持按 SKU 过滤 + 分页,所以模型只放这两个维度。

+ */ +public final class ProductQuery { + + /** + * 仓方 SKU 列表;空表示不限。 + * + *

恒健是 {@code skus} 数组(一次可传多个);信仓是 {@code key} 单值(精确匹配)。 + * 信仓收到多个 SKU 时由适配器拒绝而不是只取第一个。

+ */ + private final List providerSkus; + /** 每页条数;0 表示用仓方默认。 */ + private final int pageSize; + /** 页码游标;null 表示第一页。 */ + private final String cursor; + + private ProductQuery(Builder b) { + this.providerSkus = Collections.unmodifiableList(new ArrayList(b.providerSkus)); + this.pageSize = b.pageSize; + this.cursor = b.cursor; + } + + public static Builder builder() { + return new Builder(); + } + + /** 仓方 SKU 列表;空表示不限。不可变。 */ + public List 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 providerSkus = new ArrayList(); + private int pageSize; + private String cursor; + + public Builder providerSkus(List 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); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 09517c9..5a33493 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -96,6 +96,22 @@ public final class WarehouseOperations { } /** + * 分页查商品。只读,不走幂等。 + * + *

与 {@link #createProduct} 相对:那个写,这个读。

+ */ + 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)); + } + + /** * 创建调拨单。写操作:强制经幂等守卫,幂等键 * {@code warehouseCode + transferRequestNo + create}。 * 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 cfdb12e..81c508a 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 @@ -60,6 +60,16 @@ public final class HengjianConstants { public static final String PATH_PRODUCT_SAVE = "/v1/product/save"; /** + * 分页查询 SKU({@code POST})。 + * + *

真机确认(2026-11-17):无 token 时 {@code 403 Unauthorized},鉴权先于参数校验。

+ * + *

请求里 {@code pageSize} / {@code pageNum} 标 STRING,且文档的字段说明写反了 + * (pageSize 写「页码」)。按响应里的含义实现:pageSize = 每页条数,pageNum = 页码。

+ */ + public static final String PATH_PRODUCT_QUERY_PAGE = "/v2/product/queryPage"; + + /** * 创建销售发货单。 * *

响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与 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 43dc664..2dc2a46 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 @@ -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; 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 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 return ProductResult.of(body.sku, SAVED, json.stringAt(raw, "message")); } + /** + * 分页查商品({@code POST /v2/product/queryPage})。只读,不走幂等。 + * + *

请求的 {@code pageSize} / {@code pageNum} 文档标 STRING; + * 文档的字段说明把两者写反了,按响应里的含义实现 + * (pageSize = 每页条数,pageNum = 页码)。

+ * + *

响应 {@code data} 是分页对象(不是数组);{@code total} 用来判断是否还有下一页。

+ */ + @Override + public Page 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())); + } + // ------------------------------------------------------------------ 仓库目录 /** 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 new file mode 100644 index 0000000..cd3762a --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java @@ -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})。 + * + *

分页字段名容易搞反

+ *

请求的 {@code pageSize} / {@code pageNum} 文档标 STRING,且字段说明写反了 + * (pageSize 写「页码」)。按响应里的含义实现:{@code pageSize} = 每页条数、 + * {@code pageNum} = 页码。

+ * + *

长度字段

+ *

响应文档漏了 {@code length}(只有 {@code width} / {@code height})。 + * 映射时优先 {@code length},缺失退回 {@code itemLength},不返回 null。

+ * + *

数值都是字符串

+ *

恒健这个接口把 DOUBLE 也按 JSON 数字返回,但 DTO 用 String 接(Jackson 会转)。 + * 空值 / 非法值转 null,不转 0。

+ */ +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(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 toPage(HengjianProductQueryDtos.PageData data, + String requestedCursor, int requestedPageSize) { + if (data == null || data.data == null || data.data.isEmpty()) { + return Page.last(new ArrayList()); + } + List out = new ArrayList(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 nextPage(List 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; + } +} 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 new file mode 100644 index 0000000..2af4cb1 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductQueryDtos.java @@ -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})。 + * + *

真机确认(2026-11-17):无 token 时直接 {@code 403 Unauthorized}, + * 鉴权先于参数校验,所以必填项按文档实现。

+ * + *

请求

+ *

{@code pageSize} / {@code pageNum} 文档标 STRING(其它列表接口是 INTEGER, + * 这个页不一样);{@code skus} 选填。

+ * + *

文档的字段说明写反了:{@code pageSize} 写「页码」、{@code pageNum} 写「页数」, + * 与响应里的 {@code pageSize}(每页条数)/ {@code pageNum}(页码)自相矛盾。 + * 按响应的含义实现:{@code pageSize} = 每页条数,{@code pageNum} = 页码。

+ * + *

响应

+ *

{@code data} 是分页对象(不是数组):{@code total} / {@code pageSize} / + * {@code pageNum} / {@code data[]}。

+ * + *

文档漏了 {@code length}:商品主体长宽高里只列了 {@code width} / {@code height} + * 与 {@code itemLength},但建档接口有 {@code length}。映射时优先取 {@code length}, + * 缺失时退回 {@code itemLength}——两者语义不同(主体 vs 单品), + * 这里做兜底是为了不让「查回来没有长」变成 null。

+ */ +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 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 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)。 + * + *

文档的响应表里没有这一项,但建档接口有;按实际响应为准。

+ */ + @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; + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java new file mode 100644 index 0000000..96edc6e --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductQueryTest.java @@ -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 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 more = adapter(listing(body(ONE_ROW, 500))) + .queryProducts(CTX, ProductQuery.builder().pageSize(100).build()); + assertTrue(more.hasMore()); + assertEquals("2", more.nextCursor()); + + Page done = adapter(listing(body(ONE_ROW, 1))) + .queryProducts(CTX, ProductQuery.builder().pageSize(100).build()); + assertFalse(done.hasMore()); + assertNull(done.nextCursor()); + } + + @Test + void emptyPageIsLast() { + Page 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()); + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java index 48ba29c..bd4bffe 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java @@ -29,11 +29,14 @@ public final class XincangConstants { /** * 生产环境基址。 * - *

待核对:官方文档只给了测试地址(迁移说明里那句「生产环境接口路径与请求方法 - * 全部保持不变」只谈路径)。生产域名确认后只改这一处。调用方需要时可直接传自己的 - * {@code WarehouseConnection.endpointBaseUrl},不依赖本常量。

+ *

生产地址为 {@code https://oms.xincang-tech.com/oms/};末尾斜杠已去掉, + * 与 {@link #TEST_BASE_URL} 及 {@code WarehouseConnection} 的归一化一致 + * (路径都以 {@code /} 开头,留着斜杠会拼出 {@code //api.productlist})。

+ * + *

调用方需要时可直接传自己的 {@code WarehouseConnection.endpointBaseUrl}, + * 不依赖本常量。

*/ - 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"; diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java index 2edf1d1..70ec33d 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java @@ -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,8 +195,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa *

{@code api.productlist} 的 {@code key} 是 SKU 过滤条件,但文档没说是否精确匹配, * 这里再按 {@code product_no} 精确比对一次。

*/ - private XincangProductListDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token, - String sku) { + private XincangProductListDtos.ProductItem findTemporaryProduct(WarehouseContext ctx, AccessToken token, + String sku) { Map params = new LinkedHashMap<>(); params.put("state", 0); params.put("page", 1); @@ -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 items = - json.listAt(raw, "rst.data", XincangProductListDtos.ProductListItem.class); - for (XincangProductListDtos.ProductListItem item : items) { + List 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 return null; } + /** + * 分页查商品({@code GET api.productlist})。只读,不走幂等。 + * + *

{@code token} / {@code state} / {@code page} / {@code limit} 四项仓方必填, + * 适配器固定传 {@code state=1}(正式产品)——临时产品是建档中间态, + * 混进业务列表会让人以为能下单。

+ * + *

只支持按单个 SKU 过滤:信仓的 {@code key} 是单值。传多个时拒绝, + * 静默只取第一个会让调用方以为其余也查了,而它们缺席看起来像「仓里没有」。

+ * + *

响应同时给厘米/英寸两套尺寸、千克/磅两套重量,统一模型是 cm/g, + * 映射时直接用厘米那套,不做二次换算。

+ */ + @Override + public Page queryProducts(WarehouseContext ctx, ProductQuery query) { + AccessToken token = login(ctx); + Map 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())); + } + // ------------------------------------------------------------------ 出库 /** diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java new file mode 100644 index 0000000..3f72b7f --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductQueryMapper.java @@ -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})。 + * + *

字段表来自 Apifox「OMS接口文档V2」→ 商品 → 获取商品列表(2026-11 核对)。

+ * + *

请求

+ *

{@code token} / {@code state} / {@code page} / {@code limit} 四项必填。 + * 适配器的 {@code state} 固定传 1(正式产品)——商品查询是给业务用的, + * 临时产品是建档过程的中间态,混进列表会让调用方以为能下单。

+ * + *

单位

+ *

响应同时给厘米与英寸两套尺寸、千克与磅两套重量。统一模型是 cm / g, + * 所以直接用厘米那套、重量用 {@code weight_kg × 1000}, + * 不做「英寸换算回来」的二次舍入。

+ * + *

数值全是字符串

+ *

信仓全站这个风格。空串转 null,不转 0——「仓方没给」和「就是 0」意义不同。

+ */ +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 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 params = new LinkedHashMap(); + 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 toPage(XincangProductListDtos.ProductListResult rst, + String requestedCursor, int requestedLimit) { + if (rst == null || rst.data == null || rst.data.isEmpty()) { + return Page.last(new ArrayList()); + } + List out = new ArrayList(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); + } + + /** + * 是否还有下一页。 + * + *

按 {@code rst.count}(总数)判断,不按「本页是否满」——服务端可能对 + * {@code limit} 做上限收窄,满页不代表还有。

+ */ + static Page nextPage(List 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)); + } + + /** + * 一条商品 → 统一模型。 + * + *

{@code product_no} 缺失时返回 null(无法定位的商品,跳过而不是抛—— + * 列表里一条脏数据不该让整页失败)。

+ */ + 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(); + } + + /** + * 重量换算成克。 + * + *

优先 {@code weight_kg × 1000};没有千克字段时退回 {@code weight_lbs × 453.59237}。

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

0 在查询结果的模型里表示「仓方未给」(见 + * {@code WarehouseProduct.hasDimensions()}),不伪造一个假的最小值。

+ */ + 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java index 6ab4a35..5d58251 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java @@ -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})。 + * + *

字段表来自 Apifox「OMS接口文档V2」→ 商品 → 获取商品列表(2026-11 核对)。

+ * + *

请求

+ *
+ * GET api.productlist?token=&state=&page=&limit=&key=
+ * 
+ *

{@code token} / {@code state} / {@code page} / {@code limit} 均必填; + * {@code key} 是「产品sku」过滤条件,选填。{@code limit} 最大 100。

+ * + *

响应

+ *

外层是信仓标准信封({@code errno} / {@code err}),业务数据在 + * {@code rst.data[]},{@code rst.count} 是总数(是字符串)。

+ * + *

所有数值字段都是字符串({@code amount} / {@code weight_lbs} / + * {@code size_*_cm} …)——信仓全站这个风格,解析时按空串转 null 处理。

+ * + *

长度 / 重量两套单位都给:{@code size_*_cm} 与 {@code size_*_ln} + * (英寸,字段名沿用建档接口的 {@code _ln} 拼写);{@code weight_kg} 与 + * {@code weight_lbs}。统一模型用 cm / g,映射时直接用厘米那套,不做二次换算。

*/ 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 data; + + /** 总条数;文档标 string。 */ + @JsonProperty("count") + public String count; + } + /** - * 产品列表响应({@code GET api.productlist})中 {@code rst.data[]} 的元素。 + * {@code rst.data[]} 的一条商品。 * - *

只声明判断「是否已存在、处于什么状态」需要的字段。

+ *

所有字段用 String 接,避免仓方把数字/字符串混发时解析失败; + * 需要数值时由映射器转。

*/ @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; } } diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java new file mode 100644 index 0000000..61b69a1 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductQueryTest.java @@ -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})契约测试。 + * + *

字段表来自 Apifox「OMS接口文档V2」→ 商品 → 获取商品列表。

+ */ +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 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 more = adapter(productListing(listBody(ONE_ROW, "50"))) + .queryProducts(ctx(), ProductQuery.builder().pageSize(20).build()); + assertTrue(more.hasMore()); + assertEquals("2", more.nextCursor()); + + Page done = adapter(productListing(listBody(ONE_ROW, "1"))) + .queryProducts(ctx(), ProductQuery.builder().pageSize(20).build()); + assertFalse(done.hasMore()); + assertNull(done.nextCursor()); + } + + @Test + void emptyDataIsLastPage() { + Page 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 page = adapter(productListing(listBody(row, "1"))) + .queryProducts(ctx(), ProductQuery.builder().build()); + + assertTrue(page.items().isEmpty()); + } +}