Server Actions Reference

Server Actions（"use server"）在伺服器端執行，由 React 元件直接呼叫。

跨來源注意： Server Actions 無法跨來源呼叫。請在部署後的 app 同來源環境中操作，或用上方 API 端點做跨來源存取。

Result envelope

瑞成 PMS 的 Server Actions 多回傳一個 Result 物件（成功 / 失敗 + 訊息）：

type Result =
  | { ok: true }
  | { ok: false; error: string }

所有寫入動作都會經 rcLog 寫入稽核日誌（toast 回饋「已寫入稽核日誌」）。

案件 Actions（actions/cases.ts）

依角色與 RC_PERM_MATRIX 旗標守衛。進度 % 覆寫他人僅 admin（技師） — 行政（operator）不可填進度。

createCase(input): Promise<Result>          // 4 步精靈建檔
editCase(id, input): Promise<Result>
voidCase(id, reason): Promise<Result>       // 軟刪除（作廢），必填原因，可復原
restoreCase(id): Promise<Result>
updateProgress(caseId, pct, note): Promise<Result>   // 自填式，必填備註
completeNode(caseId, nodeId): Promise<Result>        // 節點式
addPrereq / editPrereq / markPrereq / deletePrereq(...)          // 前置資料（NAS 連結）
addSubcase / editSubcase / subStatusChange / deleteSubcase(...)  // B2 母子追加案（不計進度 %）
addNode(caseId, input): Promise<Result>     // 彈性混合式可新增節點

業主 CRM Actions（actions/clients.ts）

createClient / editClient / deleteClient(...)   // 刪除限無任何案件綁定
addContact / editContact / setContactStatus / deleteContact(...)  // 含離職／復職

一般人員（staff）對 CRM 唯讀。

待辦與系統設定

// actions/todos.ts — 我的待辦（節點 / 前置 / 進度任務）
// actions/categories.ts — 自訂分類 CRUD（內建六大分類不可刪）
// actions/calendars.ts — 業主工作日曆 CRUD（預設不可刪、有業主套用不可刪）

帳號管理 Actions（actions/accounts.ts）

全部守衛 manageUsers 旗標（從 DB re-read live role）。停用為軟刪除（可復原），不可停用自己。

createUser(input): Promise<Result>
updateUser(badge, input): Promise<Result>
disableUser(badge): Promise<Result>        // 軟刪除（停用），可復原
enableUser(badge): Promise<Result>
resetPassword(badge, newPassword): Promise<Result>   // 管理員重設密碼，bcrypt 雜湊

resetPassword（E302）： 由 adminResetPasswordSchema（lib/validations/engineering.ts）驗證工牌 + 密碼強度，以 hashPassword（bcrypt）寫入 usersTable.passwordHash，並寫一筆「重設密碼」rcLog 稽核 — 稽核列不記錄任何密碼明文或雜湊值。因工牌帳號的 email 為合成 @rc.local，/forgot-password 郵件重設無法送達，管理員重設為實務上的密碼救援路徑。

稽核與通知

// actions/admin.ts — 稽核日誌讀取（僅 admin，可篩選 + 匯出 CSV，永久不可刪）
// actions/notifications.ts — 系統內通知鈴鐺（不寄 Email）
// actions/notifications-scan.ts — 每日 02:00 燈號掃描