🎛️ BLUEPRINT FILTER MODUL KEUANGAN UNIVERSAL & KONTEKSTUAL

Standar Arsitektur Komponen Filter, Sinkronisasi URL, dan Pengalaman Pengguna ERP BUMDes#

BUMDes Bolulango — Desa Bandungan, Kecamatan Bulango Utara, Kabupaten Bone Bolango, Gorontalo Standar Arsitektur Antarmuka Modul Keuangan, Buku Besar, Utang-Piutang, dan Arus Kas

---

🧭 1. Latar Belakang & Urgensi Standardisasi#

Dalam tata kelola sistem ERP terintegrasi dengan 25 unit usaha, bilah filter (Filter Bar) merupakan garda terdepan interaksi pengelola keuangan, manajer unit, direksi, dan auditor saat mengevaluasi kinerja bisnis.

Komponen filter pada seluruh modul keuangan dan operasional telah distandarisasi untuk memenuhi kriteria baku:

1. Dukungan Dimensi Waktu Menyeluruh: Menyediakan seleksi per bulan kalender, mode setahun penuh (month=0), dan rentang tanggal kustom (date range picker) untuk audit cut-off.
2. Filter Domain-Specific: Pada modul Utang-Piutang (AR/AP), filter menyaring jenis liabilitas dan status jatuh tempo. Pada Simpan Pinjam, filter menyaring saldo aktif dan status agunan.
3. Pengalaman Visual & Desain Konsisten: Menyatukan bahasa desain modern (glassmorphism, dark mode terpadu, dan rounded tokens).
4. Indikator Visual Filter Aktif: Memberikan transparansi filter yang sedang aktif melalui chips dinamis.

Blueprint ini menetapkan spesifikasi komponen UniversalFilterBar yang seragam, adaptif, dan kontekstual.

---

🏗️ 2. Arsitektur Komponen: UniversalFilterBar#

Memuat diagram alur...

Komponen ini dirancang modular dan terbagi dalam 4 sub-komponen utama:

A. Selektor Unit Usaha Hierarkis (Business Unit Selector)

• Tampilan Pohon Unit: Menampilkan unit induk holding, sub-holding Ketapang, divisi, hingga sub-unit dengan indentasi visual yang jelas (🌐 Semua Unit, ↳ Sub-Holding, ↳ Unit Usaha).
• Isolasi Peran (RBAC): Jika pengguna memiliki peran terbatas (admin_unit, kepala_unit), opsi terkunci otomatis hanya pada unit yang ditugaskan (assigned unit).

B. Pengontrol Dimensi Waktu Fleksibel (Temporal Engine)

Mendukung 3 mode seleksi waktu:

1. Mode Bulanan Standar: Pilihan Bulan (Januari - Desember) dan Tahun (dinamis dari data transaksi riil).
2. Mode Rentang Tanggal Kustom (Custom Date Range): Dua bidang kalender popover (Tanggal Mulai s/d Tanggal Selesai) untuk kebutuhan rekonsiliasi kas spesifik.
3. Pintasan Cepat (Quick Presets): Tombol aksi instan:

• Hari Ini
• Bulan Berjalan (MTD)
• Kuartal Berjalan (Q1 / Q2 / Q3 / Q4)
• Tahun Berjalan (YTD)
• Semua Periode (Kumulatif)

C. Filter Kontekstual Spesifik Modul (Domain-Specific Slots)

Pada modul Utang & Piutang (AR/AP), filter menyematkan kontrol khusus:

1. Kategori Kewajiban / Tagihan: Semua Jenis, Utang Dagang Pakan & Sapronak, Dana Talangan Pengurus / Pihak Ketiga, Beban Operasional Akrual.
2. Mitra Bisnis Terpilih: Dropdown pencarian nama mitra (supplier, customer, atau perorangan).
3. Status Penagihan & Jatuh Tempo: Semua Status, Belum Lunas (Unpaid), Sebagian (Partial), Lunas (Paid), Jatuh Tempo H-7, Menunggak (Overdue > 30 Hari).

D. Bilah Filter Aktif (Active Filter Chips)

Menampilkan ringkasan filter yang sedang aktif dengan tombol hapus cepat per-filter untuk memudahkan navigasi pengguna.

