From 5dce79ea32ca9190a6fd1fe83f9e40eff7c61807 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 17 Nov 2026 09:37:52 +0800 Subject: [PATCH 1/7] =?UTF-8?q?fix(edayun):=20=E4=BF=AE=E6=AD=A3=20SKU=20?= =?UTF-8?q?=E6=A0=87=E7=AB=AF=E7=82=B9=E8=B7=AF=E5=BE=84=EF=BC=88=E5=8E=BB?= =?UTF-8?q?=E6=8E=89=20ContentType=20=E5=90=8E=E7=BC=80=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 正确路径是 /webApi/entryInfo/v1/newPrintCaseMark,之前按文档写成了 newPrintCaseMarkContentType,PR 环境一直报「接口不存在或未启用」, 被误判成「真机未启用」。 改路径后重测:接口存在且能过参数校验(缺 pageSize 报「纸张不能为空」、 缺 madeInChina 报「产地标签不能为空」),但补全后一律「内部服务器错误」, 试过 6 种 pageSize、madeInChina 0/1、separation、箱序号区间、skuCode、 caseCodeList、甚至不存在的 entryCode,返回都一样——说明是仓方内部异常, 不是我们的参数问题。因此仍然只有单测覆盖,TODO #68 保留。 Co-Authored-By: Claude --- docs-warehouse/edayun/README.md | 8 ++++---- docs-warehouse/edayun/TODO.md | 2 +- .../src/main/java/common/ecommerce/edayun/EdayunConstants.java | 4 ++-- .../main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java | 2 +- .../common/ecommerce/edayun/adapter/EdayunSkuLabelMapper.java | 2 +- .../main/java/common/ecommerce/edayun/dto/EdayunSkuLabelDtos.java | 2 +- .../java/common/ecommerce/edayun/adapter/EdayunSkuLabelTest.java | 2 +- 7 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md index 90ab88b..1ee293d 100644 --- a/docs-warehouse/edayun/README.md +++ b/docs-warehouse/edayun/README.md @@ -28,7 +28,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`) | | 其它业务接口 | ⬜ 等文档 | @@ -1154,7 +1154,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 +1192,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 环境该路径报「接口不存在或未启用」,去掉 diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index ff9756e..508a6bb 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -67,7 +67,7 @@ | 65 | 条码打印的纸张尺寸只有 4 档(7×3/10×6/6×4/A4),与入库贴标的 14 种不重叠 | 独立枚举 `BarcodePaperSize` | 宿主换标签纸时要选对枚举 | | 66 | 条码文件地址的**有效期**未知(OSS 链接) | 原样返回,不缓存 | 宿主存旧链接可能 403 | | 67 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 | -| 68 | **箱唛接口在 PR 环境未启用**(`newPrintCaseMarkContentType` 报「接口不存在或未启用」;去掉后缀的 `newPrintCaseMark` 能过参数校验但一律「内部服务器错误」) | 按文档实现,映射只有单测 | 上线前必须真机验证 | +| 68 | **箱唛接口在 PR 环境未启用**(`newPrintCaseMark` 报「接口不存在或未启用」;去掉后缀的 `newPrintCaseMark` 能过参数校验但一律「内部服务器错误」) | 按文档实现,映射只有单测 | 上线前必须真机验证 | | 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/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..d9b7416 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 @@ -108,12 +108,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..491d053 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 @@ -1023,7 +1023,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})。

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/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/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 与分隔符默认关。

