介面沒報錯但庫存對不上：多店鋪庫存同步失敗的 4 層排查思路

週一上午，速賣通店鋪 A 和 Shopee 店鋪 B 共享同一 SKU 池，同步腳本跑完日誌全綠，每條介面返回 200。下午對帳才發現 B 店比倉庫實際多 17 件可售。沒有彈窗、沒有異常碼，偏差就是在那兒。這類「介面沒報錯但數字對不上」的情況，本質是靜默失效——問題藏在四個獨立層級裡，從數據欄位到執行環境逐層向外排查，每層只需一個判據就能定位。

介面 200 ≠ 數據正確：靜默失效的 4 層位置

四層由內向外遞進：欄位映射決定「寫進去的是不是同一個數」，時序競態決定「兩個寫入誰覆蓋了誰」，平台規則決定「平台自己扣了多少沒吐回來」，工具與環境決定「輪詢夠不夠快、資料源對不對」。排查時從第一層開始，每層花 10 分鐘做一條最小驗證，命中即停，避免全量翻日誌。

第一層：欄位映射與精度

• 變體維度未對齊：速賣通 SKU 編碼含顏色 + 尺碼 + 包裝，Shopee 只取顏色 + 尺碼。同步腳本若把完整編碼當主鍵寫入 Shopee，同一實物會被拆成兩筆記錄，庫存被重複計入。判據：拿一個三變體 SKU，在兩平台後台逐欄位對照映射表，確認維度集合完全一致。
• 整數 vs 浮點：部分平台 API 回傳 "quantity": 5.0，腳本若直接存為浮點再與本地整數帳本比對，浮點精度會在 10 次累加後產生 0.001 級偏差，對帳工具判為不匹配。判據：在寫入前加一層 Math.round()或平台側強制 integer 欄位，跑一次全量比對看偏差是否歸零。
• SKU ID 截斷或錯位：自增 ID 在 7 位變 8 位時，下游腳本若用固定寬度字串接收，前導零被吞掉，導致 A 店 ID 寫到 B 店的槽位。判據：抽查最近 200 條同步日誌的 ID 欄位長度是否恆定。

第二層：時序與競態

輪詢間隔 5 分鐘，但 Shopee 側在兩次輪詢之間完成了一筆訂單的庫存扣減，速賣通側同時觸發了一次補貨寫入。兩個寫入到達平台的時間差只有 1.2 秒，後到的一方把前者的結果覆蓋。日誌裡兩次請求都返回 200，但終態不是任何一方的預期值。快取 TTL 加劇了這個窗口：Shopee 商品頁庫存有 60 秒 CDN 快取，即使 API 寫成功，買家端仍顯示舊值，賣家據此判斷「同步沒生效」再手動改一次，進一步放大偏差。對照自己的 cron 或 Webhook 配置，把輪詢間隔壓到寫入頻率以下，並在關鍵 SKU 上給寫入加樂觀鎖版本號，可消除大部分競態。

第三層：平台規則

本地帳本 100 件，平台顯示 83 件，差額 17 件未必是丟失，而是平台內部的庫存子狀態沒有回流到同步介面：

• 速賣通：買家下單後庫存進入「預佔」狀態，24 小時未支付才釋放。預佔期間同步介面只返回「可用庫存」，預佔部分不可見。若腳本把可用庫存當作全量回寫本地，預佔釋放時本地數字會突然跳升。
• Shopee：活動庫存（flash sale 預留）與常規庫存分桶管理，活動期間的扣減不反映在常規桶的 API 返回值中。詳見 Shopee 多店鋪履約規則中庫存被跨店佔用的失效鏈。
• Lazada：預售庫存獨立計數，開售後自動轉入常規桶，但轉入有 15 分鐘延遲，延遲窗口內同步腳本讀到的仍是預售值。

判據：把平台後台的「可用 / 預佔 / 活動預留 / 預售」四個子項分別截圖，與本地賬本逐項對齊，差額落在哪個子項就屬於哪條平台規則，不是同步 bug。多平台庫存與訂單的權限切分邏輯，可參考 速賣通多店鋪庫存、訂單與客服權限分權 一文的欄位設計。

第四層：工具與環境

前三層修完仍有殘差，問題大概率在工具層：輪詢頻率低於訂單峰值、數據源仍依賴手動匯出 Excel、多店鋪登入環境未隔離導致 Cookie 串擾。判斷是否該升級工具，看三個訊號：手動對賬頻率超過每週 3 次、跨平台數量超過 3 個、同時操作庫存的團隊成員超過 4 人。命中兩條以上，自建腳本的維護成本已高於引入統一工作台的邊際收益。選型上，2–3 個平台的輕量 SaaS 能覆蓋輪詢和基礎對帳；4 個以上平台或需要庫存-訂單-客服三條流收口時，再考慮 多平台訂單、庫存和訊息集中處理的統一工作台。工具能力邊界與三檔團隊的選型對比，詳見 多店鋪營運工具選型：自建表格、瀏覽器多開與統一工作台。