---

⚡ 3. Standar Implementasi Anti-Stale State (Pencegahan Laporan Membeku)#

1. Direct Data Binding untuk Komponen Read-Only: Komponen pembaca laporan keuangan (Neraca Skontro, Neraca Saldo, Neraca Lajur) tidak boleh menyalin initialData ke dalam useState. Wajib langsung menggunakan data dari Server Component:

typescript
export default function ReportClient({ initialData }: Props) {
const data = initialData
return <Table data={data} />
}

2. Prop Synchronization Hook (useEffect) untuk Form Interaktif: Pada antarmuka pengeditan anggaran RKA atau kas kecil, wajib menyinkronkan state lokal saat Server Component mengirimkan data baru:

typescript
useEffect(() => {
setBudgets(initialBudgets)
}, [initialBudgets, year, defaultUnitId, activeVersion])

---

🕒 4. Kepatuhan Zona Waktu WITA (UTC+8) & Tanggal Cut-off#

1. Larangan Metode UTC: Dilarang menggunakan new Date().toISOString().split('T')[0].
2. Standar Fungsi toLocalDateString(): Seluruh inisialisasi tanggal cut-off wajib menggunakan helper toLocalDateString() dari @/lib/utils/cutoff-period.
3. Standarisasi Daftar Tahun Buku: Seluruh bilah filter wajib menggunakan konstanta seragam FISCAL_YEARS = [2023, 2024, 2025, 2026, 2027, 2028, 2029, 2030].

---

🛡️ 5. Standar Kontrak Reset Filter & Isolasi Multi-Unit (Anti-Commingling)#

1. Kontrak onResetAll pada UniversalFilterBar: Setiap implementasi UniversalFilterBar wajib menyediakan prop opsional onResetAll?: () => void. Ketika pengguna menekan tombol "Reset Semua Filter", komponen induk wajib mengosongkan seluruh filter global dan state pencarian/filter lokal di seluruh tab.
2. Isolasi Mutlak Unit Simpan Pinjam Konvensional (.01) vs Syariah (.13): Sesuai prinsip SAK EP Zero-Overlap, dilarang keras mencampur query simpanan, pinjaman, dan agunan tanpa memfilter unit_id. Seluruh tautan navigasi di modul Syariah (/dashboard/simpan-pinjam-syariah/) dilarang keras menautkan pengguna ke rute Konvensional (/dashboard/simpan-pinjam/).
3. Otorisasi Kartu Statistik Jurnal Kegiatan: Setiap fungsi agregasi ringkasan atau statistik (seperti getActivityStats) wajib menerapkan otorisasi resolveFinanceRBAC dan memfilter unit_id yang diizinkan untuk mencegah kebocoran angka belanja holding ke unit bawahan.

---

🔄 6. Standar Sinkronisasi Konteks Unit, Hierarki Sub-Holding & Ekspor Sadar-Filter (Fase 2)#

A. Sinkronisasi Konteks Unit Dua Arah (UnitUrlSyncProvider & useOptionalUnitContext)

1. Penyelarasan URL Parameter & Header Global: Penggantian unit kerja pada WorkContextBar di header aplikasi disinkronkan ke parameter URL ?unitId= melalui components/dashboard/UnitUrlSyncProvider.tsx.
2. Penggunaan Aman useOptionalUnitContext(): Komponen filter global dan client laporan (UniversalFilterBar, LedgerClient, TrialBalanceClient, WorksheetClient) dilarang menggunakan useUnitContext() secara langsung yang melempar error saat konteks absen. Wajib menggunakan useOptionalUnitContext() dari @/contexts/UnitContext:

typescript
const unitCtx = useOptionalUnitContext()
const setActiveUnit = unitCtx?.setActiveUnit

Ketika pengguna memilih "Semua Unit (Konsolidasi)", bilah filter wajib memanggil setActiveUnit?.(null) untuk membersihkan indikator unit aktif di header tanpa merusak pengujian otomatis Jest.

B. Kontrak Mode Setahun Penuh (month=0) & Tahun Fiskal Terpusat

