API 參考 (API Reference)

瑞成 PMS 是單一 Next.js 16 app — 沒有獨立的 API server。它對外有 兩種介面：

1. 真實 HTTP Route Handlers（app/api/**）— 可用 fetch 呼叫的少數端點。
2. 真正的「API」其實是 ~46 個 Server Actions（actions/*.ts）— 以 documentary RPC 的形式記錄為 POST /actions/{domain}/{name}。

⚠️ 本服務採用 Server Actions（RPC），非 REST。 除了 GET /api/health 這個唯一的真實 REST 端點外，所有操作在傳輸層皆為 POST —— 這是 Next.js 對 Server Action 的固定行為（加密 form-post，沒有 GET/PUT/DELETE 之分），不是錯誤、也不是文件渲染問題。

---

互動式 API 文件（建議從這裡開始）

完整、可瀏覽、隨程式碼自動同步的 API 介面在 app 內 提供，由 Zod schema 驅動（drift-guarded）：

介面	路徑	內容
Scalar 互動式文件	/api-docs	渲染後的 OpenAPI 介面（含所有 Server Actions 分組）
原始 OpenAPI 描述	/api/openapi	OpenAPI 3.1 JSON（~47 paths：1 health + 46 actions）

dev 站直接連結： https://dev-pms.rei-chen.com/api-docs

/api-docs 與 /api/openapi 由 ENABLE_API_DOCS 這個 runtime env（非 NEXT_PUBLIC_*，切換免重 build）控制： dev / stg 開啟、prd 回 404。OpenAPI 文件由 pnpm openapi:generate（在 next-app/）從 Zod 生成至 docs/openapi.yaml，永不手改；scripts/smoke.sh 的 drift gate 會在它過期時失敗。

---

一、真實 HTTP Route Handlers

所有 Route Handler 端點都相對於你部署後的 Next.js app URL（見下方 playground 設定 base URL）。

Health

Method	Path	說明
GET	/api/health	Health check — 回傳 { status: "ok", timestamp }，供 smoke test / uptime monitor 使用

OpenAPI

Method	Path	說明
GET	/api/openapi	回傳 OpenAPI 3.1 描述文件（dev/stg；prd 回 404）

Auth（Auth.js v5，工牌登入）

Auth.js 在 /api/auth/[...nextauth] 下提供 framework-owned 端點（不在 OpenAPI 文件中）。瑞成 PMS 以 工牌編號 + 密碼（Credentials provider）登入，沒有 OAuth、沒有金流 webhook（billing 功能已從產品移除）。

Method	Path	說明
GET	/api/auth/session	取得目前 session
POST	/api/auth/signin	以工牌編號 + 密碼登入
POST	/api/auth/signout	登出
GET	/api/auth/csrf	表單用 CSRF token

詳見 Auth Endpoints。

---

二、Server Actions = 真正的 API（documentary RPC）

系統的絕大多數讀寫由 React Server Component 直接 fetch + ~46 個 Server Actions 完成。它們在 OpenAPI 文件中 被記錄為 POST /actions/{domain}/{name}，這些路徑僅供文件瀏覽分組，不是 live HTTP endpoint、無法 try-it-out （Next.js 會加密實際的 wire format）。

全 POST / RPC 模型

CRUD 的語意在 「操作名稱」，不在 HTTP 動詞：

你想做的事	對應 action（名稱即意圖）
建立案件	createCase
編輯案件	editCase
作廢案件（軟刪除）	voidCase
復原案件	restoreCase
完成節點	completeNode

完整 46 個 action 依 10 大領域分組見 Server Actions Reference。

Response 契約：ActionResult / FormState

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

// 成功
{ ok: true }        // mutation actions
{ success: true }   // form-action 模式

// 失敗
{ error?: string }                              // 人類可讀錯誤訊息
{ fieldErrors?: Record<string, string[]> }      // 依欄位的驗證錯誤

所有寫入動作都會經 rcLog 寫入稽核日誌（toast 回饋「已寫入稽核日誌」），詳見 Server Actions Reference 與 架構 (Architecture)。

---

Base URL

所有 Route Handler 端點都相對於你部署後的 Next.js app URL。在下方 playground 設定 base URL。

Interactive Playground

設定你部署後的 Next.js app URL，即可發送真實 HTTP 請求：

GET/api/healthGET /api/healthGET /api/auth/sessionPOST /api/auth/signin

Base URL (your deployed Next.js app)

Authorization Header (optional)

Try in Live App →

跨來源注意： Server Actions 無法跨來源呼叫，由 React 元件在伺服器端直接 invoke。從本文件站發出的 跨來源請求不會自動帶 session cookie；請在部署後的 app 同來源環境測試（或用上方 /api-docs）。

Authentication

大多數操作需要有效的 Auth.js session（工牌登入後自動設定的 httpOnly cookie）。

1. 以 POST /api/auth/signin 帶 { badge, password } 登入取得 session cookie
2. 以 GET /api/auth/session 檢視目前 session
3. 後續同來源請求會自動帶上 session cookie

伺服器端的權限守衛會 re-read 目前 DB 中的 live role（getLiveRole()），詳見 Auth Endpoints 與 架構：Auth + RBAC。