管理後台與開發工具套件開發

管理後台與開發工具套件開發 是做什麼的？

此技能幫助您遵循既有模式，擴充管理後台並建構內部工具。

決策點

何時新增分頁 vs 修改端點 vs 建立新工具

新增管理功能：
├─ 使用者需要唯讀資料檢視？
│  ├─ 資料存在於目前 API？→ 修改現有分頁
│  ├─ 需要新的資料類型？→ 新增分頁 + 新端點
│  └─ 需要複雜分析？→ 建立專用分析分頁
│
├─ 使用者需要修改系統資料？
│  ├─ 簡單 CRUD 操作？→ 新增管理分頁
│  ├─ 需要批次操作？→ 建立維運主控台分頁
│  └─ 多步驟工作流程？→ 建構精靈元件
│
├─ 內部開發者工具？
│  ├─ 程式碼檢視/文件？→ 加入 /dev 入口
│  ├─ 系統監控？→ 加入 /ops 主控台
│  └─ 用戶支援工具？→ 加入管理後台
│
└─ 外部使用者功能？
   → 停止：請改用前端開發技能

分頁內容實作策略

分頁複雜度評估：
├─ 簡單統計顯示 (< 5 個指標)？
│  → 使用 StatCard 網格模式
│
├─ 含篩選功能的資料表格？
│  ├─ < 1000 行？→ 客戶端篩選
│  └─ > 1000 行？→ 伺服器端分頁 + 搜尋
│
├─ 即時監控？
│  ├─ 每 30 秒以上更新？→ 使用含重新整理間隔的 SWR
│  └─ 每 5 秒以下更新？→ 使用 WebSocket 連線
│
└─ 互動式控制項？
   ├─ 簡單開關/按鈕？→ 行內動作
   └─ 複雜表單？→ 模態對話框 + 確認流程

失敗模式

1. 資料庫查詢效能惡性循環

症狀： 管理後台逾時或載入緩慢（>5 秒） 偵測： 監控 /api/admin/* 回應時間 >3 秒 修正： 新增資料庫索引、實作分頁、快取彙總統計

-- 錯誤：全表掃描
SELECT COUNT(*) FROM pageViews WHERE userId = ?

-- 正確：使用索引時間範圍
SELECT COUNT(*) FROM pageViews WHERE createdAt > NOW() - INTERVAL 24 HOUR

2. 過期快取顯示錯誤資料

症狀： 管理員看到過時的指標，與近期活動不符 偵測： 使用者回報已知操作後統計數據未改變 修正： 在資料變動時實作快取失效，加上「最後更新」時間戳

// 為資料變動操作加入快取清除
await updateUserData(userId);
await revalidateTag('admin-stats'); // 清除快取

3. 稽核日誌遺漏

症狀： 管理員操作未記錄在 auditLog 表中 偵測： 檢查過去 24 小時內管理員操作的 auditLog 條目 修正： 在所有管理端點中加入 logAdminAction() 呼叫

// 每個管理端點必備
await logAdminAction(admin.id, AuditAction.USER_DATA_VIEW, 'users', userId);

4. HIPAA 違規資料暴露

症狀： 錯誤訊息、日誌或彙總檢視中出現受保護健康資訊（PHI） 偵測： 錯誤訊息包含用戶電子郵件/電話/醫療資料 修正： 淨化所有錯誤回應，在管理檢視中使用雜湊識別碼

// 錯誤：暴露用戶電子郵件
{ error: "User [email protected] not found" }

// 正確：使用匿名識別碼
{ error: "User ID hash_123abc not found" }

5. 管理員權限提升

症狀： 一般使用者可以存取管理端點 偵測： 非管理員用戶收到管理資料而非 403 錯誤 修正： 在每個管理端點的第一行加入 requireAdmin() 檢查

export async function GET(request: Request) {
  const admin = await requireAdmin(); // 必須是第一行
  if (!admin) return Response.json({ error: 'Forbidden' }, { status: 403 });
  // ... 其餘處理邏輯
}

工作範例

新增生產環境健康監控分頁

情境： 加入即時 API 健康監控，包含延遲指標、錯誤率與服務狀態。

1. 決策點導航：

• 使用者需要即時監控 → 使用 SWR 並設定 30 秒重新整理
• 系統資料，非用戶資料 → 加入管理後台
• 新的資料類型（API 指標） → 建立新分頁 + 端點

2. 實作步驟：

建立包含必要模式的端點：

// src/app/api/admin/health/route.ts
export async function GET(request: Request) {
  const admin = await requireAdmin(); // 安全優先
  if (!admin) return Response.json({ error: 'Forbidden' }, { status: 403 });
  
  const rateLimitResult = await rateLimiter.check(admin.id); // 速率限制
  if (!rateLimitResult.allowed) return Response.json({}, { status: 429 });
  
  await logAdminAction(admin.id, 'HEALTH_VIEW', 'metrics', null); // 稽核
  
  const metrics = await getHealthMetrics(); // 資料擷取
  return Response.json(metrics);
}

建立分頁元件：

function ProductionHealthTab() {
  const { data: health, error } = useSWR('/api/admin/health', fetcher, {
    refreshInterval: 30000 // 即時更新
  });
  
  return (
    <div className="space-y-6">
      <div className="grid grid-cols-4 gap-4">
        <StatCard label="API 正常運作時間" value="99.9%" status="good" />
        <StatCard label="平均延遲" value="45ms" trend="down" />
        <StatCard label="錯誤率" value="0.1%" status="warning" />
        <StatCard label="活躍服務" value="12/12" status="good" />
      </div>
    </div>
  );
}

3. 專家 vs 新手差異：

• 新手會遺漏： 稽核日誌、速率限制、HIPAA 安全錯誤處理
• 專家會抓到： 快取失效策略、效能監控設定、正確的錯誤邊界

品質關卡

• 管理員存取控制：requireAdmin() 檢查在管理員用戶通過，一般用戶失敗
• 速率限制：超過速率限制時端點回傳 429（預設 60 次/分鐘）
• 稽核日誌：管理員操作已記錄至 auditLog 表，包含正確的動作類型
• 效能基線：在實際資料量下，分頁載入時間 <2 秒
• HIPAA 合規：錯誤訊息或偵錯輸出中未暴露 PHI
• 資料驗證：無效請求回傳適當的 400 錯誤及安全訊息
• 快取行為：後端變更後，資料在 30 秒內更新
• 錯誤邊界：UI 能優雅處理 API 失敗，不會崩潰
• 行動裝置響應式：分頁佈局在平板尺寸（768px+）上正常工作
• 即時更新：自動重新整理在 10 分鐘以上不會造成記憶體洩漏

非適用範圍

請勿使用此技能處理：

• 外部使用者面向功能 → 使用 frontend-development 代替
• 驗證/登入流程 → 使用 auth-security 代替
• 資料庫結構變更 → 使用 database-operations 代替
• 電子郵件/通知系統 → 使用 communications 代替
• API 速率限制設定 → 使用 backend-api 代替
• HIPAA 合規設定 → 使用 security-compliance 代替
• 效能最佳化 → 使用 optimization 代替

有下列情況時，請委派給其他技能：

• 新增公開用戶功能 → frontend-development
• 修改用戶驗證 → auth-security
• 為外部使用建立新的 API 端點 → backend-api
• 設定監控基礎設施 → devops-infrastructure