1. Standar month=0 untuk Kumulatif Tahunan: Pada modul Buku Besar, Neraca Saldo, dan Neraca Lajur, nilai month=0 merepresentasikan mode "Semua Bulan / Setahun Penuh". Server Component dan Server Actions wajib menghitung saldo awal per 1 Januari dan mengakumulasikan seluruh mutasi jurnal hingga 31 Desember tahun fiskal terpilih.
2. Larangan Hardcode Array Tahun: Seluruh antarmuka laporan keuangan wajib mengimpor konstanta terpusat FISCAL_YEARS.

C. Algoritma Hierarki Sub-Holding (buildUnitHierarchy Orphan-Parent Safe)

Bagi pengguna dengan wewenang manajerial terbatas (seperti manajer_ketapang), daftar unit yang diterima dari database bersifat parsial (hanya mencakup unit anak Ketapang tanpa node holding pusat). Fungsi buildUnitHierarchy di lib/utils/unit-hierarchy.ts wajib memperlakukan unit yang parent_id-nya tidak ditemukan dalam daftar sebagai simpul akar (root nodes):

typescript
const isRoot = !unit.parent_id || !unitMap.has(unit.parent_id)

Hal ini mencegah kegagalan pembentukan pohon navigasi dan menjamin dropdown filter sub-unit tetap terisi lengkap.

D. Kontrak Dokumen Ekspor Sadar-Filter (Filter-Aware Export)

Setiap modul yang menyediakan tombol unduh Excel, PDF, atau CSV wajib mematuhi aturan integrasi filter:

1. Ekspor Data Tersaring: Tombol ekspor wajib mengekspor koleksi data hasil pemfilteran aktif (filteredRows, filterRows, atau filtered), bukan data mentah awal (raw initial data).
2. Pencantuman Identitas Unit: Generator ekspor (lib/export-utils.ts) wajib mencantumkan unitName spesifik pada judul/kop lembar kerja, atau label "Konsolidasi BUMDes Pusat" jika mode konsolidasi aktif.
3. Penyelarasan Metode Aktif: Pada modul Arus Kas, opsi ekspor PDF dan Excel wajib menyertakan parameter method: 'direct' | 'indirect' agar struktur laporan yang diunduh identik dengan tab metode yang sedang dilihat pengguna.

---

🔍 7. Arsitektur Mesin Pencarian Universal Terpadu (globalDashboardSearch)#

Pencarian universal terpadu di dashboard /dashboard/search mengintegrasikan 5 domain data ke dalam satu Server Action efisien:

Memuat diagram alur...

Spesifikasi Teknis:

1. Proteksi Wewenang: Pengguna dengan unit terbatas hanya dapat mencari jurnal, produk, dan anggota pada unit yang diizinkan.
2. Navigasi Langsung: Setiap item hasil pencarian memuat rute langsung ke transaksi atau master data bersangkutan.
3. Optimasi Debounce: Komponen SearchClient.tsx menunda pengiriman request sebesar 300 milidetik untuk mencegah request flood ke database PostgreSQL.

---

📊 8. Standarisasi Filter Transaksional Operasional & Paginasi DataTable#

Berdasarkan hasil audit Fase 3, seluruh antarmuka operasional wajib menerapkan aturan baku:

1. Anti-Stale Pagination pada <DataTable>: Komponen paginasi wajib me-reset ke halaman pertama saat koleksi data berganti:

typescript
useEffect(() => {
setCurrentPage(1)
}, [data])

2. Pencarian Multi-Tipe: Fungsi filter pencarian tabel wajib menangani nilai non-string dengan aman (String(value).toLowerCase()).
3. Larangan Mutasi State Saat Render: Pengurutan tabel wajib menggunakan shallow copy [...data].sort().
4. Presisi colSpan Baris Kosong: Atribut colSpan pada baris data kosong wajib sama persis dengan jumlah kolom header <th>.
5. Kepatuhan Mutlak Identitas Resmi: Seluruh keluaran sistem wajib menggunakan nama resmi BUMDes Bolulango, Desa Bandungan, Kecamatan Bulango Utara, Kabupaten Bone Bolango.

---

📜 9. Lembar Riwayat Pembaruan Arsitektur#