Server Actions Reference

Server Actions（"use server"）在伺服器端執行，由 React 元件直接呼叫——它們就是瑞成 PMS 的真正 API。本頁是完整清單：46 個 action，依 OpenAPI 的 10 大領域分組（案件 / 業主 / 使用者 / 待辦 / 行事曆 / 分類 / 通知 / 帳戶 / 登入 / 管理）。

此清單對齊 next-app/lib/openapi/actions-manifest.ts（唯一真實來源；coverage.test.ts 斷言每個匯出的 action 都列於此，新 action 不會悄悄漏掉文件）。OpenAPI 文件共 47 paths = 1 個 GET /api/health
46 個 documentary RPC actions。

跨來源注意： Server Actions 無法跨來源呼叫。請在部署後的 app 同來源環境中操作，或用 /api-docs 瀏覽。

Response envelope — `ActionResult` / `FormState`

所有 action 回傳統一的 envelope（對應 lib/validations/types.ts，OpenAPI 中註冊為 ActionResult）：

type ActionResult =
  | { ok: true }                            // mutation 成功
  | { success: true }                       // form-action 模式成功
  | { error: string }                       // 人類可讀錯誤
  | { fieldErrors: Record<string, string[]> } // 依欄位驗證錯誤

所有 mutation（寫入）動作都會經 rcLog 寫入稽核日誌（toast 回饋「已寫入稽核日誌」），不可篡改、保存 10 年。

權限守衛速覽

伺服器端守衛在 lib/permissions.ts，依 lib/rc-permissions.ts 的 RC_PERM_MATRIX（10 旗標） 判斷，並 re-read 目前 DB 中的 live role（getLiveRole()）——降權立即生效，UI 隱藏不算安全控制。

守衛	通過角色
`requireAuth`	任何已登入使用者
`requireOperatorOrAdmin()` / `guard(flag)`	依旗標（多為 Admin + Operator）
`requireAdmin()`	僅 Admin

核心界線：進度數字（overridePct / editNodes）為 Admin（技師）專屬——行政（Operator）可代操作文書類動作，但不能決定進度 %。

案件（`actions/cases.ts`）

Action	說明	權限守衛	Mutation
`createCase`	建立工程案件（4 步精靈輸入）	`guard('createCase')` — Admin + Operator	✓
`editCase`	編輯案件名稱、期限、狀態、指派	`guard('createCase')` — Admin + Operator	✓
`voidCase`	軟刪除（作廢），必填原因，永不真刪	`guard('deleteData')` — Admin + Operator	✓
`restoreCase`	將作廢案件復原為「進行中」	`guard('deleteData')` — Admin + Operator	✓
`completeNode`	標記節點完成並推進 current-node 指標	`requireAuth` + 被指派技師或 `can('editNodes')` — Admin	✓
`updateProgress`	自填式進度 % 更新（必填備註）	`requireAuth` + isAssigned 或 `can('overridePct')` — Admin	✓
`markPrereq`	標記前置資料已到	`requireAuth` + `can('editPrereq')` 或 isAssigned	✓
`addPrereq`	新增前置資料項（NAS 連結）	`requireAuth` + `can('editPrereq')` 或 isAssigned	✓
`editPrereq`	編輯前置資料項	`requireAuth` + `can('editPrereq')` 或 isAssigned	✓
`deletePrereq`	刪除前置資料項	`requireAuth` + `can('deleteData')` — Admin + Operator	✓
`addSubcase`	為 B2 母案新增追加案（子案）	`guard('addSubcase')` — Admin + Operator	✓
`editSubcase`	編輯追加案	`guard('addSubcase')` — Admin + Operator	✓
`subStatusChange`	從列表列快速切換追加案狀態	`guard('addSubcase')` — Admin + Operator	✓
`deleteSubcase`	刪除追加案	`guard('deleteData')` — Admin + Operator	✓
`addNode`	為彈性混合式案件新增節點	`requireAuth` + `can('editNodes')` — Admin	✓

業主（`actions/clients.ts`）— CRM

Action	說明	權限守衛	Mutation
`createClient`	建立業主（客戶）紀錄	`guard('createCase')` — Admin + Operator	✓
`updateClient`	更新業主基本資料	`guard('createCase')` — Admin + Operator	✓
`deleteClient`	刪除業主（有案件綁定則阻擋）	`guard('deleteData')` — Admin + Operator	✓
`updateContact`	編輯業主聯絡窗口	`guard('createCase')` — Admin + Operator	✓
`toggleContactResign`	聯絡窗口離職／復職切換	`guard('createCase')` — Admin + Operator	✓
`deleteContact`	刪除業主聯絡窗口	`guard('deleteData')` — Admin + Operator	✓

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

使用者（`actions/user.ts`）— 自身帳號

