🎛️ PANDUAN TEKNIS & ARSITEKTUR MASTER KILL-SWITCH AI ASSISTANT CONTROL

Proteksi Kuota Serverless Vercel, Sinkronisasi Multi-Device & Tata Kelola AI Terpadu#

[!IMPORTANT] KLASIFIKASI DOKUMEN: TEKNIKAL INTERNAL / PRIVAT SUPER ADMIN & DIREKSI Dokumen ini menjelaskan mekanisme arsitektur saklar terpusat (Global Kill-Switch) pada modul AI Assistant Control ERP BUMDes. Sistem ini dirancang untuk mencegah kebocoran kuota komputasi serverless Vercel dan konsumsi token Google Gemini secara instan dan menyeluruh.

---

1. Latar Belakang & Filosofi Tata Kelola AI#

Sebelum audit Oktober 2026, tombol AI Assistant Control pada menu Preferensi Sistem hanya berfungsi sebagai pengubah nilai lokal di peramban (localStorage). Kondisi tersebut menimbulkan masalah besar:

1. Kebocoran Kuota Serverless: Server Component (SSR) pada laporan keuangan Neraca, Laba Rugi, dan Arus Kas tetap memanggil Google Gemini di setiap kunjungan halaman meskipun tombol berstatus NON-AKTIF.
2. Desinkronisasi Antar Perangkat: Penonaktifan AI oleh Super Admin di komputer kantor tidak berpengaruh ke komputer unit usaha, tablet kasir POS, atau sesi peramban lain.
3. Ketiadaan Audit Trail: Mutasi status AI tidak terekam pada basis data audit sistem.

Melalui restrukturisasi Grand Standard v2026.2, AI Assistant Control ditingkatkan statusnya menjadi Master Kill-Switch Ekosistem. Ketika dinonaktifkan, seluruh jalur eksternal ke Google Generative AI diputus seketika pada level kode inti dengan latensi nol milidetik.

---

2. Diagram Arsitektur Terpadu (Data & Control Flow)#

Memuat diagram alur...

---

3. Single Source of Truth & Persistensi Supabase#

Pusat kendali status AI disimpan secara persisten di tabel public_content Supabase dengan slug = 'site.preferences':

json
{
 "language": "id",
 "timezone": "GMT+8",
 "isAIEnabled": false,
 "default_map_lat": 0.6185038605613407,
 "default_map_lng": 123.06575026105962
}

Server Action Terpusat: lib/actions/ai-control.ts

Fungsi-fungsi inti yang mengontrol status AI:

• isSystemAIEnabled(): Promise<boolean> Membaca status AI menggunakan mekanisme unstable_cache Next.js dengan masa berlaku (TTL) 30 detik atau direvalidasi seketika menggunakan tag ai_system_control. Fungsi ini sangat ringan dan aman dipanggil ratusan kali oleh Server Actions, Server Components, maupun API Routes.
• updateAISystemStatus(enabled: boolean) Memvalidasi hak akses pengguna (super_admin, admin_keuangan, atau direktur), memperbarui kolom isAIEnabled pada konten preferensi situs, mencatat entri riwayat pada audit_logs, dan merevalidasi seluruh jalur halaman terkait (revalidatePath('/')).

---

4. Mekanisme Hard Kill-Switch di Core Engine#

Sebelum ada panggilan fungsi yang menghubungi jaringan eksternal Google Generative AI, gerbang utama pada lib/ai/gemini-client.ts melakukan intersepsi:

typescript
export async function generateAIContent(prompt: string | any[], options: AIOptions = {}) {
 // 0. Hard Kill-Switch Check
 try {
 const { isSystemAIEnabled } = await import('@/lib/actions/ai-control')
 const isAIActive = await isSystemAIEnabled()
 if (!isAIActive) {
 console.info('[AI Kill-Switch Active] Panggilan Gemini dibatalkan karena AI Assistant non-aktif.')
 if (options.useJson) {
 return {
 disabled: true,
 ai_disabled: true,
 holdingHealthScore: 85,
 holdingSolvencyStatus: 'STABLE',
 riskAlerts: ['Fitur AI Assistant sedang dinonaktifkan oleh administrator sistem.'],
 crossUnitSynergyRecommendations: [],
 workingCapitalAdvice: 'Sistem beroperasi normal dalam mode standar tanpa rekomendasi AI.',
 title: "Fitur AI Dinonaktifkan",
 narrative: "Asisten analitik AI sedang dinonaktifkan oleh Administrator Sistem.",
 sentiment: "neutral"
 }
 }
 return "Fitur AI Assistant saat ini sedang dinonaktifkan oleh Administrator BUMDes melalui Pengaturan Sistem."
 }
 } catch (checkErr) {
 console.warn('Gagal memeriksa status AI Kill-Switch, melanjutkan secara hati-hati:', checkErr)
 }

 // Eksekusi pemanggilan Gemini API jika AI aktif...
}

