🛡️ BLUEPRINT SISTEM AUDIT TRAIL & LOG AKTIVITAS FORENSIK

Standar Tata Kelola, Jejak Digital, dan Pengawasan Mutasi Sistem ERP BUMDes#

BUMDes Bolulango — Kabupaten Boalemo, Gorontalo Standar Kepatuhan Permendesa PDTT No. 3/2021, SAK EP, & Standar Pengawasan BPKP / Inspektorat Daerah

---

🏛️ 1. Latar Belakang & Urgensi Tata Kelola#

Dalam tata kelola keuangan dan operasional badan usaha milik desa yang mengelola 25+ unit usaha produktif, transparansi dan non-repudiation (asas tidak dapat disangkal) merupakan prasyarat mutlak akuntabilitas publik.

Setiap mutasi data sensitif, seperti:

1. Perubahan & Penghapusan Jurnal Keuangan: Risiko manipulasi saldo atau penghapusan transaksi mencurigakan.
2. Pembatalan / Tutup Buku (Period Closing & Reopening): Tindakan membuka kembali periode yang sudah ditutup untuk memasukkan data historis atau perbaikan pembukuan.
3. Pemberian & Perubahan Peran Pengguna (Privilege Escalation): Pengubahan wewenang kasir, admin gudang, atau bendahara.
4. Restrukturisasi & Penghapusbukuan Piutang (USP): Tindakan write-off pinjaman macet yang rawan penyalahgunaan wewenang.

Untuk mencegah terjadinya kecurangan (fraud), sistem ERP BUMDes Bolulango mengimplementasikan Modul Audit Trail & Log Aktivitas Forensik berbasis tabel public.audit_logs dengan perlindungan ketat di tingkat basis data.

Memuat diagram alur...

---

🗄️ 2. Struktur Basis Data & Model Data (audit_logs)#

Tabel audit_logs didesain secara append-only (hanya bisa menambah record, tidak diizinkan pengeditan manual).

2.1. Skema Tabel PostgreSQL

sql
CREATE TABLE IF NOT EXISTS public.audit_logs (
 id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
 actor_id UUID REFERENCES public.profiles(id) ON DELETE SET NULL,
 action VARCHAR(64) NOT NULL,
 module VARCHAR(64) NOT NULL,
 details JSONB DEFAULT '{}'::jsonb,
 status VARCHAR(20) DEFAULT 'success',
 ip_address VARCHAR(45) NULL,
 created_at TIMESTAMPTZ DEFAULT NOW()
);

2.2. Indeks Kinerja Kueri Forensik & Skalabilitas (Migrasi 207)

Untuk mengantisipasi ingesti dan migrasi massal ribuan data transaksi tanpa degradasi performa atau full-table scan:

sql
-- 1. Index Kronologis Utama (Latency O(log N) ~1-2ms)
CREATE INDEX IF NOT EXISTS idx_audit_logs_created_at 
 ON public.audit_logs (created_at DESC);

-- 2. Index Komposit Modul & Kronologis
CREATE INDEX IF NOT EXISTS idx_audit_logs_module_created 
 ON public.audit_logs (module, created_at DESC);

-- 3. Index Komposit Pelaku / Operator
CREATE INDEX IF NOT EXISTS idx_audit_logs_actor_created 
 ON public.audit_logs (actor_id, created_at DESC);

-- 4. Index B-Tree Aksi Mutasi
CREATE INDEX IF NOT EXISTS idx_audit_logs_action 
 ON public.audit_logs (action);

-- 5. Partial Index Aksi Kritis & Anomali Error
CREATE INDEX IF NOT EXISTS idx_audit_logs_critical 
 ON public.audit_logs (created_at DESC) 
 WHERE action IN ('DELETE', 'UPDATE', 'VOID', 'MIGRATION_MODE_TOGGLE') OR status = 'error';

-- 6. Index GIN untuk Penelusuran Payload JSONB (jsonb_path_ops)
CREATE INDEX IF NOT EXISTS idx_audit_logs_details_gin 
 ON public.audit_logs USING GIN (details jsonb_path_ops);

2.3. Kamus Data Atribut

---

🔐 3. Arsitektur Keamanan & Kebijakan Row-Level Security (RLS)#

3.1. Klasifikasi RLS Tier 5 (Admin-Only / Service-Role)

