库存调整 mutation 的 changes 写法与幂等键

现象#

想把库存从 10 调到 14，调用后后台显示 18；inventoryAdjustmentGroup.changes.delta 里是一条 -4 或 +14 的记录，和预期完全不符。

原因#

• changes.delta 是增量而不是目标值，传 14 等于在现有数量上加 14
• 同一次请求对同一 inventoryItem 与 location 写了多条 change，服务端全部累加
• 2026-04 起该 mutation 必须用 @idempotent 带幂等键，缺键请求被拒
• name 写成 available 之外的状态，例如 on_hand，前台可售数量不会变

处理步骤#

1. 先查 inventoryLevel.quantities 拿当前 available，再算 delta = 目标值 - 当前值
2. 组装 changes: [{ delta, inventoryItemId, locationId }]，一次只留一条
3. 在 mutation 上加 @idempotent(key: $idempotencyKey)，键用 UUID 并落库
4. reason 按业务选 correction 或 cycle_count_available，name 固定 available
5. 回读 inventoryAdjustmentGroup.changes 与 inventoryLevel，确认最终数量

验收标准#

回读 available 等于目标值，changes 里只有一条方向正确的 delta；同一幂等键重复提交不会二次加减。