From 97be2aebe92075ba7ccfd2c07695cf8fccfa0a53 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 17 Nov 2026 09:40:45 +0800 Subject: [PATCH 2/7] =?UTF-8?q?docs(edayun):=20SKU=20=E6=A0=87=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E4=B8=8D=E6=98=AF=E6=9C=AA=E5=90=AF=E7=94=A8=EF=BC=8C?= =?UTF-8?q?=E6=98=AF=E4=BB=93=E6=96=B9=E5=86=85=E9=83=A8=E6=8A=A5=E9=94=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 路径 /webApi/entryInfo/v1/newPrintCaseMark 确认存在——缺 pageSize 报 「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」、缺 entryCode 报 「入库单号不能为空」。之前写错成 newPrintCaseMarkContentType 才会报 「接口不存在或未启用」。 参数补全后一律「内部服务器错误」,换 6 种 pageSize / madeInChina 0-1 / separation / 箱序号区间 / skuCode / caseCodeList / 不存在的 entryCode 都是同一个错误,判断是仓方内部异常,不是我们的参数问题。 Co-Authored-By: Claude --- docs-warehouse/edayun/TODO.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index 508a6bb..3c744c6 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -67,7 +67,7 @@ | 65 | 条码打印的纸张尺寸只有 4 档(7×3/10×6/6×4/A4),与入库贴标的 14 种不重叠 | 独立枚举 `BarcodePaperSize` | 宿主换标签纸时要选对枚举 | | 66 | 条码文件地址的**有效期**未知(OSS 链接) | 原样返回,不缓存 | 宿主存旧链接可能 403 | | 67 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 | -| 68 | **箱唛接口在 PR 环境未启用**(`newPrintCaseMark` 报「接口不存在或未启用」;去掉后缀的 `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 标注 | 无(已规避) | From 8dabf9fb1bea694d2f93edebaa19cd5d6e9193db Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 17 Nov 2026 09:50:08 +0800 Subject: [PATCH 3/7] =?UTF-8?q?test(edayun):=20=E8=A1=A5=20SDK=20=E8=A3=85?= =?UTF-8?q?=E9=85=8D=E9=93=BE=E8=B7=AF=E5=86=92=E7=83=9F=EF=BC=88=E7=A6=BB?= =?UTF-8?q?=E7=BA=BF=EF=BC=8C=E6=8C=89=E4=B8=9A=E5=8A=A1=E5=9C=BA=E6=99=AF?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 从门面 WarehouseSdk 走一遍,覆盖: - 装配:能力位全量断言(12 个已声明 + 3 个必须为假)、工厂能建出适配器 - 场景 1 主数据:仓库 / 承运商 / 物流产品(-998 已跳过) - 场景 2 发货:试算 → 建单 → 查单 → 面单 → 取消前校验 → 取消, 外加建单幂等(同一 outboundRequestNo 只打一次仓方) - 场景 3 库存:safeStock 缺失映射为 -1 - 场景 4 退货:建单 → 详情 → 列表 → 取消 - 场景 5 单据 / 轨迹 / 打印:BOL、节点与运单级轨迹(上网/妥投时间)、 箱唛、入库单 - 未实现能力(调拨 / 退货检验后处理)必须抛,不返回空 不联网:用 RecordingTransport + 真实报文样本。适配器直接注册(传输层可替换), 另用一例单独验证工厂路径能 build 出适配器。 验证:9 个用例全绿;全仓 mvn test 通过。 Co-Authored-By: Claude --- .../ecommerce/edayun/sdk/EdayunSdkSmokeTest.java | 436 +++++++++++++++++++++ 1 file changed, 436 insertions(+) create mode 100644 warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/sdk/EdayunSdkSmokeTest.java 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())); + } +} From 7629a52ab85f95ac085d96f0184bcae7a06ee279 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 17 Nov 2026 11:53:08 +0800 Subject: [PATCH 4/7] =?UTF-8?q?fix(edayun):=20=E4=BF=AE=20CR=20=E5=8F=91?= =?UTF-8?q?=E7=8E=B0=E7=9A=84=E4=B8=89=E4=B8=AA=E7=9C=9F=20bug=20=E4=B8=8E?= =?UTF-8?q?=E8=8B=A5=E5=B9=B2=E8=AF=AD=E4=B9=89=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Critical: 1. EdayunRmaListMapper 静默丢弃调用方的仓库过滤——账户绑了数字仓 id 时, 传入不同的 warehouseCode 会被忽略,结果反而变宽。改为冲突时本地拒绝。 2. EdayunTrackMapper 把 track.receiver(收件人)映射到 signedBy(签收人), 导致每个在途包裹都被判成已签收。易达云响应没有签收人字段,改为不填。 3. 退货详情 / 列表用 warehouseName(美西1仓)当 warehouseCode,宿主拿它 equals / 回传查询会全线失效。改为只用仓编码,缺失直接回退 OMS 仓编码。 Important: 4. EdayunReturnMapper 静默丢弃 returnReason / estimatedReceiveDate / lineName——三个字段易达云都不支持,改为本地拒绝并说明原因。 5. WarehouseDirectoryCapable.carrierDirectory 默认实现把 carriers() 的码 包装成假的两层结构(carrierId == nameEn == FEDEX-G),改成默认抛不支持。 6. EdayunAdapter.printSkuLabel 改包级可见:SKU_LABEL 未声明,门面够不到, 留 public 会让调用方误以为能用。 7. products(warehouseCode) 之前完全忽略入参;改为显式优先,且必须数字。 8. 删掉 EdayunCarrierTest.warehousesAreUnsupported——它断言的是相反行为, 能过只是因为没注册路由。 9. EdayunAdapter 类注释还写着「已实现:商品建档、创建出库单」。 Minor:EdayunAdapterFactory 重复 import、CaseMarkPrintCapable javadoc 写的 BARCODE_PRINT 不存在、TODO.md 表格分隔行丢失、EdayunInventoryTest 合并残留 换行错乱。 新增回归用例:仓库过滤冲突 / 一致、三个不支持字段被拒。 验证:全仓 mvn test 通过;易达云 304 个用例全绿。 Co-Authored-By: Claude --- docs-warehouse/edayun/TODO.md | 1 + .../warehouse/capability/CaseMarkPrintCapable.java | 2 +- .../capability/WarehouseDirectoryCapable.java | 18 ++++------ .../ecommerce/edayun/adapter/EdayunAdapter.java | 23 +++++++------ .../edayun/adapter/EdayunAdapterFactory.java | 1 - .../adapter/EdayunLogisticsProductMapper.java | 20 +++++++++++ .../edayun/adapter/EdayunReturnDetailMapper.java | 6 ++-- .../edayun/adapter/EdayunReturnMapper.java | 35 +++++++++++++++++++ .../edayun/adapter/EdayunRmaListMapper.java | 40 +++++++++++++++++----- .../edayun/adapter/EdayunTrackMapper.java | 4 ++- .../edayun/adapter/EdayunCarrierTest.java | 8 ----- .../edayun/adapter/EdayunInventoryTest.java | 6 ++-- .../ecommerce/edayun/adapter/EdayunReturnTest.java | 35 +++++++++++++++++++ .../edayun/adapter/EdayunRmaListTest.java | 33 +++++++++++++++--- .../ecommerce/edayun/adapter/EdayunTrackTest.java | 3 +- 15 files changed, 185 insertions(+), 50 deletions(-) diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index 3c744c6..61b3053 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 接口免签,现在是正确的 | 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-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java index 491d053..6d89a22 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 @@ -98,8 +98,8 @@ import java.util.List; /** * 易达云适配器。 * - *

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

+ *

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

* *

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

@@ -905,7 +905,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, @@ -1031,12 +1033,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 +1049,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/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/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/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/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/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()); From efc248c27d744428ba6f17029dbfeb55c7fbfa97 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 17 Nov 2026 11:55:42 +0800 Subject: [PATCH 5/7] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20CR=20=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=E5=90=8E=E7=9A=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README:queryReturns 已实现(之前写的是「没有列表接口」); BarcodePaperSize -> CaseMarkPaperSize - TODO:#38 标记已解决;#65 枚举名修正 - architecture:能力位 26 -> 27,WAREHOUSE_DIRECTORY -> DIRECTORY, 补 CASE_MARK_PRINT 一行 Co-Authored-By: Claude --- docs-warehouse/architecture.md | 5 +++-- docs-warehouse/edayun/README.md | 4 ++-- docs-warehouse/edayun/TODO.md | 4 ++-- 3 files changed, 7 insertions(+), 6 deletions(-) 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 1ee293d..8e36380 100644 --- a/docs-warehouse/edayun/README.md +++ b/docs-warehouse/edayun/README.md @@ -913,10 +913,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`,不返回空列表。 ### 探针 diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index 61b3053..01119f6 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -38,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 退货都得人工 | @@ -65,7 +65,7 @@ | 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 | **SKU 标接口调通但仓方内部报错**:路径 `/webApi/entryInfo/v1/newPrintCaseMark` 确认存在(缺参数有中文校验提示),但参数补全后一律「内部服务器错误」,试过 6 种 pageSize、madeInChina 0/1、separation、箱序号区间、skuCode、caseCodeList、不存在的 entryCode 都一样 | 按文档实现,映射只有单测 | 上线前必须真机验证 | From b5e94c1157385a4642eaf9ac854b38c8a79b7a2a Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 17 Nov 2026 14:11:05 +0800 Subject: [PATCH 6/7] =?UTF-8?q?feat:=20=E8=BF=90=E5=8E=BB=E5=93=AA=20/=20?= =?UTF-8?q?=E6=98=93=E8=BE=BE=E4=BA=91=20=E5=95=86=E5=93=81=E6=9F=A5?= =?UTF-8?q?=E8=AF=A2=E6=8E=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 统一模型新增: - ProductQuery:providerSkus(仓侧 SKU)/ barcode / 创建时间窗 / 分页, 单次上限 100 个 SKU - ProductInfo:查询结果(仓侧 SKU、条码、尺寸重量、装箱、状态、创建时间) - WarehouseProductCapable.query(...) 默认抛不支持;门面 queryProducts(ProductQuery) 运去哪(API 113 /v1/product/findPage): - **页码从 0 开始**(文档原文),游标即页码、不做 ±1 换算 - 单页上限 100、skuList 上限 100 - 该接口没有条码 / 时间窗过滤,传了本地拒绝 - 翻页优先 last,其次 number+1 < totalPages,最后按满页兜底 - cost 没有 currency 时不成 Money(避免丢单位) 易达云(/webApi/skuInfo/v1/listProductPage): - skuCode 是逗号拼接的单个字符串,一次最多 50 个,超了本地拒绝 - 页码从 1 开始、单页上限 200 - 尺寸取**实际值**,缺失才回落 forecast*(真机 ybtest:实际 55 vs 预报 10,差 5 倍) - 「查询无数据」按空页处理,不抛异常(与轨迹接口同口径) - 查询条件全空时仓方默认查最近一个月,本地不补默认值 真机验证(2026-11-17): - 易达云:不带时间窗 total=52244;skuCode=ybtest 命中 1 行; 30 天窗口 + 2021 年建的 SKU → 「查询无数据」;10 年窗口正常命中 - 运去哪:未提供 x-api-key,只做了离线单测 SKU 口径已确认并写入文档:两边都传仓侧 SKU(建档下发的 providerSku, 为空时才是 omsSku),SDK 不做 OMS→仓侧转换。 Co-Authored-By: Claude --- docs-warehouse/edayun/README.md | 67 ++++ docs-warehouse/yqn/README.md | 31 ++ .../capability/WarehouseProductCapable.java | 21 +- .../ecommerce/warehouse/model/ProductInfo.java | 423 +++++++++++++++++++++ .../ecommerce/warehouse/model/ProductQuery.java | 140 +++++++ .../warehouse/sdk/WarehouseOperations.java | 19 + .../common/ecommerce/edayun/EdayunConstants.java | 3 + .../ecommerce/edayun/adapter/EdayunAdapter.java | 44 ++- .../edayun/adapter/EdayunProductQueryMapper.java | 153 ++++++++ .../edayun/dto/EdayunProductQueryDtos.java | 96 +++++ .../edayun/adapter/EdayunProductQueryTest.java | 215 +++++++++++ .../edayun/probe/EdayunProductQueryProbeTest.java | 106 ++++++ .../java/common/ecommerce/yqn/YqnConstants.java | 3 + .../common/ecommerce/yqn/adapter/YqnAdapter.java | 29 ++ .../yqn/adapter/YqnProductQueryMapper.java | 175 +++++++++ .../ecommerce/yqn/dto/YqnProductQueryDtos.java | 112 ++++++ .../ecommerce/yqn/adapter/YqnProductQueryTest.java | 190 +++++++++ .../ecommerce/yqn/probe/YqnReadOnlyProbeTest.java | 33 ++ 18 files changed, 1855 insertions(+), 5 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductQueryMapper.java create mode 100644 warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunProductQueryDtos.java create mode 100644 warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunProductQueryTest.java create mode 100644 warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/probe/EdayunProductQueryProbeTest.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductQueryMapper.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnProductQueryDtos.java create mode 100644 warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductQueryTest.java diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md index 8e36380..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`) | @@ -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 口径」)。 + ## 创建出库单 ``` @@ -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/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/WarehouseProductCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProductCapable.java index a8f4753..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 @@ -3,12 +3,31 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; -/** 商品建档 / 更新能力。 */ +/** 商品建档 / 更新 / 查询能力。 */ public interface WarehouseProductCapable extends WarehouseAdapter { /** 在某仓创建或更新一个 SKU。 */ ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product); + /** + * 批量 / 分页查询仓侧商品资料。 + * + *

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

+ * + *

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

+ * + * @return 分页结果;仓方无数据时为空页(不是错误) + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不提供商品查询 + */ + 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); + } + /** 商品建档结果。 */ final class ProductResult { 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..ab2236e --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductInfo.java @@ -0,0 +1,423 @@ +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; + private final String remark; + /** 该商品来自哪家仓。 */ + private final WarehouseProvider sourceProvider; + + 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.remark = b.remark; + this.sourceProvider = b.sourceProvider; + } + + 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; + } + + 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 String remark; + private WarehouseProvider sourceProvider; + + 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 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 new file mode 100644 index 0000000..8e3463a --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java @@ -0,0 +1,140 @@ +package common.ecommerce.warehouse.model; + +import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 商品查询条件(批量 / 分页)。 + * + *

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

