变体 GID 和 SKU 混用导致对账错行怎么选主键

现象#

ERP 按 SKU 回写库存，两个变体 SKU 都是空字符串，结果两边数量被写到同一个变体；改用条码后只读到了第一个条码。

原因#

• Shopify 不强制 SKU 唯一，也不禁止为空，导入之后重复 SKU 很常见
• variant.id 全局唯一且不随标题、价格变化，但复制商品会生成新 id
• 一个变体最多 20 个条码，旧的 barcode 字段只返回第一个，其余静默丢失
• POS 能扫任意已关联条码，渠道 feed 仍只读第一个条码

处理步骤#

1. 内部主键统一用 gid://shopify/ProductVariant/...，SKU 只当业务编码
2. 入库前用 productVariants(query: "sku:XXX") 查重，空 SKU 直接判失败
3. 读全部条码用 barcodes(first: 20){ barcode type }，不要再读 barcode
4. 写条码用 barcodes 数组，它会整体替换，且不能与 barcode 同时传
5. 商品复制或重建后重新映射 id，把旧 id 存进 metafield 做追溯

验收标准#

回写后每个 variant.id 的数量与 ERP 明细逐行相等；barcodes 返回条数与录入数量一致。