Dokumentasi

Aplikasi ini adalah sistem administrasi pesantren terpadu yang mendukung pengelolaan santri, penerimaan peserta didik baru (PPDB), absensi, keuangan, kegiatan, catatan santri, dan raport. Sistem bersifat multi-workspace: setiap pesantren (instansi) memiliki ruang kerja (workspace) terpisah dengan konfigurasi, hak akses, dan datanya sendiri.

Seluruh identitas aplikasi — nama, versi, logo, nama pesantren, alamat, rekening, dan ketentuan lainnya — disimpan dalam basis data dan dapat diubah melalui menu antarmuka, tanpa perlu mengubah kode program.

Workspace adalah satu unit pesantren yang terisolasi. Setiap workspace memiliki modul, hak akses, peran, rute, menu, pengguna, dan data bisnisnya sendiri. Dua workspace tidak saling berbagi data.

• Administrator sistem dapat berpindah ke workspace mana pun melalui pemilih workspace di bilah atas.
• Pengguna biasa hanya dapat berpindah ke workspace tempat akunnya terdaftar (username yang sama, akun aktif).
• Ketika berpindah, sesi di-reissue agar identik dengan workspace tujuan; menu, rute, dan hak akses dihitung ulang otomatis.
• Workspace baru dibuat oleh administrator sistem melalui menu Sistem → Workspace (bootstrap konfigurasi berjalan otomatis dan idempoten).
• Identitas workspace (nama, kode, slug, kontak, zona waktu, bahasa, logo, status) dapat diubah melalui tombol "Ubah" pada halaman yang sama.

Catatan: Jika layar "Sesi tidak berlaku" muncul, gunakan tombol "Kembali ke Workspace Saya" untuk kembali ke workspace milik Anda, atau masuk kembali.

Masuk menggunakan username dan kata sandi yang diberikan administrator workspace. Workspace yang dimasuki mengikuti cookie workspace (diatur melalui pemilih workspace di bilah atas setelah login, atau pilihan saat login bila tersedia lebih dari satu workspace).

Akun contoh (demo) hanya tampil di halaman masuk bila akun-akun tersebut benar-benar terdaftar pada workspace aktif dan pengaturan "Tampilkan daftar akun contoh di halaman masuk" (Sistem → Pengaturan, grup Umum) diizinkan. Pada lingkungan produksi yang bersih, daftar ini otomatis kosong.

Akses pengguna ditentukan oleh peran dan hak akses langsung (pengecualian). Peran bawaan mencakup Administrator (semua hak), Kesantrian, Keuangan, Pengajar, Pendidikan/Kurikulum, dan Panitia PPDB. Hak akses standar per modul: Tambah, Lihat, Ubah, Hapus, serta hak tambahan seperti ekspor.

• Peran dikelola pada menu Sistem → Peran (tambah/hapus hak akses per peran).
• Hak akses langsung dapat diberikan atau ditarik per pengguna pada menu Sistem → Pengguna.
• Administrator sistem memiliki akses lintas workspace dan mengelola konfigurasi tingkat sistem.
• Setiap halaman aplikasi memverifikasi rute, modul, dan hak akses secara otomatis; bila tidak memenuhi, halaman menampilkan "Akses Ditolak".

• Santri — profil santri, jenjang, kelas, tahun ajaran, status (aktif/pulang/cuti).
• PPDB — pendaftaran calon santri, verifikasi dokumen, tahapan seleksi, cek status publik.
• Absensi — presensi harian per kelas dengan statistik kehadiran.
• Keuangan — pembayaran tunai & transfer (dengan verifikasi bukti), tagihan, pengembalian dana berjenjang.
• Kegiatan & Kalender — program kegiatan pesantren dan agenda.
• Catatan — catatan perkembangan, penanganan kasus, dan tindak lanjut berbasis alur kerja.
• Raport — penilaian per mapel, peringkat, dan pelaporan nilai.

Setiap modul dapat diaktifkan/nonaktifkan dan dikonfigurasi (menu, rute, hak akses) melalui menu Sistem → Modul, Rute, dan Menu. Menambah modul berarti menyalin entitas yang belum ada — bootstrap bersifat idempoten dan tidak menggandakan data.

Semua nilai yang sebelumnya bersifat tetap kini dikelola dari antarmuka:

• Sistem → Pengaturan — nama & alamat pesantren, kop laporan, mata uang, rekening bank, NISN, prefiks NIS, dokumen wajib PPDB, dan flag tampilan (mis. tampilkan akun contoh).
• Sistem → Aplikasi — nama, kode, versi, URL dasar, dan logo aplikasi (menggantikan teks yang di-hardcode pada footer, dokumen ekspor, dan metadata halaman).
• Sistem → Workspace — daftar workspace, pembuatan workspace baru, pengubahan identitas workspace, dan bootstrap ulang.
• Sistem → Modul / Rute / Menu / Hak Akses / Peran — konfigurasi struktur aplikasi per workspace.

Catatan: Perubahan nama/versi aplikasi pada menu Sistem → Aplikasi langsung tercermin pada footer area aplikasi, kop & metadata berkas ekspor, dan judul tab peramban.

Data dapat diekspor ke Excel (.xlsx), CSV, dan PDF melalui tautan ekspor pada halaman daftar. Kop dokumen, nama penerbit, dan versi pada berkas diambil dari pengaturan & aplikasi aktif, bukan teks tetap.

Setiap ekspor dicatat pada log audit (siapa, kapan, jenis, jumlah baris, dan filter yang dipakai).

Aktivitas penting (login, keluar, pergantian workspace, pembuatan/perubahan data, ekspor, pengelolaan pengguna & peran) tercatat pada log audit per workspace dan dapat dilihat pada menu Sistem → Audit. Kolom audit (pembuat, pembuat waktu, pengubah, pengubah waktu) diisi otomatis oleh trigger basis data pada seluruh tabel persisten.

Aplikasi menggunakan Bahasa Indonesia sebagai bahasa utama. Dokumentasi ini tersedia dalam Bahasa Indonesia pada alamat tanpa prefiks dan dalam English pada alamat berprefiks "/en". Gunakan pengalih bahasa pada kepala halaman dokumentasi untuk berpindah bahasa.

Catatan: Bahasa lain (jika ditambahkan di kemudian hari) mewarisi terjemahan Bahasa Indonesia untuk kunci yang belum tersedia.

Aplikasi memakai Next.js (App Router), PocketBase (REST API, via adaptor `src/lib/db/`), dan sesi JWT berbasis cookie. Penyiapan database: skema diterapkan lalu bootstrap per workspace (modul, hak akses, peran, rute, menu, pengaturan awal, dan administrator pertama).

1. Siapkan PocketBase dan isi variabel lingkungan (URL + kredensial superuser, kunci JWT, dsb.).
2. Jalankan migrasi skema (npm run db:migrate) — idempoten.
3. Jalankan seed/bootstrap (npm run db:seed) untuk membuat workspace demo + akun contoh, atau buat workspace melalui halaman penyiapan /setup.
4. Jalankan aplikasi (npm run dev / npm start). Instance administrasi berjalan pada port 9003 dan instance PPDB publik pada port 9002 (mode per instance diatur lewat variabel lingkungan).