+ * + *

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

+ */ +public final class ProductQuery { + + /** 单次最多查多少个 SKU(各仓不同,由适配器按自己的上限再校验)。 */ + public static final int MAX_SKUS = 100; + + private final List providerSkus; + /** 条码(UPC / 仓方条码)。 */ + private final String barcode; + private final Instant createdAfter; + private final Instant createdBefore; + private final int pageSize; + private final String cursor; + + 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; + } + + public static Builder builder() { + return new Builder(); + } + + /** 仓侧 SKU 列表;空表示不按 SKU 过滤。 */ + public List providerSkus() { + return providerSkus; + } + + /** 条码;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 表示第一页。 */ + public String cursor() { + return cursor; + } + + public static final class Builder { + private final List providerSkus = new ArrayList(); + 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) { + if (v != null) { + for (String s : v) { + providerSku(s); + } + } + return this; + } + + 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; + } + + public Builder pageSize(int v) { + this.pageSize = v; + return this; + } + + public Builder cursor(String v) { + this.cursor = v; + return this; + } + + public ProductQuery build() { + return new ProductQuery(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 09517c9..0445a22 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,6 +98,23 @@ public final class WarehouseOperations { } /** + * 批量 / 分页查询仓侧商品资料。只读,不走幂等。 + * + *

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

+ */ + public Page queryProducts(ProductQuery query) { + require(WarehouseCapability.PRODUCT, WarehouseProductCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.product.query", + CallSupport.params("skuCount", query.providerSkus().size(), + "barcode", query.barcode(), + "hasCreatedRange", query.hasCreatedRange(), + "cursor", query.cursor()), + p -> p.size(), + () -> ((WarehouseProductCapable) adapter).query(ctx, query)); + } + + /** * 创建调拨单。写操作:强制经幂等守卫,幂等键 * {@code warehouseCode + transferRequestNo + create}。 * 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 d9b7416..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"; 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 6d89a22..57714ea 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; @@ -213,6 +216,38 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa parsed.data == null ? null : parsed.data.skuId); } + /** + * 批量查询仓侧商品资料({@code POST /webApi/skuInfo/v1/listProductPage})。 + * + *

入参 SKU 是仓侧 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); + } + // ------------------------------------------------------------------ 出库 /** @@ -964,7 +999,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, @@ -973,9 +1008,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("跟踪号为空")); } // ------------------------------------------------------------------ 条码打印 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/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/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/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-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..71d72eb 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,34 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl json.stringAt(raw, "message")); } + /** + * 批量查询仓侧商品资料(API 113,{@code /v1/product/findPage})。 + * + *

入参 SKU 是仓侧 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/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() { From 5bbfb33261a72345e5c61c22ab5d65d3828d4030 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 17 Nov 2026 14:41:29 +0800 Subject: [PATCH 7/7] =?UTF-8?q?docs:=20=E5=86=99=E6=B8=85=20SKU=20?= =?UTF-8?q?=E5=8F=A3=E5=BE=84=E2=80=94=E2=80=94=E5=BB=BA=E6=A1=A3=E4=B8=8B?= =?UTF-8?q?=E5=8F=91=E7=9A=84=E9=82=A3=E4=B8=B2=EF=BC=8C=E4=B9=8B=E5=90=8E?= =?UTF-8?q?=E5=85=A8=E7=A8=8B=E7=94=A8=E5=AE=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 核心结论(代码注释 + 文档都补上): - 建档时 skuOf() = providerSku 优先,为空才回退 omsSku 易达云写到 skuCode 字段、运去哪写到 sku 字段 - 仓方一旦落库,之后 查商品 / 下单 / 查库存 都必须传同一串 - 所以「仓侧 SKU」不一定等于 OMS SKU: 给了 providerSku(如 AP0000X9US0010601)则两者不同;没给则同名 - SDK 不做 OMS→仓侧转换(映射表在宿主手里,静默转换会静默查空) 补注释的位置: - WarehouseProduct.providerSku 字段与 getter - ProductQuery.providerSkus / InventoryQuery.providerSkus - YqnProductMapper.skuOf / EdayunProductMapper.skuOf(含真机证据说明) - 两个适配器的商品查询方法 javadoc - YqnOutboundMapper / EdayunOrderMapper 的出库行 SKU 赋值处 Co-Authored-By: Claude --- .../warehouse/capability/WarehouseProduct.java | 20 +++++++++++++++++++- .../ecommerce/warehouse/model/InventoryQuery.java | 7 +++++++ .../ecommerce/warehouse/model/ProductQuery.java | 9 ++++++++- .../ecommerce/edayun/adapter/EdayunAdapter.java | 4 +++- .../ecommerce/edayun/adapter/EdayunOrderMapper.java | 2 ++ .../edayun/adapter/EdayunProductMapper.java | 20 ++++++++++++++++++++ .../common/ecommerce/yqn/adapter/YqnAdapter.java | 5 +++-- .../ecommerce/yqn/adapter/YqnOutboundMapper.java | 2 ++ .../ecommerce/yqn/adapter/YqnProductMapper.java | 20 +++++++++++++++++++- 9 files changed, 83 insertions(+), 6 deletions(-) diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java index 8b46474..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; @@ -233,7 +251,7 @@ public final class WarehouseProduct { return omsSku; } - /** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。 */ + /** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。详见字段注释。 */ public String providerSku() { return providerSku; } 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/ProductQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java index 8e3463a..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 @@ -51,7 +51,14 @@ public final class ProductQuery { return new Builder(); } - /** 仓侧 SKU 列表;空表示不按 SKU 过滤。 */ + /** + * 仓侧 SKU 列表;空表示不按 SKU 过滤。 + * + *

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

+ */ public List providerSkus() { return providerSkus; } 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 57714ea..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 @@ -219,7 +219,9 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa /** * 批量查询仓侧商品资料({@code POST /webApi/skuInfo/v1/listProductPage})。 * - *

入参 SKU 是仓侧 SKU。易达云的 {@code skuCode} 是逗号拼接的 + *

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

* 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-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 71d72eb..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 @@ -174,8 +174,9 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl /** * 批量查询仓侧商品资料(API 113,{@code /v1/product/findPage})。 * - *

入参 SKU 是仓侧 SKU;运去哪这个接口没有条码 / 时间窗过滤, - * 传了要本地拒绝而不是静默忽略。

+ *

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

* *

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

*/ 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()) {