Ragdoll Electron IPC 與 Local Storage 整合指南。涵蓋 Electron 主進程與 Next.js 渲染進程之間的 IPC 通訊架構、ragdollAPI 完整 API 清單、electron-store 本地儲存機制、硬體裝置 IPC 介面， 以及新增 IPC Channel 或擴充 Local Storage 的標準步驟。 以下情況必須參考此文件再動手： - 新增或修改 Electron IPC 通訊介面 - 擴充 electron-store 本地儲存欄位（RagdollStore 型別異動） - 使用 ragdollAPI 呼叫硬體裝置（發票機、刷卡機、台新 ONE 碼、宜睿禮券） - 使用 ragdollAPI.store / ragdollAPI.db / ragdollAPI.graphql 操作資料 - 從渲染端呼叫主進程的任何功能 - 理解 Preload → IPC Channel → Main Handler 三層架構
Ragdoll 採用 Electron 的 contextBridge + ipcRenderer.invoke 模式，所有渲染進程對主進程的呼叫都透過 window.ragdollAPI（全域常數 ragdollAPI）進行。
┌──────────────────────────────────────────────────────────────┐
│ Next.js 渲染進程 (Renderer) │
│ │
│ ragdollAPI.store.get('KEY') │
│ ragdollAPI.devices.invoice.open() │
│ ragdollAPI.db.list('tableName') │
│ │ │
│ ▼ │
│ ipc-renderer-preload.ts │
│ (contextBridge.exposeInMainWorld) │
│ ipcRenderer.invoke('channel', ...args) │
└────────────────────────┬─────────────────────────────────────┘
│ IPC Channel
┌────────────────────────▼─────────────────────────────────────┐
│ Electron 主進程 (Main) │
│ │
│ ipc-main-setup.ts │
│ ipcMain.handle('channel', handler) │
│ │ │
│ ▼ │
│ 實際實作：storage.ts / database/ / devices/ / jobs/ │
└──────────────────────────────────────────────────────────────┘
| 檔案 | 職責 |
|---|---|
electron/main/settings/ipc-renderer-preload.ts | Preload 腳本，定義 ElectronAPI class 並透過 contextBridge 曝露為 ragdollAPI |
electron/main/settings/ipc-main-setup.ts | 主進程 IPC handler 註冊中心 |
electron/main/types/api.ts | ElectronAPIMethods 介面（ragdollAPI 的完整型別合約） |
electron/main/types/ipc-devices.ts | 所有硬體裝置 IPC 介面、Channel 常數 |
electron/main/types/storage.ts | RagdollStore 型別（electron-store 可用 key） |
electron/main/lib/storage.ts | electron-store 實例初始化與存取 |
next/types/global.d.ts | 渲染端 ragdollAPI 全域型別宣告 |
ipcRenderer.invoke vs ipcRenderer.send 的使用時機ragdollAPI.store — 本地儲存 CRUDragdollAPI.db — SQLite 資料庫操作ragdollAPI.graphql — GraphQL 遠端操作ragdollAPI.devices — 硬體裝置操作syncData、commitInvoice、calcBestPosPromotion 等）RagdollStore 型別定義與現有欄位ragdollAPI.store.get/set/delete 使用方式