Tabel audit_logs digolongkan ke dalam Tier 5 RLS, di mana tidak ada kebijakan baris publik (no user row policies). Artinya:

• Pengguna biasa (koneksi anon / authenticated standar) secara mutlak tidak dapat membaca maupun memanipulasi tabel audit_logs.
• Kueri pembacaan dan penulisan hanya dapat dijalankan melalui createAdminClient() yang diverifikasi di sisi server (Server Action) setelah melewati pengecekan peran pengguna.

3.2. Implementasi Server Action Terpusat (audit.ts)

typescript
import { createAdminClient } from '@/lib/supabase/service'
import { getCurrentUser } from '@/lib/auth'

// 1. Kueri Ringan Cepat (Dashboard Summary)
export async function getAuditLogs(limit = 500) {
 const user = await getCurrentUser()
 const allowedRoles = [
 'super_admin', 'admin_keuangan', 'direktur', 
 'pengawas', 'pengawas_1', 'pengawas_2', 
 'pendamping_desa', 'bendahara_desa', 'auditor'
 ]

 if (!user?.profile?.role || !allowedRoles.includes(user.profile.role)) {
 return []
 }
 
 const supabase = createAdminClient()
 const { data, error } = await supabase
 .from('audit_logs')
 .select(`*, profiles (full_name, role)`)
 .order('created_at', { ascending: false })
 .limit(limit)

 return error ? [] : (data || [])
}

// 2. Kueri Enterprise Server-Side Pagination (100k+ Record Skalabilitas Bebas Lag)
export async function getPaginatedAuditLogs(options?: {
 page?: number
 pageSize?: number
 category?: string
 severity?: 'all' | 'critical'
 search?: string
}) {
 // Validasi otorisasi RBAC (Pengawas & Eksekutif)
 const user = await getCurrentUser()
 const allowedRoles = ['super_admin', 'admin_keuangan', 'direktur', 'pengawas', 'pengawas_1', 'pengawas_2', 'pendamping_desa', 'bendahara_desa', 'auditor']
 if (!user?.profile?.role || !allowedRoles.includes(user.profile.role)) {
 return { logs: [], totalCount: 0, totalPages: 0, currentPage: 1, pageSize: 25 }
 }

 const supabase = createAdminClient()
 // Kueri dengan index B-Tree created_at, category in/module filter, partial critical index, dan .range(from, to)
 // ...
}

3.3. Perluasan Akses Pengawasan & Segregation of Duties (SoD)

Berdasarkan amanat PP 11/2021 tentang Badan Usaha Milik Desa, peran Pengawas BUMDes (pengawas, pengawas_1, pengawas_2) serta perangkat pengawasan desa (pendamping_desa, bendahara_desa, auditor) memiliki kedudukan independen:

1. Hak Akses Penuh Log Forensik: Pengawas dapat meninjau seluruh mutasi sistem, riwayat transaksi finansial, pergantian peran, serta sesi masuk/keluar di seluruh unit usaha.
2. Pemisahan Tugas Mutlak (Segregation of Duties): Pengawas tidak memiliki hak mutasi pada akun pengguna (registerUser, updateUser, deleteUser, updateUserRole, resetUserPassword). Antarmuka sistem secara otomatis beralih ke Mode Pengawasan Read-Only dan menonaktifkan seluruh tombol aksi modifikasi.
3. Navigasi Khusus: Pada bilah sisi (Sidebar), pengawas diberikan menu langsung Audit & Pengawasan → Log Audit & Forensik yang langsung mengarah ke tab audit tanpa membuka pengaturan teknis lainnya.

3.4. Hooking Siklus Hidup Autentikasi & Forensik Jaringan

Sistem merekam setiap interaksi sesi akun secara otomatis dan non-blocking:

1. Login Berhasil (recordAuthLogin): Mencatat actor_id, alamat IP klien via header HTTP (x-forwarded-for / x-real-ip), dan string user-agent browser.
2. Login Gagal / Brute-Force Warning (recordAuthFailedLogin): Mencatat percobaan login yang ditolak (kata sandi keliru atau email tak terdaftar) dengan status warning, modul AUTH, alamat IP, dan alasan penolakan demi deteksi serangan siber sedini mungkin.
3. Penutupan Sesi / Logout (recordAuthLogout): Mencatat terminasi sesi dengan mengklasifikasikan penyebab:

