diff --git a/docs-warehouse/architecture.md b/docs-warehouse/architecture.md index 7e12139..58cdddf 100644 --- a/docs-warehouse/architecture.md +++ b/docs-warehouse/architecture.md @@ -85,7 +85,7 @@ public enum YqnOutboundStatus { `sortDirection` 是 core 枚举 `SortDirection`(`ASC` / `DESC`)。适配器不支持排序时忽略, 调用方不应假定排序一定生效。 -`WarehouseCapability`(26 个): +`WarehouseCapability`(27 个): | 能力 | 说明 | 运去哪 | 信仓 | |---|---|:---:|:---:| @@ -99,7 +99,7 @@ public enum YqnOutboundStatus { | `BOX_LABEL` | 入库箱标(异步) | ✅ | — | | `SKU_LABEL` | SKU 标(异步) | ✅ | — | | `LOGISTICS_PRODUCT` | 物流产品清单 | ✅ | ✅ | -| `WAREHOUSE_DIRECTORY` | 仓库目录 | ✅ | — | +| `DIRECTORY` | 仓库 / 承运商目录 | ✅ | — | | `WEBHOOK` | 状态回调 | ✅ | — | | `TRANSFER` | 仓间调拨 | ✅ | ✅ | | `RETURN` | 退货发起 / 查询 | ✅ | — | @@ -107,6 +107,7 @@ public enum YqnOutboundStatus { | `TRACKING` | 物流轨迹 | ✅ | — | | `TRACKING_CHANGE` | 物流异动单(召回 / 换址 / 在途异常) | — | — | | `ADDRESS_CLASSIFICATION` | 地址属性识别(商业 / 住宅) | — | — | +| `CASE_MARK_PRINT` | 箱唛打印(同步 PDF) | — | — | | `DESTRUCTION` | 销毁 / 报废 | ✅ | — | | `INVENTORY_ADJUST` | 库存调整 | ❌ 无接口 | — | | `EXCHANGE` / `UNSHIPPED_ITEM` / `BOL` / `SPLIT` | 预留 | ❌ | — | diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md index 90ab88b..0069713 100644 --- a/docs-warehouse/edayun/README.md +++ b/docs-warehouse/edayun/README.md @@ -8,6 +8,7 @@ | 适配器 / 工厂 | ✅ 类型就绪,能力位为空 | | 获取 token | ✅ 已对接(`POST /oauth/token`) | | 创建产品 | ✅ 已对接(`POST /webApi/skuInfo/v1/createProduct`) | +| 商品查询 | ✅ 已对接(`POST /webApi/skuInfo/v1/listProductPage`) | | 创建出库单 | ✅ 已对接(`POST /webApi/order/v1/createOrder`) | | 查询出库单 | ✅ 已对接(`POST /webApi/order/v1/getOrderInfo`) | | 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) | @@ -28,7 +29,7 @@ | 物流产品清单 | ✅ 已对接(`POST /webApi/order/listByLogisticProductHasPerm`) | | 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) | | 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) | -| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** | +| 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMark`),**真机未启用** | | 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) | | 仓库清单 | ✅ 已对接(`warehouse/listWarehouseHasPerm` + `warehouse/listActive`) | | 其它业务接口 | ⬜ 等文档 | @@ -156,6 +157,55 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false -Dedayun.probe.product=tr ... -Dedayun.probe.write=true -Dedayun.probe.token=... -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... ``` +## 商品查询 + +``` +POST /webApi/skuInfo/v1/listProductPage → Page +``` + +### 三个坑 + +**1. SKU 是逗号拼接的单个字符串,且一次最多 50 个。** + +```java +req.skuCode = String.join(",", query.providerSkus()); // "A,B,C" +``` +统一模型是 `List`,超 50 本地拒绝(不截断)。 + +**2. 没有数据时回 `code=500, msg=查询无数据`。** + +这是「查不到」不是「调用失败」,按空页处理——与轨迹接口的「未匹配到轨迹」同一处理。 +其它 500 仍抛异常。 + +**3. 查询条件全空时默认只查最近一个月。** + +`ybtest` 创建于 2021 年,不带时间窗就查不到。查老数据必须显式给时间窗。 + +### 尺寸取实际值,缺失才回落预报值 + +| 易达云 | 我们用的 | +|---|---| +| `length/width/height/weight` | **优先**(仓方当前存的值) | +| `forecastLength/...` | 实际值缺失时回落 | + +真机对比很能说明问题:`ybtest` 的 `length` 是 55(实际量过), +`forecastLength` 是 10(预报时填的)——两者差 5 倍,拿错会算错运费。 + +### 页码从 1 开始,单页最多 200 + +### 真机验证(2026-11-17) + +| 场景 | 结果 | +|---|---| +| 只给 `pageNum/pageSize`(不带时间窗) | `total=52244`(全量) | +| `skuCode=ybtest` | `total=1`,实际尺寸 55×4×3、重量 1 | +| `skuCode=ybtest` + 最近 30 天窗口 | **`code=500 查询无数据`**(该 SKU 建于 2021) | +| 不存在的 SKU / 条码 | 同样「查询无数据」 | +| 10 年窗口 + `ybtest` | 1 行,`createdAt=2021-02-04` | + +**SKU 是仓侧 SKU**:`ybtest` 既是 OMS SKU 也是建档时下发的 `providerSku`, +所以看不出口径差异;若两者不同,必须传仓侧那串(见下方「SKU 口径」)。 + ## 创建出库单 ``` @@ -913,10 +963,10 @@ POST /webApi/rma/info/v1/saveAndPublish → WarehouseReturn | 方法 | 状态 | |---|---| -| `queryReturns(ctx, cursor)` | ❌ 文档只给了按单号查,没有列表接口 | +| `queryReturns(ReturnQuery)` | ✅ 已实现(`selectRmaInfoList`) | | `process(ctx, cmd)` | ❌ 要仓侧明细行 id,而详情响应里**没有行 id**(`checkList` / `skuList` / `shelfList` 都没有) | -`queryReturns` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。 +`process` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。 ### 探针 @@ -1154,7 +1204,7 @@ POST /webApi/track/getTrackInfoList → List / TrackingInfo | 端点 | 实际打印 | 我们的方法 | 能力位 | |---|---|---|---| | `/webApi/skuInfo/v2/printBarcode` | **箱唛**(外箱标) | `printCaseMarks(...)` | `CASE_MARK_PRINT` | -| `/webApi/entryInfo/v1/newPrintCaseMarkContentType` | **SKU 标** | `printSkuLabel(...)` | 走入库 `SKU_LABEL` 语义 | +| `/webApi/entryInfo/v1/newPrintCaseMark` | **SKU 标** | `printSkuLabel(...)` | 走入库 `SKU_LABEL` 语义 | **不要被路径名误导**。代码里两个方法的 javadoc 都写了这条提醒。 @@ -1192,10 +1242,10 @@ POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel 仓方其它校验:缺 `productInfos` →「产品信息不能为空」、缺 `pageSize` → 「纸张尺寸不能为空」、SKU 不存在 →「sku=XXX信息不存在」。 -### SKU 标(newPrintCaseMarkContentType) +### SKU 标(newPrintCaseMark) ``` -POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel +POST /webApi/entryInfo/v1/newPrintCaseMark → WarehouseLabel ``` **真机未启用**:PR 环境该路径报「接口不存在或未启用」,去掉 @@ -1317,6 +1367,23 @@ DTO 按 `List` 收。 `listWarehouseHasPerm` 只有 17 个。DTO 只声明统一模型用得上的十几个—— Jackson 会忽略未知字段。 +## SKU 口径:传的是 OMS SKU 还是仓侧 SKU? + +**结论:两边都必须是仓侧 SKU(建档时下发的那串)。** + +代码依据: + +- 建档:`YqnProductMapper.skuOf()` / `EdayunProductMapper.skuOf()` 都是 + **`providerSku` 优先,为空才回退 `omsSku`** +- 出库行:`OutboundLine` 同时有 `omsSku` 与 `providerSku`,映射时同样 providerSku 优先 +- 商品查询:`ProductQuery.providerSkus()` 是仓侧 SKU,**SDK 不做 OMS→仓侧转换** + +所以仓方库里存的永远是「我们建档时下发的那串」。如果宿主给 `providerSku` +建了档,那么查询也必须用它;只有两者相同时(如 `ybtest`)才能混用。 + +**SDK 不会静默转换的原因**:OMS→仓侧 SKU 的映射表在宿主手里(供应商编码规则、 +按仓不同的前缀等),SDK 猜不出来。查错了会拿到空结果或错的商品,比报错更难发现。 + ## 待确认(问易达云) | # | 要确认 | diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index ff9756e..01119f6 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -5,6 +5,7 @@ ## 待仓方确认 | # | 问题 | 当前处理 | 影响 | +|---|---|---|---| | 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 | | 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 | | 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 | @@ -37,7 +38,7 @@ | 35 | 入库明细接口不回仓库 / 创建时间 / 到仓时间 / 箱号 | 仓库用 OMS 配置;时间与箱明细为 null | 拿不到完整单据,需要 entryInfo 单头查询接口 | | 36 | 是否有入库单列表 / 时间窗查询 | `query()` 的 cursor 当 entryCode 用 | 无法做增量同步,只能按单号轮询 | | 37 | `forecastWeight` / `weight` 是克、`firstWeight` 是千克 | 未映射(统一模型没有行级重量) | 想按箱对账重量时需要 | -| 38 | 退货单**没有列表查询** | `queryReturns` 显式拒绝 | 无法批量同步退货单 | +| 38 | ~~退货单没有列表查询~~ ✅ 已对接 `selectRmaInfoList` | `queryReturns(ReturnQuery)` | 无 | | 39 | 退货 `skus[].command` 码表(文档只写「1 上架 / 2 销毁」) | 只确定 DESTROY→2,其余都归 1 | 非销毁类处理方式可能与仓方预期不符 | | 40 | 退货 `valueAddedService` / `shelveSkuCode` / `catalog` / `picUrls` 码值与语义 | 不下发 | 重新包装 / 换标上架等场景发不了 | | 41 | 未妥投 / 返邮 / FBA 三种退货方式要不要做 | 只实现 `returnType=2` | 买家退货的返邮面单、FBA 退货都得人工 | @@ -64,10 +65,10 @@ | 62 | PR 环境查不到任何轨迹(连出库单里的真实跟踪号都「未匹配到轨迹」) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 | | 63 | 轨迹接口一次可查多个跟踪号,统一模型只有单号口径 | 逐个查、按单号匹配 | 批量查只能循环调用 | | 64 | 轨迹的 `eventStatus` 取值(文档示例是 `"string"` 占位) | 原样透传 | 宿主无法按事件类型分支 | -| 65 | 条码打印的纸张尺寸只有 4 档(7×3/10×6/6×4/A4),与入库贴标的 14 种不重叠 | 独立枚举 `BarcodePaperSize` | 宿主换标签纸时要选对枚举 | +| 65 | 箱唛纸张尺寸只有 4 档,与入库贴标的 14 种不重叠 | 独立枚举 `CaseMarkPaperSize`(按实测尺寸命名) | 宿主换标签纸时要选对枚举 | | 66 | 条码文件地址的**有效期**未知(OSS 链接) | 原样返回,不缓存 | 宿主存旧链接可能 403 | | 67 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 | -| 68 | **箱唛接口在 PR 环境未启用**(`newPrintCaseMarkContentType` 报「接口不存在或未启用」;去掉后缀的 `newPrintCaseMark` 能过参数校验但一律「内部服务器错误」) | 按文档实现,映射只有单测 | 上线前必须真机验证 | +| 68 | **SKU 标接口调通但仓方内部报错**:路径 `/webApi/entryInfo/v1/newPrintCaseMark` 确认存在(缺参数有中文校验提示),但参数补全后一律「内部服务器错误」,试过 6 种 pageSize、madeInChina 0/1、separation、箱序号区间、skuCode、caseCodeList、不存在的 entryCode 都一样 | 按文档实现,映射只有单测 | 上线前必须真机验证 | | 69 | SKU 标纸张码值 4/2/5 不连续 | 独立枚举 `EdayunSkuLabelPaper`,按映射表走 | 无(已规避) | | 72 | **`printBarcode` 的 pageSize=2 / pageSize=3 文档标称与实际相反**(文档 2=6×4cm、3=A4;实测 2=100×150mm、3=60×40mm) | 枚举按实测尺寸命名,码值不变 | 按文档标称选纸会打错 | | 73 | 两个端点名与实际语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标) | 代码按实际语义命名并在 javadoc 标注 | 无(已规避) | diff --git a/docs-warehouse/yqn/README.md b/docs-warehouse/yqn/README.md index d784d05..71eaf31 100644 --- a/docs-warehouse/yqn/README.md +++ b/docs-warehouse/yqn/README.md @@ -206,6 +206,36 @@ WarehouseConnection.of( **未指定时按 UTC 解释,不猜成北京时间。** +## 9.5 商品查询(API 113) + +``` +POST /v1/product/findPage → Page +``` + +### 页码从 0 开始 + +文档原文「起始页为从0开始」。统一模型的游标就是页码字符串,**不做 ±1 换算**—— +空游标 = 第 0 页。这和运去哪其它分页接口(从 1 开始)不一致,容易踩。 + +### 单页上限 100,SKU 上限 100 + +`pageSize` 默认 100、最大 100;`skuList` 最大 100 个。超了各自本地拒绝。 + +### 只支持 SKU 过滤 + +运去哪这个接口没有条码 / 创建时间过滤,`ProductQuery` 里传了这两个会本地拒绝, +不静默忽略。 + +### 翻页优先看 `last` + +响应是 Spring Data 风格,`last=true` 即末页。缺失时用 `number + 1 < totalPages` +推断,再缺失才按「本页是否满页」兜底。 + +### 成本要带币种才是 Money + +`cost` 与 `currency` 是两列;没有币种时只保留数字会丢单位,所以 +没有 `currency` 时 `cost()` 为 null。 + ## 10. 联调探针 两个探针,默认跳过: @@ -235,4 +265,5 @@ mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \ | 库存调整 | 运去哪无此接口 | | 换货 / 无头件 / BOL | 仓方无对应接口 | | 退货查询列表 | 只有按单号查,无列表接口 | +| 商品查询的条码 / 时间窗过滤 | API 113 只接受 skuList 与分页 | | 出库列表 / 时间窗查询 | 只有按单号查 | diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java index 7f8211f..d37c3aa 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java @@ -21,7 +21,7 @@ public interface CaseMarkPrintCapable extends WarehouseAdapter { * * @return 已生成的文件(地址或 base64);仓方未返回文件时抛出异常,不返回 null * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException - * 该仓不声明 {@code BARCODE_PRINT} + * 该仓不声明 {@code CASE_MARK_PRINT} */ WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java index cbdfa19..371ac8d 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java @@ -44,22 +44,18 @@ public interface WarehouseDirectoryCapable extends WarehouseAdapter { *

