Browse Source

docs: 写清 SKU 口径——建档下发的那串,之后全程用它

核心结论(代码注释 + 文档都补上):
- 建档时 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 <noreply@anthropic.com>
feature/Walmart
chenchuchuan 3 days ago
parent
commit
5bbfb33261
  1. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  2. 7
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
  3. 9
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ProductQuery.java
  4. 4
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  5. 2
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java
  6. 20
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java
  7. 5
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  8. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
  9. 20
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java

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

@ -19,6 +19,24 @@ import java.util.Objects; @@ -19,6 +19,24 @@ import java.util.Objects;
public final class WarehouseProduct {
private final String omsSku;
/**
* 仓侧 SKU——<b>建档时下发给仓方的那串,之后所有查询 / 下单都用它</b>。
*
* <p>各适配器在建档时按「{@code providerSku} 优先,为空才回退 {@link #omsSku}」
* 决定仓方库里存什么,字段名各不相同(易达云 {@code skuCode}、
* 运去哪 {@code sku})。仓方一旦落库,<b>之后按 SKU 查询、下单、查库存都必须传
* 同一串</b>——所以它不一定等于 {@link #omsSku()}:</p>
*
* <ul>
* <li>给了 {@code providerSku}(如 {@code AP0000X9US0010601})→ 仓方存它,
* 后续传入 {@code ProductQuery.providerSkus()} / {@code InventoryQuery.providerSkus()}
* / {@code OutboundLine.providerSku()} 时也必须是它</li>
* <li>没给 → 仓方存的就是 {@code omsSku},两者同名</li>
* </ul>
*
* <p>SDK <b>不做 OMS→仓侧 SKU 的转换</b>:映射表在宿主手里,静默转换会拿回
* 空结果或错商品,比报错更难发现。</p>
*/
private final String providerSku;
private final String customItemNo;
private final String barcode;
@ -233,7 +251,7 @@ public final class WarehouseProduct { @@ -233,7 +251,7 @@ public final class WarehouseProduct {
return omsSku;
}
/** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。 */
/** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。详见字段注释。 */
public String providerSku() {
return providerSku;
}

7
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java

@ -37,6 +37,13 @@ public final class InventoryQuery { @@ -37,6 +37,13 @@ public final class InventoryQuery {
return new Builder();
}
/**
* 仓侧 SKU 列表;空表示不按 SKU 过滤。
*
* <p>同 {@link ProductQuery#providerSkus()}:必须是建档时下发的仓侧 SKU
* ({@code WarehouseProduct.providerSku()},未给映射时即 {@code omsSku()}),
* 不一定是 OMS SKU。</p>
*/
public List<String> providerSkus() {
return providerSkus;
}

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

@ -51,7 +51,14 @@ public final class ProductQuery { @@ -51,7 +51,14 @@ public final class ProductQuery {
return new Builder();
}
/** 仓侧 SKU 列表;空表示不按 SKU 过滤。 */
/**
* 仓侧 SKU 列表;空表示不按 SKU 过滤。
*
* <p>这串必须等于<b>建档时下发给仓方的 SKU</b>({@code WarehouseProduct.providerSku()},
* 未给映射时即 {@code omsSku()})。各仓入库字段不同:易达云 {@code skuCode}
* (逗号拼接,≤50)/ 运去哪 {@code skuList}(JSON 数组,≤100)。
* 传错不会报错,只会查不到——SDK 不做 OMS→仓侧转换。</p>
*/
public List<String> providerSkus() {
return providerSkus;
}

4
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java

@ -219,7 +219,9 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -219,7 +219,9 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
/**
* 批量查询仓侧商品资料({@code POST /webApi/skuInfo/v1/listProductPage})。
*
* <p>入参 SKU 是<b>仓侧 SKU</b>。易达云的 {@code skuCode} 是逗号拼接的
* <p>入参 SKU 是<b>仓侧 SKU</b>,即建档时下发到 {@code skuCode} 字段的那串
* ({@link EdayunProductMapper} 的 {@code skuOf}),不一定等于 OMS SKU。
* 易达云的 {@code skuCode} 是逗号拼接的
* 单个字符串且一次最多 50 个,超了本地拒绝(不截断)。
* 审核时间窗统一模型没有对应字段,不传。</p>
*

2
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java

@ -163,6 +163,8 @@ public final class EdayunOrderMapper { @@ -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();

20
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunProductMapper.java

@ -128,6 +128,26 @@ public final class EdayunProductMapper { @@ -128,6 +128,26 @@ public final class EdayunProductMapper {
return d;
}
/**
* 下发到易达云 {@code skuCode} 字段的值——<b>整条链路都以这个为准</b>。
*
* <p>规则:{@code providerSku} 优先,为空才回退 {@code omsSku}。</p>
*
* <p><b>为什么这条规则要写在建档这里</b>:易达云把 {@code skuCode} 当唯一键落库,
* 之后<b>查商品({@code listProductPage} 的 {@code skuCode})、建出库单
* (商品行 {@code productSku})、查库存({@code skuCodeList})全都按这串匹配</b>。
* 所以:</p>
* <ul>
* <li>宿主给了 {@code providerSku} → 仓方库里存它,之后所有查询 / 下单都必须传它,
* <b>不等于 OMS SKU</b></li>
* <li>宿主没给(如 {@code ybtest})→ 仓方库里存的就是 OMS SKU,两者同名</li>
* </ul>
*
* <p>SDK <b>不做 OMS→仓侧 SKU 的转换</b>:映射表在宿主手里(供应商编码规则、
* 按仓不同的前缀),SDK 猜不出来;静默转换会拿回空结果或错商品,比报错更难发现。</p>
*
* <p>出库行同理,见 {@code EdayunOrderMapper}({@code firstNonBlank(providerSku, omsSku)})。</p>
*/
private static String skuOf(WarehouseProduct product) {
String sku = product.providerSku();
return sku != null && !sku.trim().isEmpty() ? sku.trim() : product.omsSku();

5
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -174,8 +174,9 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -174,8 +174,9 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
/**
* 批量查询仓侧商品资料(API 113,{@code /v1/product/findPage})。
*
* <p>入参 SKU 是<b>仓侧 SKU</b>;运去哪这个接口没有条码 / 时间窗过滤,
* 传了要本地拒绝而不是静默忽略。</p>
* <p>入参 SKU 是<b>仓侧 SKU</b>,即建档时下发到 {@code sku} 字段的那串
* ({@link YqnProductMapper#skuOf}),不一定等于 OMS SKU。
* 运去哪这个接口没有条码 / 时间窗过滤,传了要本地拒绝而不是静默忽略。</p>
*
* <p>页码从 0 开始——游标就是页码字符串,不做 ±1 换算。</p>
*/

2
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java

@ -140,6 +140,8 @@ public final class YqnOutboundMapper { @@ -140,6 +140,8 @@ public final class YqnOutboundMapper {
new ArrayList<YqnCreateOrderDtos.CreateOrderRequest.ProductItem>(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();

20
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java

@ -85,7 +85,25 @@ public final class YqnProductMapper { @@ -85,7 +85,25 @@ public final class YqnProductMapper {
return req;
}
/** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */
/**
* 下发到运去哪 {@code sku} 字段的值——<b>整条链路都以这个为准</b>。
*
* <p>规则:{@code providerSku} 优先,为空才回退 {@code omsSku}。</p>
*
* <p><b>为什么这条规则要写在建档这里</b>:运去哪把 {@code sku} 当唯一键落库,
* 之后<b>查商品(API 113 {@code skuList})、建出库单(商品行 {@code sku})、
* 查库存({@code skuList})全都按这串匹配</b>。所以:</p>
* <ul>
* <li>宿主给了 {@code providerSku}(如 {@code AP0000X9US0010601})→ 仓方库里存它,
* 之后所有查询 / 下单都必须传它,<b>不等于 OMS SKU</b></li>
* <li>宿主没给(如 {@code ybtest})→ 仓方库里存的就是 OMS SKU,两者同名</li>
* </ul>
*
* <p>SDK <b>不做 OMS→仓侧 SKU 的转换</b>:映射表在宿主手里(供应商编码规则、
* 按仓不同的前缀),SDK 猜不出来;静默转换会拿回空结果或错商品,比报错更难发现。</p>
*
* <p>出库行同理,见 {@code YqnOutboundMapper}({@code providerSku} 优先)。</p>
*/
public static String skuOf(WarehouseProduct product) {
String providerSku = product.providerSku();
if (providerSku != null && !providerSku.trim().isEmpty()) {

Loading…
Cancel
Save