• user_initiated: Pengguna keluar secara sadar melalui tombol Sign Out pada TopBar/Sidebar.
• inactivity: Sesi diputus otomatis oleh pelindung peramban setelah 30 menit tanpa aktivitas (Session Timeout Protection).

3.5. Arsitektur Server-Side Pagination & High-Scale Filtering (getPaginatedAuditLogs)

Untuk mengantisipasi pertumbuhan log hingga puluhan ribu hingga ratusan ribu transaksi tanpa penurunan kecepatan sistem (zero-lag):

1. Beban Data Konstan (10–30 KB per request): Menggantikan pemuatan in-memory client-side yang berisiko Out of Memory (OOM). Kueri database mengeksekusi klausa .range(from, to) yang dipetakan langsung ke LIMIT dan OFFSET PostgreSQL.
2. Eksekusi Filter di Basis Data: Parameter category, severity, dan search diproses langsung di level PostgreSQL memanfaatkan indeks idx_audit_logs_created_at dan idx_audit_logs_module dari Migrasi 207.
3. Pencarian Cerdas Terjadwal (Debounced Search 350ms): Masukan kata kunci pengguna ditahan selama 350ms sebelum dikirim ke server, mencegah kelebihan beban query saat pengetikan berlangsung.
4. Navigasi Presisi: Antarmuka visualizer dilengkapi kontrol nomor halaman (Halaman X dari Y), seleksi ukuran batch (10 | 25 | 50 | 100), dan tombol lompat cepat (First, Prev, Next, Last).

---

🖥️ 4. Antarmuka Visualisasi Pengawasan (UI/UX)#

Sistem menyediakan 2 titik akses antarmuka untuk meninjau log aktivitas:

4.1. Visualizer Utama: /dashboard/pengguna (Tab: Log Aktivitas)

Komponen AuditLogVisualizer.tsx menyajikan antarmuka visual komprehensif:

1. Kartu Ringkasan Eksekutif (4 KPI Cards):

• Total Aktivitas: Akumulasi seluruh log yang terekam.
• Tingkat Keberhasilan: Rasio aksi status === 'success' dalam persentase dengan progress bar dinamis.
• Tindakan Sensitif: Jumlah operasi kritis (DELETE atau UPDATE) pada data master/keuangan.
• Kegagalan Sistem: Jumlah aksi berstatus error yang tertangkap sistem.

2. Visualisasi Analitik Recharts:

• Tren Aktivitas (7 Hari): Grafik area interaktif yang menunjukkan volume mutasi per hari dalam sepekan terakhir.
• Distribusi Modul: Donut chart persentase aktivitas per modul sistem (FINANCE, COA_MAPPING, RBAC, dll).

3. Penyaring Interaktif (Filter & Search):

• Pencarian real-time berdasarkan nama operator, modul, jenis aksi, atau teks di dalam JSON detail.
• Dropdown filter modul dinamis.

4. Tabel Riwayat Rinci:

• Menampilkan ikon status (hijau/merah), tanggal, nama aktor & peran, badge aksi, dan tombol modal detail.

4.2. Pusat Telemetri & Audit Master: /dashboard/pengaturan (Tab: Database)

Komponen DatabaseSettingsTab.tsx merupakan dasbor operasional kelas enterprise yang menyajikan:

1. Sub-Header Status & Live Ping: Menampilkan status PostgreSQL Cloud, enkripsi RLS Tier 5 aktif, live latency (ms), dan tombol pintas ke Console Forensik.
2. 4 Bento Telemetry Cards:

• Koneksi Database & Latensi: Pengukuran waktu respons query (ms) dengan indikator kecepatan dan tombol uji ping interaktif.
• Total Jejak Audit: Jumlah record log audit di cloud database dengan jumlah aktivitas termuat dalam sesi.
• Aksi Kritis / Mutasi: Agregasi aksi berisiko tinggi (DELETE, UPDATE, VOID, MIGRATION_MODE_TOGGLE, error) dengan alert badge.
• Auto-Backup & Disaster Recovery: Jadwal snapshot otomatis pukul 03:00 WITA.

3. Audit Explorer Interaktif:

• Pencarian teks real-time lintas modul, nama personil, aksi, dan kata kunci di dalam payload JSON.
• Kancing filter kategori: Semua Modul, Keuangan & Jurnal, USP Simpan Pinjam, Otoritas & User, serta Operasional & Unit.
• Filter keparahan (Semua vs Kritis / Sensitif) dan pemilih limit batch (10, 25, 50 entri).