与 {@link #carriers} 的区别:那个只给一串物流方式码,这个是承运商 → * 物流服务的两层结构,宿主要做下拉框或按承运商筛选时用这个。

* - *

默认走 {@link #carriers} 把码包装成没有名称的条目;能给出结构的仓应覆盖。

+ *

默认不支持,不拿 {@link #carriers} 的码硬凑成两层结构—— + * 那样会得到 {@code carrierId == nameEn == "FEDEX-G"} 这种假条目, + * 宿主若按类注释「下单时 carrierName 填 nameEn()」使用,就会把物流方式码 + * 当成承运商名发出去。能给出真实结构的仓自己覆盖。

* * @return 承运商列表;仓方返回空时为 empty list(不是错误) * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException - * 该仓不声明 {@code DIRECTORY} 或没有承运商接口 + * 该仓没有承运商目录接口 */ default List carrierDirectory( WarehouseContext ctx) { - List out = - new java.util.ArrayList(); - for (String code : carriers(ctx)) { - out.add(common.ecommerce.warehouse.model.WarehouseCarrier.builder() - .carrierId(code) - .nameEn(code) - .build()); - } - return out; + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.DIRECTORY); } } 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 1b5e249..9c40eb9 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 @@ -19,6 +19,24 @@ import java.util.Objects; public final class WarehouseProduct { private final String omsSku; + /** + * 仓侧 SKU——建档时下发给仓方的那串,之后所有查询 / 下单都用它。 + * + *

各适配器在建档时按「{@code providerSku} 优先,为空才回退 {@link #omsSku}」 + * 决定仓方库里存什么,字段名各不相同(易达云 {@code skuCode}、 + * 运去哪 {@code sku})。仓方一旦落库,之后按 SKU 查询、下单、查库存都必须传 + * 同一串——所以它不一定等于 {@link #omsSku()}:

+ * + *
    + *
  • 给了 {@code providerSku}(如 {@code AP0000X9US0010601})→ 仓方存它, + * 后续传入 {@code ProductQuery.providerSkus()} / {@code InventoryQuery.providerSkus()} + * / {@code OutboundLine.providerSku()} 时也必须是它
  • + *
  • 没给 → 仓方存的就是 {@code omsSku},两者同名
  • + *
+ * + *

SDK 不做 OMS→仓侧 SKU 的转换:映射表在宿主手里,静默转换会拿回 + * 空结果或错商品,比报错更难发现。

+ */ private final String providerSku; private final String customItemNo; private final String barcode; @@ -161,43 +179,6 @@ 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 表示不传。 * @@ -220,23 +201,10 @@ 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.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; @@ -256,16 +224,6 @@ 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; @@ -293,7 +251,7 @@ public final class WarehouseProduct { return omsSku; } - /** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。 */ + /** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。详见字段注释。 */ public String providerSku() { return providerSku; } @@ -492,17 +450,6 @@ 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"); @@ -517,56 +464,6 @@ 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; @@ -598,22 +495,6 @@ 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; @@ -859,76 +740,6 @@ 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 d5f960f..3812aee 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 @@ -10,17 +10,19 @@ public interface WarehouseProductCapable extends WarehouseAdapter { ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product); /** - * 分页查商品。只读,不走幂等。 + * 批量 / 分页查询仓侧商品资料。 * - *

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

+ *

查询用的 SKU 是仓侧 SKU(建档时下发的那串,通常是 + * {@code WarehouseProduct.providerSku()},没给映射时等于 OMS SKU)。 + * SDK 不做 OMS→仓侧 SKU 的转换——映射表在宿主手里,静默转换会让结果对不上。

* - * @param query 查询条件;游标为空表示第一页 - * @return 当前页商品;{@code nextCursor} 非空表示还有下一页 + *

默认不支持:只有提供商品查询接口的仓才覆盖。

+ * + * @return 分页结果;仓方无数据时为空页(不是错误) * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException - * 该仓不支持商品查询 + * 该仓不提供商品查询 */ - default common.ecommerce.shared.support.Page queryProducts( + default common.ecommerce.shared.support.Page query( WarehouseContext ctx, common.ecommerce.warehouse.model.ProductQuery query) { throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( common.ecommerce.warehouse.enums.WarehouseCapability.PRODUCT); diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java index ff61d4e..5932b5a 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java @@ -40,6 +40,26 @@ public interface WarehouseReturnCapable extends WarehouseAdapter { Page queryReturns(WarehouseContext ctx, ReturnQuery query); /** + * 分页查退货处理单(仓方收货检验后按明细行拆出的处理单元)。 + * + *

只有提供该接口的仓才覆盖;默认不支持。

+ * + *

与 {@link #queryReturns} 的区别:那个查「一张退货计划」, + * 这个查「计划下每一行 SKU 的待处理记录」。填处理方式要用的四项定位 + * (计划单号 + 处理单号 + SKU + tracking)就在返回的 + * {@link common.ecommerce.warehouse.model.ReturnHandle} 里。

+ * + * @return 分页结果;仓方无数据时为空页(不是错误) + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不提供处理单查询 + */ + default Page queryHandles( + WarehouseContext ctx, ReturnQuery query) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.RETURN); + } + + /** * 按明细行设置检验后处理方式。写操作,幂等键 * {@code warehouseCode + providerReturnNo + lineId + "process"}。 */ diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java index 1d74310..c0b67dc 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java @@ -37,6 +37,13 @@ public final class InventoryQuery { return new Builder(); } + /** + * 仓侧 SKU 列表;空表示不按 SKU 过滤。 + * + *

同 {@link ProductQuery#providerSkus()}:必须是建档时下发的仓侧 SKU + * ({@code WarehouseProduct.providerSku()},未给映射时即 {@code omsSku()}), + * 不一定是 OMS SKU。

+ */ public List providerSkus() { return providerSkus; } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java new file mode 100644 index 0000000..7ec609b --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java @@ -0,0 +1,632 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.enums.WarehouseProvider; + +import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 仓侧商品资料(查询结果)。 + * + *

与 {@link common.ecommerce.warehouse.capability.WarehouseProduct} 的区别: + * 那个是建档入参(我们下发给仓方),这个是查询结果(仓方存着什么)。 + * 两者字段高度重叠但语义不同——入参里没有 id / 状态 / 创建时间, + * 结果里也没有「要求仓方必填」这类约束,所以不复用同一个类。

+ * + *

单位与入参一致:尺寸 cm、重量 g。

+ */ +public final class ProductInfo { + + /** 仓侧 SKU(建档时下发的那串)。 */ + private final String providerSku; + /** OMS 侧 SKU;仓方不回时为 null(SDK 不做反查)。 */ + private final String omsSku; + /** 仓方内部商品 id;不同仓给不给不一。 */ + private final String providerProductId; + /** 自定义产品编码。 */ + private final String customItemNo; + private final String barcode; + private final List extraBarcodes; + + private final String name; + private final String nameEn; + private final String description; + + /** 产品类型:1 成品 / 2 配件 / 3 耗材;未给为 -1。 */ + private final int productType; + + /** 外箱 / 整箱尺寸重量。 */ + private final double lengthCm; + private final double widthCm; + private final double heightCm; + private final double weightGrams; + + /** 单品尺寸;未给为 null。 */ + private final Double itemLengthCm; + private final Double itemWidthCm; + private final Double itemHeightCm; + + /** 装箱数量;未给为 null。 */ + private final Integer packedQuantity; + private final Double packedLengthCm; + private final Double packedWidthCm; + private final Double packedHeightCm; + private final Double packedWeightGrams; + + /** 是否需要 SN;未给为 null。 */ + private final Boolean requireSn; + /** 成本;未给为 null。 */ + private final Money cost; + + /** 仓方状态原值(如 edayun 的 0 草稿 / 1 已发布);未给为 null。 */ + private final Integer rawStatus; + /** 仓方状态名原值。 */ + private final String rawStatusName; + + /** 创建时间;未给为 null。 */ + private final Instant createdAt; + /** 更新时间;仓方未给为 null。 */ + private final Instant updatedAt; + private final String remark; + /** 该商品来自哪家仓。 */ + private final WarehouseProvider sourceProvider; + + // ==================== 仓方实测尺寸(恒健 measurement*)==================== + + /** + * 仓方收货后实测尺寸 / 重量;未给为 null。 + * + *

与 {@link #lengthCm()} 等不是一回事:那些是我们申报的。 + * 下标成本、抛重计算都以实测为准。

+ */ + private final Double measuredLengthCm; + private final Double measuredWidthCm; + private final Double measuredHeightCm; + private final Double measuredWeightGrams; + + // ==================== 申报价值 / 保价(恒健、信仓)==================== + + /** 申报价值;恒健 {@code cost}+{@code currency}、信仓 {@code amount}(USD);未给为 null。 */ + private final Money declaredValue; + /** 是否保价;恒健 {@code isInsuranceFlag}(Y/N);未给为 null。 */ + private final Boolean insured; + /** 保价费用;恒健 {@code isInsuranceRate};未给为 null。 */ + private final Money insuranceFee; + + // ==================== 保质期(恒健)==================== + + /** 是否开启保质期管理;未给为 null。 */ + private final Boolean expirationControl; + /** 保质期天数;未给为 null。 */ + private final Integer expirationDays; + + // ==================== 体积 / 图片 / 状态名(信仓、恒健)==================== + + /** 体积(立方厘米);未给为 null。 */ + private final java.math.BigDecimal volumeCm3; + /** 商品图片 URL;仓方未给为 null。 */ + private final String imageUrl; + /** 仓方状态码的原值文本(信仓 {@code state} 是字符串 0/1);未给为 null。 */ + private final String rawState; + + private ProductInfo(Builder b) { + this.providerSku = require(b.providerSku, "providerSku"); + this.omsSku = b.omsSku; + this.providerProductId = b.providerProductId; + this.customItemNo = b.customItemNo; + this.barcode = b.barcode; + this.extraBarcodes = Collections.unmodifiableList( + new ArrayList(b.extraBarcodes)); + this.name = b.name; + this.nameEn = b.nameEn; + this.description = b.description; + this.productType = b.productType; + this.lengthCm = b.lengthCm; + this.widthCm = b.widthCm; + this.heightCm = b.heightCm; + this.weightGrams = b.weightGrams; + this.itemLengthCm = b.itemLengthCm; + this.itemWidthCm = b.itemWidthCm; + this.itemHeightCm = b.itemHeightCm; + this.packedQuantity = b.packedQuantity; + this.packedLengthCm = b.packedLengthCm; + this.packedWidthCm = b.packedWidthCm; + this.packedHeightCm = b.packedHeightCm; + this.packedWeightGrams = b.packedWeightGrams; + this.requireSn = b.requireSn; + this.cost = b.cost; + this.rawStatus = b.rawStatus; + this.rawStatusName = b.rawStatusName; + this.createdAt = b.createdAt; + this.updatedAt = b.updatedAt; + this.remark = b.remark; + this.sourceProvider = b.sourceProvider; + this.measuredLengthCm = b.measuredLengthCm; + this.measuredWidthCm = b.measuredWidthCm; + this.measuredHeightCm = b.measuredHeightCm; + this.measuredWeightGrams = b.measuredWeightGrams; + this.declaredValue = b.declaredValue; + this.insured = b.insured; + this.insuranceFee = b.insuranceFee; + this.expirationControl = b.expirationControl; + this.expirationDays = b.expirationDays; + this.volumeCm3 = b.volumeCm3; + this.imageUrl = b.imageUrl; + this.rawState = b.rawState; + } + + public static Builder builder() { + return new Builder(); + } + + public String providerSku() { + return providerSku; + } + + /** OMS SKU;仓方不回时为 null。 */ + public String omsSku() { + return omsSku; + } + + public String providerProductId() { + return providerProductId; + } + + public String customItemNo() { + return customItemNo; + } + + public String barcode() { + return barcode; + } + + /** 额外条码(仓方支持多个时);不可变。 */ + public List extraBarcodes() { + return extraBarcodes; + } + + public String name() { + return name; + } + + public String nameEn() { + return nameEn; + } + + public String description() { + return description; + } + + /** 产品类型:1 成品 / 2 配件 / 3 耗材;未给为 -1。 */ + public int productType() { + return productType; + } + + public double lengthCm() { + return lengthCm; + } + + public double widthCm() { + return widthCm; + } + + public double heightCm() { + return heightCm; + } + + public double weightGrams() { + return weightGrams; + } + + public Double itemLengthCm() { + return itemLengthCm; + } + + public Double itemWidthCm() { + return itemWidthCm; + } + + public Double itemHeightCm() { + return itemHeightCm; + } + + public Integer packedQuantity() { + return packedQuantity; + } + + public Double packedLengthCm() { + return packedLengthCm; + } + + public Double packedWidthCm() { + return packedWidthCm; + } + + public Double packedHeightCm() { + return packedHeightCm; + } + + public Double packedWeightGrams() { + return packedWeightGrams; + } + + public Boolean requireSn() { + return requireSn; + } + + public Money cost() { + return cost; + } + + /** 仓方状态原值。 */ + public Integer rawStatus() { + return rawStatus; + } + + /** 仓方状态名原值。 */ + public String rawStatusName() { + return rawStatusName; + } + + public Instant createdAt() { + return createdAt; + } + + public String remark() { + return remark; + } + + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + + /** 更新时间;仓方未给为 null。 */ + public Instant updatedAt() { + return updatedAt; + } + + /** 仓方实测长(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; + } + + /** 申报价值;未给为 null。 */ + public Money declaredValue() { + return declaredValue; + } + + /** 是否保价;未给为 null。 */ + public Boolean insured() { + return insured; + } + + /** 保价费用;未给为 null。 */ + public Money insuranceFee() { + return insuranceFee; + } + + /** 是否开启保质期管理;未给为 null。 */ + public Boolean expirationControl() { + return expirationControl; + } + + /** 保质期天数;未给为 null。 */ + public Integer expirationDays() { + return expirationDays; + } + + /** 体积(立方厘米);未给为 null。 */ + public java.math.BigDecimal volumeCm3() { + return volumeCm3; + } + + /** 商品图片 URL;未给为 null。 */ + public String imageUrl() { + return imageUrl; + } + + /** 仓方状态码原值文本;未给为 null。 */ + public String rawState() { + return rawState; + } + + private static String require(String v, String name) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + private String providerSku; + private String omsSku; + private String providerProductId; + private String customItemNo; + private String barcode; + private final List extraBarcodes = new ArrayList(); + private String name; + private String nameEn; + private String description; + private int productType = -1; + private double lengthCm; + private double widthCm; + private double heightCm; + private double weightGrams; + private Double itemLengthCm; + private Double itemWidthCm; + private Double itemHeightCm; + private Integer packedQuantity; + private Double packedLengthCm; + private Double packedWidthCm; + private Double packedHeightCm; + private Double packedWeightGrams; + private Boolean requireSn; + private Money cost; + private Integer rawStatus; + private String rawStatusName; + private Instant createdAt; + private Instant updatedAt; + private String remark; + private WarehouseProvider sourceProvider; + private Double measuredLengthCm; + private Double measuredWidthCm; + private Double measuredHeightCm; + private Double measuredWeightGrams; + private Money declaredValue; + private Boolean insured; + private Money insuranceFee; + private Boolean expirationControl; + private Integer expirationDays; + private java.math.BigDecimal volumeCm3; + private String imageUrl; + private String rawState; + + public Builder providerSku(String v) { + this.providerSku = v; + return this; + } + + public Builder omsSku(String v) { + this.omsSku = v; + return this; + } + + public Builder providerProductId(String v) { + this.providerProductId = v; + return this; + } + + public Builder customItemNo(String v) { + this.customItemNo = v; + return this; + } + + public Builder barcode(String v) { + this.barcode = v; + return this; + } + + public Builder extraBarcode(String v) { + if (v != null && !v.trim().isEmpty()) { + this.extraBarcodes.add(v.trim()); + } + return this; + } + + public Builder name(String v) { + this.name = v; + return this; + } + + public Builder nameEn(String v) { + this.nameEn = v; + return this; + } + + public Builder description(String v) { + this.description = v; + return this; + } + + /** 产品类型:1 成品 / 2 配件 / 3 耗材;-1 表示未给。 */ + public Builder productType(int v) { + this.productType = v; + return this; + } + + public Builder lengthCm(double v) { + this.lengthCm = v; + return this; + } + + public Builder widthCm(double v) { + this.widthCm = v; + return this; + } + + public Builder heightCm(double v) { + this.heightCm = v; + return this; + } + + public Builder weightGrams(double v) { + this.weightGrams = v; + return this; + } + + public Builder itemLengthCm(Double v) { + this.itemLengthCm = v; + return this; + } + + public Builder itemWidthCm(Double v) { + this.itemWidthCm = v; + return this; + } + + public Builder itemHeightCm(Double v) { + this.itemHeightCm = v; + return this; + } + + public Builder packedQuantity(Integer v) { + this.packedQuantity = v; + return this; + } + + public Builder packedLengthCm(Double v) { + this.packedLengthCm = v; + return this; + } + + public Builder packedWidthCm(Double v) { + this.packedWidthCm = v; + return this; + } + + public Builder packedHeightCm(Double v) { + this.packedHeightCm = v; + return this; + } + + public Builder packedWeightGrams(Double v) { + this.packedWeightGrams = v; + return this; + } + + public Builder requireSn(Boolean v) { + this.requireSn = v; + return this; + } + + public Builder cost(Money v) { + this.cost = v; + return this; + } + + public Builder rawStatus(Integer v) { + this.rawStatus = v; + return this; + } + + public Builder rawStatusName(String v) { + this.rawStatusName = v; + return this; + } + + public Builder createdAt(Instant v) { + this.createdAt = v; + return this; + } + + public Builder remark(String v) { + this.remark = v; + return this; + } + + /** 更新时间。 */ + public Builder updatedAt(Instant v) { + this.updatedAt = 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; + } + + /** 申报价值。 */ + public Builder declaredValue(Money v) { + this.declaredValue = v; + return this; + } + + /** 是否保价。 */ + public Builder insured(Boolean v) { + this.insured = v; + return this; + } + + /** 保价费用。 */ + public Builder insuranceFee(Money v) { + this.insuranceFee = v; + return this; + } + + /** 是否开启保质期管理。 */ + public Builder expirationControl(Boolean v) { + this.expirationControl = v; + return this; + } + + /** 保质期天数。 */ + public Builder expirationDays(Integer v) { + this.expirationDays = v; + return this; + } + + /** 体积(立方厘米)。 */ + public Builder volumeCm3(java.math.BigDecimal v) { + this.volumeCm3 = v; + return this; + } + + /** 商品图片 URL。 */ + public Builder imageUrl(String v) { + this.imageUrl = v; + return this; + } + + /** 仓方状态码原值文本。 */ + public Builder rawState(String v) { + this.rawState = v; + return this; + } + + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + + public ProductInfo build() { + return new ProductInfo(this); + } + } +} 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 index aab234e..e286538 100644 --- 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 @@ -1,35 +1,48 @@ package common.ecommerce.warehouse.model; +import java.time.Instant; import java.util.ArrayList; import java.util.Collections; import java.util.List; /** - * 商品查询条件。 + * 商品查询条件(批量 / 分页)。 * - *

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

+ *

与 {@link InventoryQuery} 的口径一致:{@code providerSkus} 是仓侧 SKU, + * 即建档时下发给仓方的那一串(通常等于 {@code WarehouseProduct.providerSku()}, + * 没给映射时就是 OMS SKU)。SDK 不做 OMS→仓侧 SKU 的转换—— + * 那张映射表在宿主手里,这里静默转换会让查回来的东西对不上。

* - *

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

+ *

各仓支持的过滤维度不同,不支持的由适配器显式拒绝, + * 不静默忽略——忽略一个过滤条件会让结果对不上。

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

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

- */ + /** 单次最多查多少个 SKU(各仓不同,由适配器按自己的上限再校验)。 */ + public static final int MAX_SKUS = 100; + private final List providerSkus; - /** 每页条数;0 表示用仓方默认。 */ + /** 条码(UPC / 仓方条码)。 */ + private final String barcode; + private final Instant createdAfter; + private final Instant createdBefore; private final int pageSize; - /** 页码游标;null 表示第一页。 */ private final String cursor; - private ProductQuery(Builder b) { - this.providerSkus = Collections.unmodifiableList(new ArrayList(b.providerSkus)); + public ProductQuery(Builder b) { + this.providerSkus = Collections.unmodifiableList( + new ArrayList(b.providerSkus)); + if (this.providerSkus.size() > MAX_SKUS) { + throw new IllegalArgumentException( + "at most " + MAX_SKUS + " skus per query, got " + this.providerSkus.size()); + } + if (b.createdAfter != null && b.createdBefore != null + && !b.createdAfter.isBefore(b.createdBefore)) { + throw new IllegalArgumentException("createdAfter must be before createdBefore"); + } + this.barcode = b.barcode; + this.createdAfter = b.createdAfter; + this.createdBefore = b.createdBefore; this.pageSize = b.pageSize; this.cursor = b.cursor; } @@ -38,48 +51,82 @@ public final class ProductQuery { return new Builder(); } - /** 仓方 SKU 列表;空表示不限。不可变。 */ + /** + * 仓侧 SKU 列表;空表示不按 SKU 过滤。 + * + *

这串必须等于建档时下发给仓方的 SKU({@code WarehouseProduct.providerSku()}, + * 未给映射时即 {@code omsSku()})。各仓入库字段不同:易达云 {@code skuCode} + * (逗号拼接,≤50)/ 运去哪 {@code skuList}(JSON 数组,≤100)。 + * 传错不会报错,只会查不到——SDK 不做 OMS→仓侧转换。

+ */ public List providerSkus() { return providerSkus; } - /** 每页条数;0 表示用仓方默认。 */ + /** 条码;null 表示不按条码过滤。 */ + public String barcode() { + return barcode; + } + + public Instant createdAfter() { + return createdAfter; + } + + public Instant createdBefore() { + return createdBefore; + } + + /** 是否给了完整的创建时间窗。 */ + public boolean hasCreatedRange() { + return createdAfter != null && createdBefore != null; + } + public int pageSize() { return pageSize; } - /** 页码游标;null 表示第一页。 */ + /** 分页游标;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 barcode; + private Instant createdAfter; + private Instant createdBefore; + private int pageSize = 100; private String cursor; + /** 一个仓侧 SKU;空串忽略。 */ + public Builder providerSku(String v) { + if (v != null && !v.trim().isEmpty()) { + this.providerSkus.add(v.trim()); + } + return this; + } + 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()); - } + for (String s : v) { + providerSku(s); } } return this; } - public Builder providerSku(String v) { - if (v != null && !v.trim().isEmpty()) { - this.providerSkus.add(v.trim()); - } + public Builder barcode(String v) { + this.barcode = v; + return this; + } + + public Builder createdAfter(Instant v) { + this.createdAfter = v; + return this; + } + + public Builder createdBefore(Instant v) { + this.createdBefore = v; return this; } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnHandle.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnHandle.java new file mode 100644 index 0000000..f4781ed --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnHandle.java @@ -0,0 +1,336 @@ +package common.ecommerce.warehouse.model; + +import common.ecommerce.warehouse.enums.WarehouseProvider; + +import java.time.Instant; +import java.util.List; + +/** + * 退货处理单(仓方收货检验后按明细行拆出的处理单元)。 + * + *

与 {@link WarehouseReturn} 的区别:那是一张退货计划, + * 这是计划下一行 SKU 的一条待处理记录——一张计划可以有多个处理单, + * 每行可以分别拍照 / 销毁 / 上架。

+ * + *

填写处理方式({@code ReturnProcessCommand})要用的定位字段就在本对象里: + * {@link #returnPlanNo()} + {@link #returnHandleNo()} + {@link #providerSku()} + * + {@link #trackingNumber()}。

+ */ +public final class ReturnHandle { + + private final String returnPlanNo; + private final String returnHandleNo; + private final String returnNo; + private final String trackingNumber; + private final String providerSku; + private final String changeSku; + private final Integer quantity; + private final Integer handledQuantity; + private final Integer photosQuantity; + private final Integer inventoryType; + private final String handlingStatus; + private final String handlingStatusName; + private final String primaryHandlingMethod; + private final String sourceNo; + private final String warehouseCode; + private final String errorStatus; + private final String errorMessage; + private final List photoUrls; + private final List handledPhotoUrls; + private final Instant createdAt; + private final Instant updatedAt; + private final Instant completedAt; + private final WarehouseProvider sourceProvider; + + private ReturnHandle(Builder b) { + if (b.returnPlanNo == null || b.returnPlanNo.trim().isEmpty()) { + throw new IllegalArgumentException("returnPlanNo must not be blank"); + } + this.returnPlanNo = b.returnPlanNo.trim(); + this.returnHandleNo = b.returnHandleNo; + this.returnNo = b.returnNo; + this.trackingNumber = b.trackingNumber; + this.providerSku = b.providerSku; + this.changeSku = b.changeSku; + this.quantity = b.quantity; + this.handledQuantity = b.handledQuantity; + this.photosQuantity = b.photosQuantity; + this.inventoryType = b.inventoryType; + this.handlingStatus = b.handlingStatus; + this.handlingStatusName = b.handlingStatusName; + this.primaryHandlingMethod = b.primaryHandlingMethod; + this.sourceNo = b.sourceNo; + this.warehouseCode = b.warehouseCode; + this.errorStatus = b.errorStatus; + this.errorMessage = b.errorMessage; + this.photoUrls = java.util.Collections.unmodifiableList( + new java.util.ArrayList(b.photoUrls)); + this.handledPhotoUrls = java.util.Collections.unmodifiableList( + new java.util.ArrayList(b.handledPhotoUrls)); + this.createdAt = b.createdAt; + this.updatedAt = b.updatedAt; + this.completedAt = b.completedAt; + this.sourceProvider = b.sourceProvider; + } + + public static Builder builder() { + return new Builder(); + } + + /** 退货计划单号;必填。 */ + public String returnPlanNo() { + return returnPlanNo; + } + + /** 仓侧处理单号(恒健 {@code returnPlanHandleItemsNo})。 */ + public String returnHandleNo() { + return returnHandleNo; + } + + /** 退货编码;部分仓单独给一个(恒健「退货编码」)。 */ + public String returnNo() { + return returnNo; + } + + /** tracking 号。 */ + public String trackingNumber() { + return trackingNumber; + } + + /** 仓侧 SKU。 */ + public String providerSku() { + return providerSku; + } + + /** 换标后的 SKU;非换标为 null。 */ + public String changeSku() { + return changeSku; + } + + public Integer quantity() { + return quantity; + } + + /** 已处理数量;未给为 null。 */ + public Integer handledQuantity() { + return handledQuantity; + } + + /** 已拍照片数量;未给为 null。 */ + public Integer photosQuantity() { + return photosQuantity; + } + + /** 库存类型:0 可售 / 1 不可售;未给为 null。 */ + public Integer inventoryType() { + return inventoryType; + } + + /** 处理状态原值。 */ + public String handlingStatus() { + return handlingStatus; + } + + /** 处理状态中文名;仓方未给为 null。 */ + public String handlingStatusName() { + return handlingStatusName; + } + + /** 主要处理方式原值(仓方码,如恒健 101~206)。 */ + public String primaryHandlingMethod() { + return primaryHandlingMethod; + } + + /** 来源单号。 */ + public String sourceNo() { + return sourceNo; + } + + public String warehouseCode() { + return warehouseCode; + } + + /** 异常码原值;无异常为 null。 */ + public String errorStatus() { + return errorStatus; + } + + public String errorMessage() { + return errorMessage; + } + + /** 照片 URL;不可变。 */ + public List photoUrls() { + return photoUrls; + } + + /** 处理后照片 URL;不可变。 */ + public List handledPhotoUrls() { + return handledPhotoUrls; + } + + public Instant createdAt() { + return createdAt; + } + + public Instant updatedAt() { + return updatedAt; + } + + public Instant completedAt() { + return completedAt; + } + + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + + public static final class Builder { + private String returnPlanNo; + private String returnHandleNo; + private String returnNo; + private String trackingNumber; + private String providerSku; + private String changeSku; + private Integer quantity; + private Integer handledQuantity; + private Integer photosQuantity; + private Integer inventoryType; + private String handlingStatus; + private String handlingStatusName; + private String primaryHandlingMethod; + private String sourceNo; + private String warehouseCode; + private String errorStatus; + private String errorMessage; + private final List photoUrls = new java.util.ArrayList(); + private final List handledPhotoUrls = new java.util.ArrayList(); + private Instant createdAt; + private Instant updatedAt; + private Instant completedAt; + private WarehouseProvider sourceProvider; + + public Builder returnPlanNo(String v) { + this.returnPlanNo = v; + return this; + } + + public Builder returnHandleNo(String v) { + this.returnHandleNo = v; + return this; + } + + public Builder returnNo(String v) { + this.returnNo = v; + return this; + } + + public Builder trackingNumber(String v) { + this.trackingNumber = v; + return this; + } + + public Builder providerSku(String v) { + this.providerSku = v; + return this; + } + + public Builder changeSku(String v) { + this.changeSku = v; + return this; + } + + public Builder quantity(Integer v) { + this.quantity = v; + return this; + } + + public Builder handledQuantity(Integer v) { + this.handledQuantity = v; + return this; + } + + public Builder photosQuantity(Integer v) { + this.photosQuantity = v; + return this; + } + + public Builder inventoryType(Integer v) { + this.inventoryType = v; + return this; + } + + public Builder handlingStatus(String v) { + this.handlingStatus = v; + return this; + } + + public Builder handlingStatusName(String v) { + this.handlingStatusName = v; + return this; + } + + public Builder primaryHandlingMethod(String v) { + this.primaryHandlingMethod = v; + return this; + } + + public Builder sourceNo(String v) { + this.sourceNo = v; + return this; + } + + public Builder warehouseCode(String v) { + this.warehouseCode = v; + return this; + } + + public Builder errorStatus(String v) { + this.errorStatus = v; + return this; + } + + public Builder errorMessage(String v) { + this.errorMessage = v; + return this; + } + + public Builder photoUrl(String v) { + if (v != null && !v.trim().isEmpty()) { + this.photoUrls.add(v.trim()); + } + return this; + } + + public Builder handledPhotoUrl(String v) { + if (v != null && !v.trim().isEmpty()) { + this.handledPhotoUrls.add(v.trim()); + } + return this; + } + + public Builder createdAt(Instant v) { + this.createdAt = v; + return this; + } + + public Builder updatedAt(Instant v) { + this.updatedAt = v; + return this; + } + + public Builder completedAt(Instant v) { + this.completedAt = v; + return this; + } + + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + + public ReturnHandle build() { + return new ReturnHandle(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 5a33493..cdd0200 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 @@ -40,6 +40,8 @@ import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; +import common.ecommerce.warehouse.model.ProductInfo; +import common.ecommerce.warehouse.model.ProductQuery; import common.ecommerce.warehouse.model.LabelPrintTask; import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.ReturnCommand; @@ -96,19 +98,20 @@ public final class WarehouseOperations { } /** - * 分页查商品。只读,不走幂等。 + * 批量 / 分页查询仓侧商品资料。只读,不走幂等。 * - *

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

+ *

查询入参的 {@code providerSkus} 是仓侧 SKU(建档时下发的那串)。 + * SDK 不做 OMS→仓侧 SKU 转换。

*/ - public common.ecommerce.shared.support.Page< - common.ecommerce.warehouse.capability.WarehouseProduct> queryProducts( - final common.ecommerce.warehouse.model.ProductQuery query) { + public Page queryProducts(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()), + "barcode", query.barcode(), + "hasCreatedRange", query.hasCreatedRange(), + "cursor", query.cursor()), p -> p.size(), - () -> ((WarehouseProductCapable) adapter).queryProducts(ctx, query)); + () -> ((WarehouseProductCapable) adapter).query(ctx, query)); } /** @@ -460,7 +463,10 @@ public final class WarehouseOperations { /** 本仓默认的库存同步策略。 */ public InventorySyncStrategy inventorySyncStrategy() { require(WarehouseCapability.INVENTORY_QUERY, InventoryCapable.class); - return ((InventoryCapable) adapter).syncStrategy(); + return CallSupport.observe(observer, ctx, "warehouse.inventory.syncStrategy", + CallSupport.params(), + r -> CallSupport.NO_COUNT, + () -> ((InventoryCapable) adapter).syncStrategy()); } private void require(WarehouseCapability cap, Class type) { @@ -534,16 +540,21 @@ public final class WarehouseOperations { throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); } final InboundCapable capable = (InboundCapable) adapter; - common.ecommerce.shared.idempotency.WriteResult result = - guard.execute( - WarehouseWriteScope.of(provider.name(), account.warehouseCode(), - cmd.inboundRequestNo(), "create"), - () -> capable.create(ctx, cmd), - receipt -> receipt.providerInboundId()); - if (result.alreadyCompleted()) { - return InboundReceipt.of(cmd.inboundRequestNo(), result.resultRef()); - } - return result.value(); + return CallSupport.observe(observer, ctx, "warehouse.inbound.create", + CallSupport.params("inboundRequestNo", cmd.inboundRequestNo()), + r -> CallSupport.NO_COUNT, + () -> { + common.ecommerce.shared.idempotency.WriteResult result = + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + cmd.inboundRequestNo(), "create"), + () -> capable.create(ctx, cmd), + receipt -> receipt.providerInboundId()); + if (result.alreadyCompleted()) { + return InboundReceipt.of(cmd.inboundRequestNo(), result.resultRef()); + } + return result.value(); + }); } /** 查入库单。 */ @@ -631,7 +642,10 @@ public final class WarehouseOperations { /** BOL 文档。 */ public List bols(String inboundRef) { require(WarehouseCapability.INBOUND, InboundCapable.class); - return ((InboundCapable) adapter).bols(ctx, inboundRef); + return CallSupport.observe(observer, ctx, "warehouse.inbound.bols", + CallSupport.params("inboundRef", inboundRef), + List::size, + () -> ((InboundCapable) adapter).bols(ctx, inboundRef)); } /** @@ -683,20 +697,25 @@ public final class WarehouseOperations { throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); } final WarehouseReturnCapable capable = (WarehouseReturnCapable) adapter; - common.ecommerce.shared.idempotency.WriteResult result = - guard.execute( - WarehouseWriteScope.of(provider.name(), account.warehouseCode(), - cmd.returnRequestNo(), "create"), - () -> capable.create(ctx, cmd), - ret -> ret.providerReturnId()); - if (result.alreadyCompleted()) { - return WarehouseReturn.builder() - .returnRequestNo(cmd.returnRequestNo()) - .providerReturnId(result.resultRef()) - .warehouseCode(account.warehouseCode()) - .build(); - } - return result.value(); + return CallSupport.observe(observer, ctx, "warehouse.return.create", + CallSupport.params("returnRequestNo", cmd.returnRequestNo()), + r -> CallSupport.NO_COUNT, + () -> { + common.ecommerce.shared.idempotency.WriteResult result = + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + cmd.returnRequestNo(), "create"), + () -> capable.create(ctx, cmd), + ret -> ret.providerReturnId()); + if (result.alreadyCompleted()) { + return WarehouseReturn.builder() + .returnRequestNo(cmd.returnRequestNo()) + .providerReturnId(result.resultRef()) + .warehouseCode(account.warehouseCode()) + .build(); + } + return result.value(); + }); } public WarehouseReturn get(String returnRequestNo) { @@ -725,6 +744,22 @@ public final class WarehouseOperations { } /** + * 分页查退货处理单。只读,不走幂等。 + * + *

与 {@link #query(ReturnQuery)} 的区别:那个查一张退货计划, + * 这个查计划下每一行 SKU 的待处理记录。填处理方式要用的四项定位就在结果里。

+ */ + public Page queryHandles(ReturnQuery query) { + require(WarehouseCapability.RETURN, WarehouseReturnCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.return.queryHandles", + CallSupport.params("cursor", query.cursor(), + "orderNo", query.orderNo(), + "warehouseCode", query.warehouseCode()), + p -> p.size(), + () -> ((WarehouseReturnCapable) adapter).queryHandles(ctx, query)); + } + + /** * 按明细行设置检验后处理方式。写操作:强制经幂等守卫,幂等键 * {@code warehouseCode + providerReturnNo + lineId + process}。 * @@ -765,12 +800,17 @@ public final class WarehouseOperations { throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); } final WarehouseReturnCapable capable = (WarehouseReturnCapable) adapter; - common.ecommerce.shared.idempotency.WriteResult result = guard.execute( - WarehouseWriteScope.of(provider.name(), account.warehouseCode(), - providerReturnNo, "cancel"), - () -> capable.cancel(ctx, providerReturnNo), - ok -> Boolean.TRUE.equals(ok) ? "true" : null); - return result.alreadyCompleted() || Boolean.TRUE.equals(result.value()); + return CallSupport.observe(observer, ctx, "warehouse.return.cancel", + CallSupport.params("providerReturnNo", providerReturnNo), + r -> CallSupport.NO_COUNT, + () -> { + common.ecommerce.shared.idempotency.WriteResult result = guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + providerReturnNo, "cancel"), + () -> capable.cancel(ctx, providerReturnNo), + ok -> Boolean.TRUE.equals(ok) ? "true" : null); + return result.alreadyCompleted() || Boolean.TRUE.equals(result.value()); + }); } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java index 903cbf9..73d97d3 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java @@ -57,16 +57,26 @@ public final class WarehouseOutbounds { throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); } final OutboundCapable capable = (OutboundCapable) adapter; - WriteIdentity scope = WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + final WriteIdentity scope = WarehouseWriteScope.of(provider.name(), account.warehouseCode(), cmd.outboundRequestNo(), "create"); - common.ecommerce.shared.idempotency.WriteResult result = - guard.execute(scope, () -> capable.create(ctx, cmd), - receipt -> receipt.providerOrderId()); - if (result.alreadyCompleted()) { - // 回放:本次没有调仓,只有上次记录的结果引用 - return OutboundReceipt.of(cmd.outboundRequestNo(), result.resultRef(), "ALREADY_COMPLETED"); - } - return result.value(); + // 写操作也要有一条门面级记录:幂等层只记 writes.create 的裁决, + // 不记「这次调了仓、成功还是失败」。缺了它,操作日志里就看不到下发动作。 + return common.ecommerce.shared.audit.CallSupport.observe(observer, ctx, + "warehouse.outbound.create", + common.ecommerce.shared.audit.CallSupport.params( + "outboundRequestNo", cmd.outboundRequestNo()), + r -> common.ecommerce.shared.audit.CallSupport.NO_COUNT, + () -> { + common.ecommerce.shared.idempotency.WriteResult result = + guard.execute(scope, () -> capable.create(ctx, cmd), + receipt -> receipt.providerOrderId()); + if (result.alreadyCompleted()) { + // 回放:本次没有调仓,只有上次记录的结果引用 + return OutboundReceipt.of(cmd.outboundRequestNo(), result.resultRef(), + "ALREADY_COMPLETED"); + } + return result.value(); + }); } /** 按仓单号或 OMS 单号查单。 */ diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java index 80a1a2b..23e829f 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java @@ -36,6 +36,9 @@ public final class EdayunConstants { /** 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。 */ public static final String PATH_PRODUCT_CREATE = "/webApi/skuInfo/v1/createProduct"; + /** 批量查询产品分页({@code POST /webApi/skuInfo/v1/listProductPage})。 */ + public static final String PATH_PRODUCT_LIST = "/webApi/skuInfo/v1/listProductPage"; + /** 创建出库单({@code POST /webApi/order/v1/createOrder})。 */ public static final String PATH_ORDER_CREATE = "/webApi/order/v1/createOrder"; @@ -108,12 +111,12 @@ public final class EdayunConstants { public static final String PATH_CASE_MARK_PRINT = "/webApi/skuInfo/v2/printBarcode"; /** - * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。 + * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。 * *

端点名是 newPrintCaseMark,实际打的是 SKU 标——已与仓方确认。

*/ public static final String PATH_SKU_LABEL_PRINT = - "/webApi/entryInfo/v1/newPrintCaseMarkContentType"; + "/webApi/entryInfo/v1/newPrintCaseMark"; /** 查询客户自有物流服务(承运商)({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。 */ public static final String PATH_CARRIERS = "/webApi/carrier/v1/listCarrierByWarehouse"; diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java index 37e2107..a08bf2a 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java @@ -18,6 +18,7 @@ import common.ecommerce.edayun.dto.EdayunInboundQueryDtos; import common.ecommerce.edayun.dto.EdayunInventoryDtos; import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos; import common.ecommerce.edayun.dto.EdayunOrderCostDtos; +import common.ecommerce.edayun.dto.EdayunProductQueryDtos; import common.ecommerce.edayun.dto.EdayunRentDetailDtos; import common.ecommerce.edayun.dto.EdayunReturnDetailDtos; import common.ecommerce.edayun.dto.EdayunReturnDtos; @@ -77,6 +78,8 @@ import common.ecommerce.warehouse.model.OutboundQuery; import common.ecommerce.warehouse.model.OutboundReceipt; import common.ecommerce.warehouse.model.OutboundRef; import common.ecommerce.warehouse.model.PackageResult; +import common.ecommerce.warehouse.model.ProductQuery; +import common.ecommerce.warehouse.model.ProductInfo; import common.ecommerce.warehouse.model.ReturnCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.ReturnQuery; @@ -98,8 +101,8 @@ import java.util.List; /** * 易达云适配器。 * - *

已实现:商品建档、创建出库单。其余能力不声明,门面调用会显式抛 - * {@code WarehouseUnsupportedCapabilityException},不返回空集合。

+ *

已实现的能力见 {@link #capabilities()};没声明的能力门面会显式抛 + * {@code WarehouseUnsupportedCapabilityException},不返回空集合。

* *

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

@@ -213,6 +216,40 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa parsed.data == null ? null : parsed.data.skuId); } + /** + * 批量查询仓侧商品资料({@code POST /webApi/skuInfo/v1/listProductPage})。 + * + *

入参 SKU 是仓侧 SKU,即建档时下发到 {@code skuCode} 字段的那串 + * ({@link EdayunProductMapper} 的 {@code skuOf}),不一定等于 OMS SKU。 + * 易达云的 {@code skuCode} 是逗号拼接的 + * 单个字符串且一次最多 50 个,超了本地拒绝(不截断)。 + * 审核时间窗统一模型没有对应字段,不传。

+ * + *

查询条件全空时仓方默认按创建时间查最近一个月——这一点由仓方兜底, + * 本地不补默认值。

+ */ + @Override + public Page query(WarehouseContext ctx, ProductQuery query) { + int pageNum = EdayunProductQueryMapper.pageNumber(query.cursor()); + EdayunProductQueryDtos.ListProductRequest body = + EdayunProductQueryMapper.toRequest(query, ctx.zone(), pageNum); + String bodyJson = json.toJson(body); + + HttpResponse resp = send(ctx, EdayunConstants.PATH_PRODUCT_LIST, bodyJson, + "warehouse.product.query"); + EdayunProductQueryDtos.ListProductResponse parsed = + json.fromJson(resp.body(), EdayunProductQueryDtos.ListProductResponse.class); + // 「查询无数据」是空结果,不是失败——易达云对查不到的 SKU / 条码回 code=500, + // 但语义与「运单还没轨迹」同类。 + if (parsed != null && isNoData(parsed.msg)) { + return Page.empty(); + } + requireSuccess(ctx, parsed == null ? null : parsed.code, + parsed == null ? null : parsed.msg, resp, "warehouse.product.query"); + + return EdayunProductQueryMapper.toPage(parsed, pageNum, body.pageSize); + } + // ------------------------------------------------------------------ 出库 /** @@ -905,7 +942,9 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa // 统一模型不区分业务类型,默认查「店铺订单」(1); // 不传反而返回全账号的产品,量太大 EdayunLogisticsProductDtos.ListProductRequest body = EdayunLogisticsProductMapper.toRequest( - ctx.providerWarehouseId(), APPLICABLE_BUSINESS_STORE_ORDER); + EdayunLogisticsProductMapper.resolveWarehouseId( + warehouseCode, ctx.providerWarehouseId()), + APPLICABLE_BUSINESS_STORE_ORDER); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_LOGISTICS_PRODUCTS, bodyJson, @@ -962,7 +1001,7 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa HttpResponse resp = send(ctx, EdayunConstants.PATH_TRACK, bodyJson, operation); EdayunTrackDtos.GetTrackResponse parsed = json.fromJson(resp.body(), EdayunTrackDtos.GetTrackResponse.class); - if (parsed != null && isNoTrackFound(parsed.msg)) { + if (parsed != null && isNoData(parsed.msg)) { return null; } requireSuccess(ctx, parsed == null ? null : parsed.code, @@ -971,9 +1010,10 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa return EdayunTrackMapper.find(parsed, trackingNumber); } - /** 仓方「没有轨迹」的提示语。 */ - private static boolean isNoTrackFound(String msg) { - return msg != null && (msg.contains("未匹配到轨迹") || msg.contains("跟踪号为空")); + /** 仓方「没有数据」的提示语:查不到不等于调用失败。 */ + private static boolean isNoData(String msg) { + return msg != null && (msg.contains("查询无数据") || msg.contains("未匹配到轨迹") + || msg.contains("跟踪号为空")); } // ------------------------------------------------------------------ 条码打印 @@ -1023,7 +1063,7 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa // ------------------------------------------------------------------ SKU 标 /** - * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。 + * 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。 * *

端点名叫 newPrintCaseMark,但实际打的是 SKU 标——已与仓方确认。 * 箱唛走 {@code printCaseMarks}(端点 {@code printBarcode})。

@@ -1031,12 +1071,13 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa *

统一模型的 {@code BoxLabelCommand} 没有「选哪些箱」的字段, * 所以默认整单打印;要打部分箱用重载。

* - *

真机未验证:PR 环境该接口返回「接口不存在或未启用」, - * 换到 {@code /newPrintCaseMark}(无 ContentType 后缀)能过参数校验 - * (缺 pageSize 报「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」), - * 但补全后一律「内部服务器错误」。见 docs-warehouse/edayun/TODO.md。

+ *

刻意不是 public、也没声明 {@code SKU_LABEL} 能力位:该接口在 PR 环境 + * 参数齐全后一律「内部服务器错误」(路径已确认存在,缺参数有中文校验提示), + * 属于仓方服务端异常。放成 public 会让调用方以为门面够得到,实际门面按 + * {@code SKU_LABEL} 门控、会直接抛不支持。等仓方修复后再提升可见性并声明能力位。 + * 见 docs-warehouse/edayun/TODO.md #68。

*/ - public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) { + WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) { EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd); return sendSkuLabel(ctx, body); } @@ -1046,8 +1087,8 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa * * @param selection 选箱条件;四选一,全空时本地拒绝 */ - public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd, - EdayunSkuLabelMapper.CaseSelection selection) { + WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd, + EdayunSkuLabelMapper.CaseSelection selection) { EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd, selection); return sendSkuLabel(ctx, body); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java index 7156fa4..092cff6 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java @@ -8,7 +8,6 @@ import common.ecommerce.shared.spi.TokenStore; import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.sdk.WarehouseAdapter; -import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory; /** * 易达云适配器工厂。 diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java index 2319de1..753d3e6 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java @@ -36,6 +36,26 @@ public final class EdayunLogisticsProductMapper { return req; } + /** + * 解析仓方仓 id:显式指定的 {@code warehouseCode} 优先,否则用账户配置的。 + * + *

两者都必须是易达云的数字仓 id——统一模型叫 {@code warehouseCode} + * 但易达云这个接口只认数字 id。给了非数字就本地拒绝,避免静默退回账户仓 + * (那样调用方以为按自己的仓查了,实际不是)。

+ */ + static String resolveWarehouseId(String warehouseCode, String providerWarehouseId) { + String explicit = warehouseCode == null ? null : warehouseCode.trim(); + if (explicit != null && !explicit.isEmpty()) { + if (warehouseIdOf(explicit) == null) { + throw new IllegalArgumentException( + "edayun logistics products need a numeric warehouse id, got: " + explicit + + " (the unified warehouseCode must carry edayun's numeric id here)"); + } + return explicit; + } + return providerWarehouseId; + } + /** 响应 → 统一产品清单;跳过 {@code -998} 与无效行。 */ public static List toProducts( List rows, String warehouseCode) { diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java index 635da78..49a0416 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java @@ -163,6 +163,8 @@ public final class EdayunOrderMapper { for (OutboundLine line : lines) { EdayunCreateOrderDtos.CreateOrderRequest.ProductItem item = new EdayunCreateOrderDtos.CreateOrderRequest.ProductItem(); + // 必须与建档时下发的 skuCode 一致(providerSku 优先,见 EdayunProductMapper.skuOf)。 + // 传 OMS SKU 而建档时用的是 providerSku 的话,仓方会报 SKU 不存在。 item.productSku = firstNonBlank(line.providerSku(), line.omsSku()); item.quantity = line.quantity(); Money value = line.declareValue(); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java index 7a19a29..d93d645 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java @@ -128,6 +128,26 @@ public final class EdayunProductMapper { return d; } + /** + * 下发到易达云 {@code skuCode} 字段的值——整条链路都以这个为准。 + * + *

规则:{@code providerSku} 优先,为空才回退 {@code omsSku}。

+ * + *

为什么这条规则要写在建档这里:易达云把 {@code skuCode} 当唯一键落库, + * 之后查商品({@code listProductPage} 的 {@code skuCode})、建出库单 + * (商品行 {@code productSku})、查库存({@code skuCodeList})全都按这串匹配。 + * 所以:

+ *
    + *
  • 宿主给了 {@code providerSku} → 仓方库里存它,之后所有查询 / 下单都必须传它, + * 不等于 OMS SKU
  • + *
  • 宿主没给(如 {@code ybtest})→ 仓方库里存的就是 OMS SKU,两者同名
  • + *
+ * + *

SDK 不做 OMS→仓侧 SKU 的转换:映射表在宿主手里(供应商编码规则、 + * 按仓不同的前缀),SDK 猜不出来;静默转换会拿回空结果或错商品,比报错更难发现。

+ * + *

出库行同理,见 {@code EdayunOrderMapper}({@code firstNonBlank(providerSku, omsSku)})。

+ */ private static String skuOf(WarehouseProduct product) { String sku = product.providerSku(); return sku != null && !sku.trim().isEmpty() ? sku.trim() : product.omsSku(); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java new file mode 100644 index 0000000..64b7159 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java @@ -0,0 +1,153 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.dto.EdayunProductQueryDtos; +import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.ProductInfo; +import common.ecommerce.warehouse.model.ProductQuery; + +import java.time.Instant; +import java.time.ZoneId; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 易达云商品查询映射({@code /webApi/skuInfo/v1/listProductPage})。 + * + *

SKU 过滤用逗号拼接的单个字符串({@code skuCode}), + * 且一次最多 50 个——与统一模型的 {@code providerSkus} 列表不同,这里要拼。

+ * + *

页码从 1 开始,单页最多 200。

+ */ +public final class EdayunProductQueryMapper { + + static final int MAX_PAGE_SIZE = 200; + /** skuCode 一次最多查多少个(文档:50)。 */ + static final int MAX_SKUS = 50; + + private EdayunProductQueryMapper() { + } + + /** + * 统一查询条件 → 仓方请求。 + * + * @param zone 解释创建时间窗的时区(仓方口径) + */ + public static EdayunProductQueryDtos.ListProductRequest toRequest(ProductQuery query, + ZoneId zone, + int pageNum) { + EdayunProductQueryDtos.ListProductRequest req = + new EdayunProductQueryDtos.ListProductRequest(); + req.pageNum = pageNum; + req.pageSize = pageSize(query.pageSize()); + + if (!query.providerSkus().isEmpty()) { + if (query.providerSkus().size() > MAX_SKUS) { + throw new IllegalArgumentException( + "edayun product query accepts at most " + MAX_SKUS + " skus, got " + + query.providerSkus().size() + + "; split into multiple queries"); + } + req.skuCode = String.join(",", query.providerSkus()); + } + if (query.barcode() != null && !query.barcode().trim().isEmpty()) { + req.barcode = query.barcode().trim(); + } + if (query.hasCreatedRange()) { + req.startCreateTime = query.createdAfter().toEpochMilli(); + req.endCreateTime = query.createdBefore().toEpochMilli(); + } + return req; + } + + /** 每页条数:默认 100、上限 200。 */ + static int pageSize(int requested) { + if (requested <= 0) { + return 100; + } + return Math.min(requested, MAX_PAGE_SIZE); + } + + /** 游标是字符串化的页码(从 1 开始)。 */ + static int pageNumber(String cursor) { + if (cursor == null || cursor.trim().isEmpty()) { + return 1; + } + try { + int v = Integer.parseInt(cursor.trim()); + return v > 0 ? v : 1; + } catch (NumberFormatException e) { + return 1; + } + } + + /** 响应 → 分页结果。 */ + public static Page toPage(EdayunProductQueryDtos.ListProductResponse response, + int currentPage, int pageSize) { + if (response == null || response.rows == null || response.rows.isEmpty()) { + return Page.empty(); + } + List out = new ArrayList(response.rows.size()); + for (EdayunProductQueryDtos.ProductRow row : response.rows) { + ProductInfo info = toInfo(row); + if (info != null) { + out.add(info); + } + } + return Page.of(out, nextCursor(response.total, currentPage, pageSize, out.size())); + } + + /** 有下一页时返回下一页页码;优先用 {@code total}(总行数)。 */ + static String nextCursor(Long total, int currentPage, int pageSize, int fetched) { + boolean more = total != null + ? (long) currentPage * pageSize < total + : fetched >= pageSize; + return more ? String.valueOf(currentPage + 1) : null; + } + + /** + * 一行 → 统一商品资料。 + * + *

尺寸取实际({@code length/width/height/weight}),缺失才回落 + * 预报值({@code forecast*})——查询商品资料的目的就是拿到仓方当前存的值。

+ */ + static ProductInfo toInfo(EdayunProductQueryDtos.ProductRow row) { + if (row == null || row.skuCode == null || row.skuCode.trim().isEmpty()) { + return null; + } + ProductInfo.Builder b = ProductInfo.builder() + .sourceProvider(WarehouseProvider.EDAYUN) + .providerSku(row.skuCode.trim()) + .providerProductId(trimToNull(row.skuId)) + .barcode(trimToNull(row.barcode)) + .name(trimToNull(row.skuName)) + .nameEn(trimToNull(row.skuNameEn)) + .lengthCm(numberOf(row.length, row.forecastLength)) + .widthCm(numberOf(row.width, row.forecastWidth)) + .heightCm(numberOf(row.height, row.forecastHeight)) + .weightGrams(numberOf(row.weight, row.forecastWeight)) + .remark(trimToNull(row.remark)) + .createdAt(instantOf(row.createTime)); + b.extraBarcode(row.extraBarcode1); + b.extraBarcode(row.extraBarcode2); + b.extraBarcode(row.extraBarcode3); + return b.build(); + } + + /** 优先实际值,缺失回落预报值;都缺为 0。 */ + private static double numberOf(Double actual, Double forecast) { + if (actual != null) { + return actual; + } + return forecast == null ? 0 : forecast; + } + + private static Instant instantOf(Long millis) { + return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis); + } + + private static String trimToNull(String v) { + return v == null || v.trim().isEmpty() ? null : v.trim(); + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java index 9c420fc..49844e7 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnDetailMapper.java @@ -56,8 +56,10 @@ public final class EdayunReturnDetailMapper { .returnRequestNo(basic == null ? trimToNull(requestedRmaCode) : firstNonBlank(basic.relationNo, basic.rmaCode, requestedRmaCode)) .providerReturnId(basic == null ? trimToNull(requestedRmaCode) : basic.rmaCode) - .warehouseCode(firstNonBlank( - basic == null ? null : basic.warehouseName, warehouseCode)) + // 响应只有仓名(美西1仓)与数字 id,没有仓编码。 + // warehouseCode 这一列必须放「编码」,不能退化成展示名—— + // 宿主会拿它做 equals / 回传查询,放中文名会全线失效。 + .warehouseCode(trimToNull(warehouseCode)) .orderRef(basic == null ? null : basic.relationNo) .type(basic == null ? null : basic.returnTypeName) .status(EdayunRmaStatus.toCore( diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java index 168556a..0883904 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunReturnMapper.java @@ -46,6 +46,8 @@ public final class EdayunReturnMapper { */ public static EdayunReturnDtos.SaveReturnRequest toRequest(ReturnCommand cmd, String providerWarehouseId) { + requireHonorable(cmd); + EdayunReturnDtos.SaveReturnRequest req = new EdayunReturnDtos.SaveReturnRequest(); req.returnType = RETURN_TYPE_SELF_SHIP; @@ -62,6 +64,35 @@ public final class EdayunReturnMapper { } /** + * 本适配器不支持的命令字段在本地拒绝,不静默丢弃。 + * + *

静默丢弃的后果是调用方以为条件生效了,实际没有。三个字段的情况:

+ *
    + *
  • {@code lineName}(项目):易达云退货单没有项目概念
  • + *
  • {@code estimatedReceiveDate}:易达云按关联单号推,不接受预计到仓日
  • + *
  • {@code returnReason}:易达云要 Integer 字典码({@code wms_rma_return_reason}), + * 统一模型给的是自由文本,对不上——见 TODO
  • + *
+ */ + private static void requireHonorable(ReturnCommand cmd) { + if (hasText(cmd.lineName())) { + throw new IllegalArgumentException( + "edayun return create does not support lineName (project): " + cmd.lineName()); + } + if (cmd.estimatedReceiveDate() != null) { + throw new IllegalArgumentException( + "edayun return create does not support estimatedReceiveDate: " + + cmd.estimatedReceiveDate()); + } + if (hasText(cmd.returnReason())) { + throw new IllegalArgumentException( + "edayun return create needs a numeric returnReason dictionary code" + + " (wms_rma_return_reason), got free text: " + cmd.returnReason() + + "; vendor dictionary mapping not implemented yet"); + } + } + + /** * 仓:{@code warehouseId} 数字优先,否则 {@code warehouseCode}。 * *

命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。

@@ -134,6 +165,10 @@ public final class EdayunReturnMapper { } } + private static boolean hasText(String v) { + return v != null && !v.trim().isEmpty(); + } + private static String firstNonBlank(String a, String b) { if (a != null && !a.trim().isEmpty()) { return a.trim(); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java index 235181e..df9f963 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java @@ -64,12 +64,7 @@ public final class EdayunRmaListMapper { req.trackingNos = query.trackingNo().trim(); } - Long warehouseId = warehouseIdOf(providerWarehouseId); - if (warehouseId != null) { - req.warehouseId = warehouseId; - } else if (hasText(query.warehouseCode())) { - req.warehouseCode = query.warehouseCode().trim(); - } + applyWarehouseFilter(req, query, providerWarehouseId); if (hasText(query.providerSku())) { req.skuCode = query.providerSku().trim(); @@ -87,6 +82,32 @@ public final class EdayunRmaListMapper { } /** + * 仓过滤:账户仓 id 与调用方给的仓编码只能二选一。 + * + *

易达云文档写明「{@code warehouseCode}(优先使用仓库 id)」,两者同时给时 + * 仓方会忽略编码。若调用方显式指定了另一个仓编码,静默按账户仓查会把 + * 过滤条件丢掉、结果反而变宽——这种冲突在本地拒绝,不猜。

+ */ + private static void applyWarehouseFilter(EdayunRmaListDtos.SelectRmaListRequest req, + ReturnQuery query, String providerWarehouseId) { + Long warehouseId = warehouseIdOf(providerWarehouseId); + String requested = hasText(query.warehouseCode()) ? query.warehouseCode().trim() : null; + + if (warehouseId != null) { + if (requested != null && !requested.equals(String.valueOf(warehouseId))) { + throw new IllegalArgumentException( + "edayun return list cannot filter by warehouseCode '" + requested + + "' while the account is bound to numeric warehouse id " + + warehouseId + "; the vendor would ignore warehouseCode" + + " and query the account warehouse instead"); + } + req.warehouseId = warehouseId; + return; + } + req.warehouseCode = requested; + } + + /** * 单号类型 → 易达云 {@code orderNoSearchType}。 * *

null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。

@@ -153,9 +174,10 @@ public final class EdayunRmaListMapper { // 列表没有来源单号字段,用 RMA 号兜底;orderRef 用平台 / 出库单号 .returnRequestNo(firstNonBlank(row.rmaCode, row.ordOrderCode)) .providerReturnId(row.rmaCode) - // 文档响应示例没有 warehouseCode,但真机会返回,优先用它 - .warehouseCode(firstNonBlank(row.warehouseCode, row.warehouseName, - fallbackWarehouseCode)) + // 列表有 warehouseCode(真机返回,文档示例里没有)就直接用; + // **不能退化成 warehouseName**——那是展示名(美西1仓), + // 宿主拿 warehouseCode 做 equals / 回传查询会全线失效。 + .warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode)) .orderRef(firstNonBlank(row.platformOrderCode, row.ordOrderCode)) .type(row.returnTypeName) .status(EdayunRmaStatus.toCore(row.status, row.statusName)) diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java index 23631ad..569fc9d 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java @@ -8,7 +8,7 @@ import common.ecommerce.warehouse.model.WarehouseLabel; import java.util.List; /** - * 易达云 SKU 标映射({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。 + * 易达云 SKU 标映射({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。 * *

统一模型只能表达「整单打印」:{@code BoxLabelCommand} 没有「选哪些箱」 * 的字段,所以选箱条件(系统箱号列表 / SKU / 箱序号区间 / 客户箱号区间) diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java index 5726b17..e753c08 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java @@ -66,7 +66,9 @@ public final class EdayunTrackMapper { .carrier(track.carrierName) // 仓方状态是数字码,码表没给;保留原值而不是猜成某个字符串 .status(track.status == null ? null : String.valueOf(track.status)) - .signedBy(track.receiver) + // track.receiver 是「收件人」,不是「签收人」——在途就有值。 + // signedBy 的约定是「未签收为 null」,映射它会让每个在途包裹都被 + // 判成已签收。易达云响应里没有签收人字段,宁可不填。 .firstOnlineAt(parseLocal(track.onlineTime, zone)) .deliveredAt(parseLocal(track.deliveredTime, zone)); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java new file mode 100644 index 0000000..d67295f --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java @@ -0,0 +1,96 @@ +package common.ecommerce.edayun.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.util.List; + +/** + * 易达云报文结构:批量查询产品分页 + * ({@code POST /webApi/skuInfo/v1/listProductPage})。 + * + *

一个文件对应一个接口。查询条件全空时仓方默认按创建时间查最近一个月, + * 页码从 1 开始,单页最多 200 条。

+ */ +public final class EdayunProductQueryDtos { + + private EdayunProductQueryDtos() { + } + + /** 查询请求。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ListProductRequest { + /** 产品状态:0 草稿 / 1 已发布。 */ + public String status; + /** 每页条数,最多 200。 */ + public Integer pageSize; + /** 页码,从 1 开始。 */ + public Integer pageNum; + + public String barcode; + /** SKU 编码,多个用英文逗号拼接,一次最多 50 个。 */ + public String skuCode; + public String extraBarcode; + /** 中文品名。 */ + public String skuName; + + /** 创建时间窗(毫秒)。 */ + public Long startCreateTime; + public Long endCreateTime; + /** 审核时间窗(毫秒)。 */ + public Long startAuditTime; + public Long endAuditTime; + } + + /** 查询响应。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ListProductResponse { + public Long total; + public List rows; + public Integer code; + public String msg; + } + + /** 一行商品。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ProductRow { + /** 创建时间(毫秒)。 */ + public Long createTime; + public String remark; + /** 仓方商品 id。 */ + public String skuId; + public String skuCode; + /** 中文品名。 */ + public String skuName; + public String skuNameEn; + public String barcode; + /** 外部条码 1/2/3。 */ + public String extraBarcode1; + public String extraBarcode2; + public String extraBarcode3; + + /** 预报尺寸(cm)与重量;量级像克。 */ + public Double forecastLength; + public Double forecastWidth; + public Double forecastHeight; + public Double forecastWeight; + + /** 实际尺寸(cm)与重量;量级像克。 */ + public Double length; + public Double width; + public Double height; + public Double weight; + + /** 带电标志:0 是 / 1 否(同其它接口的反向布尔)。 */ + public Integer electricFlag; + public Integer electricType; + public Integer electricPackage; + public Integer electricPower; + public String electricUrl; + + /** 商品图片。 */ + public String skuUrl; + /** 品牌标志:0 是 / 1 否。 */ + public Integer brandFlag; + public String brandName; + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java index 64ffb89..2d92700 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java @@ -6,7 +6,7 @@ import java.util.List; /** * 易达云报文结构:打印 SKU 标 - * ({@code POST /webApi/entryInfo/v1/newPrintCaseMarkContentType})。 + * ({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。 * *

一个文件对应一个接口。响应 {@code data} 是PDF 地址字符串,同步生成。

* diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java index 2080f8b..b471856 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java @@ -18,7 +18,6 @@ import java.util.List; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNull; -import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; /** @@ -150,11 +149,4 @@ class EdayunCarrierTest { assertTrue(transport.lastDataRequest().body().contains("\"warehouseId\":2")); } - /** 仓库列表接口易达云没有,显式拒绝而不是空列表。 */ - @Test - void warehousesAreUnsupported() { - assertThrows(RuntimeException.class, - () -> new EdayunAdapter(stub("{}"), new JacksonJsonCodec()) - .warehouses(ctx("2"))); - } } diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java index 1e33d4d..da18447 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java @@ -165,7 +165,8 @@ class EdayunInventoryTest { /** 仓编码缺失时回退 OMS 仓编码,快照必须有 warehouseCode。 */ @Test - void warehouseCodeFallsBack() { EdayunInventoryDtos.InventoryRow r = row(); + void warehouseCodeFallsBack() { + EdayunInventoryDtos.InventoryRow r = row(); r.warehouseCode = null; assertEquals("EDY-WH", EdayunInventoryMapper.toPage( @@ -173,7 +174,8 @@ class EdayunInventoryTest { .items().get(0).warehouseCode()); } - /** 没有 SKU 的行跳过,不应让整页失败。 */ @Test + /** 没有 SKU 的行跳过,不应让整页失败。 */ + @Test void rowsWithoutSkuAreSkipped() { EdayunInventoryDtos.InventoryRow dirty = row(); dirty.skuCode = " "; diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java new file mode 100644 index 0000000..c82c702 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java @@ -0,0 +1,215 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.dto.EdayunProductQueryDtos; +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.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.ProductInfo; +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.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 商品查询({@code /webApi/skuInfo/v1/listProductPage})映射。 + * + *

重点:SKU 是逗号拼接的单个字符串、一次最多 50 个、页码从 1 开始、 + * 实际尺寸优先于预报尺寸。

+ */ +class EdayunProductQueryTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC); + + private static WarehouseContext ctx() { + return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, "2", + WarehouseConnection.of("https://test.example/openapi", + ChannelSecret.builder().appKey("k").appSecret("s") + .clientId("c").clientSecret("cs").build()), + "req-product-query", CLOCK); + } + + private static RecordingTransport stub(String body) { + return RecordingTransport.create() + .route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok( + "{\"access_token\":\"T1\",\"token_type\":\"bearer\"}")) + .route(common.ecommerce.edayun.EdayunConstants.PATH_PRODUCT_LIST, + req -> Responses.ok(body)); + } + + // ------------------------------------------------------------ 请求 + + /** SKU 列表要拼成逗号分隔的单个字符串。 */ + @Test + void skusAreJoinedWithComma() { + EdayunProductQueryDtos.ListProductRequest req = + EdayunProductQueryMapper.toRequest( + ProductQuery.builder().providerSku("A").providerSku("B").build(), + ZoneOffset.UTC, 1); + + assertEquals("A,B", req.skuCode); + } + + /** 一次最多 50 个 SKU,超了本地拒绝(不截断)。 */ + @Test + void moreThan50SkusRejected() { + ProductQuery.Builder b = ProductQuery.builder(); + for (int i = 0; i < 51; i++) { + b.providerSku("SKU-" + i); + } + + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> EdayunProductQueryMapper.toRequest(b.build(), ZoneOffset.UTC, 1)); + + assertTrue(ex.getMessage().contains("at most 50"), ex.getMessage()); + } + + @Test + void pageSizeCappedAt200() { + assertEquals(200, EdayunProductQueryMapper.pageSize(1000)); + assertEquals(100, EdayunProductQueryMapper.pageSize(0)); + } + + /** 页码从 1 开始。 */ + @Test + void pageNumberStartsAtOne() { + assertEquals(1, EdayunProductQueryMapper.pageNumber(null)); + assertEquals(1, EdayunProductQueryMapper.pageNumber("0")); + assertEquals(3, EdayunProductQueryMapper.pageNumber("3")); + } + + /** 创建时间窗按毫秒下发;只给一端时不下发(避免半开区间语义不明)。 */ + @Test + void createdRangeIsMillis() { + EdayunProductQueryDtos.ListProductRequest req = EdayunProductQueryMapper.toRequest( + ProductQuery.builder() + .createdAfter(Instant.parse("2026-01-01T00:00:00Z")) + .createdBefore(Instant.parse("2026-02-01T00:00:00Z")) + .build(), ZoneOffset.UTC, 1); + + assertEquals(Long.valueOf(Instant.parse("2026-01-01T00:00:00Z").toEpochMilli()), + req.startCreateTime); + assertEquals(Long.valueOf(Instant.parse("2026-02-01T00:00:00Z").toEpochMilli()), + req.endCreateTime); + + assertNull(EdayunProductQueryMapper.toRequest( + ProductQuery.builder().createdAfter(Instant.parse("2026-01-01T00:00:00Z")).build(), + ZoneOffset.UTC, 1).startCreateTime); + } + + // ------------------------------------------------------------ 响应 + + private static EdayunProductQueryDtos.ProductRow row() { + EdayunProductQueryDtos.ProductRow r = new EdayunProductQueryDtos.ProductRow(); + r.skuCode = "ybtest"; + r.skuId = "1001"; + r.skuName = "苹果14"; + r.skuNameEn = "iphone14"; + r.barcode = "N94902313123"; + r.extraBarcode1 = "E1"; + r.extraBarcode3 = "E3"; + r.length = 12.0; + r.width = 11.0; + r.height = 10.0; + r.weight = 600.0; + r.forecastLength = 99.0; + r.createTime = 1745473090263L; + return r; + } + + /** 实际尺寸优先于预报尺寸。 */ + @Test + void actualSizeWinsOverForecast() { + ProductInfo info = EdayunProductQueryMapper.toInfo(row()); + + assertEquals(12.0, info.lengthCm()); + assertEquals(11.0, info.widthCm()); + assertEquals(600.0, info.weightGrams()); + assertEquals("ybtest", info.providerSku()); + assertEquals("1001", info.providerProductId()); + assertEquals(2, info.extraBarcodes().size()); + assertEquals(WarehouseProvider.EDAYUN, info.sourceProvider()); + assertEquals(Instant.ofEpochMilli(1745473090263L), info.createdAt()); + } + + /** 实际尺寸缺失才回落预报值。 */ + @Test + void fallsBackToForecastSize() { + EdayunProductQueryDtos.ProductRow r = row(); + r.length = null; + r.weight = null; + + ProductInfo info = EdayunProductQueryMapper.toInfo(r); + + assertEquals(99.0, info.lengthCm()); + assertEquals(0.0, info.weightGrams()); + } + + /** 没有 SKU 的行跳过。 */ + @Test + void rowsWithoutSkuAreSkipped() { + EdayunProductQueryDtos.ProductRow bad = row(); + bad.skuCode = " "; + + assertNull(EdayunProductQueryMapper.toInfo(bad)); + assertNull(EdayunProductQueryMapper.toInfo(null)); + } + + /** 「查询无数据」是空结果,不抛异常(同轨迹接口的处理)。 */ + @Test + void noDataYieldsEmptyPage() { + RecordingTransport transport = stub( + "{\"total\":0,\"rows\":null,\"code\":500,\"msg\":\"查询无数据\"}"); + + Page page = new EdayunAdapter(transport, new JacksonJsonCodec()) + .query(ctx(), ProductQuery.builder().providerSku("NOPE").build()); + + assertTrue(page.items().isEmpty()); + assertTrue(!page.hasMore()); + } + + /** 其它业务错误仍然抛。 */ + @Test + void otherBusinessErrorsStillThrow() { + RecordingTransport transport = stub("{\"code\":500,\"msg\":\"系统异常\"}"); + + assertThrows(RuntimeException.class, + () -> new EdayunAdapter(transport, new JacksonJsonCodec()) + .query(ctx(), ProductQuery.builder().build())); + } + + @Test + void nextCursorUsesTotal() { + assertEquals("2", EdayunProductQueryMapper.nextCursor(250L, 1, 100, 100)); + assertNull(EdayunProductQueryMapper.nextCursor(250L, 3, 100, 50)); + // total 缺失时按满页判断 + assertEquals("2", EdayunProductQueryMapper.nextCursor(null, 1, 100, 100)); + } + + @Test + void adapterQueriesProducts() { + RecordingTransport transport = stub("{\"total\":1,\"code\":200,\"msg\":\"成功\",\"rows\":[{" + + "\"skuCode\":\"ybtest\",\"skuName\":\"苹果14\",\"length\":12,\"width\":11," + + "\"height\":10,\"weight\":600,\"createTime\":1745473090263}]}"); + + Page page = new EdayunAdapter(transport, new JacksonJsonCodec()) + .query(ctx(), ProductQuery.builder().providerSku("ybtest").build()); + + assertEquals(1, page.size()); + assertEquals("ybtest", page.items().get(0).providerSku()); + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"skuCode\":\"ybtest\""), body); + assertTrue(body.contains("\"pageNum\":1"), body); + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java index 19f5921..f81e129 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java @@ -84,6 +84,41 @@ class EdayunReturnTest { EdayunReturnMapper.toRequest(cmd, "2").relationNo); } + /** 易达云不接受的命令字段要在本地拒绝,不能静默丢弃。 */ + @Test + void unsupportedCommandFieldsAreRejected() { + assertTrue(throwsOn(ReturnCommand.builder() + .returnRequestNo("RT-9").saleOrderNo("SO-1") + .returnTrackingNo("1Z1").carrierCode("UPS") + .lineName("默认项目") + .line("sku", 1, ReturnDealMethod.DESTROY).build()) + .contains("lineName")); + + assertTrue(throwsOn(ReturnCommand.builder() + .returnRequestNo("RT-9").saleOrderNo("SO-1") + .returnTrackingNo("1Z1").carrierCode("UPS") + .estimatedReceiveDate(java.time.LocalDate.of(2026, 12, 1)) + .line("sku", 1, ReturnDealMethod.DESTROY).build()) + .contains("estimatedReceiveDate")); + + assertTrue(throwsOn(ReturnCommand.builder() + .returnRequestNo("RT-9").saleOrderNo("SO-1") + .returnTrackingNo("1Z1").carrierCode("UPS") + .returnReason("damaged") + .line("sku", 1, ReturnDealMethod.DESTROY).build()) + .contains("returnReason")); + } + + private static String throwsOn(ReturnCommand cmd) { + try { + EdayunReturnMapper.toRequest(cmd, "2"); + org.junit.jupiter.api.Assertions.fail("should have thrown"); + return ""; + } catch (IllegalArgumentException e) { + return e.getMessage(); + } + } + @Test void nonNumericWarehouseGoesToWarehouseCode() { ReturnCommand noWarehouse = ReturnCommand.builder() diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java index 3496789..10cc8d6 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java @@ -102,6 +102,29 @@ class EdayunRmaListTest { EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PLATFORM_ORDER_NO)); } + /** + * 账户绑了数字仓 id 时,调用方再传一个不同的仓编码要本地拒绝—— + * 仓方会忽略 warehouseCode,静默按账户仓查会让结果反而变宽。 + */ + @Test + void conflictingWarehouseCodeIsRejected() { + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> EdayunRmaListMapper.toRequest( + base().warehouseCode("USNY").build(), "2", ZoneOffset.UTC, 1)); + + assertTrue(ex.getMessage().contains("cannot filter by warehouseCode"), ex.getMessage()); + } + + /** 传的仓编码与账户仓 id 一致时放行。 */ + @Test + void matchingWarehouseCodeIsAccepted() { + EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest( + base().warehouseCode("2").build(), "2", ZoneOffset.UTC, 1); + + assertEquals(Long.valueOf(2L), req.warehouseId); + assertNull(req.warehouseCode); + } + @Test void warehouseIdGoesNumeric() { EdayunRmaListDtos.SelectRmaListRequest numeric = @@ -155,6 +178,7 @@ class EdayunRmaListTest { row.ordOrderCode = "ORD822935302"; row.trackingNo = "ORD822935302"; row.warehouseName = "美西1仓"; + row.warehouseCode = "USLA"; row.warehouseId = 2L; row.returnType = 0; row.returnTypeName = "未妥投退回"; @@ -170,7 +194,8 @@ class EdayunRmaListTest { assertEquals("RMA2411058099", ret.returnRequestNo()); assertEquals("RMA2411058099", ret.providerReturnId()); - assertEquals("美西1仓", ret.warehouseCode()); + // warehouseCode 必须是仓编码,不能是展示名(美西1仓) + assertEquals("USLA", ret.warehouseCode()); assertEquals("102002", ret.orderRef()); assertEquals("未妥投退回", ret.type()); // 6 = 处理中-等待指令 → 待收货 @@ -191,11 +216,11 @@ class EdayunRmaListTest { assertEquals("USLA", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode()); } - /** 没有仓编码时回退仓名,再回退 OMS 仓编码。 */ + /** 响应没有仓编码时直接回退 OMS 仓编码——**不能**退化成仓名(美西1仓)。 */ @Test - void warehouseCodeFallsBackToOms() { + void warehouseCodeFallsBackToOmsNotDisplayName() { EdayunRmaListDtos.RmaRow r = row(); - r.warehouseName = null; + r.warehouseCode = null; assertEquals("EDY-WH", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode()); } diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java index 845a4e7..df8dd7d 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java @@ -15,7 +15,7 @@ import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; /** - * SKU 标打印({@code newPrintCaseMarkContentType})映射。 + * SKU 标打印({@code newPrintCaseMark})映射。 * *

重点:码值不连续(4/2/5)、统一模型只能表达整单打印、 * Made in China 与分隔符默认关。

diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java index 407616e..bbdfa95 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java @@ -102,7 +102,8 @@ class EdayunTrackTest { assertEquals("LF-1741871641090", info.trackingNumber()); assertEquals("fedex", info.carrier()); assertEquals("1", info.status()); - assertEquals("123", info.signedBy()); + // receiver 是收件人,不是签收人;signedBy 必须为空(未签收契约) + assertNull(info.signedBy()); // 上网 / 妥投时间按 GMT-04:00 解释 assertEquals(Instant.parse("2025-08-19T12:17:00Z"), info.firstOnlineAt()); assertEquals(Instant.parse("2025-08-20T14:00:00Z"), info.deliveredAt()); diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java new file mode 100644 index 0000000..aef7104 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java @@ -0,0 +1,106 @@ +package common.ecommerce.edayun.probe; + +import common.ecommerce.edayun.EdayunConstants; +import common.ecommerce.edayun.adapter.EdayunAdapter; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.shared.error.ChannelException; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.ProductInfo; +import common.ecommerce.warehouse.model.ProductQuery; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import org.junit.jupiter.api.Assumptions; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledIfSystemProperty; + +import java.time.Clock; +import java.util.Arrays; +import java.util.UUID; + +/** + * 商品查询联调探针:只读。 + * + *
+ * # 只看报文(不联网)
+ * mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \
+ *     -Dedayun.probe.productQuery=true -Dtest=EdayunProductQueryProbeTest test
+ *
+ * # 真查(只读)
+ * ... -Dedayun.probe.productQuery=true -Dedayun.probe.call=true \
+ *     -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \
+ *     -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \
+ *     [-Dedayun.probe.sku=ybtest] [-Dedayun.probe.days=30]
+ * 
+ */ +@EnabledIfSystemProperty(named = "edayun.probe.productQuery", matches = "true") +class EdayunProductQueryProbeTest { + + private static final String BASE_URL = opt("edayun.probe.baseUrl", EdayunConstants.PR_BASE_URL); + private static final String CLIENT_ID = System.getProperty("edayun.probe.clientId", ""); + private static final String CLIENT_SECRET = System.getProperty("edayun.probe.clientSecret", ""); + private static final String APP_KEY = System.getProperty("edayun.probe.appKey", ""); + private static final String APP_SECRET = System.getProperty("edayun.probe.appSecret", ""); + private static final String SKU = System.getProperty("edayun.probe.sku", "ybtest"); + private static final int DAYS = Integer.getInteger("edayun.probe.days", 30); + private static final boolean CALL = Boolean.getBoolean("edayun.probe.call"); + + @Test + void probeProductQuery() { + ProductQuery query = ProductQuery.builder() + .providerSku(SKU) + .createdAfter(java.time.Instant.now().minus(java.time.Duration.ofDays(DAYS))) + .createdBefore(java.time.Instant.now()) + .build(); + + System.out.println("\n================ edayun / POST " + + EdayunConstants.PATH_PRODUCT_LIST + " ================"); + System.out.println("[probe] baseUrl=" + BASE_URL + " sku=" + SKU + " days=" + DAYS); + + Assumptions.assumeTrue(CALL, "dry-run:未加 -Dedayun.probe.call=true,不实际调用"); + Assumptions.assumeTrue(!CLIENT_ID.trim().isEmpty() && !CLIENT_SECRET.trim().isEmpty() + && !APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(), + "真查需要 -Dedayun.probe.clientId / clientSecret / appKey / appSecret"); + + try { + WarehouseContext ctx = WarehouseContext.of("EDY-PROBE", WarehouseProvider.EDAYUN, "2", + WarehouseConnection.of(BASE_URL, + ChannelSecret.builder() + .appKey(APP_KEY).appSecret(APP_SECRET) + .clientId(CLIENT_ID).clientSecret(CLIENT_SECRET) + .build()), + "probe-" + UUID.randomUUID(), Clock.systemUTC()); + EdayunAdapter adapter = new EdayunAdapter( + new OkHttpTransport("common-ecommerce/1.0.0 (edayun-probe)", 10_000, 60_000), + new JacksonJsonCodec()); + + Page page = adapter.query(ctx, query); + System.out.println("[OK] rows=" + page.size() + " hasMore=" + page.hasMore() + + " nextCursor=" + page.nextCursor()); + for (ProductInfo p : page.items()) { + System.out.println(" " + p.providerSku() + " " + p.name() + + " lwh=" + p.lengthCm() + "x" + p.widthCm() + "x" + p.heightCm() + + " weight=" + p.weightGrams() + + " barcode=" + p.barcode() + + " createdAt=" + p.createdAt()); + } + } catch (RuntimeException e) { + String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage(); + System.out.println("[ERROR] " + e.getClass().getSimpleName() + ": " + + (msg.length() <= 800 ? msg : msg.substring(0, 800) + "…")); + if (e instanceof ChannelException) { + ChannelException ce = (ChannelException) e; + System.out.println(" platformCode=" + ce.platformCode() + + " retryable=" + ce.retryable()); + } + } + } + + private static String opt(String name, String fallback) { + String value = System.getProperty(name, ""); + String trimmed = value == null ? "" : value.trim(); + return trimmed.isEmpty() ? fallback : trimmed; + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java new file mode 100644 index 0000000..0f09551 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java @@ -0,0 +1,436 @@ +package common.ecommerce.edayun.sdk; + +import common.ecommerce.edayun.EdayunConstants; +import common.ecommerce.edayun.adapter.EdayunAdapter; +import common.ecommerce.edayun.adapter.EdayunAdapterFactory; +import common.ecommerce.shared.model.Platform; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.support.Money; +import common.ecommerce.shared.testkit.InMemoryIdempotencyStore; +import common.ecommerce.shared.testkit.InMemoryLockProvider; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.testkit.InMemoryTokenStore; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.CaseMarkPaperSize; +import common.ecommerce.warehouse.enums.CancelEligibility; +import common.ecommerce.warehouse.enums.ReturnDealMethod; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.CaseMarkPrintCommand; +import common.ecommerce.warehouse.model.BolDocument; +import common.ecommerce.warehouse.model.CancelCommand; +import common.ecommerce.warehouse.model.CancelResult; +import common.ecommerce.warehouse.model.FeeEstimateQuery; +import common.ecommerce.warehouse.model.FeeEstimateResult; +import common.ecommerce.warehouse.model.InventoryQuery; +import common.ecommerce.warehouse.model.InventorySnapshot; +import common.ecommerce.warehouse.model.LogisticsProduct; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.OutboundOrder; +import common.ecommerce.warehouse.model.OutboundReceipt; +import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.ReturnCommand; +import common.ecommerce.warehouse.model.ReturnQuery; +import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.model.TrackEvent; +import common.ecommerce.warehouse.model.TrackingInfo; +import common.ecommerce.warehouse.model.WarehouseCarrier; +import common.ecommerce.warehouse.model.WarehouseFacility; +import common.ecommerce.warehouse.model.WarehouseLabel; +import common.ecommerce.warehouse.model.WarehouseReturn; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseSdk; +import common.ecommerce.warehouse.spi.WarehouseAccount; +import common.ecommerce.warehouse.testkit.InMemoryWarehouses; +import org.junit.jupiter.api.Test; + +import java.math.BigDecimal; +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 易达云 SDK 装配链路冒烟。 + * + *

不联网:走 {@link WarehouseSdk} 门面 → 工厂 → 适配器 → 假传输层, + * 用真实报文样本验一遍「能不能装起来、能力位对不对、字段有没有搬对」。

+ * + *

覆盖的业务场景:

+ *
    + *
  1. 主数据:仓库 / 承运商 / 物流产品
  2. + *
  3. 发货:试算 → 建单 → 查单 → 面单 → 取消
  4. + *
  5. 库存:查询
  6. + *
  7. 退货:建单 → 查详情 → 列表 → 取消
  8. + *
  9. 单据 / 轨迹 / 打印
  10. + *
+ */ +class EdayunSdkSmokeTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC); + private static final String WH = "EDY-USLA"; + private static final String BASE = "https://test.omniselling.com.cn/saas-service/openapi/microService"; + + private static WarehouseSdk sdk(RecordingTransport transport) { + InMemoryWarehouses repo = new InMemoryWarehouses().put(WarehouseAccount.builder() + .warehouseCode(WH) + .provider(WarehouseProvider.EDAYUN.name()) + .providerWarehouseId("2") + .credentialRef("kms://test/edayun") + .timeZone("America/Los_Angeles") + .build()); + // 直接注册适配器实例:把传输层换成假的,其余装配(token 缓存 / 锁 / 时钟)与 + // 生产走同一套构造参数。工厂路径由 factoryAssemblesAdapter 单独验证。 + EdayunAdapter adapter = new EdayunAdapter(transport, new JacksonJsonCodec(), + new InMemoryTokenStore(), new InMemoryLockProvider(), CLOCK); + return WarehouseSdk.builder() + .warehouseRepository(repo) + .idempotencyStore(new InMemoryIdempotencyStore()) + .clock(CLOCK) + .register(adapter) + .build(); + } + + private static WarehouseConnection conn() { + return WarehouseConnection.of(BASE, ChannelSecret.builder() + .appKey("ak").appSecret("sk") + .clientId("cid").clientSecret("cs") + .build()); + } + + /** 所有业务接口共用的假传输层:token + 按路径路由。 */ + private static RecordingTransport transport() { + return RecordingTransport.create() + .route(EdayunConstants.PATH_TOKEN, req -> Responses.ok( + "{\"access_token\":\"T1\",\"token_type\":\"bearer\"}")) + .route(EdayunConstants.PATH_WAREHOUSE_PERMITTED, req -> Responses.ok( + "{\"code\":200,\"data\":[{\"warehouseId\":\"2\",\"warehouseName\":\"美西1仓\"," + + "\"warehouseCode\":\"USLA\",\"countryCode\":\"US\"}]}")) + .route(EdayunConstants.PATH_CARRIERS, req -> Responses.ok( + "{\"code\":200,\"data\":[{\"carrierId\":\"1\",\"carrierNameEn\":\"FedEx\"," + + "\"carrierNameCn\":\"FedEx\",\"ownLogisticList\":[" + + "{\"logisticId\":\"250\",\"logisticName\":\"FedEx-express\"}]}]}")) + .route(EdayunConstants.PATH_LOGISTICS_PRODUCTS, req -> Responses.ok( + "{\"code\":200,\"data\":[{\"productId\":\"133\",\"productName\":\"USPS\"}," + + "{\"productId\":\"-998\",\"productName\":\"使用分物流规则\"}]}")) + .route(EdayunConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"successItems\":[{" + + "\"logisticProductId\":\"80\",\"logisticProductName\":\"美国经济派送\"," + + "\"currencyCode\":\"USD\",\"estimatedPrice\":5.315," + + "\"detailList\":[{\"billingItemName\":\"尾程配送费\"," + + "\"estimatedPrice\":3.315,\"currencyCode\":\"USD\"}]}]," + + "\"failItems\":[]}}")) + .route(EdayunConstants.PATH_ORDER_CREATE, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"orderNo\":\"ORD1001\"," + + "\"poNumber\":\"SO-1\"}}")) + .route(EdayunConstants.PATH_ORDER_GET, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"orderNo\":\"ORD1001\"," + + "\"poNumber\":\"SO-1\",\"orderStatus\":\"Shipped\"," + + "\"trackingNo\":\"1Z111\"}}")) + .route(EdayunConstants.PATH_ORDER_LABEL, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"orderNo\":\"ORD1001\"," + + "\"trackingNo\":\"1Z111\",\"labels\":\"https://oss/l1.pdf\"}}")) + .route(EdayunConstants.PATH_ORDER_CHECK_CANCEL, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":\"Published\"}")) + .route(EdayunConstants.PATH_ORDER_CANCEL, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":true}")) + .route(EdayunConstants.PATH_INVENTORY, req -> Responses.ok( + "{\"code\":200,\"msg\":\"success\",\"total\":1,\"rows\":[{" + + "\"skuCode\":\"ybtest\",\"stock\":\"4\",\"totalStock\":\"10\"," + + "\"inTransitStock\":\"20\",\"frozenStock\":\"1\"," + + "\"toDeliverStock\":\"2\",\"safeStock\":null," + + "\"warehouseCode\":\"USLA\"}]}")) + .route(EdayunConstants.PATH_RETURN_CREATE, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":\"RMA1001\"}")) + .route(EdayunConstants.PATH_RETURN_DETAIL, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":{\"basicInfo\":{" + + "\"rmaCode\":\"RMA1001\",\"status\":5,\"statusName\":\"已处理\"," + + "\"relationNo\":\"SO-1\",\"warehouseName\":\"美西1仓\"}," + + "\"checkList\":[{\"skuCode\":\"ybtest\",\"skuNum\":1," + + "\"commandName\":\"上架\"}]}}")) + .route(EdayunConstants.PATH_RETURN_LIST, req -> Responses.ok( + "{\"total\":1,\"code\":200,\"rows\":[{\"rmaCode\":\"RMA1001\"," + + "\"status\":5,\"statusName\":\"已处理\",\"warehouseName\":\"美西1仓\"," + + "\"createTime\":1790568000000}]}")) + .route(EdayunConstants.PATH_RETURN_CANCEL, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":true}")) + .route(EdayunConstants.PATH_BOL_LIST, req -> Responses.ok( + "{\"code\":200,\"data\":{\"bolList\":[{\"bolCode\":\"cp005\"," + + "\"status\":11,\"statusName\":\"已妥投\",\"bolFileUrl\":\"https://oss/b.pdf\"}]}}")) + .route(EdayunConstants.PATH_TRACK, req -> Responses.ok( + "{\"code\":200,\"data\":[{\"trackingNo\":\"1Z111\",\"status\":1," + + "\"carrierName\":\"fedex\",\"onlineTime\":\"2025-08-19 08:17:00\"," + + "\"deliveredTime\":\"2025-08-20 10:00:00\",\"timeZone\":\"GMT-04:00\"," + + "\"trackDetaillVoList\":[{\"recentDescribe\":\"上网\"," + + "\"recentDescribeTime\":1741145821000}]}]}")) + .route(EdayunConstants.PATH_CASE_MARK_PRINT, req -> Responses.ok( + "{\"code\":200,\"msg\":\"操作成功\",\"data\":\"https://oss/case.pdf\"}")) + .route(EdayunConstants.PATH_INBOUND_SKU_DETAIL, req -> Responses.ok( + "{\"total\":1,\"code\":200,\"rows\":[{\"entryCode\":\"REV1\"," + + "\"skuCode\":\"ybtest\",\"forecastQuantity\":10," + + "\"actualCheckedQuantity\":10,\"shelvesQuantity\":10," + + "\"status\":4,\"statusName\":\"已上架\"}]}")); + } + + // ================================================================ 装配 + + /** + * 工厂装配:不联网,只验证 {@code build()} 能把适配器建出来、 + * 能力位与 provider 对得上。 + */ + @Test + void factoryAssemblesAdapter() { + InMemoryWarehouses repo = new InMemoryWarehouses().put(WarehouseAccount.builder() + .warehouseCode(WH) + .provider(WarehouseProvider.EDAYUN.name()) + .providerWarehouseId("2") + .credentialRef("kms://test/edayun") + .timeZone("America/Los_Angeles") + .build()); + WarehouseSdk built = WarehouseSdk.builder() + .warehouseRepository(repo) + .clock(CLOCK) + .register(new EdayunAdapterFactory( + new InMemoryTokenStore(), new InMemoryLockProvider(), CLOCK)) + .build(); + + assertTrue(built.capabilities(WH).supported().contains(WarehouseCapability.OUTBOUND)); + // 能按仓解析到适配器:仓库清单会真的打一次仓方,用假传输层接 + assertNotNull(built.warehouses(WH, conn())); + } + + // ================================================================ 能力位 + + @Test + void declaresAllImplementedCapabilities() { + WarehouseSdk sdk = sdk(transport()); + java.util.EnumSet caps = sdk.capabilities(WH).supported(); + + // 已实现 + assertTrue(caps.contains(WarehouseCapability.PRODUCT), "商品"); + assertTrue(caps.contains(WarehouseCapability.OUTBOUND), "出库"); + assertTrue(caps.contains(WarehouseCapability.INVENTORY_QUERY), "库存"); + assertTrue(caps.contains(WarehouseCapability.INBOUND), "入库"); + assertTrue(caps.contains(WarehouseCapability.RETURN), "退货"); + assertTrue(caps.contains(WarehouseCapability.FEE_SETTLEMENT), "费用"); + assertTrue(caps.contains(WarehouseCapability.FEE_ESTIMATE), "试算"); + assertTrue(caps.contains(WarehouseCapability.BOL), "BOL"); + assertTrue(caps.contains(WarehouseCapability.TRACKING), "轨迹"); + assertTrue(caps.contains(WarehouseCapability.LOGISTICS_PRODUCT), "物流产品"); + assertTrue(caps.contains(WarehouseCapability.CASE_MARK_PRINT), "箱唛"); + assertTrue(caps.contains(WarehouseCapability.DIRECTORY), "基础资料"); + + // 未实现——调了必须抛,不能返回空 + assertTrue(!caps.contains(WarehouseCapability.TRANSFER), "易达云没有调拨"); + assertTrue(!caps.contains(WarehouseCapability.WEBHOOK), "回调文档还没给"); + assertTrue(!caps.contains(WarehouseCapability.RETURN_DISPOSITION), "缺行 id"); + } + + // ================================================================ 场景 1:主数据 + + @Test + void scenario1_masterData() { + WarehouseSdk sdk = sdk(transport()); + + List warehouses = sdk.warehouses(WH, conn()).warehouses(); + assertEquals(1, warehouses.size()); + assertEquals("USLA", warehouses.get(0).warehouseCode()); + assertEquals("2", warehouses.get(0).providerWarehouseId()); + + List carriers = sdk.warehouses(WH, conn()).carrierDirectory(); + assertEquals(1, carriers.size()); + assertEquals("FedEx", carriers.get(0).nameEn()); + assertEquals(1, carriers.get(0).logists().size()); + + List products = sdk.warehouses(WH, conn()).logisticsProducts(null); + // -998 已跳过 + assertEquals(1, products.size()); + assertEquals("133", products.get(0).logisticsProductCode()); + } + + // ================================================================ 场景 2:发货 + + @Test + void scenario2_shipping() { + RecordingTransport transport = transport(); + WarehouseSdk sdk = sdk(transport); + + // 2.1 发货前试算 + List quotes = sdk.warehouses(WH, conn()).fees().estimate( + FeeEstimateQuery.builder() + .lengthCm(new BigDecimal("22")).widthCm(new BigDecimal("22")) + .heightCm(new BigDecimal("22")).weightGrams(new BigDecimal("1000")) + .receiveCountry("US").receivePostal("91761") + .logisticsServiceCode("80") + .build()); + assertEquals(1, quotes.size()); + assertEquals(1, quotes.get(0).carriers().size()); + assertEquals(new BigDecimal("5.315"), quotes.get(0).carriers().get(0).totalRate().amount()); + + // 2.2 建单 + OutboundReceipt receipt = sdk.warehouses(WH, conn()).outbound().create(outbound()); + assertEquals("ORD1001", receipt.providerOrderId()); + + // 2.3 查单 + OutboundOrder order = sdk.warehouses(WH, conn()).outbound() + .get(OutboundRef.ofRequestNo("SO-1")); + assertNotNull(order); + assertEquals("ORD1001", order.providerOrderId()); + + // 2.4 面单 + assertEquals(1, sdk.warehouses(WH, conn()).outbound() + .packages(OutboundRef.ofRequestNo("SO-1")).size()); + + // 2.5 取消前校验 → 免费 + assertEquals(CancelEligibility.FREE, sdk.warehouses(WH, conn()).outbound() + .checkCancel(OutboundRef.ofRequestNo("SO-1"))); + + // 2.6 取消 + CancelResult cancelled = sdk.warehouses(WH, conn()).outbound().cancel( + CancelCommand.builder().outboundRequestNo("SO-1").providerOrderId("ORD1001").build()); + assertTrue(cancelled.cancelled()); + } + + /** 建单幂等:同一个 outboundRequestNo 调两次只发一次请求。 */ + @Test + void scenario2_createIsIdempotent() { + RecordingTransport transport = transport(); + WarehouseSdk sdk = sdk(transport); + + sdk.warehouses(WH, conn()).outbound().create(outbound()); + sdk.warehouses(WH, conn()).outbound().create(outbound()); + + long creates = transport.dataRequests().stream() + .filter(r -> r.url().endsWith(EdayunConstants.PATH_ORDER_CREATE)) + .count(); + assertEquals(1, creates, "第二次应命中幂等,不再调仓"); + } + + private static OutboundCommand outbound() { + return OutboundCommand.builder() + .outboundRequestNo("OB-1") + .orderRef("SO-1") + .warehouseId("2") + .currency("USD") + .salesPlatform(Platform.AMAZON_SC) + .shipTo(ShipTo.builder() + .name("Buyer").phone("+1-555-0100") + .countryCode("US").stateOrProvince("California") + .city("Escondido").addressLine1("1308 E Washington Ave") + .postalCode("92027") + .build()) + .line(OutboundLine.builder() + .lineNo("1").omsSku("ybtest").quantity(1) + .declareValue(Money.of("19.99", "USD")) + .build()) + .build(); + } + + // ================================================================ 场景 3:库存 + + @Test + void scenario3_inventory() { + WarehouseSdk sdk = sdk(transport()); + + List rows = sdk.warehouses(WH, conn()).inventory() + .query(InventoryQuery.builder().sku("ybtest").build()).items(); + + assertEquals(1, rows.size()); + InventorySnapshot s = rows.get(0); + assertEquals("ybtest", s.providerSku()); + assertEquals(4, s.available()); + assertEquals(10, s.onHand()); + assertEquals(20, s.inTransit()); + // safeStock 为 null → -1(统一模型约定) + assertEquals(-1, s.alertQuantity()); + } + + // ================================================================ 场景 4:退货 + + @Test + void scenario4_returns() { + WarehouseSdk sdk = sdk(transport()); + + // 4.1 建退货单(自行退回) + WarehouseReturn created = sdk.warehouses(WH, conn()).returns().create( + ReturnCommand.builder() + .returnRequestNo("RT-1") + .saleOrderNo("SO-1") + .returnTrackingNo("1Z999") + .carrierCode("FedEx") + .warehouseId("2") + .line("ybtest", 1, ReturnDealMethod.WAREHOUSE_CONFIRM) + .build()); + assertEquals("RMA1001", created.providerReturnId()); + + // 4.2 查详情 + WarehouseReturn detail = sdk.warehouses(WH, conn()).returns().get("RMA1001"); + assertNotNull(detail); + assertEquals("RMA1001", detail.providerReturnId()); + assertEquals(1, detail.lines().size()); + + // 4.3 列表 + assertEquals(1, sdk.warehouses(WH, conn()).returns() + .query(ReturnQuery.builder().pageSize(100).build()).size()); + + // 4.4 取消 + assertTrue(sdk.warehouses(WH, conn()).returns().cancel("RMA1001")); + } + + // ================================================================ 场景 5:单据 / 轨迹 / 打印 + + @Test + void scenario5_documentsTrackingAndPrinting() { + WarehouseSdk sdk = sdk(transport()); + + // BOL + List bols = sdk.warehouses(WH, conn()).orderBols("FBA1"); + assertEquals(1, bols.size()); + assertEquals("cp005", bols.get(0).bolCode()); + + // 轨迹:节点 + List events = sdk.warehouses(WH, conn()).track("1Z111"); + assertEquals(1, events.size()); + // 轨迹:运单级,带上网 / 妥投时间 + TrackingInfo info = sdk.warehouses(WH, conn()).trackShipment("1Z111"); + assertNotNull(info.firstOnlineAt()); + assertNotNull(info.deliveredAt()); + + // 箱唛(同步 PDF) + WarehouseLabel label = sdk.warehouses(WH, conn()).printCaseMarks( + CaseMarkPrintCommand.builder() + .paperSize(CaseMarkPaperSize.SIZE_70_30) + .item("ybtest", 1) + .build()); + assertEquals("https://oss/case.pdf", label.url()); + + // 入库单 + assertNotNull(sdk.warehouses(WH, conn()).inbound().get("REV1")); + } + + // ================================================================ 未实现能力 + + @Test + void unimplementedCapabilitiesThrow() { + WarehouseSdk sdk = sdk(transport()); + + // 调拨 + assertThrows(RuntimeException.class, + () -> sdk.warehouses(WH, conn()).getTransfer("T-1")); + // 退货检验后处理(缺行 id) + assertThrows(RuntimeException.class, + () -> sdk.warehouses(WH, conn()).returns().process( + common.ecommerce.warehouse.model.ReturnProcessCommand.builder() + .providerReturnNo("RMA1").lineId(1) + .disposition(common.ecommerce.warehouse.enums + .ReturnProcessDisposition.RESTOCK) + .build())); + } +} 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 2dc2a46..5fc1a69 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 @@ -50,7 +50,6 @@ import common.ecommerce.warehouse.capability.TrackingChangeCapable; import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; -import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.enums.AddressType; import common.ecommerce.warehouse.enums.CancelEligibility; @@ -85,6 +84,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.ReturnCommand; +import common.ecommerce.warehouse.model.ReturnHandle; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.ReturnQuery; import common.ecommerce.warehouse.model.TransferQuery; @@ -94,6 +94,8 @@ 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.capability.WarehouseProduct; +import common.ecommerce.warehouse.model.ProductInfo; import common.ecommerce.warehouse.model.ProductQuery; import common.ecommerce.warehouse.model.OutboundReceipt; import common.ecommerce.warehouse.model.OutboundRef; @@ -367,7 +369,33 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti * *

恒健没有对应的统一模型:这里返回仓方的处理单行,供宿主填写处理方式与回收照片。

*/ - public Page queryReturnHandles( + @Override + public Page queryHandles(WarehouseContext ctx, ReturnQuery query) { + if (query == null) { + query = ReturnQuery.builder().build(); + } + // 统一入口只带游标 / 仓库 / 单号;其余维度恒健这里没有对应口径,给了就拒绝 + if (query.hasCreatedRange() || query.trackingNo() != null + || query.providerSku() != null || !query.statuses().isEmpty() + || query.orderNoType() != null) { + throw validation(ctx, OP_RETURN_HANDLES, + "hengjian return handle list takes returnPlanNo / tracking / warehouse / " + + "handlingStatus only; use queryHandlesAdvanced for those"); + } + List planNos = query.orderNo() == null + ? null : java.util.Collections.singletonList(query.orderNo()); + List warehouseCodes = query.warehouseCode() == null + ? null : java.util.Collections.singletonList(query.warehouseCode()); + return queryHandlesAdvanced(ctx, planNos, null, warehouseCodes, + null, null, null, query.cursor()); + } + + /** + * 多条件分页查退货处理单({@code POST /v1/saleReturn/getReturnPlanHandlePage})。 + * + *

请求是平铺的(无 {@code params} 包裹),与 thirdParty 那两个不同。

+ */ + public Page queryHandlesAdvanced( WarehouseContext ctx, List returnPlanNos, List trackingNos, List warehouseCodes, List handlingStatuses, String createdStart, String createdEnd, String cursor) { @@ -1645,7 +1673,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti *

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

*/ @Override - public Page queryProducts(WarehouseContext ctx, ProductQuery query) { + public Page query(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 = diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java index cd3762a..c967f98 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductQueryMapper.java @@ -3,7 +3,7 @@ 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.ProductInfo; import common.ecommerce.warehouse.model.ProductQuery; import java.math.BigDecimal; @@ -80,17 +80,17 @@ public final class HengjianProductQueryMapper { // ================================================================ 响应 /** 响应 → 分页商品。 */ - public static Page toPage(HengjianProductQueryDtos.PageData data, + 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()); + return Page.last(new ArrayList()); } - List out = new ArrayList(data.data.size()); + List out = new ArrayList(data.data.size()); for (HengjianProductQueryDtos.ProductRow row : data.data) { if (row == null) { continue; } - WarehouseProduct product = toProduct(row); + ProductInfo product = toProduct(row); if (product != null) { out.add(product); } @@ -99,7 +99,7 @@ public final class HengjianProductQueryMapper { } /** 按 {@code total} 判断是否还有下一页。 */ - static Page nextPage(List items, Long totalRaw, + static Page nextPage(List items, Long totalRaw, String requestedCursor, int requestedPageSize) { int page = pageOf(requestedCursor); if (totalRaw == null) { @@ -112,16 +112,13 @@ public final class HengjianProductQueryMapper { return Page.of(items, String.valueOf(page + 1)); } - /** 一条商品 → 统一模型;{@code sku} 缺失时返回 null(跳过脏数据,不整页失败)。 */ - static WarehouseProduct toProduct(HengjianProductQueryDtos.ProductRow row) { + /** 一条商品 → 查询结果模型;{@code sku} 缺失时返回 null(跳过脏数据,不整页失败)。 */ + static ProductInfo toProduct(HengjianProductQueryDtos.ProductRow row) { String sku = trimToNull(row.sku); if (sku == null) { return null; } - WarehouseProduct.Builder b = WarehouseProduct.builder() - // 查询结果允许尺寸 / 重量缺失(用 0 表示),不伪造 - .allowUnknownDimensions(true) - .omsSku(sku) + ProductInfo.Builder b = ProductInfo.builder() .providerSku(sku) .name(firstNonBlank(row.name, row.nameEn, sku)) .nameEn(trimToNull(row.nameEn)) @@ -133,9 +130,9 @@ public final class HengjianProductQueryMapper { .widthCm(doubleOrZero(row.width)) .heightCm(doubleOrZero(row.height)) .weightGrams(doubleOrZero(row.weight)) - .itemLengthCm(doubleOrZero(row.itemLength)) - .itemWidthCm(doubleOrZero(row.itemWidth)) - .itemHeightCm(doubleOrZero(row.itemHeight)) + .itemLengthCm(doubleOrNull(row.itemLength)) + .itemWidthCm(doubleOrNull(row.itemWidth)) + .itemHeightCm(doubleOrNull(row.itemHeight)) // 仓库实测,与申报尺寸分开存 .measuredLengthCm(doubleOrNull(row.measurementLength)) .measuredWidthCm(doubleOrNull(row.measurementWidth)) @@ -149,7 +146,8 @@ public final class HengjianProductQueryMapper { .packedWeightGrams(doubleOrNull(row.packedWeight)) // 保质期 .expirationControl(oneZeroToBoolean(row.expirationControl)) - .expirationDays(intOrNull(row.expirationDate)); + .expirationDays(intOrNull(row.expirationDate)) + .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.HENGJIAN); Integer productType = intOrNull(row.productType); if (productType != null) { @@ -160,11 +158,11 @@ public final class HengjianProductQueryMapper { 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)); + b.declaredValue(Money.of(cost, currency)); } BigDecimal rate = decimalOrNull(row.isInsuranceRate); if (rate != null && currency != null) { diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java index 6d85e09..de14035 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryMapper.java @@ -8,6 +8,7 @@ import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.enums.ReturnProcessDisposition; import common.ecommerce.warehouse.enums.ReturnStatus; import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.ReturnHandle; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.WarehouseAttachment; import common.ecommerce.warehouse.model.WarehouseReturn; @@ -260,16 +261,16 @@ public final class HengjianReturnQueryMapper { } /** 处理单列表 → 统一 Page(每行是一条处理单,不是退货单)。 */ - public static Page toHandlePage( + public static Page toHandlePage( HengjianReturnHandleDtos.HandlePageData data, String cursor, int requestedRows) { if (data == null) { - return Page.last(new ArrayList()); + return Page.last(new ArrayList()); } - List out = new ArrayList(); + List out = new ArrayList(); if (data.content != null) { for (HengjianReturnHandleDtos.HandleRow row : data.content) { if (row != null) { - out.add(row); + out.add(toHandle(row)); } } } @@ -282,6 +283,97 @@ public final class HengjianReturnQueryMapper { return Page.of(out, String.valueOf(next)); } + /** + * 一条处理单 → 统一模型。 + * + *

恒健的处理单行没给「退货编码」({@code returnNo}),那个字段只在 + * 填写处理方式时必填。所以这里 {@code returnNo} 留 null——不拿处理单号冒充, + * 两者语义不同。调用方填处理方式时需要从别处拿到它。

+ */ + static ReturnHandle toHandle(HengjianReturnHandleDtos.HandleRow row) { + ReturnHandle.Builder b = ReturnHandle.builder() + .returnPlanNo(row.returnPlanNo) + .returnHandleNo(trimToNull(row.returnPlanHandleItemsNo)) + .trackingNumber(trimToNull(row.tracking)) + .providerSku(trimToNull(row.erpSku)) + .changeSku(trimToNull(row.changeErpsku)) + .quantity(row.quantity) + .handledQuantity(row.handlingQuantity) + .photosQuantity(row.photosQuantity) + .inventoryType(parseIntOrNull(row.inventoryType)) + .handlingStatus(trimToNull(row.handlingStatus)) + .handlingStatusName(handlingStatusName(row.handlingStatus)) + .primaryHandlingMethod(trimToNull(row.primaryHandlingMethod)) + .sourceNo(firstNonBlank(row.sourceNo, row.openSourceNo)) + .warehouseCode(trimToNull(row.orgWarehouseCode)) + .errorStatus(trimToNull(row.errorStatus)) + .createdAt(parseTime(row.createdAt)) + .updatedAt(parseTime(row.updatedAt)) + .completedAt(parseTime(row.completeAt)) + .sourceProvider(WarehouseProvider.HENGJIAN); + for (String url : urls(row.fileUrlList)) { + b.photoUrl(url); + } + for (String url : urls(row.handleFileUrlList)) { + b.handledPhotoUrl(url); + } + return b.build(); + } + + /** 处理状态码 → 中文名;认不出的返回 null,不猜。 */ + static String handlingStatusName(String raw) { + String v = trimToNull(raw); + if (v == null) { + return null; + } + switch (v) { + case "5": + return "待处理"; + case "10": + return "处理中"; + case "15": + return "已完成"; + case "20": + return "已取消"; + default: + return null; + } + } + + /** 照片字段文档标 string、实际可能是数组:两种都接。 */ + static List urls(Object raw) { + List out = new ArrayList(); + if (raw == null) { + return out; + } + if (raw instanceof List) { + for (Object o : (List) raw) { + String v = trimToNull(o == null ? null : String.valueOf(o)); + if (v != null) { + out.add(v); + } + } + return out; + } + String v = trimToNull(String.valueOf(raw)); + if (v != null) { + out.add(v); + } + return out; + } + + static Integer parseIntOrNull(String raw) { + String v = trimToNull(raw); + if (v == null) { + return null; + } + try { + return Integer.valueOf(v); + } catch (NumberFormatException e) { + return null; + } + } + // ================================================================ 处理方式 /** 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 index 96edc6e..d5287c6 100644 --- 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 @@ -6,7 +6,7 @@ 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.ProductInfo; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.model.ProductQuery; import common.ecommerce.warehouse.sdk.WarehouseConnection; @@ -69,7 +69,7 @@ class HengjianProductQueryTest { @Test void sendsPagingAsString() { RecordingTransport transport = listing(body(ONE_ROW, 1)); - adapter(transport).queryProducts(CTX, ProductQuery.builder().pageSize(50).build()); + adapter(transport).query(CTX, ProductQuery.builder().pageSize(50).build()); String json = transport.lastDataRequest().body(); assertTrue(json.contains("\"pageSize\":\"50\""), json); @@ -79,11 +79,11 @@ class HengjianProductQueryTest { @Test void sendsSkusOnlyWhenGiven() { RecordingTransport absent = listing(body("", 0)); - adapter(absent).queryProducts(CTX, ProductQuery.builder().build()); + adapter(absent).query(CTX, ProductQuery.builder().build()); assertFalse(absent.lastDataRequest().body().contains("\"skus\"")); RecordingTransport present = listing(body("", 0)); - adapter(present).queryProducts(CTX, ProductQuery.builder() + adapter(present).query(CTX, ProductQuery.builder() .providerSkus(java.util.Arrays.asList("A", "B")).build()); String json = present.lastDataRequest().body(); assertTrue(json.contains("\"skus\":[\"A\",\"B\"]"), json); @@ -92,7 +92,7 @@ class HengjianProductQueryTest { @Test void cursorBecomesPageNum() { RecordingTransport transport = listing(body(ONE_ROW, 1000)); - adapter(transport).queryProducts(CTX, ProductQuery.builder().cursor("3").pageSize(10).build()); + adapter(transport).query(CTX, ProductQuery.builder().cursor("3").pageSize(10).build()); assertTrue(transport.lastDataRequest().body().contains("\"pageNum\":\"3\"")); } @@ -100,7 +100,7 @@ class HengjianProductQueryTest { @Test void rejectsPageSizeAboveMax() { assertThrows(IllegalArgumentException.class, - () -> adapter(listing(body("", 0))).queryProducts(CTX, + () -> adapter(listing(body("", 0))).query(CTX, ProductQuery.builder().pageSize(500).build())); } @@ -108,12 +108,12 @@ class HengjianProductQueryTest { @Test void mapsProductFields() { - Page page = adapter(listing(body(ONE_ROW, 1))) - .queryProducts(CTX, ProductQuery.builder().build()); + Page page = adapter(listing(body(ONE_ROW, 1))) + .query(CTX, ProductQuery.builder().build()); assertEquals(1, page.size()); - WarehouseProduct p = page.items().get(0); - assertEquals("SKU-A", p.omsSku()); + ProductInfo p = page.items().get(0); + assertEquals("SKU-A", p.providerSku()); assertEquals("小部件", p.name()); assertEquals("Widget", p.nameEn()); assertEquals("UPC-A", p.barcode()); @@ -134,8 +134,8 @@ class HengjianProductQueryTest { /** 仓库实测尺寸与申报尺寸分开存。 */ @Test void keepsMeasuredDimensionsSeparate() { - WarehouseProduct p = adapter(listing(body(ONE_ROW, 1))) - .queryProducts(CTX, ProductQuery.builder().build()).items().get(0); + ProductInfo p = adapter(listing(body(ONE_ROW, 1))) + .query(CTX, ProductQuery.builder().build()).items().get(0); assertEquals(30.0, p.lengthCm(), 0.001); assertEquals(30.5, p.measuredLengthCm(), 0.001); @@ -147,8 +147,8 @@ class HengjianProductQueryTest { 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); + ProductInfo p = adapter(listing(body(row, 1))) + .query(CTX, ProductQuery.builder().build()).items().get(0); assertEquals(29.0, p.lengthCm(), 0.001, "没有 length 时用 itemLength"); } @@ -156,21 +156,21 @@ class HengjianProductQueryTest { /** total 决定是否还有下一页。 */ @Test void pagingUsesTotal() { - Page more = adapter(listing(body(ONE_ROW, 500))) - .queryProducts(CTX, ProductQuery.builder().pageSize(100).build()); + Page more = adapter(listing(body(ONE_ROW, 500))) + .query(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()); + Page done = adapter(listing(body(ONE_ROW, 1))) + .query(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()); + Page page = adapter(listing(body("", 0))) + .query(CTX, ProductQuery.builder().build()); assertTrue(page.items().isEmpty()); assertFalse(page.hasMore()); } @@ -180,17 +180,17 @@ class HengjianProductQueryTest { void skipsRowsWithoutSku() { String row = "{\"name\":\"无SKU\"}"; assertTrue(adapter(listing(body(row, 1))) - .queryProducts(CTX, ProductQuery.builder().build()).items().isEmpty()); + .query(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); + ProductInfo p = adapter(listing(body(row, 1))) + .query(CTX, ProductQuery.builder().build()).items().get(0); assertEquals(0.0, p.lengthCm(), 0.001); - assertFalse(p.hasDimensions()); + assertEquals(0.0, p.lengthCm(), 0.001); } } diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java index fbbe274..82ffeeb 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianReturnQueryTest.java @@ -9,6 +9,7 @@ import common.ecommerce.shared.testkit.RecordingTransport; import common.ecommerce.shared.testkit.Responses; import common.ecommerce.warehouse.enums.ReturnProcessDisposition; import common.ecommerce.warehouse.enums.ReturnStatus; +import common.ecommerce.warehouse.model.ReturnHandle; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.ReturnQuery; import common.ecommerce.warehouse.model.WarehouseReturn; @@ -229,7 +230,7 @@ class HengjianReturnQueryTest { @Test void handleListPostsFlatBody() { RecordingTransport transport = handling(); - adapter(transport).queryReturnHandles(CTX, + adapter(transport).queryHandlesAdvanced(CTX, Collections.singletonList("RC1"), null, null, Collections.singletonList(15), null, null, null); @@ -243,19 +244,18 @@ class HengjianReturnQueryTest { @Test void handleListMapsRows() { - Page page = - adapter(handling()).queryReturnHandles(CTX, - Collections.singletonList("RC1"), null, null, null, null, null, null); + Page page = + adapter(handling()).queryHandlesAdvanced(CTX, Collections.singletonList("RC1"), null, null, null, null, null, null); assertEquals(1, page.size()); assertTrue(page.hasMore(), "last=false 应给出下一页"); assertEquals("2", page.nextCursor()); - HengjianReturnHandleDtos.HandleRow row = page.items().get(0); - assertEquals("RC25081300010", row.returnPlanNo); - assertEquals("RP25081400001", row.returnPlanHandleItemsNo); - assertEquals("15", row.handlingStatus); - assertEquals("203", row.primaryHandlingMethod); - assertEquals("C-2077-BU", row.changeErpsku); + ReturnHandle row = page.items().get(0); + assertEquals("RC25081300010", row.returnPlanNo()); + assertEquals("RP25081400001", row.returnHandleNo()); + assertEquals("15", row.handlingStatus()); + assertEquals("203", row.primaryHandlingMethod()); + assertEquals("C-2077-BU", row.changeSku()); } // ================================================================ 处理方式 diff --git a/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseCallObserverTest.java b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseCallObserverTest.java new file mode 100644 index 0000000..4b9a375 --- /dev/null +++ b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseCallObserverTest.java @@ -0,0 +1,213 @@ +package common.ecommerce.warehouse.sdk; + +import common.ecommerce.shared.audit.CallObserver; +import common.ecommerce.shared.audit.CallRecord; +import common.ecommerce.shared.testkit.InMemoryIdempotencyStore; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.enums.LabelMode; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.testkit.FakeWarehouseAdapter; +import common.ecommerce.warehouse.testkit.InMemoryWarehouses; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.ArrayList; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 门面操作日志({@code CallObserver})契约测试。 + * + *

这里验证的是「新仓接入后操作日志默认就通」这个承诺: + * 适配器只写协议转换、不自己造门面,宿主注入 {@code callObserver} 之后 + * 每个门面调用都必然产生一条 {@link CallRecord}。

+ */ +class WarehouseCallObserverTest { + + private static final Instant T0 = Instant.parse("2026-11-09T00:00:00Z"); + private static final Clock CLOCK = Clock.fixed(T0, ZoneOffset.UTC); + private static final String WH = "YQN-RF_NY_US"; + + private RecordingObserver observer; + private WarehouseSdk sdk; + + @BeforeEach + void setUp() { + observer = new RecordingObserver(); + InMemoryWarehouses repo = new InMemoryWarehouses() + .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)); + sdk = WarehouseSdk.builder() + .warehouseRepository(repo) + .idempotencyStore(new InMemoryIdempotencyStore()) + .clock(CLOCK) + .register(new FakeWarehouseAdapter()) + .callObserver(observer) + .build(); + } + + private static OutboundCommand cmd(String requestNo) { + return OutboundCommand.builder() + .outboundRequestNo(requestNo) + .orderRef("SO-1") + .labelMode(LabelMode.WAREHOUSE_LABEL) + .salesPlatform(common.ecommerce.shared.model.Platform.WALMART_SC) + .shipTo(ShipTo.builder() + .name("B") // 测试数据 + .countryCode("US") + .city("New York") + .addressLine1("1 Test St") + .build()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku("DM00001") + .quantity(1) + .declareName("Sample") + .declareValue(Money.of("10.00", "USD")) + .build()) + .build(); + } + + /** 成功调用要记一条,operation / provider / 结果都要有。 */ + @Test + void recordsSuccessfulCall() { + sdk.warehouses(WH, conn()).outbound().create(cmd("OB-1")); + + CallRecord record = observer.lastOf("warehouse.outbound.create"); + assertEquals(WarehouseProvider.CUSTOM.name(), record.provider()); + assertNotNull(record.outcome()); + assertEquals("OB-1", String.valueOf(record.params().get("outboundRequestNo"))); + } + + /** 失败也要记:异常不能把日志吞掉。 */ + @Test + void recordsFailedCall() { + InMemoryWarehouses repo = new InMemoryWarehouses() + .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM)); + WarehouseSdk blocking = WarehouseSdk.builder() + .warehouseRepository(repo) + .idempotencyStore(new InMemoryIdempotencyStore()) + .clock(CLOCK) + .register(new FakeWarehouseAdapter().blockCancel()) + .callObserver(observer) + .build(); + assertThrows(RuntimeException.class, + () -> blocking.warehouses(WH, conn()).outbound() + .cancel(common.ecommerce.warehouse.model.CancelCommand.builder() + .outboundRequestNo("OB-X") + .acceptCharge(false) + .build())); + + CallRecord record = observer.lastOf("warehouse.outbound.cancel"); + assertNotNull(record.errorType(), "失败记录要带异常类型"); + } + + /** 只读方法同样记。 */ + @Test + void recordsReadOnlyCall() { + sdk.warehouses(WH, conn()).outbound().query( + common.ecommerce.warehouse.model.OutboundQuery.builder().build()); + + assertNotNull(observer.lastOf("warehouse.outbound.query")); + } + + /** 同一 SDK 多次调用各记一条,不合并。 */ + @Test + void recordsOnePerCall() { + WarehouseOperations ops = sdk.warehouses(WH, conn()); + ops.outbound().create(cmd("OB-1")); + ops.outbound().get(common.ecommerce.warehouse.model.OutboundRef.ofRequestNo("OB-1")); + + assertNotNull(observer.lastOf("warehouse.outbound.create")); + assertNotNull(observer.lastOf("warehouse.outbound.get")); + assertTrue(observer.records.size() >= 2, "每次门面调用至少一条记录"); + } + + /** 没注入 observer 时什么都不记,但业务照常跑——不能因为没日志就抛。 */ + @Test + void noObserverMeansNoRecordsButStillWorks() { + WarehouseSdk quiet = WarehouseSdk.builder() + .warehouseRepository(new InMemoryWarehouses() + .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM))) + .idempotencyStore(new InMemoryIdempotencyStore()) + .clock(CLOCK) + .register(new FakeWarehouseAdapter()) + .build(); + + assertNotNull(quiet.warehouses(WH, conn()).outbound().create(cmd("OB-1"))); + } + + /** observer 自己抛异常要被吞掉,不能影响业务返回值。 */ + @Test + void observerFailureDoesNotBreakBusinessCall() { + WarehouseSdk broken = WarehouseSdk.builder() + .warehouseRepository(new InMemoryWarehouses() + .put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM))) + .idempotencyStore(new InMemoryIdempotencyStore()) + .clock(CLOCK) + .register(new FakeWarehouseAdapter()) + .callObserver(record -> { + throw new IllegalStateException("observer boom"); + }) + .build(); + + assertNotNull(broken.warehouses(WH, conn()).outbound().create(cmd("OB-1"))); + } + + /** 参数摘要里不能出现密钥类字段。 */ + @Test + void paramsDoNotLeakSecrets() { + sdk.warehouses(WH, conn()).outbound().create(cmd("OB-1")); + + for (String key : observer.lastOf("warehouse.outbound.create").params().keySet()) { + assertFalse(key.toLowerCase().contains("secret"), "params 不应含密钥字段: " + key); + assertFalse(key.toLowerCase().contains("token"), "params 不应含 token 字段: " + key); + } + } + + private static WarehouseConnection conn() { + return WarehouseConnection.of("https://example.test", + ChannelSecret.builder().appSecret("s").build()); + } + + /** 记录型观察者。 */ + private static final class RecordingObserver implements CallObserver { + private final List records = new ArrayList(); + + @Override + public void onCall(CallRecord record) { + records.add(record); + } + + /** 找指定 operation 的记录(写操作前面还会有幂等审计记录,所以不能只看条数)。 */ + CallRecord lastOf(String operation) { + CallRecord found = null; + for (CallRecord record : records) { + if (operation.equals(record.operation())) { + found = record; + } + } + assertNotNull(found, "没有 " + operation + " 的记录,实际有 " + operations()); + return found; + } + + List operations() { + List out = new ArrayList(); + for (CallRecord record : records) { + out.add(record.operation()); + } + return out; + } + } +} 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 70ec33d..6185e7f 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.ProductInfo; import common.ecommerce.warehouse.model.ProductQuery; import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundQuery; @@ -228,7 +229,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa * 映射时直接用厘米那套,不做二次换算。

*/ @Override - public Page queryProducts(WarehouseContext ctx, ProductQuery query) { + public Page query(WarehouseContext ctx, ProductQuery query) { AccessToken token = login(ctx); Map params = XincangProductQueryMapper.toParams(query); String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token, 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 index 3f72b7f..7b63664 100644 --- 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 @@ -2,7 +2,8 @@ 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.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.ProductInfo; import common.ecommerce.warehouse.model.ProductQuery; import common.ecommerce.xincang.XincangConstants; import common.ecommerce.xincang.dto.XincangProductListDtos; @@ -97,17 +98,17 @@ public final class XincangProductQueryMapper { // ================================================================ 响应 /** 响应 → 分页商品。 */ - public static Page toPage(XincangProductListDtos.ProductListResult rst, + 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()); + return Page.last(new ArrayList()); } - List out = new ArrayList(rst.data.size()); + List out = new ArrayList(rst.data.size()); for (XincangProductListDtos.ProductItem item : rst.data) { if (item == null) { continue; } - WarehouseProduct product = toProduct(item); + ProductInfo product = toProduct(item); if (product != null) { out.add(product); } @@ -121,7 +122,7 @@ public final class XincangProductQueryMapper { *

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

*/ - static Page nextPage(List items, String totalRaw, + static Page nextPage(List items, String totalRaw, String requestedCursor, int requestedLimit) { int page = pageOf(requestedCursor); Integer total = intOrNull(totalRaw); @@ -142,15 +143,12 @@ public final class XincangProductQueryMapper { *

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

*/ - static WarehouseProduct toProduct(XincangProductListDtos.ProductItem item) { + static ProductInfo toProduct(XincangProductListDtos.ProductItem item) { String sku = trimToNull(item.productNo); if (sku == null) { return null; } - WarehouseProduct.Builder b = WarehouseProduct.builder() - // 查询结果允许尺寸 / 重量为 0(仓方没给),不伪造最小值 - .allowUnknownDimensions(true) - .omsSku(sku) + ProductInfo.Builder b = ProductInfo.builder() .providerSku(sku) .name(firstNonBlank(item.chnName, item.enName, sku)) .nameEn(trimToNull(item.enName)) @@ -164,12 +162,12 @@ public final class XincangProductQueryMapper { // 查询结果才有 .providerProductId(trimToNull(item.id)) .rawState(trimToNull(item.state)) - .stateName(trimToNull(item.stateName)) + .rawStatusName(trimToNull(item.stateName)) .volumeCm3(decimalOrNull(item.volumeCm)) .createdAt(XincangOrderDetailMapper.parseTime(item.gmtCreate)) .updatedAt(XincangOrderDetailMapper.parseTime(item.gmtModify)) .imageUrl(trimToNull(item.imageUrl)) - .remark(null); + .sourceProvider(WarehouseProvider.XINCANG); // packing_rate → 装箱数量 Integer packing = intOrNull(item.packingRate); @@ -181,7 +179,6 @@ public final class XincangProductQueryMapper { if (amount != null) { b.declaredValue(Money.of(amount, "USD")); } - // 统一模型没有「长度/重量单位」以外的差异;外箱尺寸信仓不提供,保持 null return b.build(); } 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 index 61b69a1..b707c96 100644 --- 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 @@ -6,7 +6,7 @@ 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.ProductInfo; import common.ecommerce.warehouse.model.ProductQuery; import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseContext; @@ -94,7 +94,7 @@ class XincangProductQueryTest { @Test void sendsMandatoryQueryParams() { RecordingTransport transport = productListing(listBody(ONE_ROW, "1")); - adapter(transport).queryProducts(ctx(), ProductQuery.builder().build()); + adapter(transport).query(ctx(), ProductQuery.builder().build()); String url = productListUrl(transport); // 四项必填 @@ -108,7 +108,7 @@ class XincangProductQueryTest { @Test void alwaysQueriesFormalState() { RecordingTransport transport = productListing(listBody("", "0")); - adapter(transport).queryProducts(ctx(), ProductQuery.builder().build()); + adapter(transport).query(ctx(), ProductQuery.builder().build()); assertTrue(productListUrl(transport).contains("state=1")); } @@ -118,7 +118,7 @@ class XincangProductQueryTest { void rejectsMultipleSkus() { RecordingTransport transport = productListing(listBody("", "0")); IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, - () -> adapter(transport).queryProducts(ctx(), ProductQuery.builder() + () -> adapter(transport).query(ctx(), ProductQuery.builder() .providerSkus(java.util.Arrays.asList("A", "B")).build())); assertTrue(ex.getMessage().contains("single sku"), ex.getMessage()); } @@ -126,7 +126,7 @@ class XincangProductQueryTest { @Test void sendsSingleSkuAsKey() { RecordingTransport transport = productListing(listBody(ONE_ROW, "1")); - adapter(transport).queryProducts(ctx(), ProductQuery.builder().providerSku("SKU-A").build()); + adapter(transport).query(ctx(), ProductQuery.builder().providerSku("SKU-A").build()); assertTrue(productListUrl(transport).contains("key=SKU-A")); } @@ -135,19 +135,19 @@ class XincangProductQueryTest { void rejectsLimitAboveMax() { RecordingTransport transport = productListing(listBody("", "0")); assertThrows(IllegalArgumentException.class, - () -> adapter(transport).queryProducts(ctx(), ProductQuery.builder().pageSize(500).build())); + () -> adapter(transport).query(ctx(), ProductQuery.builder().pageSize(500).build())); } // ---------------------------------------------------------------- 响应 @Test void mapsProductFields() { - Page page = adapter(productListing(listBody(ONE_ROW, "1"))) - .queryProducts(ctx(), ProductQuery.builder().build()); + Page page = adapter(productListing(listBody(ONE_ROW, "1"))) + .query(ctx(), ProductQuery.builder().build()); assertEquals(1, page.size()); - WarehouseProduct p = page.items().get(0); - assertEquals("SKU-A", p.omsSku()); + ProductInfo p = page.items().get(0); + assertEquals("SKU-A", p.providerSku()); assertEquals("SKU-A", p.providerSku()); assertEquals("小部件", p.name()); assertEquals("Widget", p.nameEn()); @@ -163,7 +163,7 @@ class XincangProductQueryTest { assertEquals(0, p.declaredValue().amount().compareTo(new java.math.BigDecimal("12.34"))); assertEquals("9001", p.providerProductId()); assertEquals("1", p.rawState()); - assertEquals("正式产品", p.stateName()); + assertEquals("正式产品", p.rawStatusName()); assertEquals("https://oss/x.png", p.imageUrl()); // 北京时间 → UTC:10:00 北京 = 02:00 UTC assertEquals(Instant.parse("2026-11-01T02:00:00Z"), p.createdAt()); @@ -172,21 +172,21 @@ class XincangProductQueryTest { /** count 决定是否还有下一页,不看本页是否满。 */ @Test void pagingUsesCount() { - Page more = adapter(productListing(listBody(ONE_ROW, "50"))) - .queryProducts(ctx(), ProductQuery.builder().pageSize(20).build()); + Page more = adapter(productListing(listBody(ONE_ROW, "50"))) + .query(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()); + Page done = adapter(productListing(listBody(ONE_ROW, "1"))) + .query(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()); + Page page = adapter(productListing(listBody("", "0"))) + .query(ctx(), ProductQuery.builder().build()); assertTrue(page.items().isEmpty()); assertFalse(page.hasMore()); } @@ -195,20 +195,20 @@ class XincangProductQueryTest { @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); + ProductInfo p = adapter(productListing(listBody(row, "1"))) + .query(ctx(), ProductQuery.builder().build()).items().get(0); assertEquals(0.0, p.lengthCm(), 0.001); assertEquals(0.0, p.weightGrams(), 0.001); - assertFalse(p.hasDimensions()); + assertEquals(0.0, p.lengthCm(), 0.001); } /** 缺 product_no 的脏数据跳过,不让整页失败。 */ @Test void skipsRowsWithoutSku() { String row = "{\"id\":\"1\",\"chn_name\":\"无 SKU\"}"; - Page page = adapter(productListing(listBody(row, "1"))) - .queryProducts(ctx(), ProductQuery.builder().build()); + Page page = adapter(productListing(listBody(row, "1"))) + .query(ctx(), ProductQuery.builder().build()); assertTrue(page.items().isEmpty()); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index cd27445..031d42d 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -26,6 +26,9 @@ public final class YqnConstants { /** 商品创建 / 编辑(V1 推荐版)。 */ public static final String PATH_PRODUCT_SAVE = "/v1/product/save"; + + /** 批量查询 SKU 分页(API 113)。页码从 0 开始。 */ + public static final String PATH_PRODUCT_FIND_PAGE = "/v1/product/findPage"; /** 创建销售订单(API 123)。 */ public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create"; /** 订单详情(API 128):按来源单号查完整订单。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 9553651..02e5749 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -13,6 +13,7 @@ import common.ecommerce.yqn.dto.YqnInventoryDtos; import common.ecommerce.yqn.dto.YqnLogisticsProductDtos; import common.ecommerce.yqn.dto.YqnOrderDetailDtos; import common.ecommerce.yqn.dto.YqnProductDtos; +import common.ecommerce.yqn.dto.YqnProductQueryDtos; import common.ecommerce.yqn.dto.YqnReturnProcessDtos; import common.ecommerce.yqn.dto.YqnSaleReturnPlanDtos; import common.ecommerce.yqn.dto.YqnSkuLabelDtos; @@ -170,6 +171,35 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl json.stringAt(raw, "message")); } + /** + * 批量查询仓侧商品资料(API 113,{@code /v1/product/findPage})。 + * + *

入参 SKU 是仓侧 SKU,即建档时下发到 {@code sku} 字段的那串 + * ({@link YqnProductMapper#skuOf}),不一定等于 OMS SKU。 + * 运去哪这个接口没有条码 / 时间窗过滤,传了要本地拒绝而不是静默忽略。

+ * + *

页码从 0 开始——游标就是页码字符串,不做 ±1 换算。

+ */ + @Override + public common.ecommerce.shared.support.Page< + common.ecommerce.warehouse.model.ProductInfo> query( + WarehouseContext ctx, common.ecommerce.warehouse.model.ProductQuery query) { + if (query.barcode() != null) { + throw new IllegalArgumentException( + "yqn product query does not support barcode filter"); + } + if (query.hasCreatedRange()) { + throw new IllegalArgumentException( + "yqn product query does not support created time range"); + } + YqnProductQueryDtos.FindPageRequest body = YqnProductQueryMapper.toRequest(query); + String raw = execute(ctx, YqnConstants.PATH_PRODUCT_FIND_PAGE, body, + "warehouse.product.query"); + YqnProductQueryDtos.FindPageResponse resp = + json.fromJson(raw, YqnProductQueryDtos.FindPageResponse.class); + return YqnProductQueryMapper.toPage(resp); + } + // ------------------------------------------------------------------ 出库 @Override diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java index 4386fe5..70ab650 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java @@ -140,6 +140,8 @@ public final class YqnOutboundMapper { new ArrayList(lines.size()); for (OutboundLine line : lines) { YqnCreateOrderDtos.CreateOrderRequest.ProductItem item = new YqnCreateOrderDtos.CreateOrderRequest.ProductItem(); + // 必须与建档时下发给仓方的 sku 一致(providerSku 优先,见 YqnProductMapper.skuOf)。 + // 传 OMS SKU 而建档时用的是 providerSku 的话,仓方会报 SKU 不存在。 item.sku = line.providerSku() != null ? line.providerSku() : line.omsSku(); item.quantity = line.quantity(); item.lineNo = line.lineNo(); diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java index 0f261cb..a08c189 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java @@ -85,7 +85,25 @@ public final class YqnProductMapper { return req; } - /** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */ + /** + * 下发到运去哪 {@code sku} 字段的值——整条链路都以这个为准。 + * + *

规则:{@code providerSku} 优先,为空才回退 {@code omsSku}。

+ * + *

为什么这条规则要写在建档这里:运去哪把 {@code sku} 当唯一键落库, + * 之后查商品(API 113 {@code skuList})、建出库单(商品行 {@code sku})、 + * 查库存({@code skuList})全都按这串匹配。所以:

+ *
    + *
  • 宿主给了 {@code providerSku}(如 {@code AP0000X9US0010601})→ 仓方库里存它, + * 之后所有查询 / 下单都必须传它,不等于 OMS SKU
  • + *
  • 宿主没给(如 {@code ybtest})→ 仓方库里存的就是 OMS SKU,两者同名
  • + *
+ * + *

SDK 不做 OMS→仓侧 SKU 的转换:映射表在宿主手里(供应商编码规则、 + * 按仓不同的前缀),SDK 猜不出来;静默转换会拿回空结果或错商品,比报错更难发现。

+ * + *

出库行同理,见 {@code YqnOutboundMapper}({@code providerSku} 优先)。

+ */ public static String skuOf(WarehouseProduct product) { String providerSku = product.providerSku(); if (providerSku != null && !providerSku.trim().isEmpty()) { diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java new file mode 100644 index 0000000..77aa590 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java @@ -0,0 +1,175 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.shared.support.Money; +import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.ProductInfo; +import common.ecommerce.warehouse.model.ProductQuery; +import common.ecommerce.yqn.dto.YqnProductQueryDtos; + +import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 运去哪商品查询映射(API 113,{@code /v1/product/findPage})。 + * + *

页码从 0 开始——统一模型的游标语义是「下一页页码」, + * 这里用字符串页码原样透传,不做 ±1 换算,免得调用方和仓方口径对不上。

+ */ +public final class YqnProductQueryMapper { + + /** 单页上限(文档:默认 100、最大 100)。 */ + static final int MAX_PAGE_SIZE = 100; + + /** 一次最多查多少个 SKU(文档:最大 100)。 */ + static final int MAX_SKUS = 100; + + private YqnProductQueryMapper() { + } + + /** 统一查询条件 → 仓方请求。 */ + public static YqnProductQueryDtos.FindPageRequest toRequest(ProductQuery query) { + YqnProductQueryDtos.FindPageRequest req = new YqnProductQueryDtos.FindPageRequest(); + if (!query.providerSkus().isEmpty()) { + if (query.providerSkus().size() > MAX_SKUS) { + throw new IllegalArgumentException( + "yqn product query accepts at most " + MAX_SKUS + " skus, got " + + query.providerSkus().size()); + } + req.skuList = new ArrayList(query.providerSkus()); + } + req.pageSize = pageSize(query.pageSize()); + req.pageNum = pageNum(query.cursor()); + return req; + } + + /** 每页条数:默认 100、上限 100。 */ + static int pageSize(int requested) { + if (requested <= 0) { + return MAX_PAGE_SIZE; + } + return Math.min(requested, MAX_PAGE_SIZE); + } + + /** 游标 → 页码;从 0 开始,空游标即第 0 页。 */ + static int pageNum(String cursor) { + if (cursor == null || cursor.trim().isEmpty()) { + return 0; + } + try { + int v = Integer.parseInt(cursor.trim()); + return Math.max(v, 0); + } catch (NumberFormatException e) { + return 0; + } + } + + /** 响应 → 分页结果。 */ + public static Page toPage(YqnProductQueryDtos.FindPageResponse response) { + if (response == null || response.data == null + || response.data.content == null || response.data.content.isEmpty()) { + return Page.empty(); + } + List out = new ArrayList(response.data.content.size()); + for (YqnProductQueryDtos.ProductRow row : response.data.content) { + ProductInfo info = toInfo(row); + if (info != null) { + out.add(info); + } + } + return Page.of(out, nextCursor(response.data)); + } + + /** + * 下一页游标。 + * + *

优先用 {@code last}(仓方明确给了是否末页);缺失时用 + * {@code number+1 < totalPages} 推断。两者都给不出时按「本页是否满页」兜底。

+ */ + static String nextCursor(YqnProductQueryDtos.ProductPage page) { + if (page == null) { + return null; + } + if (page.last != null) { + if (page.last) { + return null; + } + int current = page.number == null ? 0 : page.number; + return String.valueOf(current + 1); + } + if (page.number != null && page.totalPages != null) { + return page.number + 1 < page.totalPages + ? String.valueOf(page.number + 1) : null; + } + if (page.size != null && page.numberOfElements != null) { + return page.numberOfElements < page.size + ? null : String.valueOf((page.number == null ? 0 : page.number) + 1); + } + return null; + } + + /** 一行 → 统一商品资料;没有 SKU 的行跳过。 */ + static ProductInfo toInfo(YqnProductQueryDtos.ProductRow row) { + if (row == null || row.sku == null || row.sku.trim().isEmpty()) { + return null; + } + ProductInfo.Builder b = ProductInfo.builder() + .sourceProvider(WarehouseProvider.YQN) + .providerSku(row.sku.trim()) + .customItemNo(trimToNull(row.customItemNo)) + .barcode(trimToNull(row.upc)) + .name(trimToNull(row.name)) + .nameEn(trimToNull(row.nameEn)) + .description(trimToNull(row.description)) + // 文档:1 成品 / 2 配件 / 3 耗材;未给保持 -1 + .productType(row.productType == null ? -1 : row.productType) + .lengthCm(numberOf(row.length)) + .widthCm(numberOf(row.width)) + .heightCm(numberOf(row.height)) + .weightGrams(numberOf(row.weight)) + .itemLengthCm(row.itemLength) + .itemWidthCm(row.itemWidth) + .itemHeightCm(row.itemHeight) + .packedQuantity(row.packedQty) + .packedLengthCm(row.packedLength) + .packedWidthCm(row.packedWidth) + .packedHeightCm(row.packedHeight) + .packedWeightGrams(row.packedWeight) + .requireSn(flagOf(row.isRequireSn)) + .remark(trimToNull(row.remark)); + + // 成本:文档标 integer,但货币是另一列;没有币种时不造 Money + if (row.cost != null && trimToNull(row.currency) != null) { + b.cost(Money.of(java.math.BigDecimal.valueOf(row.cost), row.currency.trim())); + } + return b.build(); + } + + /** + * 文档把 {@code isRequireSn} 标成 string,真机可能是数字。 + * 统一按「是不是 1 / "1" / true」判,认不出返回 null(不猜)。 + */ + static Boolean flagOf(String raw) { + if (raw == null) { + return null; + } + String v = raw.trim(); + if ("1".equals(v) || "true".equalsIgnoreCase(v) || "Y".equalsIgnoreCase(v)) { + return Boolean.TRUE; + } + if ("0".equals(v) || "false".equalsIgnoreCase(v) || "N".equalsIgnoreCase(v)) { + return Boolean.FALSE; + } + return null; + } + + private static double numberOf(Double v) { + return v == null ? 0 : v; + } + + private static String trimToNull(String v) { + return v == null || v.trim().isEmpty() ? null : v.trim(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java new file mode 100644 index 0000000..bce2159 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java @@ -0,0 +1,112 @@ +package common.ecommerce.yqn.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.util.List; + +/** + * 运去哪报文结构:批量查询 SKU 分页(API 113,{@code /v1/product/findPage})。 + * + *

一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。

+ * + *

页码从 0 开始(文档:「起始页为从0开始」),与其它分页接口不同。 + * {@code pageSize} 默认 100、最大 100。

+ */ +public final class YqnProductQueryDtos { + + private YqnProductQueryDtos() { + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class FindPageRequest { + + /** 仓侧 SKU 列表,最大 100 个。 */ + public List skuList; + /** 每页大小,默认 100、最大 100。 */ + public Integer pageSize; + /** 页码,从 0 开始。 */ + public Integer pageNum; + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class FindPageResponse { + public Integer code; + public String message; + public Integer statusCode; + public Integer status; + public ProductPage data; + } + + /** Spring Data 风格的分页载荷。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ProductPage { + public Pageable pageable; + public Integer totalElements; + public Integer totalPages; + public Boolean last; + public Boolean first; + public Integer numberOfElements; + public Integer size; + public Integer number; + public Boolean empty; + public List content; + } + + /** 分页元信息(只取用得到的几个)。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class Pageable { + public Integer pageNumber; + public Integer pageSize; + public Integer offset; + public Boolean paged; + public Boolean unpaged; + } + + /** 一行商品。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ProductRow { + public String sku; + public String customItemNo; + public String upc; + /** 1 成品 / 2 配件 / 3 耗材。 */ + public Integer productType; + public String name; + public String nameEn; + public String description; + + /** 整箱尺寸(cm)与重量(g)。 */ + public Double length; + public Double width; + public Double height; + public Double weight; + + /** 单品尺寸(cm)。 */ + public Double itemLength; + public Double itemWidth; + public Double itemHeight; + + /** 装箱数量 / 外箱尺寸重量。 */ + public Integer packedQty; + public Double packedLength; + public Double packedWidth; + public Double packedHeight; + public Double packedWeight; + + public Double cost; + public String currency; + public String remark; + + /** 是否需要 SN;文档标 string({@code "0"} / {@code "1"})。 */ + public String isRequireSn; + + /** 商品形态。 */ + public Integer saleType; + public String parentErpsku; + public Integer standardQuantity; + + public String customName; + public String customNameEn; + /** 是否启用。 */ + public Integer enable; + } +} diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java new file mode 100644 index 0000000..7286e17 --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java @@ -0,0 +1,190 @@ +package common.ecommerce.yqn.adapter; + +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.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.ProductInfo; +import common.ecommerce.warehouse.model.ProductQuery; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.yqn.YqnConstants; +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; + +/** + * 商品查询(API 113,{@code /v1/product/findPage})映射。 + * + *

重点:页码从 0 开始、单页上限 100、{@code last} 优先判断翻页。

+ */ +class YqnProductQueryTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC); + + private static WarehouseContext ctx() { + return WarehouseContext.of("YQN-WH", WarehouseProvider.YQN, "RF_NY_US", + WarehouseConnection.of(YqnConstants.PR_BASE_URL, + ChannelSecret.builder().appSecret("key-1").build()), + "req-product-query", CLOCK); + } + + private static RecordingTransport stub(String body) { + return RecordingTransport.create() + .route(YqnConstants.PATH_PRODUCT_FIND_PAGE, req -> Responses.ok(body)); + } + + // ------------------------------------------------------------ 请求 + + /** 游标为空 → 第 0 页(不是第 1 页)。 */ + @Test + void emptyCursorMeansPageZero() { + assertEquals(0, YqnProductQueryMapper.pageNum(null)); + assertEquals(0, YqnProductQueryMapper.pageNum(" ")); + assertEquals(0, YqnProductQueryMapper.pageNum("abc")); + assertEquals(3, YqnProductQueryMapper.pageNum("3")); + // 负数归 0 + assertEquals(0, YqnProductQueryMapper.pageNum("-1")); + } + + /** 单页上限 100。 */ + @Test + void pageSizeCappedAt100() { + assertEquals(100, YqnProductQueryMapper.pageSize(0)); + assertEquals(100, YqnProductQueryMapper.pageSize(500)); + assertEquals(50, YqnProductQueryMapper.pageSize(50)); + } + + @Test + void mapsSkusAndPaging() { + common.ecommerce.yqn.dto.YqnProductQueryDtos.FindPageRequest req = + YqnProductQueryMapper.toRequest( + ProductQuery.builder().providerSku("SKU-1").providerSku("SKU-2") + .pageSize(20).cursor("2").build()); + + assertEquals(java.util.Arrays.asList("SKU-1", "SKU-2"), req.skuList); + assertEquals(Integer.valueOf(20), req.pageSize); + assertEquals(Integer.valueOf(2), req.pageNum); + } + + @Test + void moreThan100SkusRejected() { + ProductQuery.Builder b = ProductQuery.builder(); + for (int i = 0; i < 101; i++) { + b.providerSku("SKU-" + i); + } + assertThrows(IllegalArgumentException.class, () -> b.build()); + } + + /** 运去哪这个接口没有条码 / 时间窗过滤,传了要本地拒绝。 */ + @Test + void unsupportedFiltersAreRejected() { + assertThrows(IllegalArgumentException.class, + () -> new YqnAdapter(stub("{}"), new JacksonJsonCodec()).query(ctx(), + ProductQuery.builder().barcode("UPC1").build())); + + assertThrows(IllegalArgumentException.class, + () -> new YqnAdapter(stub("{}"), new JacksonJsonCodec()).query(ctx(), + ProductQuery.builder() + .createdAfter(Instant.parse("2026-01-01T00:00:00Z")) + .createdBefore(Instant.parse("2026-02-01T00:00:00Z")) + .build())); + } + + // ------------------------------------------------------------ 响应 + + private static String pageBody(boolean last, int number, Integer totalPages) { + return "{\"code\":200,\"message\":\"ok\",\"data\":{" + + "\"pageable\":{\"pageNumber\":" + number + ",\"pageSize\":100}," + + "\"numberOfElements\":1,\"size\":100,\"number\":" + number + "," + + "\"last\":" + last + "," + + (totalPages == null ? "" : "\"totalPages\":" + totalPages + ",") + + "\"content\":[{\"sku\":\"SKU-1\",\"name\":\"商品1\",\"nameEn\":\"P1\"," + + "\"upc\":\"UPC1\",\"productType\":1,\"length\":10,\"width\":8,\"height\":6," + + "\"weight\":500,\"packedQty\":12,\"isRequireSn\":\"0\"," + + "\"cost\":9.5,\"currency\":\"USD\",\"enable\":1}]}}"; + } + + @Test + void mapsRow() { + Page page = YqnProductQueryMapper.toPage( + new JacksonJsonCodec().fromJson(pageBody(true, 0, null), + common.ecommerce.yqn.dto.YqnProductQueryDtos.FindPageResponse.class)); + + assertEquals(1, page.size()); + ProductInfo p = page.items().get(0); + assertEquals("SKU-1", p.providerSku()); + assertEquals("商品1", p.name()); + assertEquals("UPC1", p.barcode()); + assertEquals(1, p.productType()); + assertEquals(10.0, p.lengthCm()); + assertEquals(500.0, p.weightGrams()); + assertEquals(Integer.valueOf(12), p.packedQuantity()); + assertEquals(Boolean.FALSE, p.requireSn()); + assertEquals(WarehouseProvider.YQN, p.sourceProvider()); + // 成本带币种才成 Money + assertEquals(0, new java.math.BigDecimal("9.5").compareTo(p.cost().amount())); + assertEquals("USD", p.cost().currencyCode()); + assertFalse(page.hasMore()); + } + + /** {@code last=false} → 游标 = number + 1。 */ + @Test + void nextCursorUsesLast() { + assertEquals("1", YqnProductQueryMapper.nextCursor(page(0, false, null))); + assertNull(YqnProductQueryMapper.nextCursor(page(3, true, null))); + } + + /** {@code last} 缺失时用 number + 1 < totalPages 推断。 */ + @Test + void nextCursorFallsBackToTotalPages() { + assertEquals("2", YqnProductQueryMapper.nextCursor(page(1, null, 3))); + assertNull(YqnProductQueryMapper.nextCursor(page(2, null, 3))); + } + + private static common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductPage page( + int number, Boolean last, Integer totalPages) { + common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductPage p = + new common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductPage(); + p.number = number; + p.last = last; + p.totalPages = totalPages; + p.size = 100; + p.numberOfElements = 100; + return p; + } + + /** 没有 SKU 的行跳过,不整页失败。 */ + @Test + void rowsWithoutSkuAreSkipped() { + common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductRow bad = + new common.ecommerce.yqn.dto.YqnProductQueryDtos.ProductRow(); + bad.sku = " "; + assertNull(YqnProductQueryMapper.toInfo(bad)); + assertNull(YqnProductQueryMapper.toInfo(null)); + } + + @Test + void adapterQueriesProducts() { + RecordingTransport transport = stub(pageBody(true, 0, null)); + + Page page = new YqnAdapter(transport, new JacksonJsonCodec()) + .query(ctx(), ProductQuery.builder().providerSku("SKU-1").build()); + + assertEquals(1, page.size()); + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"skuList\":[\"SKU-1\"]"), body); + // 首页必须是 pageNum=0 + assertTrue(body.contains("\"pageNum\":0"), body); + } +} diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java index 3ce3917..bb82be3 100644 --- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java @@ -75,6 +75,39 @@ class YqnReadOnlyProbeTest { }); } + /** + * 商品查询(API 113)。 + * + *

不传 {@code skuList} 时仓方返回全量第一页——正好用来验「页码从 0 开始」。 + * 用 {@code -Dyqn.probe.skuList=A,B} 可以顺带验按 SKU 过滤。

+ */ + @Test + void probeProductQuery() { + assumeToken(); + run("POST /v1/product/findPage", () -> { + String raw = System.getProperty("yqn.probe.skuList", ""); + common.ecommerce.warehouse.model.ProductQuery.Builder q = + common.ecommerce.warehouse.model.ProductQuery.builder().pageSize(5); + if (!raw.trim().isEmpty()) { + q.providerSkus(java.util.Arrays.asList(raw.split(","))); + } + common.ecommerce.shared.support.Page< + common.ecommerce.warehouse.model.ProductInfo> page = + adapter().query(ctx(), q.build()); + System.out.println("[products] 本页 " + page.size() + + " hasMore=" + page.hasMore() + " nextCursor=" + page.nextCursor()); + for (int i = 0; i < Math.min(page.size(), 3); i++) { + common.ecommerce.warehouse.model.ProductInfo p = page.items().get(i); + System.out.println(" [" + i + "] sku=" + p.providerSku() + + " name=" + p.name() + + " lwh=" + p.lengthCm() + "x" + p.widthCm() + "x" + p.heightCm() + + " weight=" + p.weightGrams() + + " packedQty=" + p.packedQuantity() + + " productType=" + p.productType()); + } + }); + } + /** 物流产品:验证「GET 但参数写在 query」这条路是否被仓方接受。 */ @Test void probeLogisticsProducts() {