multi-user-synclisted

# Multi-user 即時同步系統實戰手冊 本 Skill 是「**從 0 到 production-grade 多人同編工具**」的單檔規範。任何涉及 2+ 用戶同時讀寫同一份雲端狀態的功能，都應該先讀這份。 ## 目錄 1. [為什麼這個 skill 存在](#為什麼這個-skill-存在) 2. [4 層保護架構](#4-層保護架構核心心智模型) 3. [全局原則](#全局原則不分-layer-都適用) 4. [技術棧建議](#技術棧建議驗證過能用) 5. [起手式 SOP](#起手式-new-project) 6. [Layer 1 鎖機制](#layer-1鎖機制軟提醒) 7. [Layer 2 樂觀鎖 + 3-way merge](#layer-2樂觀鎖--3-way-merge資料完整性核心) 8. [Layer 3 Broadcast Handler](#layer-3broadcast-handler別人寫完後我怎麼接) 9. [Layer 4 Yjs CRDT](#layer-4yjs-crdttextarea-字元級不丟字) 10. [Side-channel Presence](#side-channelpresence誰上線誰在哪) 11. [6 個歷史災難](#6-個歷史災難) 12. [加新 sync feature 前的 7 個必問](#加新-sync-feature-前的-7-個必問) 13. [上線前 checklist](#上線前-checklist) 14. [何時 NOT 用這個 skill / 不在範圍內](#何時-not-用這個-skill) --- ## 為什麼這個 skill 存在 多人同編看起來「就是接個 realtime 就好」，但實際上有 **6 個你不會想到的坑**： 1. **資料覆蓋** — UserA 還沒存完，UserB save 把 A 的變動吃掉 2. **刪除復活** — A 刪了 IP、B 的舊狀態又把它推回雲端 3. **新增消失** — A 點「新增」後 2 秒內，B 的 broadcast 把新項目蓋掉 4. **打字丟字** — 兩人同編同一個 textarea、字元級交錯 5. **scroll 跳頂端** — 別人 save 觸發本地重畫、user 的捲軸位置歸零 6. **災難覆蓋** — 某 edge case 讓 default state 推回雲端、把全公司資料變成「範例」 這 skill 不是教你「怎麼用 Supabase Realtime」，是教你「**怎麼避免上面這 6 個坑**」。 ## 4 層保護架構（核心心智模型） ``` ┌────────────────────────────────────────┐ │ Layer 1：鎖機制（lock） │ │ 軟提醒「對方正在編輯」、避免你也下手 │ └────────────────────────────────────────┘ ↓ ┌────────────────────────────────────────┐ │ Layer 2：樂觀鎖 + 3-way merge │ │ 真要寫雲端時、發現雲端比你新 → 自動合併 │ └────────────────────────────────────────┘ ↓ ┌────────