---

5. Optimasi SSR & Eliminasi Pembengkakan Kuota Vercel#

A. Bypass Laporan Keuangan (lib/actions/ai_finance_narrative.ts)

Setiap kali laporan keuangan Neraca, Laba Rugi, atau Arus Kas dibuka, fungsi narasi AI memeriksa status saklar terlebih dahulu. Jika isSystemAIEnabled() bernilai false, sistem langsung mengembalikan narasi berbasis aturan (rule-based fallback) standar SAK EP:

• Keuntungan Waktu Render: Menghilangkan penundaan 3–5 detik pemanggilan AI pada proses Server-Side Rendering (SSR).
• Keuntungan Kuota Vercel: Mencegah eksekusi serverless function duration yang sebelumnya menghabiskan puluhan gigabyte-jam kuota bulanan.

B. Bypass Halaman AI Analytics (app/dashboard/ai-analytics/page.tsx)

Jika AI berstatus NON-AKTIF, SSR pada rute /dashboard/ai-analytics secara otomatis melewati 8 query analitik berat ke tabel inventori, peternakan, performa unit, dan tren finansial, sehingga halaman termuat dalam waktu kurang dari 15 milidetik.

---

6. Protokol Sinkronisasi Multi-Device & Server Hydration#

1. Hydration Bersih di app/dashboard/layout.tsx: Layout membaca isSystemAIEnabled() langsung di server dan meneruskannya ke <AIConfigProvider initialEnabled={isAIEnabled}>.
2. Kesesuaian di Sisi Klien (AIConfigProvider.tsx): Provider mendengarkan perubahan prop dari server dan menyelaraskan localStorage peramban. Jika terjadi perubahan di satu perangkat, perangkat lain akan menerima nilai terkini saat memuat ulang halaman.
3. Penyelamatan Kegagalan Jaringan (Rollback Guard): Jika pengguna mengklik toggle tetapi terjadi kendala koneksi atau ditolak oleh izin RBAC, antarmuka akan membatalkan perubahan secara otomatis (optimistic rollback) dan menampilkan peringatan galat.

---

7. Tata Kelola Akses (RBAC) & Audit Trail#

A. Hak Akses Saklar

B. Format Rekaman audit_logs

Setiap mutasi status saklar dicatat secara permanen:

• actor_id: ID Pengguna yang melakukan perubahan.
• action: 'UPDATE_AI_CONTROL'.
• module: 'SYSTEM_SETTINGS'.
• details:

json
{
"isAIEnabled": false,
"action_description": "Menonaktifkan seluruh modul AI (Kill-Switch)",
"actor_name": "Ansor (Super Admin)",
"actor_role": "super_admin",
"timestamp": "2026-10-21T00:55:00.000Z"
}

---

8. Matriks Cakupan 12 Modul AI Terkoneksi#

---

9. Panduan Pengembang (Developer Checklist Modul AI Baru)#

Setiap pengembang yang menambahkan fitur AI baru di ekosistem ERP BUMDes wajib mematuhi checklist kepatuhan berikut:

1. Client Component: Gunakan hook useAIConfig() dari @/components/providers/AIConfigProvider:

tsx
const { isAIEnabled } = useAIConfig()
if (!isAIEnabled) return null // atau tampilkan banner fallback

2. Server Action: Sebelum memanggil model atau fungsi eksternal, validasi status saklar:

typescript
import { isSystemAIEnabled } from '@/lib/actions/ai-control'
if (!(await isSystemAIEnabled())) {
return { success: false, message: 'AI sedang dinonaktifkan.' }
}

3. Panggilan Inti: Selalu gunakan pembungkus resmi generateAIContent dari @/lib/ai/gemini-client yang telah dilengkapi proteksi hard kill-switch otomatis. Jangan pernah menginisialisasi pustaka @google/generative-ai secara mandiri di luar modul inti.

---

Disahkan oleh Tim Arsitektur Sistem ERP BUMDes Mandiri Bolulango.