4. Dialog Forensik AuditDiffViewer:

• Komparasi visual perbandingan data lama vs data baru dengan perhitungan delta nominal dan deviasi persentase finansial otomatis.
• Penampil payload JSON mentah ber-syntax highlighting dan tombol Salin JSON.
• Metadata teknis (UUID Aktor, status eksekusi, timestamp ISO).

5. Suite Ekspor Formal BPK / Inspektorat:

• Cetak Berita Acara Jejak Audit resmi berstandar A4 PDF via exportAuditLogsPDF().
• Ekspor rekapitulasi spreadsheet Excel (.xlsx) via exportAuditLogsExcel().
• Unduhan berkas snapshot JSON lokal browser.

---

🗺️ 5. Peta Jalan Pengembangan (Evolution Roadmap)#

Untuk meningkatkan kepatuhan tata kelola BUMDes berstandar audit profesional, ditetapkan 5 Fase Pengembangan Modul Audit Trail:

Memuat diagram alur...

🚩 Fase 1: Otomasi Pencatatan Mutasi Sistem (System-Wide Auto-Hooking) - [SELESAI]

Menghubungkan fungsi createLog() ke setiap Server Action kritikal tanpa bergantung pada input manual:

• Modul Jurnal & Transaksi Kas:
• Hook saat pembuatan jurnal manual (createManualJournalEntry).
• Hook saat edit transaksi kas / BKK / BKM (createTreasuryTransaction).
• Hook saat konfirmasi setoran fisik kas (confirmCashRemittance).
• Modul Tutup Buku & Periode Akuntansi:
• Hook saat pembatalan tutup buku (revert_sept_2025_closing).
• Modul Mode Migrasi & Unit Usaha:
• Hook saat status is_migration_mode diaktifkan atau dimatikan oleh Super Admin (updateBusinessUnit).
• Hook saat perubahan status operasional unit usaha.
• Modul Simpan Pinjam Syariah (USP):
• Hook persetujuan pinjaman, pencairan dana, restrukturisasi jadwal angsuran, pembayaran angsuran, mutasi simpanan, dan write-off pinjaman macet (loans.ts, payments.ts, savings.ts, yarnen.ts, collaterals.ts).
• Hook pembukuan jurnal penyesuaian cadangan kerugian piutang SAK EP (ckpn.ts / postUSPCKPNJournal).
• Modul Inventori & Logistik:
• Hook pembuatan draft transfer stok antar gudang (createStockTransfer).
• Hook pengiriman barang & penerbitan surat jalan (shipStockTransfer).
• Hook penerimaan barang fisik di gudang tujuan (receiveStockTransfer).
• Hook pembatalan transfer stok draft (cancelStockTransfer).
• Hook penyesuaian fisik stok opname berimbang (stock-opname.ts / performStockOpname).
• Modul Keamanan, Akun & Otorisasi RBAC:
• Hook pergantian role pengguna dan pembuatan pengguna baru (users.ts / updateUserRole, registerUser, updateUser, deleteUser).
• Hook reset kata sandi akun pengguna oleh Super Admin (resetUserPassword).
• Hook konfigurasi matriks izin peran dan delegasi peran sekunder (rbac.ts / updateRolePermissions, assignUserRole, revokeUserRole).
• Modul Autentikasi & Forensik Akses Sesi:
• Hook sesi login berhasil (recordAuthLogin) dengan atribusi aktor, IP klien, dan user-agent.
• Hook deteksi ancaman login gagal / brute-force (recordAuthFailedLogin) berstatus warning.
• Hook penutupan sesi logout sadar (user_initiated) dan sesi kedaluwarsa otomatis 30m (inactivity).
• Ekstraksi otomatis IP publik/lokal via HTTP Request Headers (x-forwarded-for / x-real-ip).
• Perluasan akses baca audit trail untuk Pengawas BUMDes (pengawas, pengawas_1, pengawas_2) dan perangkat pengawasan desa (pendamping_desa, bendahara_desa, auditor) dengan penegakan Segregation of Duties (Read-Only Mode).

🚩 Fase 2: Pelaporan & Ekspor Kepatuhan Audit (Compliance Export) - [SELESAI]

Menyediakan dokumen formal fisik untuk diserahkan kepada auditor eksternal:

• Ekspor PDF Resmi Berita Acara Jejak Audit:
• Kop Resmi BUMDes Bolulango lengkap dengan identitas sistem & nomor dokumen dinamis (BA-AUDIT/YYYY/MM/DD).
• Tata letak Landscape A4 dengan tabel kronologis aktivitas audit ber-cap waktu terotentikasi.
• Lembar pengesahan Tiga Pilar Audit: Bendahara BUMDes, Ketua BPD / Dewan Pengawas, dan Direktur Utama BUMDes.
• Ekspor Berkas Excel / CSV:
• Unduhan instan seluruh log yang terfilter untuk analisis spreadsheet auditor BPKP (Excel .xlsx multi-sheet & CSV UTF-8).

🚩 Fase 3: Penyaring Rentang Waktu & Unit Usaha (Advanced Filtering) - [SELESAI]

Memudahkan auditor memeriksa kasus spesifik:

• Komponen Date Range Picker: Pemilihan Tanggal Mulai s/d Tanggal Selesai lengkap dengan preset kilat (Hari Ini, 7 Hari Terakhir, Bulan Ini).
• Filter Multi-Pilihan Unit Usaha: Pemilahan mutasi per unit (Holding Pusat, USP-01, KTPG-PTR, dll) berdasarkan metadata transaksi dan profil staf.
• Filter Berdasarkan Tingkat Urgensi (Severity Level):
• 🔴 Kritis (Critical): Aksi DELETE, MIGRATION_MODE_TOGGLE, REVERT, atau status error.
• 🟡 Peringatan (Warning): Aksi UPDATE, UNIT_STATUS_UPDATE, atau status warning.
• 🔵 Informasi (Informational): Aksi CREATE, entri jurnal baru, login, dan mutasi normal.

🚩 Fase 4: Modal Forensik Perbandingan Data (Diff Viewer) - [SELESAI]

Memperlihatkan apa saja yang diubah oleh pengguna:

• Modal Forensik Interaktif Layar Lebar: Dialog komprehensif (max-w-4xl) dengan 3 tab navigasi: Komparasi Visual, Payload Mentah JSON, dan Forensik Jaringan.
• Tampilan Komparasi Berdampingan (Side-by-Side Diff):
• Data Lama (Old Value): Penanda merah lembut (rose-50/rose-900) untuk nilai sebelum mutasi.
• Data Baru (New Value): Penanda hijau lembut (emerald-50/emerald-900) untuk nilai setelah mutasi.
• Kalkulator Deviasi Finansial Dinamis: Perhitungan otomatis selisih nominal (Δ rupiah) dan persentase perubahan pada transaksi finansial yang mengalami revisi saldo.
• Tombol Salin Cepat JSON: Mempermudah penarikan bukti forensik digital ke clipboard.

🚩 Fase 5: Deteksi Anomali Cerdas & Early Warning System (EWS Security)

Proteksi dini pencegahan penggelapan dana:

• Threshold Alert: Memberi bendera peringatan pada mutasi kas tunai di atas Rp 5.000.000 tanpa persetujuan berjenjang.
• Out-of-Hours Alert: Deteksi dan penandaan mutasi yang diinput di luar jam kerja operasional kantor desa (misal antara pukul 23:00 - 05:00 WITA).
• Rapid Deletion Watcher: Peringatan instan ke Direktur jika ada akun staf yang menghapus lebih dari 3 entri dalam kurun waktu 5 menit.

---

📝 6. Standar Penulisan Log Aktivitas (createLog)#

Setiap pengembang wajib mengikuti konvensi penulisan payload saat menambahkan hook audit baru:

typescript
import { createLog } from '@/lib/actions/audit'

// Contoh Standar Pencatatan Aksi Finansial:
await createLog({
 action: 'REVERT_CLOSING_PERIOD', // Gunakan huruf kapital baku
 module: 'FINANCE', // Nama modul sistem standar
 status: 'success', // 'success' | 'error' | 'warning'
 details: {
 reference_number: 'CLOSE-PUSAT-2025-09',
 period_month: 9,
 period_year: 2025,
 reason: 'Migrasi data historis 12 bulan lampau',
 affected_tables: ['financial_closings', 'journal_entries', 'depreciation_logs']
 }
})

---

Pusat Dokumentasi Sistem ERP BUMDes Bolulango — Blueprint Arsitektur Teknis Tata Kelola & Audit Trail v2026.1.