Action	說明	權限守衛	Mutation
`updateProfile`	更新自己的顯示名稱 / avatar	`requireAuth`（限本人）	✓
`changePassword`	變更自己的密碼	`requireAuth`（限本人）	✓

待辦（`actions/todos.ts`）— 我的待辦

Action	說明	權限守衛	Mutation
`completeTodoNode`	依名稱完成待辦節點（解析 name→id 後委派 `completeNode`）	`requireAuth` + 被指派技師或 `can('editNodes')`	✓
`markTodoPrereq`	依名稱標記待辦前置已到（委派 `markPrereq`）	`requireAuth` + `can('editPrereq')` 或 isAssigned	✓

行事曆（`actions/calendars.ts`）— 業主工作日曆

Action	說明	權限守衛	Mutation
`createCalendar`	建立自訂工作日曆	`guard('createCase')` — Admin + Operator	✓
`updateCalendar`	編輯工作日曆（含預設）	`guard('createCase')` — Admin + Operator	✓
`deleteCalendar`	刪除自訂工作日曆（預設與使用中阻擋）	`guard('deleteData')` — Admin + Operator	✓

分類（`actions/categories.ts`）— 分類與節點樣板

Action	說明	權限守衛	Mutation
`editNodeTemplate`	編輯節點樣板（內建或 B3 子樣板）	`guard('manageTemplates')` — Admin only	✓
`createCustomType`	建立自訂案件分類（Sn 碼自動指派）	`guard('manageTemplates')` — Admin only	✓
`updateCustomType`	編輯自訂分類（code 不可改）	`guard('manageTemplates')` — Admin only	✓
`deleteCustomType`	刪除自訂分類（內建與使用中阻擋）	`guard('manageTemplates')` — Admin only	✓
`listTemplateItems`	列出某樣板的所有節點項（唯讀查詢 helper）	none（server component helper）	—

通知（`actions/notifications.ts` · `actions/notifications-scan.ts`）

Action	說明	權限守衛	Mutation
`markRead`	標記單一通知已讀（限本人）	`requireAuth`（限自己的通知）	✓
`markAllRead`	標記目前使用者所有未讀為已讀	`requireAuth`	✓
`runNotificationScanCore`	燈號掃描核心邏輯（去重 upsert，可帶 today override 供測試/排程）	none（內部——由 `runNotificationScan` 與 cron 呼叫，此層無 auth 守衛）	✓
`runNotificationScan`	Admin 手動觸發燈號掃描；re-read live role、寫稽核、revalidate dashboard	`requireAdmin()` — Admin only	✓

通知為系統內鈴鐺，不寄 Email / LINE。每日 02:00 自動掃描，詳見架構：燈號預警引擎。

帳戶（`actions/accounts.ts`）— 工牌帳號管理

Action	說明	權限守衛	Mutation
`createUser`	建立工牌登入帳號（工牌自動指派，上限 30 人）	`guard('manageUsers')` — Admin + Operator	✓
`updateUser`	編輯帳號姓名 / 職稱 / 角色	`guard('manageUsers')` — Admin + Operator	✓
`disableUser`	軟停用（離職）帳號；不可停用自己；永不真刪	`guard('manageUsers')` — Admin + Operator	✓
`enableUser`	重新啟用先前停用的帳號	`guard('manageUsers')` — Admin + Operator	✓

登入（`actions/auth.ts`）— 認證

Action	說明	權限守衛	Mutation
`loginAction`	以工牌編號 + 密碼登入	public（未認證）	✓
`handleSignOut`	登出目前使用者	`requireAuth`（任何已登入使用者）	✓
`requestPasswordReset`	以 email 要求重設密碼連結（一律回成功以防列舉）	public（未認證）	✓
`resetPassword`	以重設信中的 token 完成重設密碼	public（token-gated）	✓

管理（`actions/admin.ts`）— 僅 Admin

Action	說明	權限守衛	Mutation
`exportAuditLog`	將不可篡改的稽核日誌匯出為 CSV（保存 10 年）	`requireAdmin()` — Admin only	—

計數核對

領域	Actions
案件	15
業主	6
使用者	2
待辦	2
行事曆	3
分類	5
通知	4
帳戶	4
登入	4
管理	1
合計	46

Server Actions Reference ​

Response envelope — ActionResult / FormState ​

權限守衛速覽 ​

案件（actions/cases.ts） ​

業主（actions/clients.ts）— CRM ​

使用者（actions/user.ts）— 自身帳號 ​

待辦（actions/todos.ts）— 我的待辦 ​

行事曆（actions/calendars.ts）— 業主工作日曆 ​

分類（actions/categories.ts）— 分類與節點樣板 ​

通知（actions/notifications.ts · actions/notifications-scan.ts） ​

帳戶（actions/accounts.ts）— 工牌帳號管理 ​

登入（actions/auth.ts）— 認證 ​

管理（actions/admin.ts）— 僅 Admin ​

計數核對 ​