库存调整 API 的 reason 填错会留下错账

现象#

脚本按盘点结果调用 inventoryAdjustQuantities 后，库存历史里每条都显示 Correction，收货、退货、盘点的调整混成一片，财务没法按原因汇总。

原因#

• reason 只接受固定枚举值，写成自由文本不会报错，而是被归到通用原因上
• 该 mutation 只做 delta 增减，把盘点绝对值当 delta 传会叠加而不是覆盖
• name 只接受 available、damaged、reserved、safety_stock 等状态
• 不传 referenceDocumentUri 时后台只显示应用名，单据来源无法回溯

处理步骤#

1. 按场景选枚举：盘点用 cycle_count_available，收货用 received，退货入库用 restock
2. 损伤、质检、预留分别用 damaged、quality_control、reservation_created
3. 请求体按 changes: [{delta, inventoryItemId, locationId}] 组装
4. 补 referenceDocumentUri，可用 gid://shopify/Order/123 或自定义 scheme
5. 2026-04 起必须带 @idempotent(key: "...")，重试才不会被重复扣减

验收标准#

提交后在 Inventory history 里该条记录显示所选原因与单据引用，数量变化正好等于传入的 delta。