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()}:

+ * + * + * + *

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})全都按这串匹配。 + * 所以:

+ * + * + *

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