server-api

Server API 設計規範

依實際安裝的 Nuxt／DB／auth 模組選用。Supabase helper（requireRole、getSupabaseWithContext 等）是 consumer 自己實作的函式，使用前查其來源與授權行為。

Client 端寫入預設走 Server API

Client 端（app/ 目錄）的讀取路徑依 consumer manifest（canonical .clade/manifest.json；canonical 缺席的未遷移 consumer 讀 legacy .claude/hub.json）的 modules.auth 而定：

• modules.auth 是 Supabase Auth（supabase-self-hosted）→ 預設只透過 useSupabaseClient<Database>() 執行 .select() 查詢。
• modules.auth 是 nuxt-auth-utils / better-auth → Supabase 不簽 JWT，瀏覽器的 useSupabaseClient() 恆以 anon role 存取，登入與否都一樣 —— 要讓 client 讀得到就得把表開成 TO public，等於對任何持有 publishable key 的人公開。那些 auth stack 下 client 直讀不是預設：讀寫都走 /api/v1/*，client 端 Supabase 只留 Storage（bucket policy 獨立）。見 [[auth-data-path-consistency]] § Auth 策略與資料路徑的合法組合。

所有寫入操作預設必須透過 Server API（/api/v1/*）：

// ❌ 預設不允許 — client 端直接寫入
const client = useSupabaseClient<Database>();
await client.from("posts").insert({ title: "Hello" });

// ✅ 正確 — 透過 Server API
await $fetch("/api/v1/posts", {
  method: "POST",
  body: { title: "Hello" },
});

Client 端寫入是架構例外，只有在 proposal / ADR 明確記錄並同時滿足下列條件時，才可在 client 使用 .insert() / .update() / .delete() / .upsert()：

• RLS policy 能完整表達 tenant / user scope 與所有授權規則
• GRANT 只開必要 schema / table / operation，不給寬權限
• 不需要 service_role、server-only secret、跨表 transaction、workflow transition、audit-chain、storage upload 或外部 API
• 不涉及角色 / 權限、薪資、簽核、出勤、稽核、批次修復等敏感流程
• 有 focused tests 驗證 allow path、deny path、tenant isolation 與 RLS 失敗時的 UI/錯誤處理

契約來源

新增 API 時，request/response schema 請定義在 shared/schemas/，並由同一個模組導出衍生型別。

• shared/schemas/*.ts：Zod schema + 衍生型別
• shared/types/*.ts：相容轉發或 UI/view-model 型別，不是新的 request/response 真相來源

選填欄位的 Null 慣例（Hard Rule）

接收 user input 的選填欄位 MUST 用 .nullish()，NEVER 只用 .optional()。

// ❌ 錯誤 — 只接受 string | undefined
const schema = z.object({
  return_notes: z.string().trim().max(500).optional(),
})
// Client 送 { return_notes: null } → 400 ZodError