server/api/
├── v1/                       # 版本化業務 API
│   └── resources/
│       ├── index.get.ts      # GET /api/v1/resources（列表）
│       ├── index.post.ts     # POST /api/v1/resources（新增）
│       └── [id]/
│           ├── index.get.ts     # GET /api/v1/resources/:id
│           ├── index.patch.ts   # PATCH /api/v1/resources/:id
│           └── index.delete.ts  # DELETE /api/v1/resources/:id
├── auth/                     # 認證 API
└── admin/                    # 管理員 API

// server/api/v1/resources/index.get.ts
import { getSupabaseWithContext, requireRole } from '~~/server/utils/supabase'
import { resourceListQuerySchema } from '~~/shared/types/resources'

export default defineEventHandler(async (event) => {
  // 1. 權限檢查（放在最前面）
  await requireRole(event, ['admin', 'manager', 'staff'])

  // 2. 驗證請求資料
  const query = await getValidatedQuery(event, resourceListQuerySchema.parse)

  // 3. 取得 Supabase Client
  const supabase = await getSupabaseWithContext(event)
  const db = supabase.schema('your_schema')

  // 4. 執行查詢
  const { data, count, error } = await db
    .from('resources')
    .select('*', { count: 'exact' })
    .is('deleted_at', null)

  // 5. 錯誤處理
  if (error) {
    throw createError({ statusCode: 500, message: '載入資料失敗' })
  }

  // 6. 回應
  return {
    data: data || [],
    pagination: {
      page: query.page,
      pageSize: query.pageSize,
      total: count || 0,
      totalPages: Math.ceil((count || 0) / query.pageSize),
    },
  }
})

// shared/types/resources.ts
import { z } from 'zod'

// 共用分頁查詢 Schema
export const paginationQuerySchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  pageSize: z.coerce.number().int().positive().max(1000).default(10),
  search: z.string().optional(),
  sortBy: z.string().optional(),
  sortDir: z.enum(['asc', 'desc']).default('desc'),
})

// 新增資源 Schema
export const createResourceSchema = z.object({
  name: z.string().min(1, '名稱必填').max(200),
  description: z.string().max(500).nullable().optional(),
})

// 更新資源 Schema（所有欄位變成可選）
export const updateResourceSchema = createResourceSchema.partial()

// GET 請求：驗證 Query Parameters
const query = await getValidatedQuery(event, resourceListQuerySchema.parse)

// POST/PATCH 請求：驗證 Request Body
const body = await readValidatedBody(event, createResourceSchema.parse)

// 路徑參數驗證
const params = await getValidatedRouterParams(
  event,
  z.object({ id: z.coerce.number().int().positive() }).parse
)

import { requireRole } from '~~/server/utils/supabase'

// 要求特定角色
const user = await requireRole(event, ['admin', 'manager'])

// 角色階層
// admin    → 完整系統管理權限
// manager  → 部門管理、資料 CRUD
// staff    → 基本資料讀取

return {
  data: items,
  pagination: {
    page: query.page,
    pageSize: query.pageSize,
    total: count || 0,
    totalPages: Math.ceil((count || 0) / query.pageSize),
  },
}

setResponseStatus(event, 201)
return { data: newItem }

return {
  data: {
    id: params.id,
    deleted_at: result.deleted_at,
    hard_deleted: false,
  },
}

// 處理唯一約束違反
if (error?.code === '23505') {
  throw createError({
    statusCode: 409,
    message: '此代碼已被使用',
  })
}

// 資源不存在
if (!data) {
  throw createError({
    statusCode: 404,
    message: '找不到指定的資源',
  })
}

await db.from('operation_logs').insert({
  user_id: user.id,
  action: 'create', // create | update | delete
  target_type: 'resource',
  target_id: newItem.id.toString(),
  details: body,
})

// 計算 range
const from = (query.page - 1) * query.pageSize
const to = from + query.pageSize - 1

// 建立查詢
let dbQuery = db.from('resources').select('*', { count: 'exact' }).is('deleted_at', null)

// 搜尋
if (query.search) {
  const searchStr = `%${query.search}%`
  dbQuery = dbQuery.or(`name.ilike.${searchStr},code.ilike.${searchStr}`)
}

// 排序
dbQuery = dbQuery.order(query.sortBy || 'id', { ascending: query.sortDir === 'asc' })

// 分頁
const { data, count, error } = await dbQuery.range(from, to)