在线或离线退款已经完成，Credit Memo里也勾了Return to Stock，但商品仍显示缺货。启用MSI后要先问清楚“哪个库存没回来”：Source Item的实物数量，还是前台Salable Quantity。两者更新路径不同。

用订单号还原库存动作

SELECT entity_id,increment_id,status FROM sales_order WHERE increment_id='000000123';
SELECT entity_id,order_id,total_qty FROM sales_shipment WHERE order_id=<order_id>;
SELECT entity_id,order_id,total_qty FROM sales_creditmemo WHERE order_id=<order_id>;
SELECT * FROM inventory_reservation WHERE metadata LIKE '%000000123%';

已发货商品退库时，系统应根据Shipment记录的Source执行Source Item回补；未发货订单取消主要通过reservation补偿恢复可售量。只看默认Source很容易误判。

检查这四件事

  1. Credit Memo Items中的Qty to Refund是否大于0；
  2. Return to Stock勾选的是具体行，而不是只勾页面总开关；
  3. 原Shipment是否保存了正确source_code；
  4. inventory.reservations.updateSalabilityStatus Consumer是否正常运行。
bin/magento queue:consumers:start inventory.reservations.updateSalabilityStatus --max-messages=5000
bin/magento indexer:reindex inventory

Source数量没变

检查第三方ERP或RMA插件是否在creditmemo保存后再次覆盖库存。观察退款时间点前后的 inventory_source_item，并给SourceItemsSaveInterface加临时业务日志。不要直接给inventory_source_item做UPDATE；正确补救是通过SourceItemsSaveInterface写入指定Source，并保留工单与数量依据。

Source数量恢复但前台仍缺货

核对Stock与Website关联、reservation汇总和inventory_stock_N视图/索引。执行官方不一致检查，确认输出后再创建补偿：

bin/magento inventory:reservation:list-inconsistencies -r

回归场景

分别测试：未发货取消、全部发货后全额退款、部分发货后部分退款、两个Source拆单发货。每次记录Source qty、reservation sum和Salable Quantity三列，只有三者按业务预期变化才算通过。