ragdoll-knowledge-base

Ragdoll 專案的系統設計與專案管理挑戰者。當使用者提出技術方案時， 會先查閱 Ragdoll Knowledge Base 取得完整專案脈絡，再以資深架構師的角度 嚴格審視方案的合理性、未來發展性與維護性。不合理的方案會被直接反駁並提供替代方案； 合理的方案會被大力讚揚並給予精進建議。

Ragdoll 專案知識庫管理員。根據給予的情境（程式碼變更、功能新增、重構等）， 推論影響到哪些 Ragdoll Knowledge Base 文件，並將文件內容更新至與程式碼邏輯一致的最新狀態。 熟知專案每個程式碼的位置，能快速定位變更影響範圍。

Ragdoll POS 結帳流程完整知識庫。涵蓋從銷售員登入、商品掃描、加購/贈品/點加金選擇、 10 個折扣計算器管道、付款到發票列印的每個步驟的詳細程式碼邏輯、Store 架構與資料結構定義。 以下情況必須參考此文件再動手： - 撰寫結帳流程相關的 E2E 測試（Playwright）或整合測試 - 新增或修改任何促銷計算器（discount calculator）邏輯 - 處理 /checkout 或 /summary 頁面的功能開發或 bug 修復 - 修改加購（addon）、贈品（freebie）、點加金（point promotion）相關邏輯 - 處理發票開立、付款流程、錢櫃等硬體整合 - 理解 OfflineSaleLocalRecord 的組裝過程 - 修改折扣計算的執行順序或計算邏輯

Ragdoll 專案的 createStore 狀態管理完整指南。當用戶詢問關於 Ragdoll 中的 createStore、Zustand、store 實作、狀態管理、Promise state、TrackedPromise、subscriptions、actions、跨 store 通信、useInjectedStores、並發控制策略、onMount、useProps 傳遞 props、runningActions loading 狀態等任何相關主題時觸發。也適用於「如何建立 store」、「store 之間如何通信」、「如何處理異步操作」、「Promise 狀態追蹤」、「跨 store 訂閱」、「action 互相呼叫」等問題。即使用戶只是提到 store、狀態、Zustand，也應該考慮使用此技能來提供準確且完整的資訊。

Ragdoll POS 雙 SQLite 資料庫架構完整知識庫。涵蓋 Mutable / Readonly 雙資料庫設計、 Drizzle ORM v1 + node:sqlite 設定、Schema 定義慣例與型別系統、Migration 產生與執行機制、 Operations 層五大操作（list / insert / update / remove / replace）、 以及 GraphQL Filter → Drizzle WHERE 條件轉換器。 以下情況必須參考此文件再動手： - 新增或修改 Drizzle schema（`database/schema/` 目錄） - 產生或執行 migration（`db:generate` / `db:push` / `db:migrate`） - 修改資料庫初始化流程（`database/index.ts`、client 檔案） - 修改 Operations 層的 CRUD 操作邏輯 - 修改 GraphQL Filter → WHERE 條件轉換邏輯 - 新增資料表或子表（需了解 TABLE_MAP 自動推導機制） - 處理 Worker 線程的資料庫存取 - 理解 `{ body, lines }` 資料格式的轉換流程 - 處理 .gz 離線資料庫版本管理 - 排查 migration 相容性問題（舊版 DB 升級）

Ragdoll 宜睿禮券（Edenred Voucher）完整知識庫。涵蓋票券查詢、授權核銷、 金額換算規則、product_code 解析、錯誤代碼處理、付款紀錄組裝，以及 Electron 主進程 與 Next.js 渲染端的程式碼位置與資料流。 以下情況必須參考此文件再動手： - 修改或擴充宜睿禮券付款流程（查詢、核銷、折抵） - 處理宜睿 API 回傳的錯誤代碼或異常狀態 - 修改 product_code 解析邏輯或 remaining_value 金額換算 - 修改宜睿禮券與其他付款方式（現金/信用卡）並行付款的紀錄組裝邏輯 - 修改 createSale 中 voucherTotal / totalWithoutVoucher 的計算 - 修改 Summary 頁面中宜睿禮券的顯示邏輯（已付合計、找零） - 撰寫宜睿禮券相關的單元測試或整合測試 - 理解 IPC 資料流（渲染端 store → Electron 主進程 → 宜睿 API）

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 小白單（紙本優惠券）列印功能完整知識庫。涵蓋結帳後的資格篩選邏輯、 pos_printable_coupon 資料表結構、sync 同步機制、IPC 列印呼叫， 以及 Next.js 層的 filterAndBuildPrintableCoupons 工具函式與 useSale action。 以下情況必須參考此文件再動手： - 修改或擴充小白單優惠券的篩選條件（滿額/門市群組/目標消費者/料件篩選） - 修改小白單的列印格式（topText、barcodeContent、titles、memo） - 修改 pos_printable_coupon SQLite schema 或 sync config - 在結帳流程中調整小白單列印的觸發時機 - 撰寫小白單相關的單元測試或整合測試 - 理解 IPC 資料流（Next.js store → Electron 主進程 → 發票機）

Ragdoll 台新 ONE 碼支付（One Pay）完整知識庫。涵蓋付款流程、查詢驗證機制、 錯誤處理、各錢包特殊規則（LINE Pay、悠遊付、橘子支），以及 Electron 主進程 與 Next.js 渲染端的程式碼位置與資料流。 以下情況必須參考此文件再動手： - 修改或擴充台新 ONE 碼付款流程（payment、query、refund） - 處理台新 API 回傳的錯誤代碼或異常狀態 - 修改 orderitem 組合邏輯（不同錢包的字元限制與分隔符號） - 實作退款（refund）功能 - 撰寫台新 ONE 碼相關的單元測試或整合測試 - 理解 IPC 資料流（渲染端 store → Electron 主進程 → 台新 API）